@cosmicdrift/kumiko-framework 0.269.2 → 0.273.0

package/src/engine/__tests__/read-steps-tenant-filter.integration.test.ts

@@ -0,0 +1,215 @@
+// fw#2914 — r.step.read.findOne/findMany now apply the caller's tenant
+// filter by default (own tenant + SYSTEM_TENANT_ID reference rows), like
+// ctx.db method-form reads. Cross-tenant reads need `unsafeAllTenants:
+// { reason }` on the step AND `escapeHatch: { reason }` on the handler,
+// reported as an "unsafe-raw" escape-hatch audit event. Real HTTP calls +
+// setupTestStack — never createTestDispatcher. Modelled on the M.1.5
+// section of pipeline-handler.integration.test.ts and
+// escape-hatch-audit.integration.test.ts.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { table, text, uuid } from "../../db/dialect";
+import { insertOne } from "../../db/query";
+import { defineFeature, defineWriteHandler } from "../../engine";
+import { setupTestStack, type TestStack, TestUsers, unsafePushTables } from "../../stack";
+import { stepsPipeline } from "../pipeline";
+import type { EscapeHatchUseEvent } from "../types";
+
+const readFilterTable = table("fw2914_read_filter_items", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  tenantId: uuid("tenant_id").notNull(),
+  label: text("label").notNull(),
+});
+
+const UNDECLARED_REASON =
+  "fw#2914 integration test — cross-tenant read step without a handler grant";
+const ESCAPED_REASON = "fw#2914 integration test — cross-tenant widget count for read step";
+
+const listSchema = z.object({});
+const listHandler = defineWriteHandler({
+  name: "list",
+  schema: listSchema,
+  access: { roles: ["Admin"] },
+  perform: stepsPipeline<z.infer<typeof listSchema>, { count: number; ids: string[] }>(({ r }) => [
+    r.step.read.findMany("items", { table: readFilterTable }),
+    r.step.return(({ steps }) => {
+      const rows = steps["items"] as readonly { id: string }[];
+      return {
+        isSuccess: true as const,
+        data: { count: rows.length, ids: rows.map((row) => row.id) },
+      };
+    }),
+  ]),
+});
+
+const getSchema = z.object({ id: z.uuid() });
+const getHandler = defineWriteHandler({
+  name: "get",
+  schema: getSchema,
+  access: { roles: ["Admin"] },
+  perform: stepsPipeline<z.infer<typeof getSchema>, { found: boolean; label: string | null }>(
+    ({ event, r }) => [
+      r.step.read.findOne("item", {
+        table: readFilterTable,
+        where: () => ({ id: event.payload.id }),
+      }),
+      r.step.return(({ steps }) => {
+        const row = steps["item"] as { label?: string } | null;
+        return {
+          isSuccess: true as const,
+          data: { found: row !== null, label: row?.label ?? null },
+        };
+      }),
+    ],
+  ),
+});
+
+const listUnsafeUndeclaredSchema = z.object({});
+const listUnsafeUndeclaredHandler = defineWriteHandler({
+  name: "list-unsafe-undeclared",
+  schema: listUnsafeUndeclaredSchema,
+  access: { roles: ["Admin"] },
+  perform: stepsPipeline<z.infer<typeof listUnsafeUndeclaredSchema>, { count: number }>(({ r }) => [
+    r.step.read.findMany("items", {
+      table: readFilterTable,
+      unsafeAllTenants: { reason: UNDECLARED_REASON },
+    }),
+    r.step.return(({ steps }) => ({
+      isSuccess: true as const,
+      data: { count: (steps["items"] as readonly unknown[]).length },
+    })),
+  ]),
+});
+
+const listEscapedSchema = z.object({});
+const listEscapedHandler = defineWriteHandler({
+  name: "list-escaped",
+  schema: listEscapedSchema,
+  access: { roles: ["Admin"] },
+  escapeHatch: { reason: ESCAPED_REASON },
+  perform: stepsPipeline<z.infer<typeof listEscapedSchema>, { count: number }>(({ r }) => [
+    r.step.read.findMany("items", {
+      table: readFilterTable,
+      unsafeAllTenants: { reason: ESCAPED_REASON },
+    }),
+    r.step.return(({ steps }) => ({
+      isSuccess: true as const,
+      data: { count: (steps["items"] as readonly unknown[]).length },
+    })),
+  ]),
+});
+
+const readStepsTenantFilterFeature = defineFeature("read-steps-tenant-filter", (r) => {
+  r.requires.projection("fw2914_read_filter_items");
+  r.writeHandler(listHandler);
+  r.writeHandler(getHandler);
+  r.writeHandler(listUnsafeUndeclaredHandler);
+  r.writeHandler(listEscapedHandler);
+});
+
+const admin = TestUsers.admin;
+const otherTenant = TestUsers.otherTenant;
+
+describe("r.step.read.findOne/findMany tenant-filtering (fw#2914)", () => {
+  let stack: TestStack;
+  const events: EscapeHatchUseEvent[] = [];
+  let adminRowId: string;
+  let otherTenantRowId: string;
+
+  beforeAll(async () => {
+    stack = await setupTestStack({
+      features: [readStepsTenantFilterFeature],
+      extraContext: {
+        _escapeHatchAuditSink: async (event: EscapeHatchUseEvent) => {
+          events.push(event);
+        },
+      },
+    });
+    await unsafePushTables(stack.db, { fw2914_read_filter_items: readFilterTable });
+
+    const adminRow = await insertOne<{ id: string }>(stack.db, readFilterTable, {
+      tenantId: admin.tenantId,
+      label: "admin-row",
+    });
+    const otherRow = await insertOne<{ id: string }>(stack.db, readFilterTable, {
+      tenantId: otherTenant.tenantId,
+      label: "other-tenant-row",
+    });
+    adminRowId = adminRow!.id;
+    otherTenantRowId = otherRow!.id;
+  });
+
+  afterAll(async () => {
+    await stack.cleanup();
+  });
+
+  test("read.findMany returns only the caller's own tenant rows", async () => {
+    const data = await stack.http.writeOk<{ count: number; ids: string[] }>(
+      "read-steps-tenant-filter:write:list",
+      {},
+      admin,
+    );
+
+    expect(data.count).toBe(1);
+    expect(data.ids).toEqual([adminRowId]);
+    expect(data.ids).not.toContain(otherTenantRowId);
+  });
+
+  test("read.findOne returns the row when it belongs to the caller's tenant", async () => {
+    const data = await stack.http.writeOk<{ found: boolean; label: string | null }>(
+      "read-steps-tenant-filter:write:get",
+      { id: adminRowId },
+      admin,
+    );
+
+    expect(data).toEqual({ found: true, label: "admin-row" });
+  });
+
+  test("read.findOne returns null for a row belonging to a different tenant", async () => {
+    const data = await stack.http.writeOk<{ found: boolean; label: string | null }>(
+      "read-steps-tenant-filter:write:get",
+      { id: otherTenantRowId },
+      admin,
+    );
+
+    expect(data).toEqual({ found: false, label: null });
+  });
+
+  test("unsafeAllTenants without escapeHatch on the handler is denied and reports nothing", async () => {
+    events.length = 0;
+
+    const err = await stack.http.writeErr(
+      "read-steps-tenant-filter:write:list-unsafe-undeclared",
+      {},
+      admin,
+    );
+
+    expect(err.httpStatus).toBe(403);
+    expect(err.code).toBe("access_denied");
+    expect(events.filter((e) => e.kind === "unsafe-raw")).toEqual([]);
+  });
+
+  test("unsafeAllTenants with escapeHatch on the handler sees rows across tenants and reports unsafe-raw", async () => {
+    events.length = 0;
+
+    const data = await stack.http.writeOk<{ count: number }>(
+      "read-steps-tenant-filter:write:list-escaped",
+      {},
+      admin,
+    );
+
+    expect(data.count).toBeGreaterThanOrEqual(2);
+
+    const matches = events.filter((e) => e.kind === "unsafe-raw");
+    expect(matches).toEqual([
+      {
+        handler: "read-steps-tenant-filter:write:list-escaped",
+        kind: "unsafe-raw",
+        reason: ESCAPED_REASON,
+        tenantId: admin.tenantId,
+        actor: admin.id,
+      },
+    ]);
+  });
+});

