@cosmicdrift/kumiko-framework 0.270.0 → 0.273.0

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

@@ -30,6 +30,7 @@ import {
   tryMapUniqueViolation,
 } from "./event-store-executor-context";
 import { runInSavepointIfSupported } from "./query";
+import { tenantDbRunner } from "./tenant-db-runner";
 
 // Art. 17 erasure runs as the framework operator, not as a row owner; a
 // per-role ownership map can never cover it, and a silent deny means the
@@ -117,6 +118,7 @@ export function createWriteVerbs(
 
   return {
     async create(payload, user, db, options) {
+      const runner = tenantDbRunner(db);
       if (isForeignTenantOnGlobalEntity(entity, payload["tenantId"])) {
         throw new AccessDeniedError({
           message:
@@ -215,9 +217,9 @@ export function createWriteVerbs(
         // of the version_conflict this catch classifies. runInSavepointIfSupported
         // confines the failed INSERT to a nested scope that rolls back on
         // its own (same pattern as ctx.tryAppendEvent), and falls back to a
-        // plain call when db.raw is a bare pool connection with no active
+        // plain call when the runner is a bare pool connection with no active
         // transaction to poison (seeds/tests calling the executor directly).
-        event = await runInSavepointIfSupported(db.raw, async (sp) =>
+        event = await runInSavepointIfSupported(runner, async (sp) =>
           append(sp, {
             aggregateId,
             aggregateType: entityName,
@@ -232,7 +234,7 @@ export function createWriteVerbs(
         if (e instanceof EventStoreVersionConflict) {
           let currentVersion = -1;
           try {
-            currentVersion = await getStreamVersion(db.raw, aggregateId, streamTenantFor(user));
+            currentVersion = await getStreamVersion(runner, aggregateId, streamTenantFor(user));
           } catch {
             // Lookup failure — keep the sentinel.
           }
@@ -268,7 +270,7 @@ export function createWriteVerbs(
       // failed INSERT back; the error still propagates and stays catchable.
       let result: Awaited<ReturnType<typeof applyEntityEvent>>;
       try {
-        result = await runInSavepointIfSupported(db.raw, async (sp) =>
+        result = await runInSavepointIfSupported(runner, async (sp) =>
           applyEntityEvent(event, table, entity, sp),
         );
       } catch (e) {
@@ -308,6 +310,7 @@ export function createWriteVerbs(
     },
 
     async update(payload, user, db, updateOptions) {
+      const runner = tenantDbRunner(db);
       if (isForeignTenantOnGlobalEntity(entity, payload.changes["tenantId"])) {
         throw new AccessDeniedError({
           message:
@@ -397,7 +400,7 @@ export function createWriteVerbs(
       // trip `events_aggregate_version_uq` (tenant_id, aggregate_id, version)
       // with version_conflict.
       const currentVersion = await getStreamVersion(
-        db.raw,
+        runner,
         String(payload.id),
         streamTenantFor(user),
       );
@@ -452,7 +455,7 @@ export function createWriteVerbs(
         // Savepoint-scoped — see the create() append() above for why:
         // confines a losing writer's unique-violation to a nested scope
         // instead of poisoning the whole outer transaction.
-        const event = await runInSavepointIfSupported(db.raw, (sp) =>
+        const event = await runInSavepointIfSupported(runner, (sp) =>
           append(sp, {
             aggregateId: String(payload.id),
             aggregateType: entityName,
@@ -480,7 +483,7 @@ export function createWriteVerbs(
         // failed nested one throws 500 instead of failing cleanly.
         let result: Awaited<ReturnType<typeof applyEntityEvent>>;
         try {
-          result = await runInSavepointIfSupported(db.raw, async (sp) =>
+          result = await runInSavepointIfSupported(runner, async (sp) =>
             applyEntityEvent(event, table, entity, sp),
           );
         } catch (e) {
@@ -539,6 +542,7 @@ export function createWriteVerbs(
     },
 
     async delete(payload, user, db) {
+      const runner = tenantDbRunner(db);
       const existing = await loadById(payload.id, db);
       if (!existing) return writeFailure(new NotFoundError(entityName, payload.id));
 
@@ -565,7 +569,7 @@ export function createWriteVerbs(
 
       // Stream-version authoritative (see update() for rationale).
       const currentVersion = await getStreamVersion(
-        db.raw,
+        runner,
         String(payload.id),
         streamTenantFor(user),
       );
@@ -578,7 +582,7 @@ export function createWriteVerbs(
       // land in the immutable log.
       let event: Awaited<ReturnType<typeof append>>;
       try {
-        event = await runInSavepointIfSupported(db.raw, async (sp) =>
+        event = await runInSavepointIfSupported(runner, async (sp) =>
           append(sp, {
             aggregateId: String(payload.id),
             aggregateType: entityName,
@@ -606,7 +610,7 @@ export function createWriteVerbs(
       }
 
       // Live==Rebuild via applyEntityEvent. Savepoint like create/update.
-      const deleteResult = await runInSavepointIfSupported(db.raw, async (sp) =>
+      const deleteResult = await runInSavepointIfSupported(runner, async (sp) =>
         applyEntityEvent(event, table, entity, sp),
       );
       if (deleteResult.kind !== "applied") {
@@ -636,6 +640,7 @@ export function createWriteVerbs(
     // the erasure replays on rebuild (created → forgotten → row gone). Loads
     // without the isDeleted filter so trashed (soft-deleted) rows are erased too.
     async forget(payload, user, db) {
+      const runner = tenantDbRunner(db);
       const raw = await db.fetchOne<Record<string, unknown>>(table, { id: payload.id });
       if (!raw) return writeFailure(new NotFoundError(entityName, payload.id));
       const existing = await decryptForRead(rehydrateCompoundTypes(raw as DbRow, entity) as DbRow);
@@ -660,14 +665,14 @@ export function createWriteVerbs(
 
       await assertStreamWritable(db, payload.id, streamTenantFor(user));
       const currentVersion = await getStreamVersion(
-        db.raw,
+        runner,
         String(payload.id),
         streamTenantFor(user),
       );
 
       let event: Awaited<ReturnType<typeof append>>;
       try {
-        event = await runInSavepointIfSupported(db.raw, async (sp) =>
+        event = await runInSavepointIfSupported(runner, async (sp) =>
           append(sp, {
             aggregateId: String(payload.id),
             aggregateType: entityName,
@@ -696,7 +701,7 @@ export function createWriteVerbs(
         throw e;
       }
 
-      const forgetResult = await runInSavepointIfSupported(db.raw, async (sp) =>
+      const forgetResult = await runInSavepointIfSupported(runner, async (sp) =>
         applyEntityEvent(event, table, entity, sp),
       );
       if (forgetResult.kind !== "applied") {
@@ -722,6 +727,7 @@ export function createWriteVerbs(
     },
 
     async restore(payload, user, db) {
+      const runner = tenantDbRunner(db);
       if (!softDelete) {
         return writeFailure(
           new UnprocessableError("soft_delete_not_enabled", {
@@ -731,8 +737,8 @@ export function createWriteVerbs(
       }
 
       // Tenant boundary: db.fetchOne applies TenantDb's tenant predicate,
-      // selectMany(db.raw, ...) did not — any caller could un-delete a foreign
-      // tenant's row by id. "system"-mode dbs (r.systemScope() / crossTenant
+      // selectMany(runner, ...) did not — any caller could un-delete a foreign
+      // tenant's row by id. "system"-mode dbs (r.systemScope() / escapeHatch
       // handlers) still read unfiltered. No isDeleted filter here: restore
       // targets exactly the soft-deleted row.
       const row = await db.fetchOne(table, { id: payload.id });
@@ -766,7 +772,7 @@ export function createWriteVerbs(
 
       // Stream-version authoritative (see update() for rationale).
       const currentVersion = await getStreamVersion(
-        db.raw,
+        runner,
         String(payload.id),
         streamTenantFor(user),
       );
@@ -777,7 +783,7 @@ export function createWriteVerbs(
       // already ciphertext, no re-encrypt needed.
       let event: Awaited<ReturnType<typeof append>>;
       try {
-        event = await runInSavepointIfSupported(db.raw, (sp) =>
+        event = await runInSavepointIfSupported(runner, (sp) =>
           append(sp, {
             aggregateId: String(payload.id),
             aggregateType: entityName,
@@ -807,7 +813,7 @@ export function createWriteVerbs(
       // Live==Rebuild via applyEntityEvent. Restore only writes isDeleted=false
       // plus the version bump, so there is no sensitive-field drift and no
       // payload override is needed.
-      const restoreResult = await runInSavepointIfSupported(db.raw, async (sp) =>
+      const restoreResult = await runInSavepointIfSupported(runner, async (sp) =>
         applyEntityEvent(event, table, entity, sp),
       );
       if (restoreResult.kind !== "applied" || restoreResult.row === null) {

package/src/db/queries/shadow-swap.ts

@@ -105,6 +105,40 @@ export async function assertLiveColumnsMatchMeta(
   );
 }
 
+// EntityTableMeta carries no RLS/policies, so the swap would silently drop them (#2907).
+export async function assertLiveTableHasNoRowLevelSecurity(
+  tx: AnyDb,
+  tableName: string,
+  projectionName?: string,
+): Promise<void> {
+  const rows = await asRawClient(tx).unsafe<{
+    rls_enabled: boolean;
+    rls_forced: boolean;
+    policy_count: number;
+  }>(
+    `SELECT c.relrowsecurity AS rls_enabled, c.relforcerowsecurity AS rls_forced,
+       (SELECT count(*)::int FROM pg_policy p WHERE p.polrelid = c.oid) AS policy_count
+     FROM pg_class c
+     JOIN pg_namespace n ON n.oid = c.relnamespace
+     WHERE n.nspname = 'public' AND c.relname = $1`,
+    [tableName],
+  );
+  const row = rows[0];
+  // skip: no live table yet — nothing to have RLS on
+  if (!row) return;
+  // skip: no RLS flags and no policies — nothing the swap could drop
+  if (!row.rls_enabled && !row.rls_forced && row.policy_count === 0) return;
+  const context =
+    projectionName !== undefined ? `projection-rebuild "${projectionName}"` : "shadow swap";
+  throw new Error(
+    `${context}: live table "${tableName}" has row level security (enabled: ${row.rls_enabled}, ` +
+      `forced: ${row.rls_forced}, policies: ${row.policy_count}). The shadow swap rebuilds the table ` +
+      "from EntityTableMeta and would silently drop RLS and every policy. Kumiko does not support RLS " +
+      "on rebuildable tables — see kumiko-platform docs/plans/rls-evaluation.md. Rebuild aborted; live " +
+      "table untouched.",
+  );
+}
+
 // Runs INSIDE the rebuild tx, AFTER the state/consumer row lock is taken.
 // Points search_path at the shadow schema (SET LOCAL → auto-reset on commit or
 // rollback), drops any leftover shadow from a crashed run, then builds the
@@ -300,6 +334,8 @@ export async function countColumnDrift(
 // object depends on the live table the swap fails loud and the whole rebuild
 // rolls back, leaving the old table untouched.
 export async function swapShadowIntoLive(tx: AnyDb, tableName: string): Promise<void> {
+  // Re-checked right before DROP: RLS could have been enabled after the early check.
+  await assertLiveTableHasNoRowLevelSecurity(tx, tableName);
   const raw = asRawClient(tx);
   const ident = quoteTableIdent(tableName);
   await raw.unsafe(`DROP TABLE public.${ident}`);

package/src/db/replay-migration-sql.ts

@@ -84,7 +84,7 @@ const SHAPE_NEUTRAL_ALTER_CLAUSE_RE = new RegExp(
     `ALTER COLUMN\\s+${IDENT}\\s+(SET|DROP)\\s+NOT NULL\\b`,
     `ALTER COLUMN\\s+${IDENT}\\s+(SET DEFAULT\\b|DROP DEFAULT\\b)`,
     `(ADD|DROP)\\s+CONSTRAINT\\s+${IDENT}`,
-    `\\b(ENABLE|DISABLE)\\s+ROW LEVEL SECURITY\\b`,
+    `\\b(ENABLE|DISABLE|(NO\\s+)?FORCE)\\s+ROW LEVEL SECURITY\\b`,
     `^OWNER TO\\b`,
   ].join("|"),
   "gi",
@@ -149,9 +149,9 @@ function applyStatement(
       else table.columns.delete(name);
     }
     // Shape-neutral clauses (ALTER COLUMN TYPE, SET/DROP NOT NULL, SET/DROP
-    // DEFAULT, ADD/DROP CONSTRAINT, ENABLE/DISABLE ROW LEVEL SECURITY, OWNER
-    // TO) — none add/remove/rename a column, so this replay (which only
-    // tracks column presence) correctly has nothing to do for them.
+    // DEFAULT, ADD/DROP CONSTRAINT, ENABLE/DISABLE/[NO] FORCE ROW LEVEL
+    // SECURITY, OWNER TO) — none add/remove/rename a column, so this replay
+    // (which only tracks column presence) correctly has nothing to do for them.
     if (alterBody.match(SHAPE_NEUTRAL_ALTER_CLAUSE_RE)) matchedAClause = true;
     // An ALTER TABLE that matched the outer "ALTER TABLE <name> <body>" shape
     // but whose body contains no recognized clause (e.g. RENAME TO/RENAME
@@ -177,7 +177,7 @@ function applyStatement(
         `starts with CREATE/ALTER/DROP TABLE but matched none of the replay's ` +
         `recognized patterns (CREATE TABLE, DROP TABLE, ALTER TABLE ADD/DROP ` +
         `COLUMN, ALTER COLUMN ... TYPE, SET/DROP NOT NULL, SET/DROP DEFAULT, ` +
-        `ADD/DROP CONSTRAINT, ENABLE/DISABLE ROW LEVEL SECURITY, OWNER TO — ` +
+        `ADD/DROP CONSTRAINT, ENABLE/DISABLE/[NO] FORCE ROW LEVEL SECURITY, OWNER TO — ` +
         `optionally-quoted identifiers). Likely RENAME TO/RENAME COLUMN (real ` +
         `identity change, not trackable here) or genuinely unparsed hand-written ` +
         `DDL. Statement: ${prefix}${statement.length > 200 ? "…" : ""}`,

package/src/db/tenant-db-runner.ts

@@ -0,0 +1,23 @@
+import type { TenantDb } from "@cosmicdrift/kumiko-types/tenant-db-types";
+import { InternalError } from "../errors";
+import type { DbRunner } from "./connection";
+
+const tenantDbRunners = new WeakMap<TenantDb, DbRunner>();
+
+export function bindTenantDbRunner(tenantDb: TenantDb, runner: DbRunner): void {
+  tenantDbRunners.set(tenantDb, runner);
+}
+
+// WeakMap.get never reads a property off tenantDb — safe even when tenantDb is a
+// throwing systemScope guard Proxy that rejects every property access.
+export function tenantDbRunner(tenantDb: TenantDb): DbRunner {
+  const runner = tenantDbRunners.get(tenantDb);
+  if (!runner) {
+    throw new InternalError({
+      message:
+        "framework infrastructure received a TenantDb not built by createTenantDb (or a " +
+        "fail-closed systemScope guard) — no connection bound.",
+    });
+  }
+  return runner;
+}

package/src/db/tenant-db.ts

@@ -1,5 +1,8 @@
 import type { EntityTableMeta } from "@cosmicdrift/kumiko-types/entity-table-meta-types";
-import type { EscapeHatchDeclaration } from "@cosmicdrift/kumiko-types/handlers";
+import type {
+  EscapeHatchDeclaration,
+  EscapeHatchReporter,
+} 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 {
@@ -23,7 +26,9 @@ import {
 import { SYSTEM_TENANT_ID, type TenantId } from "../engine/types/identifiers";
 import { AccessDeniedError, InternalError } from "../errors";
 import { emitDbQuery, type Meter, registerStandardMetrics, type Tracer } from "../observability";
+import { fallbackEscapeHatchReporter } from "../pipeline/escape-hatch-report";
 import type { DbRunner } from "./connection";
+import { bindTenantDbRunner, tenantDbRunner } from "./tenant-db-runner";
 
 type Table = SchemaTable;
 
@@ -34,6 +39,30 @@ export {
   type UncheckedSystemDb,
 } from "@cosmicdrift/kumiko-types/tenant-db-types";
 
+const declaredUnsafeRawRunners = new WeakMap<
+  TenantDb | UncheckedSystemDb,
+  (reason: string) => DbRunner
+>();
+
+// Framework-private (not re-exported from db/index.ts): same grant check + audit as unsafeRaw, for engine forwarding.
+export function unsafeRawForDeclaredStep(
+  holder: TenantDb | UncheckedSystemDb,
+  reason: string,
+): DbRunner {
+  if (reason.trim().length === 0) {
+    throw new Error("unsafeRawForDeclaredStep requires a non-empty reason");
+  }
+  const runner = declaredUnsafeRawRunners.get(holder);
+  if (!runner) {
+    throw new InternalError({
+      message:
+        "unsafeRawForDeclaredStep received a holder not built by createTenantDb or " +
+        "createUncheckedSystemDb — no declared unsafeRaw runner bound.",
+    });
+  }
+  return runner(reason);
+}
+
 // buildHandlerContext (pipeline/dispatch-shared.ts) always builds "system"
 // mode from the caller's own tenantId, never a foreign one.
 //
@@ -45,6 +74,7 @@ export {
 export function createUncheckedSystemDb(
   db: TenantDb,
   dbOutsideTransaction?: TenantDb,
+  report: EscapeHatchReporter = fallbackEscapeHatchReporter(db.tenantId),
 ): UncheckedSystemDb {
   const allowedTenantIds: readonly TenantId[] = [db.tenantId, SYSTEM_TENANT_ID];
 
@@ -65,7 +95,15 @@ export function createUncheckedSystemDb(
     return dbOutsideTransaction;
   }
 
-  return {
+  function grantedUnsafeRawRunner(reason: string): DbRunner {
+    if (reason.trim().length === 0) {
+      throw new Error("unsafeRaw requires a non-empty reason");
+    }
+    report("unsafe-raw", reason);
+    return tenantDbRunner(db);
+  }
+
+  const uncheckedSystemDb: UncheckedSystemDb = {
     [SYSTEM_SCOPE_CHECK_BRAND]: true,
 
     assertTenantMatch(tenantId) {
@@ -96,15 +134,11 @@ export function createUncheckedSystemDb(
       if (reason.trim().length === 0) {
         throw new Error("acknowledgeCrossTenant requires a non-empty reason");
       }
+      report("acknowledge-cross-tenant", reason);
       return db;
     },
 
-    unsafeRaw(reason) {
-      if (reason.trim().length === 0) {
-        throw new Error("unsafeRaw requires a non-empty reason");
-      }
-      return db.raw;
-    },
+    unsafeRaw: grantedUnsafeRawRunner,
 
     outsideTransaction: {
       assertTenantMatch(tenantId) {
@@ -120,10 +154,14 @@ export function createUncheckedSystemDb(
         if (reason.trim().length === 0) {
           throw new Error("acknowledgeCrossTenant requires a non-empty reason");
         }
-        return requireOutsideTransactionDb();
+        const result = requireOutsideTransactionDb();
+        report("acknowledge-cross-tenant", reason);
+        return result;
       },
     },
   };
+  declaredUnsafeRawRunners.set(uncheckedSystemDb, grantedUnsafeRawRunner);
+  return uncheckedSystemDb;
 }
 
 // @cast-boundary tenant-db-row
@@ -151,7 +189,7 @@ function isForeignTenantId(tenantIdValue: unknown): boolean {
 // `table.tenantId` property read — the latter only exists on branded EntityTables
 // and silently returned false (no tenant filter!) for plain EntityTableMeta
 // tables like unmanaged direct-write stores, e.g. userSessionTable.
-function hasTenantColumn(table: Table | EntityTableMeta): boolean {
+export function hasTenantColumn(table: Table | EntityTableMeta): boolean {
   const meta = asEntityTableMeta(table);
   if (meta) return meta.columns.some((c) => c.name === "tenant_id");
   return (table as Record<string, unknown>)["tenantId"] !== undefined;
@@ -162,6 +200,7 @@ function hasTenantColumn(table: Table | EntityTableMeta): boolean {
 export type TenantDbGrants = {
   readonly globalWrites?: EscapeHatchDeclaration;
   readonly unsafeRaw?: EscapeHatchDeclaration;
+  readonly report?: EscapeHatchReporter;
 };
 
 const unsafeRawRebinders = new WeakMap<
@@ -179,6 +218,24 @@ export function withUnsafeRawGrant(
   return rebind ? rebind(grant) : tenantDb;
 }
 
+const crossTenantRebinders = new WeakMap<TenantDb, (reason: string) => TenantDb>();
+
+// Framework-private (not re-exported from db/index.ts): lifting the tenant filter needs a registered declaration.
+export function acknowledgeConventionCrossTenant(tenantDb: TenantDb, reason: string): TenantDb {
+  if (reason.trim().length === 0) {
+    throw new Error("acknowledgeConventionCrossTenant requires a non-empty reason");
+  }
+  const rebind = crossTenantRebinders.get(tenantDb);
+  if (!rebind) {
+    throw new InternalError({
+      message:
+        "acknowledgeConventionCrossTenant received a TenantDb not built by createTenantDb — " +
+        "no cross-tenant rebinder bound.",
+    });
+  }
+  return rebind(reason);
+}
+
 export function createTenantDb(
   db: DbRunner,
   tenantId: TenantId,
@@ -189,6 +246,7 @@ export function createTenantDb(
   grants?: TenantDbGrants,
 ): TenantDb {
   if (meter) registerStandardMetrics(meter);
+  const report = grants?.report ?? fallbackEscapeHatchReporter(tenantId);
 
   function withDbSpan<T>(
     operation: "select" | "insert" | "update" | "delete",
@@ -281,6 +339,10 @@ export function createTenantDb(
     });
   }
 
+  function globalWriteReason(): string {
+    return grants?.globalWrites?.reason ?? "";
+  }
+
   function foreignTenantOnGlobalWrite(
     table: Table | EntityTableMeta,
     tenantIdValue: unknown,
@@ -315,6 +377,7 @@ export function createTenantDb(
         const denied =
           missingEscapeHatch(table) ?? foreignTenantOnGlobalWrite(table, values["tenantId"]);
         if (denied) return Promise.reject(denied);
+        report("global-write", globalWriteReason());
         return withDbSpan("insert", table, async () => bunInsertOne<T>(db, table, values));
       },
       updateMany<T = Record<string, unknown>>(
@@ -331,6 +394,7 @@ export function createTenantDb(
             ),
           );
         }
+        report("global-write", globalWriteReason());
         return withDbSpan("update", table, async () => bunUpdateMany<T>(db, table, set, where));
       },
       deleteMany(where: WhereObject): Promise<void> {
@@ -343,31 +407,34 @@ export function createTenantDb(
             ),
           );
         }
+        report("global-write", globalWriteReason());
         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>;
   }
 
+  function grantedUnsafeRawRunner(reason: string): DbRunner {
+    if (reason.trim().length === 0) {
+      throw new Error("unsafeRaw requires a non-empty reason");
+    }
+    if (!hasGrant(grants?.unsafeRaw)) {
+      throw new AccessDeniedError({
+        message:
+          'ctx.db.unsafeRaw(reason): rejected — declare `escapeHatch: { reason: "..." }` on ' +
+          "the handler or hook to allow unsafeRaw.",
+      });
+    }
+    report("unsafe-raw", reason);
+    return db;
+  }
+
   const tenantDb: TenantDb = {
     tenantId,
     mode,
-    raw: db,
     global: globalTable,
 
-    unsafeRaw(reason: string): DbRunner {
-      if (reason.trim().length === 0) {
-        throw new Error("unsafeRaw requires a non-empty reason");
-      }
-      if (!hasGrant(grants?.unsafeRaw)) {
-        throw new AccessDeniedError({
-          message:
-            'ctx.db.unsafeRaw(reason): rejected — declare `escapeHatch: { reason: "..." }` on ' +
-            "the handler or hook to allow unsafeRaw.",
-        });
-      }
-      return db;
-    },
+    unsafeRaw: grantedUnsafeRawRunner,
 
     selectMany<T = Record<string, unknown>>(
       table: Table | EntityTableMeta,
@@ -436,9 +503,15 @@ export function createTenantDb(
     },
   };
 
+  declaredUnsafeRawRunners.set(tenantDb, grantedUnsafeRawRunner);
   unsafeRawRebinders.set(tenantDb, (grant) =>
     createTenantDb(db, tenantId, mode, tracer, meter, signal, { ...grants, unsafeRaw: grant }),
   );
+  crossTenantRebinders.set(tenantDb, (reason) => {
+    report("acknowledge-cross-tenant", reason);
+    return createTenantDb(db, tenantId, "system", tracer, meter, signal, grants);
+  });
+  bindTenantDbRunner(tenantDb, db);
   return tenantDb;
 }
 

package/src/derivatives/__tests__/derivatives-context.test.ts

@@ -47,7 +47,6 @@ function fakeDbWithFileRef(row: { storageKey: string; mimeType: string }): unkno
     isDeleted: false,
   };
   return {
-    raw: { unsafe: () => {} },
     tenantId: TENANT_ID,
     selectMany: async (_table: unknown, where?: Record<string, unknown>) => {
       const matches = Object.entries(where ?? {}).every(([key, value]) => canned[key] === value);

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

@@ -0,0 +1,116 @@
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { withBootValidatorFixture } from "../../testing/boot-validator-fixture";
+import { validateBoot as validateBootRaw } from "../boot-validator";
+import { defineFeature } from "../define-feature";
+import { createEntity, createTextField } from "../factories";
+
+function validateBoot(features: Parameters<typeof validateBootRaw>[0]): void {
+  validateBootRaw(withBootValidatorFixture(features));
+}
+
+describe("validateBoot — every screen must resolve its own nav area", () => {
+  test("a screen with no nav entry, no listScreenId and no resolvable parent → Throw naming listScreenId", () => {
+    const feature = defineFeature("app", (r) => {
+      r.nav({ id: "home", label: "app.nav.home" });
+      r.screen({ id: "orphan", type: "custom", renderer: { react: "Orphan" } });
+    });
+    expect(() => validateBoot([feature])).toThrow(/no nav entry and no resolvable list/);
+    expect(() => validateBoot([feature])).toThrow(/listScreenId/);
+  });
+
+  test("the same screen with listScreenId set → no throw", () => {
+    const feature = defineFeature("app", (r) => {
+      r.nav({ id: "home", label: "app.nav.home" });
+      r.screen({
+        id: "orphan-list",
+        type: "custom",
+        renderer: { react: "List" },
+        dormant: true,
+      });
+      r.screen({
+        id: "orphan",
+        type: "custom",
+        renderer: { react: "Orphan" },
+        listScreenId: "orphan-list",
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("resolved via a list screen's rowAction navigate target → no throw", () => {
+    const feature = defineFeature("app", (r) => {
+      r.queryHandler("orphan:list", z.object({}), async () => ({ rows: [], nextCursor: null }), {
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+      });
+      r.nav({ id: "home", label: "app.nav.home", screen: "app:screen:orphan-list" });
+      r.screen({
+        id: "orphan-list",
+        type: "projectionList",
+        query: "app:query:orphan:list",
+        columns: ["name"],
+        rowActions: [{ kind: "navigate", id: "open", label: "Open", screen: "orphan" }],
+      });
+      r.screen({ id: "orphan", type: "custom", renderer: { react: "Orphan" } });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("resolved via a list screen's toolbarAction navigate target → no throw", () => {
+    const feature = defineFeature("app", (r) => {
+      r.queryHandler("orphan:list", z.object({}), async () => ({ rows: [], nextCursor: null }), {
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+      });
+      r.nav({ id: "home", label: "app.nav.home", screen: "app:screen:orphan-list" });
+      r.screen({
+        id: "orphan-list",
+        type: "projectionList",
+        query: "app:query:orphan:list",
+        columns: ["name"],
+        toolbarActions: [{ kind: "navigate", id: "create", label: "Create", screen: "orphan" }],
+      });
+      r.screen({ id: "orphan", type: "custom", renderer: { react: "Orphan" } });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("resolved via an entityList screen of the same entity → no throw", () => {
+    const feature = defineFeature("app", (r) => {
+      r.entity(
+        "widget",
+        createEntity({
+          fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+        }),
+      );
+      r.nav({ id: "home", label: "app.nav.home", screen: "app:screen:widget-list" });
+      r.screen({ id: "widget-list", type: "entityList", entity: "widget", columns: ["name"] });
+      r.screen({
+        id: "widget-edit",
+        type: "entityEdit",
+        entity: "widget",
+        layout: { sections: [{ fields: ["name"] }] },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("dormant: true → no throw even without any other resolution", () => {
+    const feature = defineFeature("app", (r) => {
+      r.nav({ id: "home", label: "app.nav.home" });
+      r.screen({
+        id: "orphan",
+        type: "custom",
+        renderer: { react: "Orphan" },
+        dormant: true,
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("a feature set with no nav entries at all (sample/recipe) → the check does not run", () => {
+    const feature = defineFeature("recipe", (r) => {
+      r.screen({ id: "orphan", type: "custom", renderer: { react: "Orphan" } });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+});