@cosmicdrift/kumiko-framework 0.266.0 → 0.269.0

package/src/db/__tests__/tenant-db-global.test.ts

@@ -2,11 +2,18 @@ import { describe, expect, test } from "bun:test";
 import type { EntityTableMeta } from "@cosmicdrift/kumiko-types/entity-table-meta-types";
 import type { TenancyBrand } from "@cosmicdrift/kumiko-types/tenancy-brand";
 import { createEntity, createTextField } from "../../engine";
+import { AccessDeniedError } from "../../errors";
 import { testTenantId } from "../../stack";
 import type { DbRunner } from "../connection";
+import type { TableColumns } from "../dialect";
 import { defineUnmanagedTable, deriveEntityTableMeta } from "../entity-table-meta";
 import { buildEntityTable } from "../table-builder";
-import { createTenantDb, createUncheckedSystemDb, type TenantDb } from "../tenant-db";
+import {
+  createTenantDb,
+  createUncheckedSystemDb,
+  type TenantDb,
+  withUnsafeRawGrant,
+} from "../tenant-db";
 
 // db.global()'s runtime + write-gate behaviour (fw#2855). No Postgres needed —
 // the stub runner throws on first touch, so a test that reaches it fails loudly
@@ -125,9 +132,7 @@ describe("TenantDb.global()", () => {
       undefined,
       undefined,
       undefined,
-      {
-        reason: "   ",
-      },
+      { globalWrites: { reason: "   " } },
     );
     await expect(tdb.global(globalUnmanagedTable).insertOne({ name: "x" })).rejects.toThrow(
       /escapeHatch/,
@@ -146,11 +151,96 @@ describe("TenantDb.global()", () => {
       },
     } as DbRunner;
     const tdb = createTenantDb(db, own, "tenant", undefined, undefined, undefined, {
-      reason: "cross-tenant backfill job",
+      globalWrites: { reason: "cross-tenant backfill job" },
     });
     await tdb.global(globalUnmanagedTable).insertOne({ name: "x" });
     expect(captured).toHaveLength(1);
   });
