feat(spec): DataEvent carries organizationId, the organization the record belongs to

.changeset/data-event-organization-id.md

@@ -0,0 +1,34 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): `DataEvent` names the organization the record belongs to, so a tenant-scoped consumer can tell whose event it is
+
+The realtime `DataEvent` payload (`@objectstack/spec/api`, the body of every
+`data.record.created` / `data.record.updated` / `data.record.deleted` event)
+gains an optional `organizationId`: the organization the record belongs to.
+Until now the event carried the object name, the record id and the row body,
+and nothing that named the tenant — so a consumer that fans events out per
+organization (a webhook subscription, a per-organization realtime subscriber)
+had no term to discriminate on short of reading the row body, which is absent
+on delete events and is not the consumer's to read.
+
+What a consumer may assume:
+
+- **Present** — exactly that organization, never a guess: the organization the
+ record belongs to, not the caller's active organization standing in for it.
+- **Absent** — the record belongs to no organization. That is every event on a
+ `single`-posture deployment (no organization wall, nothing stamps the
+ column) and an organization-less, environment-wide row under a walled
+ posture. Read it as "not behind any organization wall", never as "unknown,
+ look it up".
+
+Declared = enforced: the key is optional and nothing else. No default
+fabricates a tenant; `null` and the empty string are refused with a located
+issue, so "no organization" has exactly one spelling — the key is absent.
+
+Additive and shape-preserving: every event that parsed before parses
+identically, and no producer emits the key yet — the ObjectQL engine's publish
+site is a separate change that follows this contract. The bulk
+`BulkDataEvent` (`data.records.*`) is deliberately untouched: a predicate
+write's affected set is its own contract with its own tenant question.

content/docs/references/api/events.mdx

@@ -57,6 +57,7 @@ const result = BulkDataEventSchema.parse(data);
 | **type** | `Enum<'data.record.created' \| 'data.record.updated' \| 'data.record.deleted'>` | ✅ | Event type |
 | **object** | `string` | ✅ | Object name |
 | **recordId** | `string` | ✅ | Record ID |
+| **organizationId** | `string` | optional | Organization the record belongs to (its organization_id), so a tenant-scoped consumer can discriminate the event's tenant without reading the record body. Absent when the record belongs to no organization: every event on a single-posture deployment (no organization wall, nothing stamps the column), and a row that carries no organization under a walled posture (environment-wide, or an object outside the wall) — read absence as "not behind any organization wall", never as "unknown". Present = exactly that organization; never fabricated, and the empty string is refused. |
 | **changes** | `Record<string, any>` | optional | Changed fields |
 | **before** | `Record<string, any>` | optional | Before state |
 | **after** | `Record<string, any>` | optional | After state |

packages/spec/authorable-surface/api.json

@@ -442,6 +442,7 @@
  "api/DataEvent:changes",
  "api/DataEvent:id",
  "api/DataEvent:object",
+ "api/DataEvent:organizationId",
  "api/DataEvent:recordId",
  "api/DataEvent:timestamp",
  "api/DataEvent:type",

packages/spec/src/api/events.test.ts

@@ -239,4 +239,67 @@ describe('DataEventSchema', () => {
  expect(event.before).toEqual({ name: 'Old Name' });
  expect(event.after).toEqual({ name: 'New Name' });
  });
+
+ // The tenant term — the contract half of closing the webhook fan-out's
+ // cross-organization delivery. Both directions are pinned so
+ // "declared = enforced" is a measurement rather than a sentence: the key is
+ // optional and NOTHING else — no default fabricates a tenant, absence has
+ // exactly one spelling, and a value that is not a non-empty string is
+ // refused at the path a producer can act on. `BulkDataEventSchema` is
+ // deliberately untouched here: a predicate write's affected set is a
+ // separate contract with its own tenant question (recorded on the change
+ // that adds this member), so nothing below pins that schema either way.
+ describe('organizationId', () => {
+ const base = {
+ id: '4b4720e8-97c3-4a12-9b70-b70a3d2314a6',
+ type: 'data.record.created',
+ object: 'account',
+ recordId: 'rec_1',
+ timestamp: '2026-09-02T00:00:00.000Z',
+ } as const;
+
+ it('parses without the key and does not fabricate one (single posture: no wall, no organization)', () => {
+ const event = DataEventSchema.parse(base);
+ expect(Object.prototype.hasOwnProperty.call(event, 'organizationId')).toBe(false);
+ expect(event.organizationId).toBeUndefined();
+ });
+
+ it('parses with the key and carries it through verbatim', () => {
+ const event = DataEventSchema.parse({ ...base, organizationId: 'org_jia' });
+ expect(event.organizationId).toBe('org_jia');
+ });
+
+ it('refuses a non-string value with invalid_type at ["organizationId"]', () => {
+ const result = DataEventSchema.safeParse({ ...base, organizationId: 42 });
+ expect(result.success).toBe(false);
+ if (result.success) throw new Error('unreachable');
+ expect(result.error.issues).toEqual([
+ expect.objectContaining({ code: 'invalid_type', expected: 'string', path: ['organizationId'] }),
+ ]);
+ });
+
+ it('refuses null — absence has exactly one spelling, the missing key', () => {
+ const result = DataEventSchema.safeParse({ ...base, organizationId: null });
+ expect(result.success).toBe(false);
+ if (result.success) throw new Error('unreachable');
+ expect(result.error.issues).toEqual([
+ expect.objectContaining({ code: 'invalid_type', expected: 'string', path: ['organizationId'] }),
+ ]);
+ });
+
+ it('refuses the empty string — "no organization" is never spelled ""', () => {
+ const result = DataEventSchema.safeParse({ ...base, organizationId: '' });
+ expect(result.success).toBe(false);
+ if (result.success) throw new Error('unreachable');
+ expect(result.error.issues).toEqual([
+ expect.objectContaining({ code: 'too_small', minimum: 1, path: ['organizationId'] }),
+ ]);
+ });
+
+ it('is the only member added — every pre-existing member is still declared', () => {
+ expect(Object.keys(DataEventSchema.shape).sort()).toEqual([
+ 'after', 'before', 'changes', 'id', 'object', 'organizationId', 'recordId', 'timestamp', 'type', 'userId',
+ ]);
+ });
+ });
 });

packages/spec/src/api/events.zod.ts

@@ -215,6 +215,18 @@ export type MetadataEvent = z.input<typeof MetadataEventSchema>;
  *
  * Represents a data record change event (create, update, delete).
  * Used for real-time synchronization of data records across clients.
