@cosmicdrift/kumiko-framework 0.269.2 → 0.273.0

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.integration.test.ts

@@ -38,7 +38,7 @@ const derivativesTestFeature = defineFeature("derivativestest", (r) => {
       );
       return { isSuccess: true as const, data: result };
     },
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 
   // Catches the error INSIDE the handler (not via HTTP serialization) so the
@@ -69,7 +69,7 @@ const derivativesTestFeature = defineFeature("derivativestest", (r) => {
         };
       }
     },
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 
   r.job("record", { trigger: { manual: true }, runIn: "worker" }, async (payload, ctx) => {

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-dashboard.test.ts

@@ -19,10 +19,10 @@ function dashboardFeature(
 ) {
   return defineFeature("demo", (r) => {
     r.queryHandler("incident:open-count", z.object({}), async () => ({ count: 3 }), {
-      access: { openToAll: true },
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
     });
     r.queryHandler("incident:latest", z.object({}), async () => ({ rows: [], nextCursor: null }), {
-      access: { openToAll: true },
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
     });
     r.screen({
       id: "overview",
@@ -245,10 +245,10 @@ describe("validateBoot — dashboard screens", () => {
 
 const catalogFeature = defineFeature("catalog", (r) => {
   r.queryHandler("items:list", z.object({}), async () => ({ rows: [], nextCursor: null }), {
-    access: { openToAll: true },
+    access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
   });
   r.queryHandler("items:status", z.object({}), async () => ({ enabled: true }), {
-    access: { openToAll: true },
+    access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
   });
   r.screen({
     id: "items",
@@ -289,7 +289,7 @@ describe("validateBoot — dashboard screen panels (fw#2841)", () => {
   test("accepts a same-feature short id", () => {
     const feature = defineFeature("demo", (r) => {
       r.queryHandler("items:list", z.object({}), async () => ({ rows: [], nextCursor: null }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
       r.screen({
         id: "items",

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();
+  });
+});

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

@@ -50,7 +50,7 @@ function stubListHandler(r: any, entityName: string): void {
     name: `${entityName}:list`,
     schema: z.object({}),
     handler: async () => ({ rows: [], nextCursor: null }) as never,
-    access: { openToAll: true },
+    access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
   });
 }