+
+  test("write with an explicit non-SYSTEM tenantId rejects even with a valid escapeHatch", async () => {
+    const tdb = createTenantDb(
+      unreachableRunner(),
+      own,
+      "tenant",
+      undefined,
+      undefined,
+      undefined,
+      {
+        globalWrites: { reason: "cross-tenant backfill job" },
+      },
+    );
+    await expect(
+      tdb.global(globalUnmanagedTable).insertOne({ name: "x", tenantId: own }),
+    ).rejects.toThrow(/SYSTEM/);
+  });
+
+  test("plain (non-global) insertOne on a global-tenancy managed table (has tenant_id) with a foreign tenant rejects before touching the runner", async () => {
+    const tdb = createTenantDb(unreachableRunner(), own);
+    // insertOne's WritableTable param types out branded EntityTables — same
+    // unbranded-view cast as tenant-db-global.integration.test.ts; runtime
+    // behavior only reads the table's EntityTableMeta, not the type brand.
+    await expect(
+      tdb.insertOne(globalManagedTable as unknown as TableColumns, { name: "x" }),
+    ).rejects.toThrow(/SYSTEM/);
+  });
+});
+
+describe("TenantDb.unsafeRaw()", () => {
+  test("without a grant throws AccessDeniedError without touching the runner", () => {
+    const tdb = createTenantDb(unreachableRunner(), own);
+    expect(() => tdb.unsafeRaw("some reason")).toThrow(AccessDeniedError);
+  });
+
+  test("an empty reason throws regardless of grant", () => {
+    const tdb = createTenantDb(
+      unreachableRunner(),
+      own,
+      "tenant",
+      undefined,
+      undefined,
+      undefined,
+      {
+        unsafeRaw: { reason: "granted" },
+      },
+    );
+    expect(() => tdb.unsafeRaw("")).toThrow();
+    expect(() => tdb.unsafeRaw("   ")).toThrow();
+  });
+
+  test("with a valid grant returns the underlying DbRunner", () => {
+    const rawDb = unreachableRunner();
+    const tdb = createTenantDb(rawDb, own, "tenant", undefined, undefined, undefined, {
+      unsafeRaw: { reason: "granted" },
+    });
+    expect(tdb.unsafeRaw("some reason")).toBe(rawDb);
+  });
+});
+
+describe("withUnsafeRawGrant", () => {
+  test("rebinding to a grant makes unsafeRaw work", () => {
+    const rawDb = unreachableRunner();
+    const tdb = createTenantDb(rawDb, own);
+    expect(() => tdb.unsafeRaw("x")).toThrow(AccessDeniedError);
+
+    const rebound = withUnsafeRawGrant(tdb, { reason: "narrower hook grant" });
+    expect(rebound.unsafeRaw("x")).toBe(rawDb);
+  });
+
+  test("rebinding to undefined makes unsafeRaw throw, even if the original had a grant", () => {
+    const rawDb = unreachableRunner();
+    const tdb = createTenantDb(rawDb, own, "tenant", undefined, undefined, undefined, {
+      unsafeRaw: { reason: "handler grant" },
+    });
+    expect(tdb.unsafeRaw("x")).toBe(rawDb);
+
+    const rebound = withUnsafeRawGrant(tdb, undefined);
+    expect(() => rebound.unsafeRaw("x")).toThrow(AccessDeniedError);
+  });
+
+  test("passes an object not built by createTenantDb through unchanged", () => {
+    const notATenantDb = { some: "stub" } as unknown as TenantDb;
+    expect(withUnsafeRawGrant(notATenantDb, { reason: "x" })).toBe(notATenantDb);
+  });
 });
 
 describe("UncheckedSystemDb.unsafeRaw", () => {

package/src/db/entity-table-meta.ts

@@ -459,6 +459,13 @@ export function defineUnmanagedTable<const T extends EntityTenancy = "tenant">(
   input: UnmanagedTableInput & { readonly tenancy?: T },
 ): EntityTableMeta & TenancyBrand<T> {
   assertUnmanagedTableName(input.tableName, "defineUnmanagedTable");
+  if (input.tenancy === "global" && input.columns.some((c) => c.name === "tenant_id")) {
+    throw new Error(
+      `defineUnmanagedTable("${input.tableName}"): tenancy: "global" unmanaged tables must not ` +
+        "have a tenant_id column — a global table's rows carry the system tenant, not a per-row " +
+        "tenant identity.",
+    );
+  }
   return {
     tableName: input.tableName,
     columns: input.columns,

package/src/db/event-store-executor-context.ts

@@ -80,6 +80,16 @@ export function buildFilterWhere(
 // doesn't carry a default or no default was declared. Only scalar types
 // (text/number/boolean/select) support creation-time defaults — money/date/
 // file/embedded fields don't.
+// A "global" entity's stream must live on SYSTEM_TENANT_ID — otherwise the
+// projection row and event stream would disagree on which tenant "owns" it.
+export function isForeignTenantOnGlobalEntity(
+  entity: EntityDefinition,
+  tenantIdValue: unknown,
+): boolean {
+  if (entity.tenancy !== "global") return false;
+  return tenantIdValue !== undefined && tenantIdValue !== SYSTEM_TENANT_ID;
+}
+
 function scalarDefault(field: FieldDefinition): unknown {
   switch (field.type) {
     case "text":
@@ -180,6 +190,15 @@ export function buildExecutorContext(
   const { searchAdapter, entityName, entityCache } = options;
   const softDelete = entity.softDelete ?? false;
 
+  // Without systemStream: true, a "global" entity would silently fork one event stream per creating tenant.
+  if (entity.tenancy === "global" && entity.systemStream !== true) {
+    throw new Error(
+      `event-store-executor requires entity "${entityName}" to declare systemStream: true ` +
+        'when tenancy: "global" is set — a global entity\'s event stream must live on the ' +
+        "system tenant, not the creating tenant's.",
+    );
+  }
+
   // Stream-tenant choke-point. A systemStream entity (tenant-independent, e.g.
   // user) lives on SYSTEM_TENANT_ID deterministically — every op addresses it
   // there. Everything else stays on the caller's tenant (byte-identical to the

package/src/db/event-store-executor-write.ts

@@ -3,6 +3,7 @@ import { userCanCreateFieldRow, userCanWriteFieldRow } from "../engine/ownership
 import { SYSTEM_ROLE, SYSTEM_USER_ID } from "../engine/system-user";
 import type { EntityId, SessionUser } from "../engine/types";
 import {
+  AccessDeniedError,
   VersionConflictError as FrameworkVersionConflict,
   IdempotentReplayError,
   InternalError,
@@ -25,6 +26,7 @@ import {
   buildEventMetadata,
   type ExecutorContext,
   entityEventName,
+  isForeignTenantOnGlobalEntity,
   tryMapUniqueViolation,
 } from "./event-store-executor-context";
 import { runInSavepointIfSupported } from "./query";
@@ -115,6 +117,13 @@ export function createWriteVerbs(
 
   return {
     async create(payload, user, db, options) {
+      if (isForeignTenantOnGlobalEntity(entity, payload["tenantId"])) {
+        throw new AccessDeniedError({
+          message:
+            `${entityName}.create: entity is tenancy: "global" — payload.tenantId must be ` +
+            "SYSTEM_TENANT_ID or omitted.",
+        });
+      }
       // Respect an explicit id in the payload (seed pattern, SCIM import). Without
       // one the framework mints a fresh UUIDv7 via generateId. Strip it out of the
       // event payload so defaults + downstream consumers don't see a redundant id field.
@@ -299,6 +308,13 @@ export function createWriteVerbs(
     },
 
     async update(payload, user, db, updateOptions) {
+      if (isForeignTenantOnGlobalEntity(entity, payload.changes["tenantId"])) {
+        throw new AccessDeniedError({
+          message:
+            `${entityName}.update: entity is tenancy: "global" — payload.changes.tenantId must ` +
+            "be SYSTEM_TENANT_ID or omitted.",
+        });
+      }
       const previous = await loadById(payload.id, db);
       if (!previous) return writeFailure(new NotFoundError(entityName, payload.id));
 

package/src/db/index.ts

@@ -146,14 +146,16 @@ export { tableExists } from "./schema-inspection";
 export {
   buildBaseColumns,
   buildEntityTable,
+  declareGlobalTenancy,
   type EntityTable,
   toSnakeCase,
   toTableName,
 } from "./table-builder";
-export type { TenantDb, TenantDbMode, UncheckedSystemDb } from "./tenant-db";
+export type { TenantDb, TenantDbGrants, TenantDbMode, UncheckedSystemDb } from "./tenant-db";
 export {
   castTenantRows,
   createTenantDb,
   createUncheckedSystemDb,
   SYSTEM_SCOPE_CHECK_BRAND,
+  withUnsafeRawGrant,
 } from "./tenant-db";

package/src/db/table-builder.ts

@@ -29,6 +29,7 @@ import {
   moneyAmount,
   table as pgTable,
   plainDate,
+  type SchemaTable,
   SQL_EXPR_BRAND,
   type SqlExpression,
   serial,
@@ -505,6 +506,32 @@ function stampGlobalTenancyMeta<E extends EntityDefinition>(
   };
 }
 
+/**
+ * Stamps `tenancy: "global"` onto a `table()`/SchemaTable's meta in place.
+ * Throws if the table has a `tenant_id` column or no EntityTableMeta to stamp.
+ */
+export function declareGlobalTenancy<T extends SchemaTable>(table: T): T & TenancyBrand<"global"> {
+  const meta = (table as unknown as Record<symbol, EntityTableMeta | undefined>)[
+    KUMIKO_META_SYMBOL
+  ];
+  if (!meta) {
+    throw new Error("declareGlobalTenancy(): table has no EntityTableMeta to stamp.");
+  }
+  if (meta.columns.some((c) => c.name === "tenant_id")) {
+    throw new Error(
+      `declareGlobalTenancy("${meta.tableName}"): tables with a "tenant_id" column cannot be ` +
+        'declared tenancy: "global" — a global table\'s rows carry the system tenant, not a ' +
+        "per-row tenant identity.",
+    );
+  }
+  (table as unknown as Record<symbol, EntityTableMeta>)[KUMIKO_META_SYMBOL] = {
+    ...meta,
+    tenancy: "global",
+  };
+  // @cast-boundary type-brand — TenancyBrand<"global"> is a phantom marker with no runtime representation.
+  return table as T & TenancyBrand<"global">;
+}
+
 export function buildEntityTable<E extends EntityDefinition>(
   entityName: string,
   entity: E,

package/src/db/tenant-db.ts

@@ -137,17 +137,48 @@ function tableNameOf(table: Table | EntityTableMeta): string {
   return asEntityTableMeta(table)?.tableName ?? "<unknown>";
 }
 
+// A grant is only real when its reason is non-empty — `{ reason: "" }` must not silently unlock it.
+function hasGrant(decl: EscapeHatchDeclaration | undefined): boolean {
+  return decl !== undefined && decl.reason.trim().length > 0;
+}
+
+function isForeignTenantId(tenantIdValue: unknown): boolean {
+  return tenantIdValue !== undefined && tenantIdValue !== SYSTEM_TENANT_ID;
+}
+
 // Checks the canonical EntityTableMeta (branded EntityTable's KUMIKO_META_SYMBOL
 // or a plain deriveEntityTableMeta/defineUnmanagedTable result), not a direct
 // `table.tenantId` property read — the latter only exists on branded EntityTables
 // and silently returned false (no tenant filter!) for plain EntityTableMeta
 // tables like unmanaged direct-write stores, e.g. userSessionTable.
-function hasTenantColumn(table: Table): boolean {
+function hasTenantColumn(table: Table | EntityTableMeta): boolean {
   const meta = asEntityTableMeta(table);
   if (meta) return meta.columns.some((c) => c.name === "tenant_id");
   return (table as Record<string, unknown>)["tenantId"] !== undefined;
 }
 
+// Grants for TenantDb's two escape hatches: db.global()'s write methods
+// (write-handler-only) and ctx.db.unsafeRaw() (handler or hook, re-granted per hook).
+export type TenantDbGrants = {
+  readonly globalWrites?: EscapeHatchDeclaration;
+  readonly unsafeRaw?: EscapeHatchDeclaration;
+};
+
+const unsafeRawRebinders = new WeakMap<
+  TenantDb,
+  (grant: EscapeHatchDeclaration | undefined) => TenantDb
+>();
+
+// Rebinds tenantDb's unsafeRaw grant (e.g. a hook's own escapeHatch); inputs not built by
+// createTenantDb pass through unchanged, without touching any property (ctx.db may be a throwing Proxy).
+export function withUnsafeRawGrant(
+  tenantDb: TenantDb,
+  grant: EscapeHatchDeclaration | undefined,
+): TenantDb {
+  const rebind = unsafeRawRebinders.get(tenantDb);
+  return rebind ? rebind(grant) : tenantDb;
+}
+
 export function createTenantDb(
   db: DbRunner,
   tenantId: TenantId,
@@ -155,8 +186,7 @@ export function createTenantDb(
   tracer?: Tracer,
   meter?: Meter,
   signal?: AbortSignal,
-  // Gates db.global(table)'s write methods; write-path-only (see dispatch-shared.ts buildHandlerContext).
-  escapeHatch?: EscapeHatchDeclaration,
+  grants?: TenantDbGrants,
 ): TenantDb {
   if (meter) registerStandardMetrics(meter);
 
@@ -215,7 +245,7 @@ export function createTenantDb(
   // (e.g. exclude SYSTEM reference rows at the DB instead of post-filtering
   // after a limit). Values outside the scope are dropped; if nothing valid
   // remains, the full enforced scope applies — widening is never possible.
-  function readWhere(table: Table, where?: WhereObject): WhereObject | undefined {
+  function readWhere(table: Table | EntityTableMeta, where?: WhereObject): WhereObject | undefined {
     if (!hasTenantColumn(table) || mode === "system") return where;
     const allowed = [tenantId, SYSTEM_TENANT_ID];
     const requested = where?.["tenantId"];
@@ -242,7 +272,7 @@ export function createTenantDb(
   }
 
   function missingEscapeHatch(table: Table | EntityTableMeta): AccessDeniedError | undefined {
-    if (escapeHatch && escapeHatch.reason.trim().length > 0) return undefined;
+    if (hasGrant(grants?.globalWrites)) return undefined;
     return new AccessDeniedError({
       message:
         `db.global(${tableNameOf(table)}): write rejected — declare ` +
@@ -251,6 +281,15 @@ export function createTenantDb(
     });
   }
 
+  function foreignTenantOnGlobalWrite(
+    table: Table | EntityTableMeta,
+    tenantIdValue: unknown,
+    message: string = `db.global(${tableNameOf(table)}): tenantId "${String(tenantIdValue)}" is not SYSTEM_TENANT_ID — a "global" table's rows must carry the system tenant, not an arbitrary tenant's id.`,
+  ): AccessDeniedError | undefined {
+    if (!isForeignTenantId(tenantIdValue)) return undefined;
+    return new AccessDeniedError({ message });
+  }
+
   function globalTable<TTable extends (SchemaTable | EntityTableMeta) & TenancyBrand<"global">>(
     table: TTable,
   ): GlobalTableDb<TTable> {
@@ -273,7 +312,8 @@ export function createTenantDb(
       insertOne<T = Record<string, unknown>>(
         values: Record<string, unknown>,
       ): Promise<T | undefined> {
-        const denied = missingEscapeHatch(table);
+        const denied =
+          missingEscapeHatch(table) ?? foreignTenantOnGlobalWrite(table, values["tenantId"]);
         if (denied) return Promise.reject(denied);
         return withDbSpan("insert", table, async () => bunInsertOne<T>(db, table, values));
       },
@@ -281,7 +321,8 @@ export function createTenantDb(
         set: Record<string, unknown>,
         where: WhereObject,
       ): Promise<readonly T[]> {
-        const denied = missingEscapeHatch(table);
+        const denied =
+          missingEscapeHatch(table) ?? foreignTenantOnGlobalWrite(table, set["tenantId"]);
         if (denied) return Promise.reject(denied);
         if (!where || Object.keys(where).length === 0) {
           return Promise.reject(
@@ -308,14 +349,28 @@ export function createTenantDb(
     } as GlobalTableDb<TTable>;
   }
 
-  return {
+  const tenantDb: TenantDb = {
     tenantId,
     mode,
     raw: db,
     global: globalTable,
 
+    unsafeRaw(reason: string): DbRunner {
+      if (reason.trim().length === 0) {
+        throw new Error("unsafeRaw requires a non-empty reason");
+      }
+      if (!hasGrant(grants?.unsafeRaw)) {
+        throw new AccessDeniedError({
+          message:
+            'ctx.db.unsafeRaw(reason): rejected — declare `escapeHatch: { reason: "..." }` on ' +
+            "the handler or hook to allow unsafeRaw.",
+        });
+      }
+      return db;
+    },
+
     selectMany<T = Record<string, unknown>>(
-      table: Table,
+      table: Table | EntityTableMeta,
       where?: WhereObject,
       options?: SelectOptions,
     ): Promise<readonly T[]> {
@@ -324,7 +379,7 @@ export function createTenantDb(
     },
 
     fetchOne<T = Record<string, unknown>>(
-      table: Table,
+      table: Table | EntityTableMeta,
       where: WhereObject,
     ): Promise<T | undefined> {
       const filter = readWhere(table, where) ?? {};
@@ -335,6 +390,19 @@ export function createTenantDb(
       table: Table,
       values: Record<string, unknown>,
     ): Promise<T | undefined> {
+      if (
+        mode === "tenant" &&
+        hasTenantColumn(table) &&
+        asEntityTableMeta(table)?.tenancy === "global"
+      ) {
+        const denied = foreignTenantOnGlobalWrite(
+          table,
+          tenantId,
+          `insertOne(${tableNameOf(table)}): "global" table rows must carry SYSTEM_TENANT_ID; ` +
+            "use db.global(table) with escapeHatch instead.",
+        );
+        if (denied) return Promise.reject(denied);
+      }
       const data = insertValues(table, values);
       return withDbSpan("insert", table, async () => bunInsertOne<T>(db, table, data));
     },
@@ -367,6 +435,11 @@ export function createTenantDb(
       return withDbSpan("delete", table, async () => bunDeleteMany(db, table, filter));
     },
   };
+
+  unsafeRawRebinders.set(tenantDb, (grant) =>
+    createTenantDb(db, tenantId, mode, tracer, meter, signal, { ...grants, unsafeRaw: grant }),
+  );
+  return tenantDb;
 }
 
 export { asRawClient };

package/src/engine/__tests__/extends-registrar.test.ts

@@ -242,6 +242,7 @@ describe("extendsRegistrar", () => {
     // systemScope) — the extension hook must not inherit this.
     const handlerCtx = createGatedIdentitySwitch(
       'handler "fleet:write:vehicle:create"',
+      undefined,
       true,
       ungated,
     );

package/src/engine/__tests__/hook-identity-switch-grant.test.ts

@@ -34,6 +34,7 @@ describe("r.hook({ allOf }, ...) identity-switch gate", () => {
     // escapeHatch or is systemScope) — the hook must not inherit this.
     const handlerCtx = createGatedIdentitySwitch(
       'handler "test:write:thing:create"',
+      undefined,
       true,
       ungated,
     );
@@ -70,6 +71,7 @@ describe("r.hook({ allOf }, ...) identity-switch gate", () => {
     };
     const handlerCtx = createGatedIdentitySwitch(
       'handler "test:write:thing:create"',
+      undefined,
       false,
       ungated,
     );
@@ -114,7 +116,7 @@ describe("r.hook({ allOf }, ...) identity-switch gate", () => {
     };
     const ungatedResolveActiveMembership = mock(async () => activeResult);
     const handlerCtx = {
-      ...createGatedIdentitySwitch('handler "test:write:thing:create"', true, {
+      ...createGatedIdentitySwitch('handler "test:write:thing:create"', undefined, true, {
         queryAs: mock(async () => "ok") as QueryAsFn,
         writeAs: async () => ({ isSuccess: true as const, data: null }),
       }),
@@ -155,7 +157,7 @@ describe("r.hook({ allOf }, ...) identity-switch gate", () => {
     };
     const ungatedResolveActiveMembership = mock(async () => activeResult);
     const handlerCtx = {
-      ...createGatedIdentitySwitch('handler "test:write:thing:create"', false, {
+      ...createGatedIdentitySwitch('handler "test:write:thing:create"', undefined, false, {
         queryAs: mock(async () => "ok") as QueryAsFn,
         writeAs: async () => ({ isSuccess: true as const, data: null }),
       }),

package/src/engine/active-membership.ts

@@ -10,12 +10,26 @@ import type { TenantId } from "./types/identifiers";
 // with a since-deleted row should not silently treat it as active.
 export type PrincipalStatus = "active" | "blocked" | "unknown";
 
+// Global-roles/timezone/locale snapshot ctx.queryAsMember needs to mint a
+// resolved principal's SessionUser, without exposing its own table.
+export type PrincipalProfile = {
+  readonly globalRoles: readonly string[];
+  readonly timezone?: string;
+  readonly locale?: string;
+};
+
 // Registered via r.useExtension(EXT_PRINCIPAL_STATUS, "user", principalStatusPlugin).
 export type PrincipalStatusPlugin = {
   readonly resolveStatus: (
     userId: string,
     deps: { readonly db: DbConnection },
   ) => Promise<PrincipalStatus>;
+  // Required so a missing provider fails closed (InternalError) instead of
+  // silently minting empty global roles for ctx.queryAsMember.
+  readonly resolveProfile: (
+    userId: string,
+    deps: { readonly db: DbConnection },
+  ) => Promise<PrincipalProfile | null>;
 };
 
 // `null` means the tenant has no lifecycle row (never entered teardown).
@@ -38,7 +52,7 @@ function hasResolveStatusFn(v: unknown): v is { readonly resolveStatus: unknown
 }
 
 export function isPrincipalStatusPlugin(v: unknown): v is PrincipalStatusPlugin {
-  return hasResolveStatusFn(v);
+  return hasResolveStatusFn(v) && "resolveProfile" in v && typeof v.resolveProfile === "function";
 }
 
 export function isTenantLifecycleStatusPlugin(v: unknown): v is TenantLifecycleStatusPlugin {

package/src/engine/boot-validator/__tests__/access-declarations.test.ts

@@ -144,6 +144,43 @@ describe("validateAccessDeclarations", () => {
     expect(() => validateAccessDeclarations(feature)).not.toThrow();
   });
 
+  // 2c. escapeHatch reason must be non-empty on a stream handler too — same
+  // contract as write/query: streams can't reach db.global(), but they can
+  // still declare escapeHatch to switch identity to SYSTEM via ctx.queryAs.
+  test("stream handler escapeHatch with an empty reason throws, naming the handler", () => {
+    const feature = defineFeature("notes", (r) => {
+      r.entity("note", noteEntity);
+      r.streamHandler(
+        "note:tail",
+        z.object({}),
+        async function* () {
+          yield {};
+        },
+        { access: { roles: ["Admin"] }, escapeHatch: { reason: "" } },
+      );
+    });
+    expect(() => validateAccessDeclarations(feature)).toThrow(/Feature notes/);
+    expect(() => validateAccessDeclarations(feature)).toThrow(/"note:tail"/);
+  });
+
+  test("stream handler escapeHatch with a non-empty reason boots fine", () => {
+    const feature = defineFeature("notes", (r) => {
+      r.entity("note", noteEntity);
+      r.streamHandler(
+        "note:tail",
+        z.object({}),
+        async function* () {
+          yield {};
+        },
+        {
+          access: { roles: ["Admin"] },
+          escapeHatch: { reason: "cross-tenant note tail for auth" },
+        },
+      );
+    });
+    expect(() => validateAccessDeclarations(feature)).not.toThrow();
+  });
+
   // 3. openToAll write handler accepting an unbound personal-data field needs personalData.
   test("openToAll write handler accepting a personal-data field without personalData throws", () => {
     const feature = defineFeature("notes", (r) => {

package/src/engine/boot-validator/__tests__/global-tenancy.test.ts

@@ -0,0 +1,58 @@
+// fw#2858 — a `tenancy: "global"` entity's event stream must live on
+// SYSTEM_TENANT_ID (systemStream: true); otherwise it would silently fork
+// one stream per creating tenant while still being writable/readable
+// cross-tenant via db.global(table).
+
+import { describe, expect, test } from "bun:test";
+import { defineFeature } from "../../define-feature";
+import { createEntity, createTextField } from "../../factories";
+import { validateGlobalTenancyEntities } from "../global-tenancy";
+
+const textField = () =>
+  createTextField({
+    required: true,
+    maxLength: 64,
+    personal: false,
+    reason: "technical_reference",
+  });
+
+describe("validateGlobalTenancyEntities", () => {
+  test("a tenancy: 'global' entity WITHOUT systemStream: true throws", () => {
+    const entity = createEntity({
+      table: "read_fw2858_global_no_stream",
+      tenancy: "global",
+      fields: { name: textField() },
+    });
+    const feature = defineFeature("fw2858-global-no-stream", (r) => {
+      r.entity("fw2858GlobalNoStream", entity);
+    });
+
+    expect(() => validateGlobalTenancyEntities([feature])).toThrow(/systemStream/);
+  });
+
+  test("a tenancy: 'global' entity WITH systemStream: true passes", () => {
+    const entity = createEntity({
+      table: "read_fw2858_global_with_stream",
+      tenancy: "global",
+      systemStream: true,
+      fields: { name: textField() },
+    });
+    const feature = defineFeature("fw2858-global-with-stream", (r) => {
+      r.entity("fw2858GlobalWithStream", entity);
+    });
+
+    expect(() => validateGlobalTenancyEntities([feature])).not.toThrow();
+  });
+
+  test("a tenant-tenancy entity without systemStream is never checked", () => {
+    const entity = createEntity({
+      table: "read_fw2858_tenant_entity",
+      fields: { name: textField() },
+    });
+    const feature = defineFeature("fw2858-tenant-entity", (r) => {
+      r.entity("fw2858TenantEntity", entity);
+    });
+
+    expect(() => validateGlobalTenancyEntities([feature])).not.toThrow();
+  });
+});

package/src/engine/boot-validator/access-declarations.ts

@@ -4,6 +4,7 @@ import type {
   OwnershipMap,
   OwnershipRule,
   QueryHandlerDef,
+  StreamHandlerDef,
   WriteHandlerDef,
 } from "../types";
 import type { EntityDefinition, ResolvedPiiFlags } from "../types/fields";
@@ -133,7 +134,10 @@ function validateEscapeHatchReason(
   feature: FeatureDefinition,
   kind: HandlerKind,
   handlerName: string,
-  escapeHatch: WriteHandlerDef["escapeHatch"] | QueryHandlerDef["escapeHatch"],
+  escapeHatch:
+    | WriteHandlerDef["escapeHatch"]
+    | QueryHandlerDef["escapeHatch"]
+    | StreamHandlerDef["escapeHatch"],
 ): void {
   // skip: no escapeHatch declared, or its reason is already non-empty
   if (!escapeHatch || escapeHatch.reason.trim().length > 0) return;
@@ -212,6 +216,7 @@ export function validateAccessDeclarations(feature: FeatureDefinition): void {
   }
   for (const [handlerName, handler] of Object.entries(feature.streamHandlers)) {
     validateOpenToAllReason(feature, "stream", handlerName, handler.access);
+    validateEscapeHatchReason(feature, "stream", handlerName, handler.escapeHatch);
     validatePersonalDataOnlyOnWrite(feature, "stream", handlerName, handler.access);
   }
 }