+ *
+ * **This payload IS the contract a consumer discriminates on.** It travels as
+ * the `payload` of the `RealtimeEventPayload` envelope
+ * (`contracts/realtime-service.ts`), and the envelope is a transport shape —
+ * `type` / `object` / `payload` / `timestamp`, a TypeScript interface no
+ * parse ever validates. Every consumer that must read a per-event fact
+ * already reads it HERE, not on the envelope: the webhook fan-out takes
+ * `recordId` from the payload at its match site, and the client SDK
+ * `safeParse`s the payload against this schema before it delivers anything.
+ * So the tenant term below is a member of this validated payload rather than
+ * a second, unvalidated envelope field: one declaration, enforced at the
+ * publish site by the same `parse` that enforces `recordId`.
  */
 export const DataEventSchema = lazySchema(() => z.object({
  /** Unique event identifier */
@@ -229,6 +241,66 @@ export const DataEventSchema = lazySchema(() => z.object({
  /** Record ID */
  recordId: z.string().describe('Record ID'),
 
+ /**
+ * Organization the record belongs to — its `organization_id` column, under
+ * the camelCase spelling every published payload in this package uses for
+ * the tenant term (`organizationId`, the blessed developer-facing name).
+ *
+ * **Why a first-class member and not a read of the record body.** A
+ * tenant-scoped consumer — the webhook fan-out matching subscriptions to
+ * events, a per-organization realtime subscriber — must discriminate the
+ * event's tenant BEFORE it touches the record: `after` is absent on
+ * `data.record.deleted`, `before` is absent on create, and both are the
+ * unfiltered row body the consumer may not be entitled to read at all. The
+ * match term therefore rides beside `object` and `recordId`, validated
+ * with the rest of the event at the publish site.
+ *
+ * **Absent = the record belongs to no organization.** Two situations, one
+ * meaning:
+ * - a `single`-posture deployment — `postureEnforcesWall(posture)` is
+ * `false` and `postureStampsOrganization(posture)` with it (see
+ * `@objectstack/spec/security`): there is no organization wall and
+ * nothing stamps the column, so EVERY event is organization-less;
+ * - a row that carries no organization under a walled posture (`group` /
+ * `isolated`): an environment-wide row (`organization_id IS NULL`), or a
+ * row of an object that stands outside the wall — `tenancy.enabled:
+ * false` by declaration, or no `organization_id` column at all (the
+ * identity tables).
+ * In both, a consumer may read absence as "not behind any organization
+ * wall" — the reading it already gives an `organization_id IS NULL` row on
+ * the read path. It may NOT read absence as "unknown, resolve it yourself":
+ * either the producer had the organization in hand or the record has none,
+ * and a per-event lookup on the fan-out path is exactly the hot-path read
+ * this member exists to make unnecessary.
+ *
+ * **Present = exactly that organization, never a guess.** It names the
+ * organization the RECORD belongs to — not the caller's active organization
+ * standing in for the row's, which would mislabel an administrator's write
+ * into another organization. It is never fabricated: no `.default()`, and
+ * the empty string is refused, so "no organization" has exactly one
+ * spelling — the key is absent.
+ *
+ * **Optional as a contract fact, not as a transition.** A `single`-posture
+ * deployment stays organization-less for its whole life, so a required key
+ * would either force a fabricated tenant there or leave the engine unable to
+ * publish at all (the publish site `parse`s the event and drops it on
+ * failure). Declared = enforced: this optionality is exactly what validation
+ * enforces, and no consumer tolerates any other shape. The producer
+ * obligation is the other half of the same contract: a producer that omits
+ * the key on an organization-stamped row publishes a cross-tenant event,
+ * which is fixed at the publish site — never by a consumer-side lookup.
+ */
+ organizationId: z.string().min(1).optional().describe(
+ 'Organization the record belongs to (its organization_id), so a tenant-scoped '
+ + 'consumer can discriminate the event\'s tenant without reading the record body. '
+ + 'Absent when the record belongs to no organization: every event on a single-posture '
+ + 'deployment (no organization wall, nothing stamps the column), and a row that '
+ + 'carries no organization under a walled posture (environment-wide, or an object '
+ + 'outside the wall) — read absence as '
+ + '"not behind any organization wall", never as "unknown". Present = exactly that '
+ + 'organization; never fabricated, and the empty string is refused.',
+ ),
+
  /** Changed fields (update events only) */
  changes: z.record(z.string(), z.unknown()).optional().describe('Changed fields'),
 

.changeset/data-event-organization-id.md

@@ -0,0 +1,34 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): `DataEvent` names the organization the record belongs to, so a tenant-scoped consumer can tell whose event it is
+
+The realtime `DataEvent` payload (`@objectstack/spec/api`, the body of every
+`data.record.created` / `data.record.updated` / `data.record.deleted` event)
+gains an optional `organizationId`: the organization the record belongs to.
+Until now the event carried the object name, the record id and the row body,
+and nothing that named the tenant — so a consumer that fans events out per
+organization (a webhook subscription, a per-organization realtime subscriber)
+had no term to discriminate on short of reading the row body, which is absent
+on delete events and is not the consumer's to read.
+
+What a consumer may assume:
+
+- **Present** — exactly that organization, never a guess: the organization the
+ record belongs to, not the caller's active organization standing in for it.
+- **Absent** — the record belongs to no organization. That is every event on a
+ `single`-posture deployment (no organization wall, nothing stamps the
+ column) and an organization-less, environment-wide row under a walled
+ posture. Read it as "not behind any organization wall", never as "unknown,
+ look it up".
+
+Declared = enforced: the key is optional and nothing else. No default
+fabricates a tenant; `null` and the empty string are refused with a located
+issue, so "no organization" has exactly one spelling — the key is absent.
+
+Additive and shape-preserving: every event that parsed before parses
+identically, and no producer emits the key yet — the ObjectQL engine's publish
+site is a separate change that follows this contract. The bulk
+`BulkDataEvent` (`data.records.*`) is deliberately untouched: a predicate
+write's affected set is its own contract with its own tenant question.

content/docs/references/api/events.mdx

@@ -57,6 +57,7 @@ const result = BulkDataEventSchema.parse(data);
 | **type** | `Enum<'data.record.created' \| 'data.record.updated' \| 'data.record.deleted'>` | ✅ | Event type |
 | **object** | `string` | ✅ | Object name |
 | **recordId** | `string` | ✅ | Record ID |
+| **organizationId** | `string` | optional | Organization the record belongs to (its organization_id), so a tenant-scoped consumer can discriminate the event's tenant without reading the record body. Absent when the record belongs to no organization: every event on a single-posture deployment (no organization wall, nothing stamps the column), and a row that carries no organization under a walled posture (environment-wide, or an object outside the wall) — read absence as "not behind any organization wall", never as "unknown". Present = exactly that organization; never fabricated, and the empty string is refused. |
 | **changes** | `Record<string, any>` | optional | Changed fields |
 | **before** | `Record<string, any>` | optional | Before state |
 | **after** | `Record<string, any>` | optional | After state |

packages/spec/authorable-surface/api.json

@@ -442,6 +442,7 @@
  "api/DataEvent:changes",
  "api/DataEvent:id",
  "api/DataEvent:object",
+ "api/DataEvent:organizationId",
  "api/DataEvent:recordId",
  "api/DataEvent:timestamp",
  "api/DataEvent:type",

packages/spec/src/api/events.test.ts

@@ -239,4 +239,67 @@ describe('DataEventSchema', () => {
  expect(event.before).toEqual({ name: 'Old Name' });
  expect(event.after).toEqual({ name: 'New Name' });
  });
+
+ // The tenant term — the contract half of closing the webhook fan-out's
+ // cross-organization delivery. Both directions are pinned so
+ // "declared = enforced" is a measurement rather than a sentence: the key is
+ // optional and NOTHING else — no default fabricates a tenant, absence has
+ // exactly one spelling, and a value that is not a non-empty string is
+ // refused at the path a producer can act on. `BulkDataEventSchema` is
+ // deliberately untouched here: a predicate write's affected set is a
+ // separate contract with its own tenant question (recorded on the change
+ // that adds this member), so nothing below pins that schema either way.
+ describe('organizationId', () => {
+ const base = {
+ id: '4b4720e8-97c3-4a12-9b70-b70a3d2314a6',
+ type: 'data.record.created',
+ object: 'account',
+ recordId: 'rec_1',
+ timestamp: '2026-09-02T00:00:00.000Z',
+ } as const;
+
+ it('parses without the key and does not fabricate one (single posture: no wall, no organization)', () => {
+ const event = DataEventSchema.parse(base);
+ expect(Object.prototype.hasOwnProperty.call(event, 'organizationId')).toBe(false);
+ expect(event.organizationId).toBeUndefined();
+ });
+
+ it('parses with the key and carries it through verbatim', () => {
+ const event = DataEventSchema.parse({ ...base, organizationId: 'org_jia' });
+ expect(event.organizationId).toBe('org_jia');
+ });
+
+ it('refuses a non-string value with invalid_type at ["organizationId"]', () => {
+ const result = DataEventSchema.safeParse({ ...base, organizationId: 42 });
+ expect(result.success).toBe(false);
+ if (result.success) throw new Error('unreachable');
+ expect(result.error.issues).toEqual([
+ expect.objectContaining({ code: 'invalid_type', expected: 'string', path: ['organizationId'] }),
+ ]);
+ });
+
+ it('refuses null — absence has exactly one spelling, the missing key', () => {
+ const result = DataEventSchema.safeParse({ ...base, organizationId: null });
+ expect(result.success).toBe(false);
+ if (result.success) throw new Error('unreachable');
+ expect(result.error.issues).toEqual([
+ expect.objectContaining({ code: 'invalid_type', expected: 'string', path: ['organizationId'] }),
+ ]);
+ });
+
+ it('refuses the empty string — "no organization" is never spelled ""', () => {
+ const result = DataEventSchema.safeParse({ ...base, organizationId: '' });
+ expect(result.success).toBe(false);
+ if (result.success) throw new Error('unreachable');
+ expect(result.error.issues).toEqual([
+ expect.objectContaining({ code: 'too_small', minimum: 1, path: ['organizationId'] }),
+ ]);
+ });
+
+ it('is the only member added — every pre-existing member is still declared', () => {
+ expect(Object.keys(DataEventSchema.shape).sort()).toEqual([
+ 'after', 'before', 'changes', 'id', 'object', 'organizationId', 'recordId', 'timestamp', 'type', 'userId',
+ ]);
+ });
+ });
 });

packages/spec/src/api/events.zod.ts

@@ -215,6 +215,18 @@ export type MetadataEvent = z.input<typeof MetadataEventSchema>;
  *
  * Represents a data record change event (create, update, delete).
  * Used for real-time synchronization of data records across clients.
+ *
+ * **This payload IS the contract a consumer discriminates on.** It travels as
+ * the `payload` of the `RealtimeEventPayload` envelope
+ * (`contracts/realtime-service.ts`), and the envelope is a transport shape —
+ * `type` / `object` / `payload` / `timestamp`, a TypeScript interface no
+ * parse ever validates. Every consumer that must read a per-event fact
+ * already reads it HERE, not on the envelope: the webhook fan-out takes
+ * `recordId` from the payload at its match site, and the client SDK
+ * `safeParse`s the payload against this schema before it delivers anything.
+ * So the tenant term below is a member of this validated payload rather than
+ * a second, unvalidated envelope field: one declaration, enforced at the
+ * publish site by the same `parse` that enforces `recordId`.
  */
 export const DataEventSchema = lazySchema(() => z.object({
  /** Unique event identifier */
@@ -229,6 +241,66 @@ export const DataEventSchema = lazySchema(() => z.object({
  /** Record ID */
  recordId: z.string().describe('Record ID'),
 
+ /**
+ * Organization the record belongs to — its `organization_id` column, under
+ * the camelCase spelling every published payload in this package uses for
+ * the tenant term (`organizationId`, the blessed developer-facing name).
+ *
+ * **Why a first-class member and not a read of the record body.** A
+ * tenant-scoped consumer — the webhook fan-out matching subscriptions to
+ * events, a per-organization realtime subscriber — must discriminate the
+ * event's tenant BEFORE it touches the record: `after` is absent on
+ * `data.record.deleted`, `before` is absent on create, and both are the
+ * unfiltered row body the consumer may not be entitled to read at all. The
+ * match term therefore rides beside `object` and `recordId`, validated
+ * with the rest of the event at the publish site.
+ *
+ * **Absent = the record belongs to no organization.** Two situations, one
+ * meaning:
+ * - a `single`-posture deployment — `postureEnforcesWall(posture)` is
+ * `false` and `postureStampsOrganization(posture)` with it (see
+ * `@objectstack/spec/security`): there is no organization wall and
+ * nothing stamps the column, so EVERY event is organization-less;
+ * - a row that carries no organization under a walled posture (`group` /
+ * `isolated`): an environment-wide row (`organization_id IS NULL`), or a
+ * row of an object that stands outside the wall — `tenancy.enabled:
+ * false` by declaration, or no `organization_id` column at all (the
+ * identity tables).
+ * In both, a consumer may read absence as "not behind any organization
+ * wall" — the reading it already gives an `organization_id IS NULL` row on
+ * the read path. It may NOT read absence as "unknown, resolve it yourself":
+ * either the producer had the organization in hand or the record has none,
+ * and a per-event lookup on the fan-out path is exactly the hot-path read
+ * this member exists to make unnecessary.
+ *
+ * **Present = exactly that organization, never a guess.** It names the
+ * organization the RECORD belongs to — not the caller's active organization
+ * standing in for the row's, which would mislabel an administrator's write
+ * into another organization. It is never fabricated: no `.default()`, and
+ * the empty string is refused, so "no organization" has exactly one
+ * spelling — the key is absent.
+ *
+ * **Optional as a contract fact, not as a transition.** A `single`-posture
+ * deployment stays organization-less for its whole life, so a required key
+ * would either force a fabricated tenant there or leave the engine unable to
+ * publish at all (the publish site `parse`s the event and drops it on
+ * failure). Declared = enforced: this optionality is exactly what validation
+ * enforces, and no consumer tolerates any other shape. The producer
+ * obligation is the other half of the same contract: a producer that omits
+ * the key on an organization-stamped row publishes a cross-tenant event,
+ * which is fixed at the publish site — never by a consumer-side lookup.
+ */
+ organizationId: z.string().min(1).optional().describe(
+ 'Organization the record belongs to (its organization_id), so a tenant-scoped '
+ + 'consumer can discriminate the event\'s tenant without reading the record body. '
+ + 'Absent when the record belongs to no organization: every event on a single-posture '
+ + 'deployment (no organization wall, nothing stamps the column), and a row that '
+ + 'carries no organization under a walled posture (environment-wide, or an object '
+ + 'outside the wall) — read absence as '
+ + '"not behind any organization wall", never as "unknown". Present = exactly that '
+ + 'organization; never fabricated, and the empty string is refused.',
+ ),
+
  /** Changed fields (update events only) */
  changes: z.record(z.string(), z.unknown()).optional().describe('Changed fields'),
 

.changeset/data-event-organization-id.md

@@ -0,0 +1,34 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): `DataEvent` names the organization the record belongs to, so a tenant-scoped consumer can tell whose event it is
+
+The realtime `DataEvent` payload (`@objectstack/spec/api`, the body of every
+`data.record.created` / `data.record.updated` / `data.record.deleted` event)
+gains an optional `organizationId`: the organization the record belongs to.
+Until now the event carried the object name, the record id and the row body,
+and nothing that named the tenant — so a consumer that fans events out per
+organization (a webhook subscription, a per-organization realtime subscriber)
+had no term to discriminate on short of reading the row body, which is absent
+on delete events and is not the consumer's to read.
+
+What a consumer may assume:
+
+- **Present** — exactly that organization, never a guess: the organization the
+ record belongs to, not the caller's active organization standing in for it.
+- **Absent** — the record belongs to no organization. That is every event on a
+ `single`-posture deployment (no organization wall, nothing stamps the
+ column) and an organization-less, environment-wide row under a walled
+ posture. Read it as "not behind any organization wall", never as "unknown,
+ look it up".
+
+Declared = enforced: the key is optional and nothing else. No default
+fabricates a tenant; `null` and the empty string are refused with a located
+issue, so "no organization" has exactly one spelling — the key is absent.
+
+Additive and shape-preserving: every event that parsed before parses
+identically, and no producer emits the key yet — the ObjectQL engine's publish
+site is a separate change that follows this contract. The bulk
+`BulkDataEvent` (`data.records.*`) is deliberately untouched: a predicate
+write's affected set is its own contract with its own tenant question.

content/docs/references/api/events.mdx

@@ -57,6 +57,7 @@ const result = BulkDataEventSchema.parse(data);
 | **type** | `Enum<'data.record.created' \| 'data.record.updated' \| 'data.record.deleted'>` | ✅ | Event type |
 | **object** | `string` | ✅ | Object name |
 | **recordId** | `string` | ✅ | Record ID |
+| **organizationId** | `string` | optional | Organization the record belongs to (its organization_id), so a tenant-scoped consumer can discriminate the event's tenant without reading the record body. Absent when the record belongs to no organization: every event on a single-posture deployment (no organization wall, nothing stamps the column), and a row that carries no organization under a walled posture (environment-wide, or an object outside the wall) — read absence as "not behind any organization wall", never as "unknown". Present = exactly that organization; never fabricated, and the empty string is refused. |
 | **changes** | `Record<string, any>` | optional | Changed fields |
 | **before** | `Record<string, any>` | optional | Before state |
 | **after** | `Record<string, any>` | optional | After state |

packages/spec/authorable-surface/api.json

@@ -442,6 +442,7 @@
  "api/DataEvent:changes",
  "api/DataEvent:id",
  "api/DataEvent:object",
+ "api/DataEvent:organizationId",
  "api/DataEvent:recordId",
  "api/DataEvent:timestamp",
  "api/DataEvent:type",

packages/spec/src/api/events.test.ts

@@ -239,4 +239,67 @@ describe('DataEventSchema', () => {
  expect(event.before).toEqual({ name: 'Old Name' });
  expect(event.after).toEqual({ name: 'New Name' });
  });
+
+ // The tenant term — the contract half of closing the webhook fan-out's
+ // cross-organization delivery. Both directions are pinned so
+ // "declared = enforced" is a measurement rather than a sentence: the key is
+ // optional and NOTHING else — no default fabricates a tenant, absence has
+ // exactly one spelling, and a value that is not a non-empty string is
+ // refused at the path a producer can act on. `BulkDataEventSchema` is
+ // deliberately untouched here: a predicate write's affected set is a
+ // separate contract with its own tenant question (recorded on the change
+ // that adds this member), so nothing below pins that schema either way.
+ describe('organizationId', () => {
+ const base = {
+ id: '4b4720e8-97c3-4a12-9b70-b70a3d2314a6',
+ type: 'data.record.created',
+ object: 'account',
+ recordId: 'rec_1',
+ timestamp: '2026-09-02T00:00:00.000Z',
+ } as const;
+
+ it('parses without the key and does not fabricate one (single posture: no wall, no organization)', () => {
+ const event = DataEventSchema.parse(base);
+ expect(Object.prototype.hasOwnProperty.call(event, 'organizationId')).toBe(false);
+ expect(event.organizationId).toBeUndefined();
+ });
+
+ it('parses with the key and carries it through verbatim', () => {
+ const event = DataEventSchema.parse({ ...base, organizationId: 'org_jia' });
+ expect(event.organizationId).toBe('org_jia');
+ });
+
+ it('refuses a non-string value with invalid_type at ["organizationId"]', () => {
+ const result = DataEventSchema.safeParse({ ...base, organizationId: 42 });
+ expect(result.success).toBe(false);
+ if (result.success) throw new Error('unreachable');
+ expect(result.error.issues).toEqual([
+ expect.objectContaining({ code: 'invalid_type', expected: 'string', path: ['organizationId'] }),
+ ]);
+ });
+
+ it('refuses null — absence has exactly one spelling, the missing key', () => {
+ const result = DataEventSchema.safeParse({ ...base, organizationId: null });
+ expect(result.success).toBe(false);
+ if (result.success) throw new Error('unreachable');
+ expect(result.error.issues).toEqual([
+ expect.objectContaining({ code: 'invalid_type', expected: 'string', path: ['organizationId'] }),
+ ]);
+ });
+
+ it('refuses the empty string — "no organization" is never spelled ""', () => {
+ const result = DataEventSchema.safeParse({ ...base, organizationId: '' });
+ expect(result.success).toBe(false);
+ if (result.success) throw new Error('unreachable');
+ expect(result.error.issues).toEqual([
+ expect.objectContaining({ code: 'too_small', minimum: 1, path: ['organizationId'] }),
+ ]);
+ });
+
+ it('is the only member added — every pre-existing member is still declared', () => {
+ expect(Object.keys(DataEventSchema.shape).sort()).toEqual([
+ 'after', 'before', 'changes', 'id', 'object', 'organizationId', 'recordId', 'timestamp', 'type', 'userId',
+ ]);
+ });
+ });
 });

packages/spec/src/api/events.zod.ts

@@ -215,6 +215,18 @@ export type MetadataEvent = z.input<typeof MetadataEventSchema>;
  *
  * Represents a data record change event (create, update, delete).
  * Used for real-time synchronization of data records across clients.
+ *
+ * **This payload IS the contract a consumer discriminates on.** It travels as
+ * the `payload` of the `RealtimeEventPayload` envelope
+ * (`contracts/realtime-service.ts`), and the envelope is a transport shape —
+ * `type` / `object` / `payload` / `timestamp`, a TypeScript interface no
+ * parse ever validates. Every consumer that must read a per-event fact
+ * already reads it HERE, not on the envelope: the webhook fan-out takes
+ * `recordId` from the payload at its match site, and the client SDK
+ * `safeParse`s the payload against this schema before it delivers anything.
+ * So the tenant term below is a member of this validated payload rather than
+ * a second, unvalidated envelope field: one declaration, enforced at the
+ * publish site by the same `parse` that enforces `recordId`.
  */
 export const DataEventSchema = lazySchema(() => z.object({
  /** Unique event identifier */
@@ -229,6 +241,66 @@ export const DataEventSchema = lazySchema(() => z.object({
  /** Record ID */
  recordId: z.string().describe('Record ID'),
 
+ /**
+ * Organization the record belongs to — its `organization_id` column, under
+ * the camelCase spelling every published payload in this package uses for
+ * the tenant term (`organizationId`, the blessed developer-facing name).
+ *
+ * **Why a first-class member and not a read of the record body.** A
+ * tenant-scoped consumer — the webhook fan-out matching subscriptions to
+ * events, a per-organization realtime subscriber — must discriminate the
+ * event's tenant BEFORE it touches the record: `after` is absent on
+ * `data.record.deleted`, `before` is absent on create, and both are the
+ * unfiltered row body the consumer may not be entitled to read at all. The
+ * match term therefore rides beside `object` and `recordId`, validated
+ * with the rest of the event at the publish site.
+ *
+ * **Absent = the record belongs to no organization.** Two situations, one
+ * meaning:
+ * - a `single`-posture deployment — `postureEnforcesWall(posture)` is
+ * `false` and `postureStampsOrganization(posture)` with it (see
+ * `@objectstack/spec/security`): there is no organization wall and
+ * nothing stamps the column, so EVERY event is organization-less;
+ * - a row that carries no organization under a walled posture (`group` /
+ * `isolated`): an environment-wide row (`organization_id IS NULL`), or a
+ * row of an object that stands outside the wall — `tenancy.enabled:
+ * false` by declaration, or no `organization_id` column at all (the
+ * identity tables).
+ * In both, a consumer may read absence as "not behind any organization
+ * wall" — the reading it already gives an `organization_id IS NULL` row on
+ * the read path. It may NOT read absence as "unknown, resolve it yourself":
+ * either the producer had the organization in hand or the record has none,
+ * and a per-event lookup on the fan-out path is exactly the hot-path read
+ * this member exists to make unnecessary.
+ *
+ * **Present = exactly that organization, never a guess.** It names the
+ * organization the RECORD belongs to — not the caller's active organization
+ * standing in for the row's, which would mislabel an administrator's write
+ * into another organization. It is never fabricated: no `.default()`, and
+ * the empty string is refused, so "no organization" has exactly one
+ * spelling — the key is absent.
+ *
+ * **Optional as a contract fact, not as a transition.** A `single`-posture
+ * deployment stays organization-less for its whole life, so a required key
+ * would either force a fabricated tenant there or leave the engine unable to
+ * publish at all (the publish site `parse`s the event and drops it on
+ * failure). Declared = enforced: this optionality is exactly what validation
+ * enforces, and no consumer tolerates any other shape. The producer
+ * obligation is the other half of the same contract: a producer that omits
+ * the key on an organization-stamped row publishes a cross-tenant event,
+ * which is fixed at the publish site — never by a consumer-side lookup.
+ */
+ organizationId: z.string().min(1).optional().describe(
+ 'Organization the record belongs to (its organization_id), so a tenant-scoped '
+ + 'consumer can discriminate the event\'s tenant without reading the record body. '
+ + 'Absent when the record belongs to no organization: every event on a single-posture '
+ + 'deployment (no organization wall, nothing stamps the column), and a row that '
+ + 'carries no organization under a walled posture (environment-wide, or an object '
+ + 'outside the wall) — read absence as '
+ + '"not behind any organization wall", never as "unknown". Present = exactly that '
+ + 'organization; never fabricated, and the empty string is refused.',
+ ),
+
  /** Changed fields (update events only) */
  changes: z.record(z.string(), z.unknown()).optional().describe('Changed fields'),
 

.changeset/data-event-organization-id.md

@@ -0,0 +1,34 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): `DataEvent` names the organization the record belongs to, so a tenant-scoped consumer can tell whose event it is
+
+The realtime `DataEvent` payload (`@objectstack/spec/api`, the body of every
+`data.record.created` / `data.record.updated` / `data.record.deleted` event)
+gains an optional `organizationId`: the organization the record belongs to.
+Until now the event carried the object name, the record id and the row body,
+and nothing that named the tenant — so a consumer that fans events out per
+organization (a webhook subscription, a per-organization realtime subscriber)
+had no term to discriminate on short of reading the row body, which is absent
+on delete events and is not the consumer's to read.
+
+What a consumer may assume:
+
+- **Present** — exactly that organization, never a guess: the organization the
+ record belongs to, not the caller's active organization standing in for it.
+- **Absent** — the record belongs to no organization. That is every event on a
+ `single`-posture deployment (no organization wall, nothing stamps the
+ column) and an organization-less, environment-wide row under a walled
+ posture. Read it as "not behind any organization wall", never as "unknown,
+ look it up".
+
+Declared = enforced: the key is optional and nothing else. No default
+fabricates a tenant; `null` and the empty string are refused with a located
+issue, so "no organization" has exactly one spelling — the key is absent.
+
+Additive and shape-preserving: every event that parsed before parses
+identically, and no producer emits the key yet — the ObjectQL engine's publish
+site is a separate change that follows this contract. The bulk
+`BulkDataEvent` (`data.records.*`) is deliberately untouched: a predicate
+write's affected set is its own contract with its own tenant question.

content/docs/references/api/events.mdx

@@ -57,6 +57,7 @@ const result = BulkDataEventSchema.parse(data);
 | **type** | `Enum<'data.record.created' \| 'data.record.updated' \| 'data.record.deleted'>` | ✅ | Event type |
 | **object** | `string` | ✅ | Object name |
 | **recordId** | `string` | ✅ | Record ID |
+| **organizationId** | `string` | optional | Organization the record belongs to (its organization_id), so a tenant-scoped consumer can discriminate the event's tenant without reading the record body. Absent when the record belongs to no organization: every event on a single-posture deployment (no organization wall, nothing stamps the column), and a row that carries no organization under a walled posture (environment-wide, or an object outside the wall) — read absence as "not behind any organization wall", never as "unknown". Present = exactly that organization; never fabricated, and the empty string is refused. |
 | **changes** | `Record<string, any>` | optional | Changed fields |
 | **before** | `Record<string, any>` | optional | Before state |
 | **after** | `Record<string, any>` | optional | After state |

packages/spec/authorable-surface/api.json

@@ -442,6 +442,7 @@
  "api/DataEvent:changes",
  "api/DataEvent:id",
  "api/DataEvent:object",
+ "api/DataEvent:organizationId",
  "api/DataEvent:recordId",
  "api/DataEvent:timestamp",
  "api/DataEvent:type",

packages/spec/src/api/events.test.ts

@@ -239,4 +239,67 @@ describe('DataEventSchema', () => {
  expect(event.before).toEqual({ name: 'Old Name' });
  expect(event.after).toEqual({ name: 'New Name' });
  });
+
+ // The tenant term — the contract half of closing the webhook fan-out's
+ // cross-organization delivery. Both directions are pinned so
+ // "declared = enforced" is a measurement rather than a sentence: the key is
+ // optional and NOTHING else — no default fabricates a tenant, absence has
+ // exactly one spelling, and a value that is not a non-empty string is
+ // refused at the path a producer can act on. `BulkDataEventSchema` is
+ // deliberately untouched here: a predicate write's affected set is a
+ // separate contract with its own tenant question (recorded on the change
+ // that adds this member), so nothing below pins that schema either way.
+ describe('organizationId', () => {
+ const base = {
+ id: '4b4720e8-97c3-4a12-9b70-b70a3d2314a6',
+ type: 'data.record.created',
+ object: 'account',
+ recordId: 'rec_1',
+ timestamp: '2026-09-02T00:00:00.000Z',
+ } as const;
+
+ it('parses without the key and does not fabricate one (single posture: no wall, no organization)', () => {
+ const event = DataEventSchema.parse(base);
+ expect(Object.prototype.hasOwnProperty.call(event, 'organizationId')).toBe(false);
+ expect(event.organizationId).toBeUndefined();
+ });
+
+ it('parses with the key and carries it through verbatim', () => {
+ const event = DataEventSchema.parse({ ...base, organizationId: 'org_jia' });
+ expect(event.organizationId).toBe('org_jia');
+ });
+
+ it('refuses a non-string value with invalid_type at ["organizationId"]', () => {
+ const result = DataEventSchema.safeParse({ ...base, organizationId: 42 });
+ expect(result.success).toBe(false);
+ if (result.success) throw new Error('unreachable');
+ expect(result.error.issues).toEqual([
+ expect.objectContaining({ code: 'invalid_type', expected: 'string', path: ['organizationId'] }),
+ ]);
+ });
+
+ it('refuses null — absence has exactly one spelling, the missing key', () => {
+ const result = DataEventSchema.safeParse({ ...base, organizationId: null });
+ expect(result.success).toBe(false);
+ if (result.success) throw new Error('unreachable');
+ expect(result.error.issues).toEqual([
+ expect.objectContaining({ code: 'invalid_type', expected: 'string', path: ['organizationId'] }),
+ ]);
+ });
+
+ it('refuses the empty string — "no organization" is never spelled ""', () => {
+ const result = DataEventSchema.safeParse({ ...base, organizationId: '' });
+ expect(result.success).toBe(false);
+ if (result.success) throw new Error('unreachable');
+ expect(result.error.issues).toEqual([
+ expect.objectContaining({ code: 'too_small', minimum: 1, path: ['organizationId'] }),
+ ]);
+ });
+
+ it('is the only member added — every pre-existing member is still declared', () => {
+ expect(Object.keys(DataEventSchema.shape).sort()).toEqual([
+ 'after', 'before', 'changes', 'id', 'object', 'organizationId', 'recordId', 'timestamp', 'type', 'userId',
+ ]);
+ });
+ });
 });

packages/spec/src/api/events.zod.ts

@@ -215,6 +215,18 @@ export type MetadataEvent = z.input<typeof MetadataEventSchema>;
  *
  * Represents a data record change event (create, update, delete).
  * Used for real-time synchronization of data records across clients.
+ *
+ * **This payload IS the contract a consumer discriminates on.** It travels as
+ * the `payload` of the `RealtimeEventPayload` envelope
+ * (`contracts/realtime-service.ts`), and the envelope is a transport shape —
+ * `type` / `object` / `payload` / `timestamp`, a TypeScript interface no
+ * parse ever validates. Every consumer that must read a per-event fact
+ * already reads it HERE, not on the envelope: the webhook fan-out takes
+ * `recordId` from the payload at its match site, and the client SDK
+ * `safeParse`s the payload against this schema before it delivers anything.
+ * So the tenant term below is a member of this validated payload rather than
+ * a second, unvalidated envelope field: one declaration, enforced at the
+ * publish site by the same `parse` that enforces `recordId`.
  */
 export const DataEventSchema = lazySchema(() => z.object({
  /** Unique event identifier */
@@ -229,6 +241,66 @@ export const DataEventSchema = lazySchema(() => z.object({
  /** Record ID */
  recordId: z.string().describe('Record ID'),
 
+ /**
+ * Organization the record belongs to — its `organization_id` column, under
+ * the camelCase spelling every published payload in this package uses for
+ * the tenant term (`organizationId`, the blessed developer-facing name).
+ *
+ * **Why a first-class member and not a read of the record body.** A
+ * tenant-scoped consumer — the webhook fan-out matching subscriptions to
+ * events, a per-organization realtime subscriber — must discriminate the
+ * event's tenant BEFORE it touches the record: `after` is absent on
+ * `data.record.deleted`, `before` is absent on create, and both are the
+ * unfiltered row body the consumer may not be entitled to read at all. The
+ * match term therefore rides beside `object` and `recordId`, validated
+ * with the rest of the event at the publish site.
+ *
+ * **Absent = the record belongs to no organization.** Two situations, one
+ * meaning:
+ * - a `single`-posture deployment — `postureEnforcesWall(posture)` is
+ * `false` and `postureStampsOrganization(posture)` with it (see
+ * `@objectstack/spec/security`): there is no organization wall and
+ * nothing stamps the column, so EVERY event is organization-less;
+ * - a row that carries no organization under a walled posture (`group` /
+ * `isolated`): an environment-wide row (`organization_id IS NULL`), or a
+ * row of an object that stands outside the wall — `tenancy.enabled:
+ * false` by declaration, or no `organization_id` column at all (the
+ * identity tables).
+ * In both, a consumer may read absence as "not behind any organization
+ * wall" — the reading it already gives an `organization_id IS NULL` row on
+ * the read path. It may NOT read absence as "unknown, resolve it yourself":
+ * either the producer had the organization in hand or the record has none,
+ * and a per-event lookup on the fan-out path is exactly the hot-path read
+ * this member exists to make unnecessary.
+ *
+ * **Present = exactly that organization, never a guess.** It names the
+ * organization the RECORD belongs to — not the caller's active organization
+ * standing in for the row's, which would mislabel an administrator's write
+ * into another organization. It is never fabricated: no `.default()`, and
+ * the empty string is refused, so "no organization" has exactly one
+ * spelling — the key is absent.
+ *
+ * **Optional as a contract fact, not as a transition.** A `single`-posture
+ * deployment stays organization-less for its whole life, so a required key
+ * would either force a fabricated tenant there or leave the engine unable to
+ * publish at all (the publish site `parse`s the event and drops it on
+ * failure). Declared = enforced: this optionality is exactly what validation
+ * enforces, and no consumer tolerates any other shape. The producer
+ * obligation is the other half of the same contract: a producer that omits
+ * the key on an organization-stamped row publishes a cross-tenant event,
+ * which is fixed at the publish site — never by a consumer-side lookup.
+ */
+ organizationId: z.string().min(1).optional().describe(
+ 'Organization the record belongs to (its organization_id), so a tenant-scoped '
+ + 'consumer can discriminate the event\'s tenant without reading the record body. '
+ + 'Absent when the record belongs to no organization: every event on a single-posture '
+ + 'deployment (no organization wall, nothing stamps the column), and a row that '
+ + 'carries no organization under a walled posture (environment-wide, or an object '
+ + 'outside the wall) — read absence as '
+ + '"not behind any organization wall", never as "unknown". Present = exactly that '
+ + 'organization; never fabricated, and the empty string is refused.',
+ ),
+
  /** Changed fields (update events only) */
  changes: z.record(z.string(), z.unknown()).optional().describe('Changed fields'),
 

.changeset/data-event-organization-id.md

@@ -0,0 +1,34 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): `DataEvent` names the organization the record belongs to, so a tenant-scoped consumer can tell whose event it is
+
+The realtime `DataEvent` payload (`@objectstack/spec/api`, the body of every
+`data.record.created` / `data.record.updated` / `data.record.deleted` event)
+gains an optional `organizationId`: the organization the record belongs to.
+Until now the event carried the object name, the record id and the row body,
+and nothing that named the tenant — so a consumer that fans events out per
+organization (a webhook subscription, a per-organization realtime subscriber)
+had no term to discriminate on short of reading the row body, which is absent
+on delete events and is not the consumer's to read.
+
+What a consumer may assume:
+
+- **Present** — exactly that organization, never a guess: the organization the
+ record belongs to, not the caller's active organization standing in for it.
+- **Absent** — the record belongs to no organization. That is every event on a
+ `single`-posture deployment (no organization wall, nothing stamps the
+ column) and an organization-less, environment-wide row under a walled
+ posture. Read it as "not behind any organization wall", never as "unknown,
+ look it up".
+
+Declared = enforced: the key is optional and nothing else. No default
+fabricates a tenant; `null` and the empty string are refused with a located
+issue, so "no organization" has exactly one spelling — the key is absent.
+
+Additive and shape-preserving: every event that parsed before parses
+identically, and no producer emits the key yet — the ObjectQL engine's publish
+site is a separate change that follows this contract. The bulk
+`BulkDataEvent` (`data.records.*`) is deliberately untouched: a predicate
+write's affected set is its own contract with its own tenant question.

content/docs/references/api/events.mdx

@@ -57,6 +57,7 @@ const result = BulkDataEventSchema.parse(data);
 | **type** | `Enum<'data.record.created' \| 'data.record.updated' \| 'data.record.deleted'>` | ✅ | Event type |
 | **object** | `string` | ✅ | Object name |
 | **recordId** | `string` | ✅ | Record ID |
+| **organizationId** | `string` | optional | Organization the record belongs to (its organization_id), so a tenant-scoped consumer can discriminate the event's tenant without reading the record body. Absent when the record belongs to no organization: every event on a single-posture deployment (no organization wall, nothing stamps the column), and a row that carries no organization under a walled posture (environment-wide, or an object outside the wall) — read absence as "not behind any organization wall", never as "unknown". Present = exactly that organization; never fabricated, and the empty string is refused. |
 | **changes** | `Record<string, any>` | optional | Changed fields |
 | **before** | `Record<string, any>` | optional | Before state |
 | **after** | `Record<string, any>` | optional | After state |

packages/spec/authorable-surface/api.json

@@ -442,6 +442,7 @@
  "api/DataEvent:changes",
  "api/DataEvent:id",
  "api/DataEvent:object",
+ "api/DataEvent:organizationId",
  "api/DataEvent:recordId",
  "api/DataEvent:timestamp",
  "api/DataEvent:type",

packages/spec/src/api/events.test.ts

@@ -239,4 +239,67 @@ describe('DataEventSchema', () => {
  expect(event.before).toEqual({ name: 'Old Name' });
  expect(event.after).toEqual({ name: 'New Name' });
  });
+
+ // The tenant term — the contract half of closing the webhook fan-out's
+ // cross-organization delivery. Both directions are pinned so
+ // "declared = enforced" is a measurement rather than a sentence: the key is
+ // optional and NOTHING else — no default fabricates a tenant, absence has
+ // exactly one spelling, and a value that is not a non-empty string is
+ // refused at the path a producer can act on. `BulkDataEventSchema` is
+ // deliberately untouched here: a predicate write's affected set is a
+ // separate contract with its own tenant question (recorded on the change
+ // that adds this member), so nothing below pins that schema either way.
+ describe('organizationId', () => {
+ const base = {
+ id: '4b4720e8-97c3-4a12-9b70-b70a3d2314a6',
+ type: 'data.record.created',
+ object: 'account',
+ recordId: 'rec_1',
+ timestamp: '2026-09-02T00:00:00.000Z',
+ } as const;
+
+ it('parses without the key and does not fabricate one (single posture: no wall, no organization)', () => {
+ const event = DataEventSchema.parse(base);
+ expect(Object.prototype.hasOwnProperty.call(event, 'organizationId')).toBe(false);
+ expect(event.organizationId).toBeUndefined();
+ });
+
+ it('parses with the key and carries it through verbatim', () => {
+ const event = DataEventSchema.parse({ ...base, organizationId: 'org_jia' });
+ expect(event.organizationId).toBe('org_jia');
+ });
+
+ it('refuses a non-string value with invalid_type at ["organizationId"]', () => {
+ const result = DataEventSchema.safeParse({ ...base, organizationId: 42 });
+ expect(result.success).toBe(false);
+ if (result.success) throw new Error('unreachable');
+ expect(result.error.issues).toEqual([
+ expect.objectContaining({ code: 'invalid_type', expected: 'string', path: ['organizationId'] }),
+ ]);
+ });
+
+ it('refuses null — absence has exactly one spelling, the missing key', () => {
+ const result = DataEventSchema.safeParse({ ...base, organizationId: null });
+ expect(result.success).toBe(false);
+ if (result.success) throw new Error('unreachable');
+ expect(result.error.issues).toEqual([
+ expect.objectContaining({ code: 'invalid_type', expected: 'string', path: ['organizationId'] }),
+ ]);
+ });
+
+ it('refuses the empty string — "no organization" is never spelled ""', () => {
+ const result = DataEventSchema.safeParse({ ...base, organizationId: '' });
+ expect(result.success).toBe(false);
+ if (result.success) throw new Error('unreachable');
+ expect(result.error.issues).toEqual([
+ expect.objectContaining({ code: 'too_small', minimum: 1, path: ['organizationId'] }),
+ ]);
+ });
+
+ it('is the only member added — every pre-existing member is still declared', () => {
+ expect(Object.keys(DataEventSchema.shape).sort()).toEqual([
+ 'after', 'before', 'changes', 'id', 'object', 'organizationId', 'recordId', 'timestamp', 'type', 'userId',
+ ]);
+ });
+ });
 });

packages/spec/src/api/events.zod.ts

@@ -215,6 +215,18 @@ export type MetadataEvent = z.input<typeof MetadataEventSchema>;
  *
  * Represents a data record change event (create, update, delete).
  * Used for real-time synchronization of data records across clients.
+ *
+ * **This payload IS the contract a consumer discriminates on.** It travels as
+ * the `payload` of the `RealtimeEventPayload` envelope
+ * (`contracts/realtime-service.ts`), and the envelope is a transport shape —
+ * `type` / `object` / `payload` / `timestamp`, a TypeScript interface no
+ * parse ever validates. Every consumer that must read a per-event fact
+ * already reads it HERE, not on the envelope: the webhook fan-out takes
+ * `recordId` from the payload at its match site, and the client SDK
+ * `safeParse`s the payload against this schema before it delivers anything.
+ * So the tenant term below is a member of this validated payload rather than
+ * a second, unvalidated envelope field: one declaration, enforced at the
+ * publish site by the same `parse` that enforces `recordId`.
  */
 export const DataEventSchema = lazySchema(() => z.object({
  /** Unique event identifier */
@@ -229,6 +241,66 @@ export const DataEventSchema = lazySchema(() => z.object({
  /** Record ID */
  recordId: z.string().describe('Record ID'),
 
+ /**
+ * Organization the record belongs to — its `organization_id` column, under
+ * the camelCase spelling every published payload in this package uses for
+ * the tenant term (`organizationId`, the blessed developer-facing name).
+ *
+ * **Why a first-class member and not a read of the record body.** A
+ * tenant-scoped consumer — the webhook fan-out matching subscriptions to
+ * events, a per-organization realtime subscriber — must discriminate the
+ * event's tenant BEFORE it touches the record: `after` is absent on
+ * `data.record.deleted`, `before` is absent on create, and both are the
+ * unfiltered row body the consumer may not be entitled to read at all. The
+ * match term therefore rides beside `object` and `recordId`, validated
+ * with the rest of the event at the publish site.
+ *
+ * **Absent = the record belongs to no organization.** Two situations, one
+ * meaning:
+ * - a `single`-posture deployment — `postureEnforcesWall(posture)` is
+ * `false` and `postureStampsOrganization(posture)` with it (see
+ * `@objectstack/spec/security`): there is no organization wall and
+ * nothing stamps the column, so EVERY event is organization-less;
+ * - a row that carries no organization under a walled posture (`group` /
+ * `isolated`): an environment-wide row (`organization_id IS NULL`), or a
+ * row of an object that stands outside the wall — `tenancy.enabled:
+ * false` by declaration, or no `organization_id` column at all (the
+ * identity tables).
+ * In both, a consumer may read absence as "not behind any organization
+ * wall" — the reading it already gives an `organization_id IS NULL` row on
+ * the read path. It may NOT read absence as "unknown, resolve it yourself":
+ * either the producer had the organization in hand or the record has none,
+ * and a per-event lookup on the fan-out path is exactly the hot-path read
+ * this member exists to make unnecessary.
+ *
+ * **Present = exactly that organization, never a guess.** It names the
+ * organization the RECORD belongs to — not the caller's active organization
+ * standing in for the row's, which would mislabel an administrator's write
+ * into another organization. It is never fabricated: no `.default()`, and
+ * the empty string is refused, so "no organization" has exactly one
+ * spelling — the key is absent.
+ *
+ * **Optional as a contract fact, not as a transition.** A `single`-posture
+ * deployment stays organization-less for its whole life, so a required key
+ * would either force a fabricated tenant there or leave the engine unable to
+ * publish at all (the publish site `parse`s the event and drops it on
+ * failure). Declared = enforced: this optionality is exactly what validation
+ * enforces, and no consumer tolerates any other shape. The producer
+ * obligation is the other half of the same contract: a producer that omits
+ * the key on an organization-stamped row publishes a cross-tenant event,
+ * which is fixed at the publish site — never by a consumer-side lookup.
+ */
+ organizationId: z.string().min(1).optional().describe(
+ 'Organization the record belongs to (its organization_id), so a tenant-scoped '
+ + 'consumer can discriminate the event\'s tenant without reading the record body. '
+ + 'Absent when the record belongs to no organization: every event on a single-posture '
+ + 'deployment (no organization wall, nothing stamps the column), and a row that '
+ + 'carries no organization under a walled posture (environment-wide, or an object '
+ + 'outside the wall) — read absence as '
+ + '"not behind any organization wall", never as "unknown". Present = exactly that '
+ + 'organization; never fabricated, and the empty string is refused.',
+ ),
+
  /** Changed fields (update events only) */
  changes: z.record(z.string(), z.unknown()).optional().describe('Changed fields'),
 

.changeset/data-event-organization-id.md

@@ -0,0 +1,34 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): `DataEvent` names the organization the record belongs to, so a tenant-scoped consumer can tell whose event it is
+
+The realtime `DataEvent` payload (`@objectstack/spec/api`, the body of every
+`data.record.created` / `data.record.updated` / `data.record.deleted` event)
+gains an optional `organizationId`: the organization the record belongs to.
+Until now the event carried the object name, the record id and the row body,
+and nothing that named the tenant — so a consumer that fans events out per
+organization (a webhook subscription, a per-organization realtime subscriber)
+had no term to discriminate on short of reading the row body, which is absent
+on delete events and is not the consumer's to read.
+
+What a consumer may assume:
+
+- **Present** — exactly that organization, never a guess: the organization the
+ record belongs to, not the caller's active organization standing in for it.
+- **Absent** — the record belongs to no organization. That is every event on a
+ `single`-posture deployment (no organization wall, nothing stamps the
+ column) and an organization-less, environment-wide row under a walled
+ posture. Read it as "not behind any organization wall", never as "unknown,
+ look it up".
+
+Declared = enforced: the key is optional and nothing else. No default
+fabricates a tenant; `null` and the empty string are refused with a located
+issue, so "no organization" has exactly one spelling — the key is absent.
+
+Additive and shape-preserving: every event that parsed before parses
+identically, and no producer emits the key yet — the ObjectQL engine's publish
+site is a separate change that follows this contract. The bulk
+`BulkDataEvent` (`data.records.*`) is deliberately untouched: a predicate
+write's affected set is its own contract with its own tenant question.

content/docs/references/api/events.mdx

@@ -57,6 +57,7 @@ const result = BulkDataEventSchema.parse(data);
 | **type** | `Enum<'data.record.created' \| 'data.record.updated' \| 'data.record.deleted'>` | ✅ | Event type |
 | **object** | `string` | ✅ | Object name |
 | **recordId** | `string` | ✅ | Record ID |
+| **organizationId** | `string` | optional | Organization the record belongs to (its organization_id), so a tenant-scoped consumer can discriminate the event's tenant without reading the record body. Absent when the record belongs to no organization: every event on a single-posture deployment (no organization wall, nothing stamps the column), and a row that carries no organization under a walled posture (environment-wide, or an object outside the wall) — read absence as "not behind any organization wall", never as "unknown". Present = exactly that organization; never fabricated, and the empty string is refused. |
 | **changes** | `Record<string, any>` | optional | Changed fields |
 | **before** | `Record<string, any>` | optional | Before state |
 | **after** | `Record<string, any>` | optional | After state |

packages/spec/authorable-surface/api.json

@@ -442,6 +442,7 @@
  "api/DataEvent:changes",
  "api/DataEvent:id",
  "api/DataEvent:object",
+ "api/DataEvent:organizationId",
  "api/DataEvent:recordId",
  "api/DataEvent:timestamp",
  "api/DataEvent:type",

packages/spec/src/api/events.test.ts

@@ -239,4 +239,67 @@ describe('DataEventSchema', () => {
  expect(event.before).toEqual({ name: 'Old Name' });
  expect(event.after).toEqual({ name: 'New Name' });
  });
+
+ // The tenant term — the contract half of closing the webhook fan-out's
+ // cross-organization delivery. Both directions are pinned so
+ // "declared = enforced" is a measurement rather than a sentence: the key is
+ // optional and NOTHING else — no default fabricates a tenant, absence has
+ // exactly one spelling, and a value that is not a non-empty string is
+ // refused at the path a producer can act on. `BulkDataEventSchema` is
+ // deliberately untouched here: a predicate write's affected set is a
+ // separate contract with its own tenant question (recorded on the change
+ // that adds this member), so nothing below pins that schema either way.
+ describe('organizationId', () => {
+ const base = {
+ id: '4b4720e8-97c3-4a12-9b70-b70a3d2314a6',
+ type: 'data.record.created',
+ object: 'account',
+ recordId: 'rec_1',
+ timestamp: '2026-09-02T00:00:00.000Z',
+ } as const;
+
+ it('parses without the key and does not fabricate one (single posture: no wall, no organization)', () => {
+ const event = DataEventSchema.parse(base);
+ expect(Object.prototype.hasOwnProperty.call(event, 'organizationId')).toBe(false);
+ expect(event.organizationId).toBeUndefined();
+ });
+
+ it('parses with the key and carries it through verbatim', () => {
+ const event = DataEventSchema.parse({ ...base, organizationId: 'org_jia' });
+ expect(event.organizationId).toBe('org_jia');
+ });
+
+ it('refuses a non-string value with invalid_type at ["organizationId"]', () => {
+ const result = DataEventSchema.safeParse({ ...base, organizationId: 42 });
+ expect(result.success).toBe(false);
+ if (result.success) throw new Error('unreachable');
+ expect(result.error.issues).toEqual([
+ expect.objectContaining({ code: 'invalid_type', expected: 'string', path: ['organizationId'] }),
+ ]);
+ });
+
+ it('refuses null — absence has exactly one spelling, the missing key', () => {
+ const result = DataEventSchema.safeParse({ ...base, organizationId: null });
+ expect(result.success).toBe(false);
+ if (result.success) throw new Error('unreachable');
+ expect(result.error.issues).toEqual([
+ expect.objectContaining({ code: 'invalid_type', expected: 'string', path: ['organizationId'] }),
+ ]);
+ });
+
+ it('refuses the empty string — "no organization" is never spelled ""', () => {
+ const result = DataEventSchema.safeParse({ ...base, organizationId: '' });
+ expect(result.success).toBe(false);
+ if (result.success) throw new Error('unreachable');
+ expect(result.error.issues).toEqual([
+ expect.objectContaining({ code: 'too_small', minimum: 1, path: ['organizationId'] }),
+ ]);
+ });
+
+ it('is the only member added — every pre-existing member is still declared', () => {
+ expect(Object.keys(DataEventSchema.shape).sort()).toEqual([
+ 'after', 'before', 'changes', 'id', 'object', 'organizationId', 'recordId', 'timestamp', 'type', 'userId',
+ ]);
+ });
+ });
 });

packages/spec/src/api/events.zod.ts

@@ -215,6 +215,18 @@ export type MetadataEvent = z.input<typeof MetadataEventSchema>;
  *
  * Represents a data record change event (create, update, delete).
  * Used for real-time synchronization of data records across clients.
+ *
+ * **This payload IS the contract a consumer discriminates on.** It travels as
+ * the `payload` of the `RealtimeEventPayload` envelope
+ * (`contracts/realtime-service.ts`), and the envelope is a transport shape —
+ * `type` / `object` / `payload` / `timestamp`, a TypeScript interface no
+ * parse ever validates. Every consumer that must read a per-event fact
+ * already reads it HERE, not on the envelope: the webhook fan-out takes
+ * `recordId` from the payload at its match site, and the client SDK
+ * `safeParse`s the payload against this schema before it delivers anything.
+ * So the tenant term below is a member of this validated payload rather than
+ * a second, unvalidated envelope field: one declaration, enforced at the
+ * publish site by the same `parse` that enforces `recordId`.
  */
 export const DataEventSchema = lazySchema(() => z.object({
  /** Unique event identifier */
@@ -229,6 +241,66 @@ export const DataEventSchema = lazySchema(() => z.object({
  /** Record ID */
  recordId: z.string().describe('Record ID'),
 
+ /**
+ * Organization the record belongs to — its `organization_id` column, under
+ * the camelCase spelling every published payload in this package uses for
+ * the tenant term (`organizationId`, the blessed developer-facing name).
+ *
+ * **Why a first-class member and not a read of the record body.** A
+ * tenant-scoped consumer — the webhook fan-out matching subscriptions to
+ * events, a per-organization realtime subscriber — must discriminate the
+ * event's tenant BEFORE it touches the record: `after` is absent on
+ * `data.record.deleted`, `before` is absent on create, and both are the
+ * unfiltered row body the consumer may not be entitled to read at all. The
+ * match term therefore rides beside `object` and `recordId`, validated
+ * with the rest of the event at the publish site.
+ *
+ * **Absent = the record belongs to no organization.** Two situations, one
+ * meaning:
+ * - a `single`-posture deployment — `postureEnforcesWall(posture)` is
+ * `false` and `postureStampsOrganization(posture)` with it (see
+ * `@objectstack/spec/security`): there is no organization wall and
+ * nothing stamps the column, so EVERY event is organization-less;
+ * - a row that carries no organization under a walled posture (`group` /
+ * `isolated`): an environment-wide row (`organization_id IS NULL`), or a
+ * row of an object that stands outside the wall — `tenancy.enabled:
+ * false` by declaration, or no `organization_id` column at all (the
+ * identity tables).
+ * In both, a consumer may read absence as "not behind any organization
+ * wall" — the reading it already gives an `organization_id IS NULL` row on
+ * the read path. It may NOT read absence as "unknown, resolve it yourself":
+ * either the producer had the organization in hand or the record has none,
+ * and a per-event lookup on the fan-out path is exactly the hot-path read
+ * this member exists to make unnecessary.
+ *
+ * **Present = exactly that organization, never a guess.** It names the
+ * organization the RECORD belongs to — not the caller's active organization
+ * standing in for the row's, which would mislabel an administrator's write
+ * into another organization. It is never fabricated: no `.default()`, and
+ * the empty string is refused, so "no organization" has exactly one
+ * spelling — the key is absent.
+ *
+ * **Optional as a contract fact, not as a transition.** A `single`-posture
+ * deployment stays organization-less for its whole life, so a required key
+ * would either force a fabricated tenant there or leave the engine unable to
+ * publish at all (the publish site `parse`s the event and drops it on
+ * failure). Declared = enforced: this optionality is exactly what validation
+ * enforces, and no consumer tolerates any other shape. The producer
+ * obligation is the other half of the same contract: a producer that omits
+ * the key on an organization-stamped row publishes a cross-tenant event,
+ * which is fixed at the publish site — never by a consumer-side lookup.
+ */
+ organizationId: z.string().min(1).optional().describe(
+ 'Organization the record belongs to (its organization_id), so a tenant-scoped '
+ + 'consumer can discriminate the event\'s tenant without reading the record body. '
+ + 'Absent when the record belongs to no organization: every event on a single-posture '
+ + 'deployment (no organization wall, nothing stamps the column), and a row that '
+ + 'carries no organization under a walled posture (environment-wide, or an object '
+ + 'outside the wall) — read absence as '
+ + '"not behind any organization wall", never as "unknown". Present = exactly that '
+ + 'organization; never fabricated, and the empty string is refused.',
+ ),
+
  /** Changed fields (update events only) */
  changes: z.record(z.string(), z.unknown()).optional().describe('Changed fields'),
 

.changeset/data-event-organization-id.md

@@ -0,0 +1,34 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): `DataEvent` names the organization the record belongs to, so a tenant-scoped consumer can tell whose event it is
+
+The realtime `DataEvent` payload (`@objectstack/spec/api`, the body of every
+`data.record.created` / `data.record.updated` / `data.record.deleted` event)
+gains an optional `organizationId`: the organization the record belongs to.
+Until now the event carried the object name, the record id and the row body,
+and nothing that named the tenant — so a consumer that fans events out per
+organization (a webhook subscription, a per-organization realtime subscriber)
+had no term to discriminate on short of reading the row body, which is absent
+on delete events and is not the consumer's to read.
+
+What a consumer may assume:
+
+- **Present** — exactly that organization, never a guess: the organization the
+ record belongs to, not the caller's active organization standing in for it.
+- **Absent** — the record belongs to no organization. That is every event on a
+ `single`-posture deployment (no organization wall, nothing stamps the
+ column) and an organization-less, environment-wide row under a walled
+ posture. Read it as "not behind any organization wall", never as "unknown,
+ look it up".
+
+Declared = enforced: the key is optional and nothing else. No default
+fabricates a tenant; `null` and the empty string are refused with a located
+issue, so "no organization" has exactly one spelling — the key is absent.
+
+Additive and shape-preserving: every event that parsed before parses
+identically, and no producer emits the key yet — the ObjectQL engine's publish
+site is a separate change that follows this contract. The bulk
+`BulkDataEvent` (`data.records.*`) is deliberately untouched: a predicate
+write's affected set is its own contract with its own tenant question.

content/docs/references/api/events.mdx

@@ -57,6 +57,7 @@ const result = BulkDataEventSchema.parse(data);
 | **type** | `Enum<'data.record.created' \| 'data.record.updated' \| 'data.record.deleted'>` | ✅ | Event type |
 | **object** | `string` | ✅ | Object name |
 | **recordId** | `string` | ✅ | Record ID |
+| **organizationId** | `string` | optional | Organization the record belongs to (its organization_id), so a tenant-scoped consumer can discriminate the event's tenant without reading the record body. Absent when the record belongs to no organization: every event on a single-posture deployment (no organization wall, nothing stamps the column), and a row that carries no organization under a walled posture (environment-wide, or an object outside the wall) — read absence as "not behind any organization wall", never as "unknown". Present = exactly that organization; never fabricated, and the empty string is refused. |
 | **changes** | `Record<string, any>` | optional | Changed fields |
 | **before** | `Record<string, any>` | optional | Before state |
 | **after** | `Record<string, any>` | optional | After state |

packages/spec/authorable-surface/api.json

@@ -442,6 +442,7 @@
  "api/DataEvent:changes",
  "api/DataEvent:id",
  "api/DataEvent:object",
+ "api/DataEvent:organizationId",
  "api/DataEvent:recordId",
  "api/DataEvent:timestamp",
  "api/DataEvent:type",

packages/spec/src/api/events.test.ts

@@ -239,4 +239,67 @@ describe('DataEventSchema', () => {
  expect(event.before).toEqual({ name: 'Old Name' });
  expect(event.after).toEqual({ name: 'New Name' });
  });
+
+ // The tenant term — the contract half of closing the webhook fan-out's
+ // cross-organization delivery. Both directions are pinned so
+ // "declared = enforced" is a measurement rather than a sentence: the key is
+ // optional and NOTHING else — no default fabricates a tenant, absence has
+ // exactly one spelling, and a value that is not a non-empty string is
+ // refused at the path a producer can act on. `BulkDataEventSchema` is
+ // deliberately untouched here: a predicate write's affected set is a
+ // separate contract with its own tenant question (recorded on the change
+ // that adds this member), so nothing below pins that schema either way.
+ describe('organizationId', () => {
+ const base = {
+ id: '4b4720e8-97c3-4a12-9b70-b70a3d2314a6',
+ type: 'data.record.created',
+ object: 'account',
+ recordId: 'rec_1',
+ timestamp: '2026-09-02T00:00:00.000Z',
+ } as const;
+
+ it('parses without the key and does not fabricate one (single posture: no wall, no organization)', () => {
+ const event = DataEventSchema.parse(base);
+ expect(Object.prototype.hasOwnProperty.call(event, 'organizationId')).toBe(false);
+ expect(event.organizationId).toBeUndefined();
+ });
+
+ it('parses with the key and carries it through verbatim', () => {
+ const event = DataEventSchema.parse({ ...base, organizationId: 'org_jia' });
+ expect(event.organizationId).toBe('org_jia');
+ });
+
+ it('refuses a non-string value with invalid_type at ["organizationId"]', () => {
+ const result = DataEventSchema.safeParse({ ...base, organizationId: 42 });
+ expect(result.success).toBe(false);
+ if (result.success) throw new Error('unreachable');
+ expect(result.error.issues).toEqual([
+ expect.objectContaining({ code: 'invalid_type', expected: 'string', path: ['organizationId'] }),
+ ]);
+ });
+
+ it('refuses null — absence has exactly one spelling, the missing key', () => {
+ const result = DataEventSchema.safeParse({ ...base, organizationId: null });
+ expect(result.success).toBe(false);
+ if (result.success) throw new Error('unreachable');
+ expect(result.error.issues).toEqual([
+ expect.objectContaining({ code: 'invalid_type', expected: 'string', path: ['organizationId'] }),
+ ]);
+ });
+
+ it('refuses the empty string — "no organization" is never spelled ""', () => {
+ const result = DataEventSchema.safeParse({ ...base, organizationId: '' });
+ expect(result.success).toBe(false);
+ if (result.success) throw new Error('unreachable');
+ expect(result.error.issues).toEqual([
+ expect.objectContaining({ code: 'too_small', minimum: 1, path: ['organizationId'] }),
+ ]);
+ });
+
+ it('is the only member added — every pre-existing member is still declared', () => {
+ expect(Object.keys(DataEventSchema.shape).sort()).toEqual([
+ 'after', 'before', 'changes', 'id', 'object', 'organizationId', 'recordId', 'timestamp', 'type', 'userId',
+ ]);
+ });
+ });
 });

packages/spec/src/api/events.zod.ts

@@ -215,6 +215,18 @@ export type MetadataEvent = z.input<typeof MetadataEventSchema>;
  *
  * Represents a data record change event (create, update, delete).
  * Used for real-time synchronization of data records across clients.
+ *
+ * **This payload IS the contract a consumer discriminates on.** It travels as
+ * the `payload` of the `RealtimeEventPayload` envelope
+ * (`contracts/realtime-service.ts`), and the envelope is a transport shape —
+ * `type` / `object` / `payload` / `timestamp`, a TypeScript interface no
+ * parse ever validates. Every consumer that must read a per-event fact
+ * already reads it HERE, not on the envelope: the webhook fan-out takes
+ * `recordId` from the payload at its match site, and the client SDK
+ * `safeParse`s the payload against this schema before it delivers anything.
+ * So the tenant term below is a member of this validated payload rather than
+ * a second, unvalidated envelope field: one declaration, enforced at the
+ * publish site by the same `parse` that enforces `recordId`.
  */
 export const DataEventSchema = lazySchema(() => z.object({
  /** Unique event identifier */
@@ -229,6 +241,66 @@ export const DataEventSchema = lazySchema(() => z.object({
  /** Record ID */
  recordId: z.string().describe('Record ID'),
 
+ /**
+ * Organization the record belongs to — its `organization_id` column, under
+ * the camelCase spelling every published payload in this package uses for
+ * the tenant term (`organizationId`, the blessed developer-facing name).
+ *
+ * **Why a first-class member and not a read of the record body.** A
+ * tenant-scoped consumer — the webhook fan-out matching subscriptions to
+ * events, a per-organization realtime subscriber — must discriminate the
+ * event's tenant BEFORE it touches the record: `after` is absent on
+ * `data.record.deleted`, `before` is absent on create, and both are the
+ * unfiltered row body the consumer may not be entitled to read at all. The
+ * match term therefore rides beside `object` and `recordId`, validated
+ * with the rest of the event at the publish site.
+ *
+ * **Absent = the record belongs to no organization.** Two situations, one
+ * meaning:
+ * - a `single`-posture deployment — `postureEnforcesWall(posture)` is
+ * `false` and `postureStampsOrganization(posture)` with it (see
+ * `@objectstack/spec/security`): there is no organization wall and
+ * nothing stamps the column, so EVERY event is organization-less;
+ * - a row that carries no organization under a walled posture (`group` /
+ * `isolated`): an environment-wide row (`organization_id IS NULL`), or a
+ * row of an object that stands outside the wall — `tenancy.enabled:
+ * false` by declaration, or no `organization_id` column at all (the
+ * identity tables).
+ * In both, a consumer may read absence as "not behind any organization
+ * wall" — the reading it already gives an `organization_id IS NULL` row on
+ * the read path. It may NOT read absence as "unknown, resolve it yourself":
+ * either the producer had the organization in hand or the record has none,
+ * and a per-event lookup on the fan-out path is exactly the hot-path read
+ * this member exists to make unnecessary.
+ *
+ * **Present = exactly that organization, never a guess.** It names the
+ * organization the RECORD belongs to — not the caller's active organization
+ * standing in for the row's, which would mislabel an administrator's write
+ * into another organization. It is never fabricated: no `.default()`, and
+ * the empty string is refused, so "no organization" has exactly one
+ * spelling — the key is absent.
+ *
+ * **Optional as a contract fact, not as a transition.** A `single`-posture
+ * deployment stays organization-less for its whole life, so a required key
+ * would either force a fabricated tenant there or leave the engine unable to
+ * publish at all (the publish site `parse`s the event and drops it on
+ * failure). Declared = enforced: this optionality is exactly what validation
+ * enforces, and no consumer tolerates any other shape. The producer
+ * obligation is the other half of the same contract: a producer that omits
+ * the key on an organization-stamped row publishes a cross-tenant event,
+ * which is fixed at the publish site — never by a consumer-side lookup.
+ */
+ organizationId: z.string().min(1).optional().describe(
+ 'Organization the record belongs to (its organization_id), so a tenant-scoped '
+ + 'consumer can discriminate the event\'s tenant without reading the record body. '
+ + 'Absent when the record belongs to no organization: every event on a single-posture '
+ + 'deployment (no organization wall, nothing stamps the column), and a row that '
+ + 'carries no organization under a walled posture (environment-wide, or an object '
+ + 'outside the wall) — read absence as '
+ + '"not behind any organization wall", never as "unknown". Present = exactly that '
+ + 'organization; never fabricated, and the empty string is refused.',
+ ),
+
  /** Changed fields (update events only) */
  changes: z.record(z.string(), z.unknown()).optional().describe('Changed fields'),
 

.changeset/data-event-organization-id.md

@@ -0,0 +1,34 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): `DataEvent` names the organization the record belongs to, so a tenant-scoped consumer can tell whose event it is
+
+The realtime `DataEvent` payload (`@objectstack/spec/api`, the body of every
+`data.record.created` / `data.record.updated` / `data.record.deleted` event)
+gains an optional `organizationId`: the organization the record belongs to.
+Until now the event carried the object name, the record id and the row body,
+and nothing that named the tenant — so a consumer that fans events out per
+organization (a webhook subscription, a per-organization realtime subscriber)
+had no term to discriminate on short of reading the row body, which is absent
+on delete events and is not the consumer's to read.
+
+What a consumer may assume:
+
+- **Present** — exactly that organization, never a guess: the organization the
+ record belongs to, not the caller's active organization standing in for it.
+- **Absent** — the record belongs to no organization. That is every event on a
+ `single`-posture deployment (no organization wall, nothing stamps the
+ column) and an organization-less, environment-wide row under a walled
+ posture. Read it as "not behind any organization wall", never as "unknown,
+ look it up".
+
+Declared = enforced: the key is optional and nothing else. No default
+fabricates a tenant; `null` and the empty string are refused with a located
+issue, so "no organization" has exactly one spelling — the key is absent.
+
+Additive and shape-preserving: every event that parsed before parses
+identically, and no producer emits the key yet — the ObjectQL engine's publish
+site is a separate change that follows this contract. The bulk
+`BulkDataEvent` (`data.records.*`) is deliberately untouched: a predicate
+write's affected set is its own contract with its own tenant question.

content/docs/references/api/events.mdx

@@ -57,6 +57,7 @@ const result = BulkDataEventSchema.parse(data);
 | **type** | `Enum<'data.record.created' \| 'data.record.updated' \| 'data.record.deleted'>` | ✅ | Event type |
 | **object** | `string` | ✅ | Object name |
 | **recordId** | `string` | ✅ | Record ID |
+| **organizationId** | `string` | optional | Organization the record belongs to (its organization_id), so a tenant-scoped consumer can discriminate the event's tenant without reading the record body. Absent when the record belongs to no organization: every event on a single-posture deployment (no organization wall, nothing stamps the column), and a row that carries no organization under a walled posture (environment-wide, or an object outside the wall) — read absence as "not behind any organization wall", never as "unknown". Present = exactly that organization; never fabricated, and the empty string is refused. |
 | **changes** | `Record<string, any>` | optional | Changed fields |
 | **before** | `Record<string, any>` | optional | Before state |
 | **after** | `Record<string, any>` | optional | After state |

packages/spec/authorable-surface/api.json

@@ -442,6 +442,7 @@
  "api/DataEvent:changes",
  "api/DataEvent:id",
  "api/DataEvent:object",
+ "api/DataEvent:organizationId",
  "api/DataEvent:recordId",
  "api/DataEvent:timestamp",
  "api/DataEvent:type",

packages/spec/src/api/events.test.ts

@@ -239,4 +239,67 @@ describe('DataEventSchema', () => {
  expect(event.before).toEqual({ name: 'Old Name' });
  expect(event.after).toEqual({ name: 'New Name' });
  });
+
+ // The tenant term — the contract half of closing the webhook fan-out's
+ // cross-organization delivery. Both directions are pinned so
+ // "declared = enforced" is a measurement rather than a sentence: the key is
+ // optional and NOTHING else — no default fabricates a tenant, absence has
+ // exactly one spelling, and a value that is not a non-empty string is
+ // refused at the path a producer can act on. `BulkDataEventSchema` is
+ // deliberately untouched here: a predicate write's affected set is a
+ // separate contract with its own tenant question (recorded on the change
+ // that adds this member), so nothing below pins that schema either way.
+ describe('organizationId', () => {
+ const base = {
+ id: '4b4720e8-97c3-4a12-9b70-b70a3d2314a6',
+ type: 'data.record.created',
+ object: 'account',
+ recordId: 'rec_1',
+ timestamp: '2026-09-02T00:00:00.000Z',
+ } as const;
+
+ it('parses without the key and does not fabricate one (single posture: no wall, no organization)', () => {
+ const event = DataEventSchema.parse(base);
+ expect(Object.prototype.hasOwnProperty.call(event, 'organizationId')).toBe(false);
+ expect(event.organizationId).toBeUndefined();
+ });
+
+ it('parses with the key and carries it through verbatim', () => {
+ const event = DataEventSchema.parse({ ...base, organizationId: 'org_jia' });
+ expect(event.organizationId).toBe('org_jia');
+ });
+
+ it('refuses a non-string value with invalid_type at ["organizationId"]', () => {
+ const result = DataEventSchema.safeParse({ ...base, organizationId: 42 });
+ expect(result.success).toBe(false);
+ if (result.success) throw new Error('unreachable');
+ expect(result.error.issues).toEqual([
+ expect.objectContaining({ code: 'invalid_type', expected: 'string', path: ['organizationId'] }),
+ ]);
+ });
+
+ it('refuses null — absence has exactly one spelling, the missing key', () => {
+ const result = DataEventSchema.safeParse({ ...base, organizationId: null });
+ expect(result.success).toBe(false);
+ if (result.success) throw new Error('unreachable');
+ expect(result.error.issues).toEqual([
+ expect.objectContaining({ code: 'invalid_type', expected: 'string', path: ['organizationId'] }),
+ ]);
+ });
+
+ it('refuses the empty string — "no organization" is never spelled ""', () => {
+ const result = DataEventSchema.safeParse({ ...base, organizationId: '' });
+ expect(result.success).toBe(false);
+ if (result.success) throw new Error('unreachable');
+ expect(result.error.issues).toEqual([
+ expect.objectContaining({ code: 'too_small', minimum: 1, path: ['organizationId'] }),
+ ]);
+ });
+
+ it('is the only member added — every pre-existing member is still declared', () => {
+ expect(Object.keys(DataEventSchema.shape).sort()).toEqual([
+ 'after', 'before', 'changes', 'id', 'object', 'organizationId', 'recordId', 'timestamp', 'type', 'userId',
+ ]);
+ });
+ });
 });

packages/spec/src/api/events.zod.ts

@@ -215,6 +215,18 @@ export type MetadataEvent = z.input<typeof MetadataEventSchema>;
  *
  * Represents a data record change event (create, update, delete).
  * Used for real-time synchronization of data records across clients.
+ *
+ * **This payload IS the contract a consumer discriminates on.** It travels as
+ * the `payload` of the `RealtimeEventPayload` envelope
+ * (`contracts/realtime-service.ts`), and the envelope is a transport shape —
+ * `type` / `object` / `payload` / `timestamp`, a TypeScript interface no
+ * parse ever validates. Every consumer that must read a per-event fact
+ * already reads it HERE, not on the envelope: the webhook fan-out takes
+ * `recordId` from the payload at its match site, and the client SDK
+ * `safeParse`s the payload against this schema before it delivers anything.
+ * So the tenant term below is a member of this validated payload rather than
+ * a second, unvalidated envelope field: one declaration, enforced at the
+ * publish site by the same `parse` that enforces `recordId`.
  */
 export const DataEventSchema = lazySchema(() => z.object({
  /** Unique event identifier */
@@ -229,6 +241,66 @@ export const DataEventSchema = lazySchema(() => z.object({
  /** Record ID */
  recordId: z.string().describe('Record ID'),
 
+ /**
+ * Organization the record belongs to — its `organization_id` column, under
+ * the camelCase spelling every published payload in this package uses for
+ * the tenant term (`organizationId`, the blessed developer-facing name).
+ *
+ * **Why a first-class member and not a read of the record body.** A
+ * tenant-scoped consumer — the webhook fan-out matching subscriptions to
+ * events, a per-organization realtime subscriber — must discriminate the
+ * event's tenant BEFORE it touches the record: `after` is absent on
+ * `data.record.deleted`, `before` is absent on create, and both are the
+ * unfiltered row body the consumer may not be entitled to read at all. The
+ * match term therefore rides beside `object` and `recordId`, validated
+ * with the rest of the event at the publish site.
+ *
+ * **Absent = the record belongs to no organization.** Two situations, one
+ * meaning:
+ * - a `single`-posture deployment — `postureEnforcesWall(posture)` is
+ * `false` and `postureStampsOrganization(posture)` with it (see
+ * `@objectstack/spec/security`): there is no organization wall and
+ * nothing stamps the column, so EVERY event is organization-less;
+ * - a row that carries no organization under a walled posture (`group` /
+ * `isolated`): an environment-wide row (`organization_id IS NULL`), or a
+ * row of an object that stands outside the wall — `tenancy.enabled:
+ * false` by declaration, or no `organization_id` column at all (the
+ * identity tables).
+ * In both, a consumer may read absence as "not behind any organization
+ * wall" — the reading it already gives an `organization_id IS NULL` row on
+ * the read path. It may NOT read absence as "unknown, resolve it yourself":
+ * either the producer had the organization in hand or the record has none,
+ * and a per-event lookup on the fan-out path is exactly the hot-path read
+ * this member exists to make unnecessary.
+ *
+ * **Present = exactly that organization, never a guess.** It names the
+ * organization the RECORD belongs to — not the caller's active organization
+ * standing in for the row's, which would mislabel an administrator's write
+ * into another organization. It is never fabricated: no `.default()`, and
+ * the empty string is refused, so "no organization" has exactly one
+ * spelling — the key is absent.
+ *
+ * **Optional as a contract fact, not as a transition.** A `single`-posture
+ * deployment stays organization-less for its whole life, so a required key
+ * would either force a fabricated tenant there or leave the engine unable to
+ * publish at all (the publish site `parse`s the event and drops it on
+ * failure). Declared = enforced: this optionality is exactly what validation
+ * enforces, and no consumer tolerates any other shape. The producer
+ * obligation is the other half of the same contract: a producer that omits
+ * the key on an organization-stamped row publishes a cross-tenant event,
+ * which is fixed at the publish site — never by a consumer-side lookup.
+ */
+ organizationId: z.string().min(1).optional().describe(
+ 'Organization the record belongs to (its organization_id), so a tenant-scoped '
+ + 'consumer can discriminate the event\'s tenant without reading the record body. '
+ + 'Absent when the record belongs to no organization: every event on a single-posture '
+ + 'deployment (no organization wall, nothing stamps the column), and a row that '
+ + 'carries no organization under a walled posture (environment-wide, or an object '
+ + 'outside the wall) — read absence as '
+ + '"not behind any organization wall", never as "unknown". Present = exactly that '
+ + 'organization; never fabricated, and the empty string is refused.',
+ ),
+
  /** Changed fields (update events only) */
  changes: z.record(z.string(), z.unknown()).optional().describe('Changed fields'),