@cosmicdrift/kumiko-framework 0.266.0 → 0.268.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.266.0",
+  "version": "0.268.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -198,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.266.0",
+    "@cosmicdrift/kumiko-types": "0.268.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -214,7 +214,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.266.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.268.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/__tests__/api.test.ts

@@ -640,6 +640,12 @@ describe("POST /api/stream pre-pull race", () => {
       async resolveActiveMembership() {
         return { kind: "rejected", reason: "not_a_member" };
       },
+      // Not exercised by this route.
+      createMemberReader() {
+        return async () => {
+          throw new Error("createMemberReader not available in this stub");
+        };
+      },
     };
   }
 

package/src/api/__tests__/auth-routes-cookie.test.ts

@@ -64,6 +64,12 @@ function createStubDispatcher(overrides?: Partial<Dispatcher>): Dispatcher {
       }
       return { kind: "active", membership: { tenantId, roles: membership.roles } };
     },
+    // Not exercised by these cookie-only tests.
+    createMemberReader() {
+      return async () => {
+        throw new Error("createMemberReader not available in this stub");
+      };
+    },
     ...overrides,
   };
   return merged;

package/src/api/__tests__/auth-routes-invalid-body-invite.test.ts

@@ -39,6 +39,12 @@ function createStubDispatcher(overrides?: Partial<Dispatcher>): Dispatcher {
     },
     // Stream API added with r.streamHandler (#1446) — stub unused in these routes.
     async *stream(): AsyncGenerator<unknown> {},
+    // Not exercised by these routes.
+    createMemberReader() {
+      return async () => {
+        throw new Error("createMemberReader not available in this stub");
+      };
+    },
   };
   return { ...base, ...overrides };
 }

package/src/api/__tests__/auth-routes-mfa-preauth-confirm.test.ts

@@ -49,6 +49,12 @@ function createStubDispatcher(overrides?: Partial<Dispatcher>): Dispatcher {
     async resolveActiveMembership() {
       return { kind: "rejected", reason: "not_a_member" };
     },
+    // Not exercised by these routes.
+    createMemberReader() {
+      return async () => {
+        throw new Error("createMemberReader not available in this stub");
+      };
+    },
   };
   return { ...base, ...overrides };
 }

package/src/api/__tests__/auth-routes-mfa-preauth-enable-start.test.ts

@@ -50,6 +50,12 @@ function createStubDispatcher(overrides?: Partial<Dispatcher>): Dispatcher {
     async resolveActiveMembership() {
       return { kind: "rejected", reason: "not_a_member" };
     },
+    // Not exercised by these routes.
+    createMemberReader() {
+      return async () => {
+        throw new Error("createMemberReader not available in this stub");
+      };
+    },
   };
   return { ...base, ...overrides };
 }

package/src/api/__tests__/auth-routes-mfa-verify.test.ts

@@ -49,6 +49,12 @@ function createStubDispatcher(overrides?: Partial<Dispatcher>): Dispatcher {
     async resolveActiveMembership() {
       return { kind: "rejected", reason: "not_a_member" };
     },
+    // Not exercised by these routes.
+    createMemberReader() {
+      return async () => {
+        throw new Error("createMemberReader not available in this stub");
+      };
+    },
   };
   return { ...base, ...overrides };
 }

package/src/api/__tests__/auth-routes-trusted-proxy.test.ts

@@ -42,6 +42,12 @@ function failingDispatcher(): Dispatcher {
     async resolveActiveMembership() {
       return { kind: "rejected", reason: "not_a_member" };
     },
+    // Not exercised by these routes.
+    createMemberReader() {
+      return async () => {
+        throw new Error("createMemberReader not available in this stub");
+      };
+    },
   };
 }
 

package/src/api/__tests__/jwt.test.ts

@@ -106,6 +106,14 @@ describe("createJwtHelper.verify — payload validation (KF-2)", () => {
     const payload = await jwt.verify(await jwt.sign(user));
     expect(payload.locale).toBeUndefined();
   });
