@cosmicdrift/kumiko-framework 0.266.0 → 0.269.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.266.0",
+  "version": "0.269.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.269.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.269.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/__tests__/stream-escape-hatch.integration.test.ts

@@ -0,0 +1,203 @@
+// fw#(stream escapeHatch) — mirrors system-identity-switch.integration.test.ts's
+// coverage of ctx.queryAs(SYSTEM, ...) gating, but for stream handlers: a
+// StreamHandlerDef can now declare `escapeHatch: { reason }` to switch
+// identity to SYSTEM. Real HTTP calls (SSE POST /api/stream via Hono's
+// in-memory app.request) + setupTestStack — never createTestDispatcher.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { createLiveDispatcher } from "@cosmicdrift/kumiko-dispatcher-live";
+import { z } from "zod";
+import { generateToken } from "../../api/tokens";
+import { createSystemUser, defineFeature } from "../../engine";
+import type { SessionUser } from "../../engine/types";
+import { createTestUser, setupTestStack, type TestStack, TestUsers } from "../../stack";
+
+const user = TestUsers.user;
+const otherUserNoRole: SessionUser = createTestUser({
+  id: 60,
+  tenantId: user.tenantId,
+  roles: ["User"],
+});
+const otherUserWithAdminRole: SessionUser = createTestUser({
+  id: 61,
+  tenantId: user.tenantId,
+  roles: ["Admin"],
+});
+
+const streamProbeFeature = defineFeature("stream-idswitch-probe", (r) => {
+  r.queryHandler(
+    "whoami",
+    z.object({}),
+    async (query) => ({ roles: query.user.roles, tenantId: query.user.tenantId }),
+    { access: { roles: ["system", "User"] } },
+  );
+
+  r.queryHandler("admin-only", z.object({}), async () => ({ ok: true }), {
+    access: { roles: ["Admin"] },
+  });
+
+  // --- ctx.queryAs(SYSTEM, ...) from a stream handler: gated by the
+  // stream handler's own escapeHatch, same contract as write/query. ---
+  r.streamHandler(
+    "query-as-system-no-hatch",
+    z.object({}),
+    async function* (query, ctx) {
+      const result = await ctx.queryAs(
+        createSystemUser(query.user.tenantId),
+        "stream-idswitch-probe:query:whoami",
+        {},
+      );
+      yield result;
+    },
+    { access: { roles: ["User"] } },
+  );
+
+  r.streamHandler(
+    "query-as-system-with-hatch",
+    z.object({}),
+    async function* (query, ctx) {
+      const result = await ctx.queryAs(
+        createSystemUser(query.user.tenantId),
+        "stream-idswitch-probe:query:whoami",
+        {},
+      );
+      yield result;
+    },
+    {
+      access: { roles: ["User"] },
+      escapeHatch: { reason: "test: stream needs SYSTEM to look itself up" },
+    },
+  );
+
+  // --- ctx.queryAs(nonSystemUser, ...) from a stream handler (fw#2876): a foreign
+  // user needs the stream handler's escapeHatch; the target's own access rule still applies. ---
+  r.streamHandler(
+    "query-as-normal-user-no-hatch",
+    z.object({}),
+    async function* (_query, ctx) {
+      yield await ctx.queryAs(otherUserWithAdminRole, "stream-idswitch-probe:query:admin-only", {});
+    },
+    { access: { roles: ["User"] } },
+  );
+
+  r.streamHandler(
+    "query-as-normal-user",
+    z.object({ granted: z.boolean() }),
+    async function* (query, ctx) {
+      const result = await ctx.queryAs(
+        query.payload.granted ? otherUserWithAdminRole : otherUserNoRole,
+        "stream-idswitch-probe:query:admin-only",
+        {},
+      );
+      yield result;
+    },
+    {
+      access: { roles: ["User"] },
+      escapeHatch: { reason: "test: stream reads admin-only data as a named colleague" },
+    },
+  );
+});
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [streamProbeFeature] });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+async function buildDispatcherFor(asUser: SessionUser) {
+  const authJwt = await stack.jwt.sign(asUser);
+  const csrfToken = generateToken();
+  const cookieHeader = `kumiko_auth=${authJwt}; kumiko_csrf=${csrfToken}`;
+  const fetchImpl = (async (url: unknown, init: RequestInit | undefined) => {
+    return stack.app.request(String(url), {
+      ...(init ?? {}),
+      headers: { ...(init?.headers ?? {}), Cookie: cookieHeader },
+    });
+  }) as unknown as typeof fetch;
+  return createLiveDispatcher({ fetch: fetchImpl, readCsrf: () => csrfToken });
+}
+
+async function collectAll<T>(gen: AsyncGenerator<T>): Promise<T[]> {
+  const chunks: T[] = [];
+  for await (const chunk of gen) chunks.push(chunk);
+  return chunks;
+}
+
+describe("ctx.queryAs(SYSTEM, ...) from a stream handler — gated by the handler's own escapeHatch", () => {
+  test("WITHOUT escapeHatch: fails with access_denied", async () => {
+    const dispatcher = await buildDispatcherFor(user);
+    let thrown: unknown;
+    try {
+      for await (const _ of dispatcher.stream(
+        "stream-idswitch-probe:stream:query-as-system-no-hatch",
+        {},
+      )) {
+        // should not yield
+      }
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toMatchObject({ code: "access_denied" });
+  });
+
+  test("WITH escapeHatch: succeeds", async () => {
+    const dispatcher = await buildDispatcherFor(user);
+    const chunks = await collectAll(
+      dispatcher.stream<{ roles: readonly string[] }>(
+        "stream-idswitch-probe:stream:query-as-system-with-hatch",
+        {},
+      ),
+    );
+    expect(chunks[0]?.roles).toContain("system");
+  });
+});
+
+describe("ctx.queryAs(nonSystemUser, ...) from a stream handler — gated like write/query (fw#2876)", () => {
+  test("WITHOUT escapeHatch: a foreign user fails with identity_switch_denied", async () => {
+    const dispatcher = await buildDispatcherFor(user);
+    let thrown: unknown;
+    try {
+      for await (const _ of dispatcher.stream(
+        "stream-idswitch-probe:stream:query-as-normal-user-no-hatch",
+        {},
+      )) {
+        // should not yield
+      }
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toMatchObject({
+      code: "access_denied",
+      details: { reason: "identity_switch_denied" },
+    });
+  });
+
+  test("WITH escapeHatch, delegates to the target's own access check: denied when the target user lacks the role", async () => {
+    const dispatcher = await buildDispatcherFor(user);
+    let thrown: unknown;
+    try {
+      for await (const _ of dispatcher.stream("stream-idswitch-probe:stream:query-as-normal-user", {
+        granted: false,
+      })) {
+        // should not yield
+      }
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toMatchObject({ code: "access_denied" });
+  });
+
+  test("WITH escapeHatch, delegates to the target's own access check: allowed when the target user has the role", async () => {
+    const dispatcher = await buildDispatcherFor(user);
+    const chunks = await collectAll(
+      dispatcher.stream<{ ok: boolean }>("stream-idswitch-probe:stream:query-as-normal-user", {
+        granted: true,
+      }),
+    );
+    expect(chunks[0]?.ok).toBe(true);
+  });
+});

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,32 @@
 [
+  {
+    "version": "0.269.0",
+    "type": "breaking",
+    "title": "ctx.queryAs/ctx.writeAs to any identity other than the caller itself need r.systemScope() or escapeHatch (fw#2876).",
+    "detail": "The identity-switch gate from fw#2859 now applies to every target, not only SYSTEM (`isSystemIdentitySwitchAllowed` is replaced by `isIdentitySwitchAllowed(caller, asUser, hasGrant)` in `pipeline/system-identity-switch.ts`; `createGatedIdentitySwitch` takes the caller as second argument). Without a grant, `HandlerContext.queryAs`/`writeAs` only accept the caller itself: same `id`, same `tenantId`, same `origin`, equal `claims`, and roles that are a subset of the caller's roles (`sid`, `pat`, `timezone`, `locale` may differ). Any other target — a different user id, a different tenant, extra roles, changed claims, a stripped `origin` — throws `AccessDeniedError` (code `access_denied`, `details.reason` `identity_switch_denied`, no target id/tenant in the error); SYSTEM targets keep `system_identity_switch_denied`. The grant is the same as before: the calling handler's `r.systemScope()` feature or `escapeHatch: { reason }` on the write/query/stream handler, or the hook's own `r.hook(..., { escapeHatch })`. It stays non-transitive, hooks never inherit it, extension hooks and `r.authClaims` hooks have no declaration site (their `queryAs` only reaches the caller itself), and a hook's caller is taken from the dispatcher-built gate, never from `ctx.user`. `JobContext.queryAs`/`writeAs`, top-level `dispatcher.write`/`query`, `ctx.queryAsMember` and `ctx.resolveActiveMembership` are unchanged. `r.step.callFeature({ as })` goes through the gated `ctx.writeAs` and needs the handler's `escapeHatch` for a foreign `as`.",
+    "migration": "Find every `ctx.queryAs(user, ...)`/`ctx.writeAs(user, ...)` (also via helpers that receive `ctx`, and `r.step.callFeature({ as })`) whose user is not `createSystemUser(...)`. If the user is `event.user`/`query.user` or a copy with fewer roles, nothing to do. If it is another user, another tenant (e.g. `{ ...event.user, tenantId: other }`) or adds roles, declare `escapeHatch: { reason: \"<why this handler acts as that identity>\" }` on the write, query or stream handler (or on the `r.hook(...)` call), move the call into an `r.systemScope()` feature or a job, or use `ctx.queryAsMember(userId, ...)` for reads as a stored tenant member. Code branching on `details.reason` for these denials must also accept `identity_switch_denied`. Audit at release: bundled-features 0 sites, solon 0, offlot-app 0, kumiko-enterprise 0 (ai-agent tool dispatcher passes the caller itself)."
+  },
+  {
+    "version": "0.269.0",
+    "type": "improvement",
+    "title": "escapeHatch is now also accepted on stream handlers, gating a SYSTEM identity switch via ctx.queryAs the same way it does for write/query handlers.",
+    "detail": "StreamHandlerDef/StreamHandlerDefinition and the r.streamHandler options param accept escapeHatch: { reason }, same contract as WriteHandlerDef/QueryHandlerDef: a stream handler that switches identity to SYSTEM via ctx.queryAs now needs its own escapeHatch declaration (or its feature must be r.systemScope()), same as ctx.writeAs/queryAs already require for write and query handlers. Stream handlers still cannot reach db.global() (globalWrites stays write-only) but do get the same SYSTEM-identity-switch and ctx.db.unsafeRaw(reason) grant a query-handler escapeHatch already unlocks. The boot validator rejects an empty reason on a stream handler's escapeHatch the same way it does for write/query handlers."
+  },
+  {
+    "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" },