@cosmicdrift/kumiko-framework 0.259.0 → 0.261.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.259.0",
+  "version": "0.261.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.259.0",
+    "@cosmicdrift/kumiko-types": "0.261.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.259.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.261.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,17 @@
 [
+  {
+    "version": "0.261.0",
+    "type": "breaking",
+    "title": "access is required on handler definitions; openToAll accepts { reason } (+ publicIntake) (fw#2855).",
+    "detail": "`WriteHandlerDef`/`QueryHandlerDef`/`StreamHandlerDef`.access (`@cosmicdrift/kumiko-types/handlers`), `WriteHandlerDefinition`/`WriteHandlerInput`/`QueryHandlerDefinition`/`StreamHandlerDefinition`.access, `EntityHandlerOptions.access`, and the `r.writeHandler`/`r.queryHandler`/`r.streamHandler` positional `options` param are now required — a handler with no access rule fails to compile instead of silently registering unreachable (previously the boot-validator caught it at runtime). `registerEntityCrud` throws at registration when an enabled verb resolves no access (`write.access`/`read.access`/`verbAccess.<verb>` all unset) — was previously a boot-validator throw. `AccessRule.openToAll` accepts `{ reason: string }` (plus optional `publicIntake: true`); `true` still compiles (deprecated pre-#2855 form, tracked for removal in fw#2854's call-site migration) but a new boot-validator (`engine/boot-validator/access-declarations.ts`) rejects an empty `openToAll.reason`, an empty `escapeHatch.reason`, `publicIntake` on a query/stream handler, and — the main new catch — a write handler with `openToAll` that accepts a personal-data field (pii/userOwned/recordOwned) in its input schema without `publicIntake: true`. Code that read `access.openToAll` as a boolean must switch to `isOpenToAllGranted(rule)` (`@cosmicdrift/kumiko-types/handlers`, also re-exported from `@cosmicdrift/kumiko-framework/engine` and `/ui-types`), which handles both the `true` and `{ reason }` forms.",
+    "migration": "Add `access` to every handler definition: `r.writeHandler`/`r.queryHandler`/`r.streamHandler` object- and positional-form options, `defineWriteHandler`/`defineQueryHandler`/`definePagedQueryHandler`/`defineProjectionQueryHandler` options, `defineEntityCreate/Update/Delete/Restore/List/DetailHandler` options, and `registerEntityCrud`'s `write.access`/`read.access` (or per-verb `verbAccess`). Replace `openToAll: true` with `openToAll: { reason: \"...\" }` going forward — `true` still compiles but is deprecated (fw#2854 tracks the 471-site call-site migration; new code should use the object form). A write handler that already used `openToAll` and accepts a PII field now fails boot unless it also declares `publicIntake: true` (any authenticated user may legitimately submit that data) or is restricted to roles instead. Any code reading `access.openToAll` as a boolean must switch to `isOpenToAllGranted(rule)`."
+  },
+  {
+    "version": "0.261.0",
+    "type": "improvement",
+    "title": "EntityDefinition.tenancy + db.global(table), escapeHatch, UncheckedSystemDb.unsafeRaw(reason) (fw#2855).",
+    "detail": "`EntityDefinition.tenancy?: \"global\" | \"tenant\"` (default `\"tenant\"`; `createEntity({ tenancy: \"global\", ... })`) marks an entity's rows as shared across every tenant instead of row-scoped — only reachable via the new `TenantDb.global(table)`, which drops the tenant filter but keeps the caller's own `where` field-filter for reads, and rejects writes unless the calling write handler declared `escapeHatch: { reason: \"...\" }` (`WriteHandlerDef.escapeHatch`, threaded through `r.writeHandler`/`defineWriteHandler`/`registerEntityCrud`). `defineUnmanagedTable({ tenancy: \"global\", ... })` covers hand-built store tables the same way; a `\"tenant\"`-tenancy table passed to `db.global()` is a compile error (`TenancyBrand<\"global\">` required) and, for an erased/runtime-only table the brand can't catch, also a runtime `AccessDeniedError`. `UncheckedSystemDb.unsafeRaw(reason: string): DbRunner` replaces reaching for `ctx.systemDb`'s guarded `.raw` escape hatch with a named, auditable declaration (throws on an empty reason); `TenantDb.raw` is now `@deprecated` in favor of `unsafeRaw`/`db.global()`, removal tracked in fw#2860."
+  },
   {
     "version": "0.259.0",
     "type": "improvement",

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

@@ -0,0 +1,97 @@
+// 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.
+// Follows tenant-db-where-merge.integration.test.ts's setupTestStack pattern.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { setupTestStack, type TestStack, testTenantId, unsafePushTables } from "../../stack";
+import type { TableColumns } from "../dialect";
+import { defineUnmanagedTable } from "../entity-table-meta";
+import { insertOne } from "../query";
+import { createTenantDb } from "../tenant-db";
+
+const globalItemsTable = defineUnmanagedTable({
+  tableName: "store_fw2855_global_items_it",
+  tenancy: "global",
+  columns: [
+    {
+      name: "id",
+      pgType: "uuid",
+      notNull: true,
+      primaryKey: true,
+      defaultSql: "gen_random_uuid()",
+    },
+    { name: "tenant_id", pgType: "uuid", notNull: true },
+    { name: "some_field", pgType: "text", notNull: true },
+  ],
+});
+
+let stack: TestStack;
+
+const tenantA = testTenantId(91);
+const tenantB = testTenantId(92);
+
+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" });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+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("the normal (non-global) db.selectMany on the same table still filters by tenant", 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,
+      { someField: "match" },
+    );
+
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.tenantId).toBe(tenantA);
+  });
+});
+
+describe("TenantDb.global() — writes, real Postgres", () => {
+  test("insert/update/delete succeed when createTenantDb was given an escapeHatch", async () => {
+    const tdb = createTenantDb(stack.db, tenantA, "tenant", undefined, undefined, undefined, {
+      reason: "fw#2855 integration test — cross-tenant write via db.global()",
+    });
+    const globalDb = tdb.global(globalItemsTable);
+
+    const inserted = await globalDb.insertOne<{ id: string; tenantId: string }>({
+      tenantId: tenantB,
+      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" },
+      { id: inserted.id },
+    );
+    expect(updated[0]?.someField).toBe("escape-hatch-update");
+
+    await globalDb.deleteMany({ id: inserted.id });
+    const remaining = await globalDb.selectMany({ id: inserted.id });
+    expect(remaining).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,170 @@
+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 { testTenantId } from "../../stack";
+import type { DbRunner } from "../connection";
+import { defineUnmanagedTable, deriveEntityTableMeta } from "../entity-table-meta";
+import { buildEntityTable } from "../table-builder";
+import { createTenantDb, createUncheckedSystemDb, type TenantDb } 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
+// instead of silently "passing" on an accidental real write.
+function unreachableRunner(): DbRunner {
+  return {
+    unsafe: async () => {
+      throw new Error("db.global(): must not touch the DB runner here");
+    },
+    begin: async () => {
+      throw new Error("db.global(): must not touch the DB runner here");
+    },
+  } as DbRunner;
+}
+
+const tenantEntity = createEntity({
+  table: "fw2855_global_tenant_items",
+  fields: { name: createTextField({ required: true, personal: false, reason: "test_fixture" }) },
+});
+const tenantEntityTable = buildEntityTable("globalGuardTenantItem", tenantEntity);
+const tenantMeta = deriveEntityTableMeta("globalGuardTenantMeta", tenantEntity);
+
+const globalManagedEntity = createEntity({
+  table: "fw2855_global_managed_items",
+  tenancy: "global",
+  fields: { name: createTextField({ required: true, personal: false, reason: "test_fixture" }) },
+});
+const globalManagedTable = buildEntityTable("globalGuardManagedItem", globalManagedEntity);
+
+const globalUnmanagedTable = defineUnmanagedTable({
+  tableName: "store_fw2855_global_items",
+  tenancy: "global",
+  columns: [
+    { name: "id", pgType: "uuid", notNull: true, primaryKey: true },
+    { name: "name", pgType: "text", notNull: true },
+  ],
+});
+
+// Regression coverage for the tenancy-brand type hole (fw#2855 review): an
+// EntityDefinition object literal (bypassing createEntity) must not be
+// mis-branded "global" just because it lacks a `tenancy` property at all.
+const bareLiteralTable = buildEntityTable("globalGuardBareLiteral", {
+  fields: { name: createTextField({ required: true, personal: false, reason: "test_fixture" }) },
+});
+const explicitTenantLiteralTable = buildEntityTable("globalGuardExplicitTenant", {
+  tenancy: "tenant",
+  fields: { name: createTextField({ required: true, personal: false, reason: "test_fixture" }) },
+});
+const explicitGlobalLiteralTable = buildEntityTable("globalGuardExplicitGlobal", {
+  tenancy: "global",
+  fields: { name: createTextField({ required: true, personal: false, reason: "test_fixture" }) },
+});
+
+const own = testTenantId(1);
+
+// Type-only assertions — never invoked, checked by `tsc --build` only.
+function typeAssertions(tdb: TenantDb): void {
+  // @ts-expect-error db.global() on a "tenant"-tenancy table (default tenancy) is a type error.
+  tdb.global(tenantEntityTable);
+
+  // @ts-expect-error an EntityDefinition object literal without a `tenancy` key must not brand "global".
+  tdb.global(bareLiteralTable);
+
+  // @ts-expect-error an explicit `tenancy: "tenant"` literal must not brand "global".
+  tdb.global(explicitTenantLiteralTable);
+
+  // Compile-positive: an explicit `tenancy: "global"` literal is reachable through db.global().
+  void tdb.global(explicitGlobalLiteralTable).selectMany({ name: "x" });
+
+  // Compile-positive: an unmanaged "global" table is fully writable through db.global().
+  void tdb.global(globalUnmanagedTable).insertOne({ name: "x" });
+
+  const managedAccessor = tdb.global(globalManagedTable);
+  // @ts-expect-error managed global tables stay executor-only — no write methods through db.global() either.
+  void managedAccessor.insertOne({ name: "x" });
+}
+void typeAssertions;
+
+describe("TenantDb.global()", () => {
+  test("on a tenant-tenancy table throws AccessDeniedError at runtime (erased/unbranded table)", () => {
+    const tdb = createTenantDb(unreachableRunner(), own);
+    expect(() =>
+      tdb.global(tenantMeta as unknown as EntityTableMeta & TenancyBrand<"global">),
+    ).toThrow(/tenancy: "global"/);
+  });
+
+  test("reads on a global table never touch the caller's tenant filter", async () => {
+    const captured: { sql: string; values: readonly unknown[] }[] = [];
+    const db: DbRunner = {
+      unsafe: async (sql: string, values: readonly unknown[]) => {
+        captured.push({ sql, values });
+        return [];
+      },
+      begin: async () => {
+        throw new Error("begin not used in this test");
+      },
+    } as DbRunner;
+    const tdb = createTenantDb(db, own);
+    await tdb.global(globalUnmanagedTable).selectMany({ name: "x" });
+    expect(captured).toHaveLength(1);
+    expect(captured[0]?.sql).not.toMatch(/tenant_id/i);
+  });
+
+  test("write without escapeHatch rejects before touching the runner", async () => {
+    const tdb = createTenantDb(unreachableRunner(), own);
+    await expect(tdb.global(globalUnmanagedTable).insertOne({ name: "x" })).rejects.toThrow(
+      /escapeHatch/,
+    );
+  });
+
+  test("write with an empty-reason escapeHatch rejects before touching the runner", async () => {
+    const tdb = createTenantDb(
+      unreachableRunner(),
+      own,
+      "tenant",
+      undefined,
+      undefined,
+      undefined,
+      {
+        reason: "   ",
+      },
+    );
+    await expect(tdb.global(globalUnmanagedTable).insertOne({ name: "x" })).rejects.toThrow(
+      /escapeHatch/,
+    );
+  });
+
+  test("write with a non-empty escapeHatch reason reaches the runner", async () => {
+    const captured: { sql: string }[] = [];
+    const db: DbRunner = {
+      unsafe: async (sql: string) => {
+        captured.push({ sql });
+        return [{ id: "x" }];
+      },
+      begin: async () => {
+        throw new Error("begin not used in this test");
+      },
+    } as DbRunner;
+    const tdb = createTenantDb(db, own, "tenant", undefined, undefined, undefined, {
+      reason: "cross-tenant backfill job",
+    });
+    await tdb.global(globalUnmanagedTable).insertOne({ name: "x" });
+    expect(captured).toHaveLength(1);
+  });
+});
+
+describe("UncheckedSystemDb.unsafeRaw", () => {
+  test("throws on an empty or whitespace-only reason", () => {
+    const tdb = createTenantDb(unreachableRunner(), own);
+    const sysDb = createUncheckedSystemDb(tdb);
+    expect(() => sysDb.unsafeRaw("")).toThrow();
+    expect(() => sysDb.unsafeRaw("   ")).toThrow();
+  });
+
+  test("returns the underlying DbRunner for a non-empty reason", () => {
+    const rawDb = unreachableRunner();
+    const tdb = createTenantDb(rawDb, own);
+    const sysDb = createUncheckedSystemDb(tdb);
+    expect(sysDb.unsafeRaw("cleanup job")).toBe(rawDb);
+  });
+});

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

@@ -16,6 +16,7 @@
 //      hand-built path; app author owns tenant scoping / versioning. Prefer a
 //      `store_` table name — `read_` is reserved for managed projections (#1208/#1220).
 
+import type { EntityTenancy, TenancyBrand } from "@cosmicdrift/kumiko-types/tenancy-brand";
 import { collectPiiSubjectFields } from "../crypto";
 import type { EntityDefinition, EntityIndexDef, FieldDefinition } from "../engine/types";
 import { SQL_EXPR_BRAND } from "./dialect";
@@ -385,6 +386,7 @@ export function deriveEntityTableMeta(
     indexes,
     source,
     ...(piiSubjectFields.length > 0 && { piiSubjectFields }),
+    ...(entity.tenancy === "global" && { tenancy: "global" as const }),
   };
 }
 
@@ -453,7 +455,9 @@ function columnsByNameMeta(meta: EntityTableMeta): Map<string, ColumnMeta> {
  * table. Justify WHY in the call site; reviewers should scrutinize every new
  * unmanaged table.
  */
-export function defineUnmanagedTable(input: UnmanagedTableInput): EntityTableMeta {
+export function defineUnmanagedTable<const T extends EntityTenancy = "tenant">(
+  input: UnmanagedTableInput & { readonly tenancy?: T },
+): EntityTableMeta & TenancyBrand<T> {
   assertUnmanagedTableName(input.tableName, "defineUnmanagedTable");
   return {
     tableName: input.tableName,
@@ -463,7 +467,9 @@ export function defineUnmanagedTable(input: UnmanagedTableInput): EntityTableMet
       compositePrimaryKey: input.compositePrimaryKey,
     }),
     source: "unmanaged",
-  };
+    ...(input.tenancy === "global" && { tenancy: "global" as const }),
+    // @cast-boundary type-brand — TenancyBrand<T> is a phantom marker with no runtime representation.
+  } as EntityTableMeta & TenancyBrand<T>;
 }
 
 function assertUnmanagedTableName(tableName: string, via: string): void {

package/src/db/table-builder.ts

@@ -1,4 +1,7 @@
+import type { EntityTableMeta } from "@cosmicdrift/kumiko-types/entity-table-meta-types";
 import type { ExecutorOnly } from "@cosmicdrift/kumiko-types/executor-brand";
+import { KUMIKO_META_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
+import type { TenancyBrand } from "@cosmicdrift/kumiko-types/tenancy-brand";
 import type {
   EntityDefinition,
   EntityRelations,
@@ -408,6 +411,18 @@ type SoftDeleteColumnsType = {
 
 // ── ES-write brand ──────────────────────────────────────────────────────
 export type { ExecutorOnly, NotExecutorOnly } from "@cosmicdrift/kumiko-types/executor-brand";
+// ── Tenancy brand ────────────────────────────────────────────────────────
+export type { EntityTenancy, TenancyBrand } from "@cosmicdrift/kumiko-types/tenancy-brand";
+
+// `E extends { tenancy?: "global" }` would wrongly match any E missing
+// `tenancy` too (an absent optional property structurally satisfies an
+// optional one) — index into E["tenancy"] instead so only a literal
+// "global" (not undefined/"tenant"/a union/never) brands "global".
+type EntityTableTenancy<E extends EntityDefinition> = [NonNullable<E["tenancy"]>] extends [never]
+  ? "tenant"
+  : [NonNullable<E["tenancy"]>] extends ["global"]
+    ? "global"
+    : "tenant";
 
 export type EntityTable<E extends EntityDefinition = EntityDefinition> =
   TableColumns<// biome-ignore lint/suspicious/noExplicitAny: drizzle's internal table-config stays generic; we layer typed columns on top via the intersection below.
@@ -415,7 +430,8 @@ export type EntityTable<E extends EntityDefinition = EntityDefinition> =
     BaseColumnsType<E> &
     SoftDeleteColumnsType &
     ColumnsForEntity<E["fields"]> &
-    ExecutorOnly;
+    ExecutorOnly &
+    TenancyBrand<EntityTableTenancy<E>>;
 
 export function buildBaseColumns(softDelete: boolean, idType: "serial" | "uuid" = "uuid") {
   const idColumn =
@@ -474,6 +490,21 @@ export type BuildEntityTableOptions = {
   readonly relations?: EntityRelations;
 };
 
+function stampGlobalTenancyMeta<E extends EntityDefinition>(
+  table: EntityTable<E>,
+  entity: E,
+): void {
+  // skip: non-global entities keep pgTable's default tenancy meta
+  if (entity.tenancy !== "global") return;
+  const meta = (table as unknown as Record<symbol, EntityTableMeta>)[KUMIKO_META_SYMBOL];
+  // skip: no meta stamp present — nothing to patch
+  if (!meta) return;
+  (table as unknown as Record<symbol, EntityTableMeta>)[KUMIKO_META_SYMBOL] = {
+    ...meta,
+    tenancy: "global",
+  };
+}
+
 export function buildEntityTable<E extends EntityDefinition>(
   entityName: string,
   entity: E,
@@ -525,7 +556,7 @@ export function buildEntityTable<E extends EntityDefinition>(
   // hand in. Our typed signature narrows that to the static names from
   // EntityDefinition (kept in sync with fieldToColumns + buildBaseColumns).
   // Drizzle's runtime instance carries every needed method on top.
-  return pgTable(
+  const built = pgTable(
     tableName,
     {
       ...baseColumns,
@@ -627,4 +658,8 @@ export function buildEntityTable<E extends EntityDefinition>(
       return indexes;
     },
   ) as unknown as EntityTable<E>;
+
+  // pgTable's own meta stamp doesn't see entity.tenancy — patch it so db.global()'s runtime guard matches the type brand.
+  stampGlobalTenancyMeta(built, entity);
+  return built;
 }

package/src/db/tenant-db.ts

@@ -1,5 +1,9 @@
+import type { EntityTableMeta } from "@cosmicdrift/kumiko-types/entity-table-meta-types";
+import type { EscapeHatchDeclaration } from "@cosmicdrift/kumiko-types/handlers";
 import { KUMIKO_NAME_SYMBOL, type SchemaTable } from "@cosmicdrift/kumiko-types/schema-table-types";
+import type { TenancyBrand } from "@cosmicdrift/kumiko-types/tenancy-brand";
 import {
+  type GlobalTableDb,
   SYSTEM_SCOPE_CHECK_BRAND,
   type TenantDb,
   type TenantDbMode,
@@ -95,6 +99,13 @@ export function createUncheckedSystemDb(
       return db;
     },
 
+    unsafeRaw(reason) {
+      if (reason.trim().length === 0) {
+        throw new Error("unsafeRaw requires a non-empty reason");
+      }
+      return db.raw;
+    },
+
     outsideTransaction: {
       assertTenantMatch(tenantId) {
         if (tenantId !== db.tenantId) {
@@ -120,9 +131,10 @@ export function castTenantRows<T>(rows: readonly Record<string, unknown>[]): rea
   return rows as unknown as readonly T[];
 }
 
-function tableNameOf(table: Table): string {
-  const sym = table[KUMIKO_NAME_SYMBOL];
-  return typeof sym === "string" ? sym : "<unknown>";
+function tableNameOf(table: Table | EntityTableMeta): string {
+  const sym = (table as Record<symbol, unknown>)[KUMIKO_NAME_SYMBOL];
+  if (typeof sym === "string") return sym;
+  return asEntityTableMeta(table)?.tableName ?? "<unknown>";
 }
 
 // Checks the canonical EntityTableMeta (branded EntityTable's KUMIKO_META_SYMBOL
@@ -143,12 +155,14 @@ 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,
 ): TenantDb {
   if (meter) registerStandardMetrics(meter);
 
   function withDbSpan<T>(
     operation: "select" | "insert" | "update" | "delete",
-    table: Table,
+    table: Table | EntityTableMeta,
     runner: () => Promise<T>,
   ): Promise<T> {
     signal?.throwIfAborted();
@@ -227,10 +241,78 @@ export function createTenantDb(
     return { ...data, tenantId };
   }
 
+  function missingEscapeHatch(table: Table | EntityTableMeta): AccessDeniedError | undefined {
+    if (escapeHatch && escapeHatch.reason.trim().length > 0) return undefined;
+    return new AccessDeniedError({
+      message:
+        `db.global(${tableNameOf(table)}): write rejected — declare ` +
+        `\`escapeHatch: { reason: "..." }\` on the write handler to allow ` +
+        "writes through db.global().",
+    });
+  }
+
+  function globalTable<TTable extends (SchemaTable | EntityTableMeta) & TenancyBrand<"global">>(
+    table: TTable,
+  ): GlobalTableDb<TTable> {
+    const meta = asEntityTableMeta(table);
+    if (meta?.tenancy !== "global") {
+      throw new AccessDeniedError({
+        message: `db.global(${tableNameOf(table)}): table is not declared \`tenancy: "global"\`.`,
+      });
+    }
+    return {
+      selectMany<T = Record<string, unknown>>(
+        where?: WhereObject,
+        options?: SelectOptions,
+      ): Promise<readonly T[]> {
+        return withDbSpan("select", table, async () => bunSelectMany<T>(db, table, where, options));
+      },
+      fetchOne<T = Record<string, unknown>>(where: WhereObject): Promise<T | undefined> {
+        return withDbSpan("select", table, async () => bunFetchOne<T>(db, table, where));
+      },
+      insertOne<T = Record<string, unknown>>(
+        values: Record<string, unknown>,
+      ): Promise<T | undefined> {
+        const denied = missingEscapeHatch(table);
+        if (denied) return Promise.reject(denied);
+        return withDbSpan("insert", table, async () => bunInsertOne<T>(db, table, values));
+      },
+      updateMany<T = Record<string, unknown>>(
+        set: Record<string, unknown>,
+        where: WhereObject,
+      ): Promise<readonly T[]> {
+        const denied = missingEscapeHatch(table);
+        if (denied) return Promise.reject(denied);
+        if (!where || Object.keys(where).length === 0) {
+          return Promise.reject(
+            new Error(
+              "db.global().updateMany without where would mass-update every tenant's rows. Pass at least one where condition.",
+            ),
+          );
+        }
+        return withDbSpan("update", table, async () => bunUpdateMany<T>(db, table, set, where));
+      },
+      deleteMany(where: WhereObject): Promise<void> {
+        const denied = missingEscapeHatch(table);
+        if (denied) return Promise.reject(denied);
+        if (!where || Object.keys(where).length === 0) {
+          return Promise.reject(
+            new Error(
+              "db.global().deleteMany without where would mass-delete every tenant's rows. Pass at least one where condition.",
+            ),
+          );
+        }
+        return withDbSpan("delete", table, async () => bunDeleteMany(db, table, where));
+      },
+      // @cast-boundary type-brand — GlobalWrites is only present in the type when TTable is not ExecutorOnly; the object above always carries the methods.
+    } as GlobalTableDb<TTable>;
+  }
+
   return {
     tenantId,
     mode,
     raw: db,
+    global: globalTable,
 
     selectMany<T = Record<string, unknown>>(
       table: Table,

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

@@ -578,41 +578,42 @@ describe("boot-validator", () => {
   // --- Handler access validation (default-deny) ---
 
   test("throws when a write handler has no access rule", () => {
-    const features = [
+    // Access is a required option since fw#2855 — the registrar itself throws
+    // before validateBoot ever runs (was: caught at boot-validator level).
+    expect(() =>
       defineFeature("a", (r) => {
+        // @ts-expect-error options.access is required since fw#2855.
         r.writeHandler("createThing", z.object({ name: z.string() }), async () => ({
           isSuccess: true as const,
           data: {},
         }));
       }),
-    ];
-    expect(() => validateBoot(features)).toThrow(/a:write:createThing.*missing an access rule/i);
+    ).toThrow(/requires schema \+ handler \+ options\.access/);
   });
 
   test("throws when a query handler has no access rule", () => {
-    const features = [
+    expect(() =>
       defineFeature("a", (r) => {
+        // @ts-expect-error options.access is required since fw#2855.
         r.queryHandler("list", z.object({}), async () => []);
       }),
-    ];
-    expect(() => validateBoot(features)).toThrow(/a:query:list.*missing an access rule/i);
+    ).toThrow(/requires schema \+ handler \+ options\.access/);
   });
 
-  test("registerEntityCrud without access options fails boot (no implicit openToAll)", () => {
+  test("registerEntityCrud without access options fails registration (no implicit openToAll)", () => {
     const widgetEntity = createEntity({
       table: "phase0_widgets",
       fields: {
         name: createTextField({ required: true, personal: false, reason: "test_fixture" }),
       },
     });
-    const features = [
+    // Access is required since fw#2855 — registerEntityCrud now throws at
+    // registration time (was: caught at boot-validator level).
+    expect(() =>
       defineFeature("phase0", (r) => {
         registerEntityCrud(r, "widget", widgetEntity);
       }),
-    ];
-    expect(() => validateBoot(features)).toThrow(
-      /phase0:write:widget:create.*missing an access rule/i,
-    );
+    ).toThrow(/no access rule resolved/i);
   });
 
   test("accepts role-based access rule", () => {
@@ -684,12 +685,12 @@ describe("boot-validator", () => {
   });
 
   test("throws when a stream handler has no access rule", () => {
-    const features = [
+    expect(() =>
       defineFeature("a", (r) => {
+        // @ts-expect-error options.access is required since fw#2855.
         r.streamHandler("chat:complete", z.object({}), async function* () {});
       }),
-    ];
-    expect(() => validateBoot(features)).toThrow(/a:stream:chat:complete.*missing an access rule/i);
+    ).toThrow(/requires schema \+ handler \+ options\.access/);
   });
 
   test("object-form streamHandler with access rule passes boot", () => {
@@ -3167,7 +3168,10 @@ describe("boot-validator", () => {
   // Post-save navigation target, same validation as actionForm's redirect:
   // short screen-ID, same feature, must resolve to a registered screen.
   describe("entityEdit redirect", () => {
-    function makeFeature(redirect?: string, extraScreens: readonly string[] = []) {
+    function makeFeature(
+      redirect?: string | { readonly screen: string; readonly idFrom: string },
+      extraScreens: readonly string[] = [],
+    ) {
       return defineFeature("shop", (r) => {
         r.entity(
           "product",
@@ -3224,6 +3228,27 @@ describe("boot-validator", () => {
         /redirect "statements:screen:ghost-screen" does not resolve to a registered screen/,
       );
     });
+
+    // --- redirect object form with idFrom (same rule as actionForm's) ---
+    test("redirect object → existing screen-id → kein Throw", () => {
+      expect(() =>
+        validateBoot([
+          makeFeature({ screen: "product-list", idFrom: "parentId" }, ["product-list"]),
+        ]),
+      ).not.toThrow();
+    });
+
+    test("redirect object → unknown screen-id → Throw", () => {
+      expect(() =>
+        validateBoot([makeFeature({ screen: "ghost-screen", idFrom: "parentId" })]),
+      ).toThrow(/redirect "ghost-screen" does not resolve to a registered screen/);
+    });
+
+    test("redirect object mit leerem idFrom → Throw", () => {
+      expect(() =>
+        validateBoot([makeFeature({ screen: "product-list", idFrom: "  " }, ["product-list"])]),
+      ).toThrow(/redirect\.idFrom is empty/);
+    });
   });
 
   // --- no-widget field types + required (#1925) ---