+
+  // A ctx.queryAsMember-resolved SessionUser must never be minted into a
+  // session — it carries no `sid` and is read-only by construction.
+  it("refuses to sign a SessionUser with origin set", async () => {
+    await expect(jwt.sign({ ...user, origin: "member-resolution" })).rejects.toThrow(
+      /member-resolution/,
+    );
+  });
 });
 
 describe("createJwtHelper — keyring form", () => {

package/src/api/jwt.ts

@@ -2,6 +2,7 @@ import * as jose from "jose";
 import type { DbRow } from "../db/connection";
 import type { SessionUser, TenantId } from "../engine/types";
 import { parseTenantId } from "../engine/types";
+import { InternalError } from "../errors";
 
 export type JwtPayload = {
   // JWT `sub` is a string per RFC 7519. Matches SessionUser.id — a UUID-string
@@ -108,6 +109,13 @@ export function createJwtHelper(
 
   return {
     async sign(user) {
+      // A resolved member principal (origin set) carries no `sid` and must
+      // never be minted into a session — only interactive sign-in may sign.
+      if (user.origin !== undefined) {
+        throw new InternalError({
+          message: `jwt.sign: refusing to sign a SessionUser with origin "${user.origin}" — only interactively-authenticated sessions may be minted.`,
+        });
+      }
       const body: Omit<JwtPayload, "sub" | "jti"> = {
         tenantId: user.tenantId,
         roles: [...user.roles],

package/src/changes.json

@@ -1,4 +1,19 @@
 [
+  {
+    "version": "0.267.0",
+    "type": "breaking",
+    "title": "ctx.db.unsafeRaw(reason) gated by escapeHatch, tenancy: \"global\" invariants, bundled features migrated off ctx.db.raw (fw#2858).",
+    "detail": "`TenantDb.unsafeRaw(reason)` returns the unfiltered `DbRunner` only when the calling write or query handler declares `escapeHatch: { reason }` (lifecycle hooks: `r.hook(..., { escapeHatch })`; a hook no longer inherits the handler's grant, same as the #2859 SYSTEM identity-switch gate). Without a declaration it throws `AccessDeniedError`; an empty reason throws `Error`. `r.systemScope()` features keep using `ctx.systemDb.unsafeRaw(reason)`. `TenantDb.raw` stays deprecated until fw#2860. `createTenantDb`'s 7th parameter changed from an `EscapeHatchDeclaration` to `TenantDbGrants` `{ globalWrites?, unsafeRaw? }`; `withUnsafeRawGrant(tenantDb, grant)` rebinds the unsafeRaw grant. `bindHookIdentitySwitchGrant`/`withHookIdentitySwitchGrant` are renamed to `bindHookEscapeHatchGrant`/`withHookEscapeHatchGrant`. Global tenancy: a `tenancy: \"global\"` entity must declare `systemStream: true` (boot validator + executor) and its create/update payloads may not carry a non-SYSTEM `tenantId`; tenant-mode `insertOne` into a global table with a `tenant_id` column and `db.global(table)` writes with a non-SYSTEM `tenantId` are rejected; `defineUnmanagedTable({ tenancy: \"global\" })` rejects a `tenant_id` column; new `declareGlobalTenancy(table)` declares a plain `table()` store without `tenant_id` as global. Bundled features: `userEntity` is `tenancy: \"global\"`, `store_global_feature_state` is declared global, and every bundled `ctx.db.raw` call site now uses `ctx.db.global(table)`, a filtered `ctx.db` method, or `ctx.db.unsafeRaw(reason)` with an `escapeHatch` on the handler. Handlers that call the auth-mfa `mfaStatusChecker`/MFA code verifier callbacks, handlers wrapped by cap-counter `withStockCap` (declares it automatically) and callers of the custom-fields quota/field-access query helpers now need that declaration.",
+    "migration": "Replace each `ctx.db.raw` use: reads of a `tenancy: \"global\"` table → `ctx.db.global(table).selectMany/fetchOne(...)`; reads/inserts whose where/values only use the caller's own tenantId → `ctx.db.selectMany/fetchOne/insertOne(table, ...)` (method form); everything else → `ctx.db.unsafeRaw(\"<what is read/written and why the tenant filter cannot apply>\")` plus `escapeHatch: { reason }` on the write/query handler definition or in the `r.hook` options. Generic reasons (todo, legacy, migration) fail infra#788. `bun scripts/migrate-db-raw.ts --dry-run <paths>` rewrites the global-table and own-tenant cases and lists the remaining sites; drop `--dry-run` to apply. Custom handlers calling `mfaStatusChecker`/the MFA code verifier or the custom-fields query helpers must declare `escapeHatch`. Direct `createTenantDb(..., escapeHatch)` calls pass `{ globalWrites: escapeHatch }` (and `unsafeRaw` if needed). Rename imports of `bindHookIdentitySwitchGrant`/`withHookIdentitySwitchGrant`. `defineUnmanagedTable({ tenancy: \"global\" })` definitions must drop their `tenant_id` column; `tenancy: \"global\"` entities must add `systemStream: true`.",
+    "codemod": "bun scripts/migrate-db-raw.ts --dry-run <paths>"
+  },
+  {
+    "version": "0.267.0",
+    "type": "improvement",
+    "title": "ctx.queryAsMember reads a query handler as a stored tenant member, resolved internally by the framework (fw#2873).",
+    "detail": "New `ctx.queryAsMember(userId, qn, payload)` on `HandlerContext`, `JobContext` and (optional) `AppContext` — resolves a background SessionUser for `userId` in the current tenant (active membership, via a new stricter `BACKGROUND_READ_POLICY` — no pending-destruction grace window, no unknown-principal pass → `PrincipalStatusPlugin.resolveProfile` → `buildSessionRoles` → `resolveAuthClaims`) and runs the target query handler as that member. The resolved SessionUser is never exposed: no `sid`, `origin: \"member-resolution\"`. Rejection for any reason (not a member, blocked principal, tenant teardown, or would-be-SYSTEM) surfaces the same generic AccessDeniedError (`member_resolution_denied`, no rejection reason in `details`). Resolution is cached per handler invocation (its lifecycle hooks share that cache) or job run; a nested dispatch gets its own cache. Needs the same grant as a SYSTEM `queryAs` (`r.systemScope()` or `escapeHatch`); a hook's OWN escapeHatch re-gates it independently of the enclosing handler's grant (can grant even when the handler has none). Jobs stay ungated. There is no `writeAsMember` — a resolved member principal is read-only by construction: `write`/`writeAs`/`appendEvent`/`unsafeAppendEvent`/`tryAppendEvent`/`fetchForWriting`/`archiveStream`/`restoreStream`/`snapshotAggregate`/`queryAsMember`/`resolveActiveMembership`/`jobRunner`/`scheduleAfterCommit` all throw `member_resolution_read_only` (also enforced at the shared event-append sink behind `appendEvent`/`fetchForWriting().appendOne`), and `dbOutsideTransaction`/`systemDb`/`runPreSave`/`files`/`derivatives` are unset (raw `ctx.db` writes are NOT blocked — same reachability as that handler running for the member over HTTP). `jwt.sign()` now refuses a SessionUser with `origin` set.",
+    "migration": "Custom principalStatus providers must implement resolveProfile for ctx.queryAsMember; login/switch-tenant unaffected."
+  },
   {
     "version": "0.266.0",
     "type": "breaking",

package/src/db/__tests__/event-store-executor-global-tenancy.integration.test.ts

@@ -0,0 +1,73 @@
+// fw#2858 — a `tenancy: "global"` entity's aggregate is tenant-agnostic: create/update
+// must reject an explicit foreign (non-SYSTEM) payload.tenantId before it ever reaches
+// the projection insert/update. Modelled on event-store-system-stream.integration.test.ts.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { createEntity, createTextField } from "../../engine";
+import { AccessDeniedError } from "../../errors";
+import {
+  createTestDb,
+  type TestDb,
+  TestUsers,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "../../stack";
+import { createEventStoreExecutor } from "../event-store-executor";
+import { buildEntityTable } from "../table-builder";
+import { createTenantDb } from "../tenant-db";
+
+const globalEntity = createEntity({
+  table: "gtenancy_global",
+  tenancy: "global",
+  systemStream: true,
+  fields: { name: createTextField({ required: true, personal: false, reason: "test_fixture" }) },
+});
+
+const globalTable = buildEntityTable("gtenancyGlobal", globalEntity);
+const globalExec = createEventStoreExecutor(globalTable, globalEntity, {
+  entityName: "gtenancyGlobal",
+});
+
+const user = TestUsers.admin; // tenantId === testTenantId(1)
+const foreignTenantId = testTenantId(2);
+
+let testDb: TestDb;
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  await unsafeCreateEntityTable(testDb.db, globalEntity, "gtenancyGlobal");
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+describe("global entity tenantId invariant (fw#2858)", () => {
+  test("create with an explicit foreign tenantId throws AccessDeniedError", async () => {
+    const db = createTenantDb(testDb.db, user.tenantId);
+    await expect(
+      globalExec.create({ name: "a", tenantId: foreignTenantId }, user, db),
+    ).rejects.toBeInstanceOf(AccessDeniedError);
+  });
+
+  test("create without a tenantId (or SYSTEM) succeeds", async () => {
+    const db = createTenantDb(testDb.db, user.tenantId);
+    const res = await globalExec.create({ name: "a" }, user, db);
+    expect(res.isSuccess).toBe(true);
+  });
+
+  test("update with an explicit foreign tenantId in changes throws AccessDeniedError", async () => {
+    const db = createTenantDb(testDb.db, user.tenantId);
+    const created = await globalExec.create({ name: "a" }, user, db);
+    if (!created.isSuccess) throw new Error("create failed");
+
+    await expect(
+      globalExec.update(
+        { id: String(created.data.id), changes: { tenantId: foreignTenantId } },
+        user,
+        db,
+        { skipOptimisticLock: true },
+      ),
+    ).rejects.toBeInstanceOf(AccessDeniedError);
+  });
+});

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

@@ -1,8 +1,11 @@
-// fw#2855 — db.global(table) against real Postgres: tenant filter lifted, caller's
-// `where` still applies; a normal accessor on the same table still filters by tenant.
+// fw#2858 — db.global(table) against real Postgres: a "global" unmanaged table has
+// no tenant_id column at all (binding decision, issue comment 2026-09-14), so its
+// rows are tenant-agnostic — every caller sees the same rows through db.global().
+// A normal tenancy: "tenant" table is unaffected and still isolates by tenant.
 // Follows tenant-db-where-merge.integration.test.ts's setupTestStack pattern.
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { AccessDeniedError } from "../../errors";
 import { setupTestStack, type TestStack, testTenantId, unsafePushTables } from "../../stack";
 import type { TableColumns } from "../dialect";
 import { defineUnmanagedTable } from "../entity-table-meta";
@@ -10,8 +13,22 @@ import { insertOne } from "../query";
 import { createTenantDb } from "../tenant-db";
 
 const globalItemsTable = defineUnmanagedTable({
-  tableName: "store_fw2855_global_items_it",
+  tableName: "store_fw2858_global_items_it",
   tenancy: "global",
+  columns: [
+    {
+      name: "id",
+      pgType: "uuid",
+      notNull: true,
+      primaryKey: true,
+      defaultSql: "gen_random_uuid()",
+    },
+    { name: "some_field", pgType: "text", notNull: true },
+  ],
+});
+
+const tenantItemsTable = defineUnmanagedTable({
+  tableName: "store_fw2858_tenant_items_it",
   columns: [
     {
       name: "id",
@@ -27,15 +44,20 @@ const globalItemsTable = defineUnmanagedTable({
 
 let stack: TestStack;
 
-const tenantA = testTenantId(91);
-const tenantB = testTenantId(92);
+const tenantA = testTenantId(93);
+const tenantB = testTenantId(94);
 
 beforeAll(async () => {
   stack = await setupTestStack({ features: [] });
-  await unsafePushTables(stack.db, { globalItems: globalItemsTable });
-  await insertOne(stack.db, globalItemsTable, { tenantId: tenantA, someField: "match" });
-  await insertOne(stack.db, globalItemsTable, { tenantId: tenantB, someField: "match" });
-  await insertOne(stack.db, globalItemsTable, { tenantId: tenantB, someField: "no-match" });
+  await unsafePushTables(stack.db, {
+    globalItems: globalItemsTable,
+    tenantItems: tenantItemsTable,
+  });
+  await insertOne(stack.db, globalItemsTable, { someField: "match" });
+  await insertOne(stack.db, globalItemsTable, { someField: "match" });
+  await insertOne(stack.db, globalItemsTable, { someField: "no-match" });
+  await insertOne(stack.db, tenantItemsTable, { tenantId: tenantA, someField: "match" });
+  await insertOne(stack.db, tenantItemsTable, { tenantId: tenantB, someField: "match" });
 });
 
 afterAll(async () => {
@@ -43,25 +65,35 @@ afterAll(async () => {
 });
 
 describe("TenantDb.global() — reads, real Postgres", () => {
-  test("db.global(t).selectMany keeps the field filter but drops the tenant filter", async () => {
-    const tdb = createTenantDb(stack.db, tenantA);
-    const rows = await tdb.global(globalItemsTable).selectMany<{
-      tenantId: string;
-      someField: string;
-    }>({ someField: "match" });
-
-    const tenantIds = rows.map((r) => r.tenantId).sort();
-    expect(tenantIds).toEqual([tenantA, tenantB].sort());
-    expect(rows.every((r) => r.someField === "match")).toBe(true);
+  test("selectMany returns the same rows to callers on different tenants, unfiltered by tenant", async () => {
+    const rowsForA = await createTenantDb(stack.db, tenantA)
+      .global(globalItemsTable)
+      .selectMany<{ id: string; someField: string }>({ someField: "match" });
+    const rowsForB = await createTenantDb(stack.db, tenantB)
+      .global(globalItemsTable)
+      .selectMany<{ id: string; someField: string }>({ someField: "match" });
+
+    expect(rowsForA).toHaveLength(2);
+    expect(rowsForA.map((r) => r.id).sort()).toEqual(rowsForB.map((r) => r.id).sort());
   });
 
-  test("the normal (non-global) db.selectMany on the same table still filters by tenant", async () => {
+  test("fetchOne finds a row for a caller whose own tenant never wrote it", async () => {
+    const row = await createTenantDb(stack.db, tenantA)
+      .global(globalItemsTable)
+      .fetchOne<{ someField: string }>({ someField: "no-match" });
+
+    expect(row?.someField).toBe("no-match");
+  });
+});
+
+describe("TenantDb — tenant-mode isolation on a normal tenant table", () => {
+  test("db.selectMany only returns the caller's own tenant's rows", async () => {
     const tdb = createTenantDb(stack.db, tenantA);
     // selectMany's Table param types the branded-EntityTable shape only;
     // EntityTableMeta reads work identically at runtime (both normalize via
     // asEntityTableMeta) — same unbranded-view cast as tenant-db-where-merge.test.ts.
     const rows = await tdb.selectMany<{ tenantId: string; someField: string }>(
-      globalItemsTable as unknown as TableColumns,
+      tenantItemsTable as unknown as TableColumns,
       { someField: "match" },
     );
 
@@ -71,18 +103,23 @@ describe("TenantDb.global() — reads, real Postgres", () => {
 });
 
 describe("TenantDb.global() — writes, real Postgres", () => {
-  test("insert/update/delete succeed when createTenantDb was given an escapeHatch", async () => {
+  test("insert/update/delete are rejected without a globalWrites grant", async () => {
+    const tdb = createTenantDb(stack.db, tenantA);
+    await expect(
+      tdb.global(globalItemsTable).insertOne({ someField: "ungranted" }),
+    ).rejects.toThrow(AccessDeniedError);
+  });
+
+  test("insert/update/delete succeed when createTenantDb was given a globalWrites grant", async () => {
     const tdb = createTenantDb(stack.db, tenantA, "tenant", undefined, undefined, undefined, {
-      reason: "fw#2855 integration test — cross-tenant write via db.global()",
+      globalWrites: { reason: "fw#2858 integration test — cross-tenant write via db.global()" },
     });
     const globalDb = tdb.global(globalItemsTable);
 
-    const inserted = await globalDb.insertOne<{ id: string; tenantId: string }>({
-      tenantId: tenantB,
+    const inserted = await globalDb.insertOne<{ id: string }>({
       someField: "escape-hatch-insert",
     });
     if (!inserted) throw new Error("insertOne returned no row");
-    expect(inserted.tenantId).toBe(tenantB);
 
     const updated = await globalDb.updateMany<{ someField: string }>(
       { someField: "escape-hatch-update" },

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";