package/src/engine/__tests__/registry.test.ts

@@ -78,13 +78,17 @@ describe("getAllQueryHandlers", () => {
     const taskFeature = defineFeature("registry-test-task", (r) => {
       r.crud("task", taskEntity, {
         write: { access: { roles: ["Admin"] } },
-        read: { access: { openToAll: true } },
+        read: {
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+        },
       });
     });
     const noteFeature = defineFeature("registry-test-note", (r) => {
       r.crud("note", noteEntity, {
         write: { access: { roles: ["Admin"] } },
-        read: { access: { openToAll: true } },
+        read: {
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+        },
       });
     });
 
@@ -109,12 +113,12 @@ describe("getAllStreamHandlers", () => {
   test("returns every registered stream handler, qualified, across multiple features", () => {
     const aiFeature = defineFeature("registry-test-ai", (r) => {
       r.streamHandler("chat:complete", z.object({ prompt: z.string() }), async function* () {}, {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
     });
     const otherFeature = defineFeature("registry-test-other", (r) => {
       r.streamHandler("chat:complete", z.object({ prompt: z.string() }), async function* () {}, {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
     });
 
@@ -137,12 +141,12 @@ describe("getAllStreamHandlers", () => {
   test("duplicate stream-handler short-name across features qualifies independently, no collision", () => {
     const aiFeature = defineFeature("registry-test-dup-a", (r) => {
       r.streamHandler("chat:complete", z.object({}), async function* () {}, {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
     });
     const otherFeature = defineFeature("registry-test-dup-b", (r) => {
       r.streamHandler("chat:complete", z.object({}), async function* () {}, {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
     });
     expect(() => createRegistry([aiFeature, otherFeature])).not.toThrow();
@@ -154,12 +158,12 @@ describe("getAllStreamHandlers", () => {
     // fire) but toKebab() collapses both to the same qualified name.
     const featureA = defineFeature("registry-test-kebab-dup", (r) => {
       r.streamHandler("chat:complete", z.object({}), async function* () {}, {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
     });
     const featureB = defineFeature("registryTestKebabDup", (r) => {
       r.streamHandler("chat:complete", z.object({}), async function* () {}, {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
     });
     expect(() => createRegistry([featureA, featureB])).toThrow(/Duplicate stream handler/);
@@ -173,7 +177,7 @@ describe("getAllStreamHandlers", () => {
         name: "chat:complete",
         schema,
         handler: handlerFn,
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         rateLimit: { per: "ip+handler", limit: 5, windowSeconds: 60 },
       });
     });
@@ -184,7 +188,9 @@ describe("getAllStreamHandlers", () => {
     expect(registered).toBeDefined();
     expect(registered?.schema).toBe(schema);
     expect(registered?.handler).toBe(handlerFn);
-    expect(registered?.access).toEqual({ openToAll: true });
+    expect(registered?.access).toEqual({
+      openToAll: { reason: "test handler callable by any signed-in test user" },
+    });
     expect(registered?.rateLimit).toEqual({ per: "ip+handler", limit: 5, windowSeconds: 60 });
   });
 });
@@ -196,7 +202,7 @@ describe("double-qualified handler names (#1991)", () => {
         "registry-test-ai-orch:query:duplicate-candidates",
         z.object({}),
         async () => ({}),
-        { access: { openToAll: true } },
+        { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
       );
     });
 
@@ -206,7 +212,7 @@ describe("double-qualified handler names (#1991)", () => {
   test("createRegistry allows a sub-structured short name whose entity prefix merely resembles the feature name", () => {
     const feature = defineFeature("registry-test-invoices", (r) => {
       r.queryHandler("invoice:mark-paid", z.object({}), async () => ({}), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
     });
 
@@ -309,7 +315,7 @@ describe("extensionSelector boot-validation", () => {
         "doSomething",
         z.object({}),
         async () => ({ isSuccess: true as const, data: {} }),
-        { access: { openToAll: true } },
+        { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
       );
       r.useExtension("credit-cap", "credit");
     });

package/src/engine/__tests__/required-surface-keys.test.ts

@@ -44,6 +44,22 @@ describe("requiredKeysFromScreen", () => {
     expect(keys).toContain(fieldLabelKey("publicstatus", ACTION_FORM_ENTITY, "title"));
   });
 
+  test("actionForm honors a fieldLabels override, falls back to ACTION_FORM_ENTITY otherwise", () => {
+    const keys = requiredKeysFromScreen("publicstatus", {
+      id: "reschedule-form",
+      type: "actionForm",
+      handler: "publicstatus:write:incident:reschedule",
+      fields: { dueAt: { type: "date" }, note: { type: "text" } },
+      fieldLabels: { dueAt: "publicstatus:override.dueAt" },
+      layout: {
+        sections: [{ fields: ["dueAt", "note"] }],
+      },
+    });
+    expect(keys).toContain("publicstatus:override.dueAt");
+    expect(keys).not.toContain(fieldLabelKey("publicstatus", ACTION_FORM_ENTITY, "dueAt"));
+    expect(keys).toContain(fieldLabelKey("publicstatus", ACTION_FORM_ENTITY, "note"));
+  });
+
   test("entityEdit emits submitLabel + section titles + field labels (override honored)", () => {
     const screen: EntityEditScreenDefinition = {
       id: "component-edit",

package/src/engine/__tests__/screen.test.ts

@@ -4,6 +4,7 @@ import { withBootValidatorFixture } from "../../testing/boot-validator-fixture";
 import { validateBoot as validateBootRaw } from "../boot-validator";
 import { createTenantConfig } from "../config-helpers";
 import { defineFeature } from "../define-feature";
+import { defineEntityListHandler } from "../entity-handlers";
 import { createDerivedField, createEntity, createTextField } from "../factories";
 import { createRegistry } from "../registry";
 import type { ScreenDefinition } from "../types/screen";
@@ -211,7 +212,7 @@ describe("r.screen() — registration", () => {
     const features = [
       defineFeature("app", (r) => {
         r.queryHandler("foo:detail", z.object({}), async () => ({}), {
-          access: { openToAll: true },
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         });
         r.screen({
           id: "x",
@@ -281,10 +282,10 @@ describe("r.screen() — registration", () => {
     const features = [
       defineFeature("app", (r) => {
         r.queryHandler("foo:detail", z.object({}), async () => ({}), {
-          access: { openToAll: true },
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         });
         r.queryHandler("foo: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: "x",
@@ -345,10 +346,10 @@ describe("r.screen() — registration", () => {
     const features = [
       defineFeature("app", (r) => {
         r.queryHandler("foo:detail", z.object({}), async () => ({}), {
-          access: { openToAll: true },
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         });
         r.queryHandler("foo: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: "x",
@@ -370,10 +371,10 @@ describe("r.screen() — registration", () => {
       const features = [
         defineFeature("app", (r) => {
           r.queryHandler("foo:detail", z.object({}), async () => ({}), {
-            access: { openToAll: true },
+            access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
           });
           r.queryHandler("foo: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: "x",
@@ -400,13 +401,15 @@ describe("r.screen() — registration", () => {
       const features = [
         defineFeature("app", (r) => {
           r.queryHandler("foo:detail", z.object({}), async () => ({}), {
-            access: { openToAll: true },
+            access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
           });
           r.queryHandler(
             "foo:list",
             z.object({ search: z.string().optional() }),
             async () => ({ rows: [], nextCursor: null }),
-            { access: { openToAll: true } },
+            {
+              access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+            },
           );
           r.screen({
             id: "x",
@@ -433,10 +436,10 @@ describe("r.screen() — registration", () => {
       const features = [
         defineFeature("app", (r) => {
           r.queryHandler("foo:detail", z.object({}), async () => ({}), {
-            access: { openToAll: true },
+            access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
           });
           r.queryHandler("foo: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: "x",
@@ -470,13 +473,15 @@ describe("r.screen() — registration", () => {
       const features = [
         defineFeature("app", (r) => {
           r.queryHandler("foo:detail", z.object({}), async () => ({}), {
-            access: { openToAll: true },
+            access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
           });
           r.queryHandler(
             "foo:list",
             z.object({ filters: z.array(z.object({})).optional() }),
             async () => ({ rows: [], nextCursor: null }),
-            { access: { openToAll: true } },
+            {
+              access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+            },
           );
           r.screen({
             id: "x",
@@ -512,13 +517,15 @@ describe("r.screen() — registration", () => {
       const features = [
         defineFeature("app", (r) => {
           r.queryHandler("foo:detail", z.object({}), async () => ({}), {
-            access: { openToAll: true },
+            access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
           });
           r.queryHandler(
             "foo:list",
             z.object({ filters: z.array(z.object({})).optional() }),
             async () => ({ rows: [], nextCursor: null }),
-            { access: { openToAll: true } },
+            {
+              access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+            },
           );
           r.screen({
             id: "x",
@@ -549,6 +556,155 @@ describe("r.screen() — registration", () => {
     });
   });
 
+  describe("relatedList parentFilter", () => {
+    test("rejects parentFilter combined with parentParam on the same section", () => {
+      const features = [
+        defineFeature("app", (r) => {
+          r.queryHandler("foo:detail", z.object({}), async () => ({}), {
+            access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+          });
+          r.queryHandler(
+            "foo:list",
+            z.object({ filter: z.unknown().optional() }),
+            async () => ({ rows: [], nextCursor: null }),
+            {
+              access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+            },
+          );
+          r.screen({
+            id: "x",
+            type: "projectionDetail",
+            query: "app:query:foo:detail",
+            layout: {
+              sections: [
+                {
+                  kind: "relatedList",
+                  title: "s",
+                  query: "app:query:foo:list",
+                  columns: ["name"],
+                  parentParam: "orderId",
+                  parentFilter: { field: "orderId" },
+                },
+              ],
+            },
+          });
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/declares both parentFilter and parentParam/);
+    });
+
+    test("rejects parentFilter when the bound query's schema has no filter parameter", () => {
+      const features = [
+        defineFeature("app", (r) => {
+          r.queryHandler("foo:detail", z.object({}), async () => ({}), {
+            access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+          });
+          r.queryHandler("foo:list", z.object({}), async () => ({ rows: [], nextCursor: null }), {
+            access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+          });
+          r.screen({
+            id: "x",
+            type: "projectionDetail",
+            query: "app:query:foo:detail",
+            layout: {
+              sections: [
+                {
+                  kind: "relatedList",
+                  title: "s",
+                  query: "app:query:foo:list",
+                  columns: ["name"],
+                  parentFilter: { field: "orderId" },
+                },
+              ],
+            },
+          });
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(
+        /declares parentFilter but query.*no "filter" parameter/,
+      );
+    });
+
+    test("rejects parentFilter.field that is not a declared field on the entity behind the query", () => {
+      const orderEntity = createEntity({
+        table: "orders",
+        fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+      });
+      const features = [
+        defineFeature("app", (r) => {
+          r.entity("order", orderEntity);
+          r.queryHandler(
+            defineEntityListHandler("order", orderEntity, {
+              access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+            }),
+          );
+          r.screen({
+            id: "x",
+            type: "projectionDetail",
+            query: "app:query:foo:detail",
+            layout: {
+              sections: [
+                {
+                  kind: "relatedList",
+                  title: "s",
+                  query: "app:query:order:list",
+                  columns: ["name"],
+                  parentFilter: { field: "unknownField" },
+                },
+              ],
+            },
+          });
+          r.queryHandler("foo:detail", z.object({}), async () => ({}), {
+            access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+          });
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(
+        /parentFilter\.field "unknownField" is not a declared field/,
+      );
+    });
+
+    test("accepts a valid parentFilter whose field is a real entity field and the query accepts filter", () => {
+      const orderEntity = createEntity({
+        table: "orders",
+        fields: {
+          name: createTextField({ personal: false, reason: "test_fixture" }),
+          orderId: createTextField({ personal: false, reason: "test_fixture" }),
+        },
+      });
+      const features = [
+        defineFeature("app", (r) => {
+          r.entity("order", orderEntity);
+          r.queryHandler(
+            defineEntityListHandler("order", orderEntity, {
+              access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+            }),
+          );
+          r.screen({
+            id: "x",
+            type: "projectionDetail",
+            query: "app:query:foo:detail",
+            layout: {
+              sections: [
+                {
+                  kind: "relatedList",
+                  title: "s",
+                  query: "app:query:order:list",
+                  columns: ["name"],
+                  parentFilter: { field: "orderId" },
+                },
+              ],
+            },
+          });
+          r.queryHandler("foo:detail", z.object({}), async () => ({}), {
+            access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+          });
+        }),
+      ];
+      expect(() => validateBoot(features)).not.toThrow();
+    });
+  });
+
   test("validateBoot rejects a relatedList section on entityEdit (fw#2166)", () => {
     const features = [
       defineFeature("shop", (r) => {
@@ -660,10 +816,10 @@ describe("r.screen() — registration", () => {
           },
         );
         r.queryHandler("foo:detail", z.object({}), async () => ({}), {
-          access: { openToAll: true },
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         });
         r.queryHandler("foo: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: "x",
@@ -873,7 +1029,7 @@ describe("r.screen() — registration", () => {
     const features = [
       defineFeature("app", (r) => {
         r.queryHandler("foo:detail", z.object({}), async () => ({}), {
-          access: { openToAll: true },
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         });
         r.writeHandler(
           "save",
@@ -917,7 +1073,7 @@ describe("r.screen() — registration", () => {
         // here so the throw below isolates the one key this test is about.
         r.translations({ keys: { "screen:x.title": { en: "X" } } });
         r.queryHandler("foo:detail", z.object({}), async () => ({}), {
-          access: { openToAll: true },
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         });
         r.writeHandler(
           "save",
@@ -959,7 +1115,7 @@ describe("r.screen() — registration", () => {
           },
         });
         r.queryHandler("foo:detail", z.object({}), async () => ({}), {
-          access: { openToAll: true },
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         });
         r.writeHandler(
           "save",

package/src/engine/__tests__/soft-delete-cleanup.test.ts

@@ -58,7 +58,6 @@ function makeCtx(opts: { graceDays?: number; calls: DeleteCall[] }): JobContext
   // to this recorder instead of trying to extract real table metadata.
   const fakeDb = {
     tenantId: "t1",
-    raw: { unsafe: async () => [] },
     selectMany: async () => [],
     fetchOne: async () => undefined,
     insertOne: async () => undefined,