@cosmicdrift/kumiko-framework 0.269.1 → 0.270.0

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

@@ -42,7 +42,7 @@ function stubListHandler(
     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" } },
   });
 }
 
@@ -534,7 +534,7 @@ describe("boot-validator", () => {
             isSuccess: true as const,
             data: { id: "1" },
           }),
-          { access: { openToAll: true } },
+          { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
         );
       }),
     ];
@@ -566,7 +566,7 @@ describe("boot-validator", () => {
           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");
     });
@@ -631,7 +631,7 @@ describe("boot-validator", () => {
     const features = [
       defineFeature("a", (r) => {
         r.queryHandler("list", z.object({}), async () => [], {
-          access: { openToAll: true },
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         });
       }),
     ];
@@ -711,7 +711,7 @@ describe("boot-validator", () => {
     const features = [
       defineFeature("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" } },
         });
       }),
     ];
@@ -2430,7 +2430,7 @@ describe("boot-validator", () => {
           name: "invoice:approve",
           schema: { _type: "stub" } as never,
           handler: async () => ({ isSuccess: true, data: {} }) as never,
-          access: { openToAll: true },
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         });
         r.screen({
           id: "approve-invoice",
@@ -2713,14 +2713,14 @@ describe("boot-validator", () => {
           name: "token:mint",
           schema: { _type: "stub" } as never,
           handler: async () => ({ isSuccess: true, data: {} }) as never,
-          access: { openToAll: true },
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         });
         if (confirmOverride !== undefined) {
           r.writeHandler({
             name: "token:confirm",
             schema: { _type: "stub" } as never,
             handler: async () => ({ isSuccess: true, data: {} }) as never,
-            access: { openToAll: true },
+            access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
           });
         }
         r.screen({
@@ -4177,7 +4177,7 @@ describe("boot-validator", () => {
           }),
         );
         r.queryHandler("products", z.object({}), async () => ({ rows: [], nextCursor: null }), {
-          access: { openToAll: true },
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         });
         r.screen({
           id: "product-projection",
@@ -4207,7 +4207,7 @@ describe("boot-validator", () => {
           }),
         );
         r.queryHandler("products", z.object({}), async () => ({ rows: [], nextCursor: null }), {
-          access: { openToAll: true },
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         });
         r.screen({
           id: "product-projection",
@@ -4426,13 +4426,13 @@ describe("boot-validator", () => {
     test("projectionDetail relatedList defaultSort.field sortable → kein Throw", () => {
       const feature = defineFeature("shop", (r) => {
         r.queryHandler("order-detail", z.object({}), async () => ({ id: "o1" }), {
-          access: { openToAll: true },
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         });
         r.queryHandler(
           "order-positions",
           z.object({}),
           async () => ({ rows: [], nextCursor: null }),
-          { access: { openToAll: true } },
+          { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
         );
         r.screen({
           id: "order-detail",
@@ -4993,7 +4993,7 @@ describe("boot-validator", () => {
       const targetId = opts.targetId ?? "restock-form";
       return defineFeature("shop", (r) => {
         r.queryHandler("products", z.object({}), async () => ({ rows: [], nextCursor: null }), {
-          access: { openToAll: true },
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         });
         r.writeHandler(
           "restock",
@@ -5223,7 +5223,7 @@ describe("boot-validator — config key backing × scope", () => {
         ],
       });
       r.queryHandler("count", z.object({}), async () => ({ total: 0 }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
       r.screen({
         id: "product-dashboard",
@@ -5268,7 +5268,7 @@ describe("boot-validator — config key backing × scope", () => {
         ],
       });
       r.queryHandler("count", z.object({}), async () => ({ total: 0 }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
       r.screen({
         id: "product-dashboard",
@@ -5317,7 +5317,7 @@ describe("boot-validator — config key backing × scope", () => {
         ],
       });
       r.queryHandler("count", z.object({}), async () => ({ total: 0 }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
       r.screen({
         id: "product-dashboard",
@@ -5542,7 +5542,7 @@ describe("boot-validator — config key backing × scope", () => {
         }),
       );
       r.queryHandler("products", z.object({}), async () => ({ rows: [], nextCursor: null }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
       r.screen({
         id: "product-projection",
@@ -5624,7 +5624,7 @@ describe("boot-validator — config key backing × scope", () => {
         "create",
         z.object({ name: z.string() }),
         async () => ({ isSuccess: true as const, data: { id: "1" } }),
-        { access: { openToAll: true } },
+        { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
       );
       r.screen({
         id: "product-list",

package/src/engine/__tests__/build-app-schema.test.ts

@@ -209,7 +209,7 @@ describe("buildAppSchema", () => {
       r.workspace({
         id: "admin",
         label: "Admin",
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         nav: ["orders:nav:list", "fleet:nav:vehicles"],
         default: true,
       });
@@ -832,7 +832,11 @@ describe("buildAppSchema", () => {
     const f = defineFeature("ent", (r) => {
       r.entity("thing", entity);
       r.nav({ id: "n", label: "N" });
-      r.workspace({ id: "ws", label: "Ws", access: { openToAll: true } });
+      r.workspace({
+        id: "ws",
+        label: "Ws",
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+      });
     });
     const app = buildAppSchema(createRegistry([f]));
     const json = JSON.stringify(app);
@@ -980,7 +984,7 @@ describe("buildAppSchema", () => {
           cursor: 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: "schedule-list",
@@ -1000,7 +1004,7 @@ describe("buildAppSchema", () => {
   test("projectionList: a query schema without search/sort/cursor derives no capability", () => {
     const f = defineFeature("ledger", (r) => {
       r.queryHandler("schedule: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: "schedule-list",
@@ -1023,7 +1027,7 @@ describe("buildAppSchema", () => {
         "schedule:list",
         z.union([z.object({ a: z.string() }), z.object({ b: z.string() })]),
         async () => ({ rows: [], nextCursor: null }),
-        { access: { openToAll: true } },
+        { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
       );
       r.screen({
         id: "schedule-list",
@@ -1052,7 +1056,7 @@ describe("buildAppSchema", () => {
           rows: [],
           nextCursor: null,
         }),
-        { access: { openToAll: true } },
+        { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
       );
       r.screen({
         id: "schedule-list",

package/src/engine/__tests__/build-config-feature-schema-secrets.test.ts

@@ -1,8 +1,10 @@
 import { describe, expect, test } from "bun:test";
 import { z } from "zod";
 import { buildConfigFeatureSchema } from "../build-config-feature-schema";
+import { createTenantConfig } from "../config-helpers";
 import { defineFeature } from "../define-feature";
 import { createRegistry } from "../registry";
+import type { AccessRule } from "../types/handlers";
 import type { NavDefinition } from "../types/nav";
 import type { ScreenDefinition, SecretsEditScreenDefinition } from "../types/screen";
 
@@ -114,6 +116,52 @@ describe("buildConfigFeatureSchema — secrets derivation", () => {
     expect(navById(schema, "audience-tenant")?.access).toEqual({ roles: customRoles });
   });
 
+  test("audience nav union keeps a granted openToAll's own reason, not the generic ALL_ROLE reason", () => {
+    const customReason = "billing key rotation is safe for any signed-in tenant member";
+    const secretsOpenToAll = defineFeature("secrets", (r) => {
+      r.writeHandler(
+        "set",
+        z.object({ key: z.string(), value: z.string() }),
+        async () => ({ isSuccess: true, data: null }),
+        { access: { openToAll: { reason: customReason } } },
+      );
+    });
+    const billing = defineFeature("billing", (r) => {
+      r.config({
+        keys: { apiKey: createTenantConfig("text", { mask: { title: "billing.api-key" } }) },
+      });
+      r.secret("apiKey", { label: { en: "Billing API Key" }, scope: "tenant" });
+    });
+    const schema = buildConfigFeatureSchema(createRegistry([secretsOpenToAll, billing]));
+
+    expect(navById(schema, "audience-tenant")?.access).toEqual({
+      openToAll: { reason: customReason },
+    });
+  });
+
+  test("audience nav union ignores a malformed openToAll — falls back to the role union", () => {
+    const secretsMalformedOpenToAll = defineFeature("secrets", (r) => {
+      r.writeHandler(
+        "set",
+        z.object({ key: z.string(), value: z.string() }),
+        async () => ({ isSuccess: true, data: null }),
+        // @cast-boundary test — simulates JSON/Designer input that doesn't match the static union
+        { access: { openToAll: {} } as unknown as AccessRule },
+      );
+    });
+    const billing = defineFeature("billing", (r) => {
+      r.config({
+        keys: { apiKey: createTenantConfig("text", { mask: { title: "billing.api-key" } }) },
+      });
+      r.secret("apiKey", { label: { en: "Billing API Key" }, scope: "tenant" });
+    });
+    const schema = buildConfigFeatureSchema(createRegistry([secretsMalformedOpenToAll, billing]));
+
+    expect(navById(schema, "audience-tenant")?.access).toEqual({
+      roles: ["TenantAdmin", "Admin", "SystemAdmin"],
+    });
+  });
+
   test("declared secrets without a mounted secrets feature yield no secretsEdit screen and no secrets nav", () => {
     const stripe = defineFeature("stripe", (r) => {
       r.secret("apiKey", { label: { en: "Stripe API Key" }, scope: "tenant" });

package/src/engine/__tests__/build-config-feature-schema.test.ts

@@ -8,6 +8,7 @@ import {
 } from "../config-helpers";
 import { defineFeature } from "../define-feature";
 import { createRegistry } from "../registry";
+import { isOpenToAllGranted } from "../types/handlers";
 import type { NavDefinition } from "../types/nav";
 import type { ConfigEditScreenDefinition, ScreenDefinition } from "../types/screen";
 
@@ -265,7 +266,15 @@ describe("buildConfigFeatureSchema — access + workspace", () => {
       roles: ["TenantAdmin", "Admin", "SystemAdmin"],
     });
     // digest is createUserConfig → write access.all (["all"]) → openToAll
-    expect(configScreen("notify-user").access).toEqual({ openToAll: true });
+    const notifyUserAccess = configScreen("notify-user").access;
+    expect(notifyUserAccess).toEqual({
+      openToAll: {
+        reason:
+          'config key declares the "all" role, so every signed-in user of the tenant may read/write it',
+      },
+    });
+    // The synthesized reason must actually grant access, not just look configured.
+    expect(notifyUserAccess !== undefined && isOpenToAllGranted(notifyUserAccess)).toBe(true);
   });
 
   test("a screen mixing an openToAll key with role-restricted keys collapses to openToAll", () => {
@@ -283,8 +292,18 @@ describe("buildConfigFeatureSchema — access + workspace", () => {
     const screen = out.screens.find((s) => s.id === "mixedwrite-tenant");
     if (screen?.type !== "configEdit")
       throw new Error('expected configEdit screen "mixedwrite-tenant"');
-    expect(screen.access).toEqual({ openToAll: true });
-    expect(out.navs.find((n) => n.id === "audience-tenant")?.access).toEqual({ openToAll: true });
+    expect(screen.access).toEqual({
+      openToAll: {
+        reason:
+          'config key declares the "all" role, so every signed-in user of the tenant may read/write it',
+      },
+    });
+    expect(out.navs.find((n) => n.id === "audience-tenant")?.access).toEqual({
+      openToAll: {
+        reason:
+          'config key declares the "all" role, so every signed-in user of the tenant may read/write it',
+      },
+    });
   });
 
   test("openToAll collapse holds regardless of key declaration order (516/2)", () => {
@@ -305,7 +324,12 @@ describe("buildConfigFeatureSchema — access + workspace", () => {
     const screen = out.screens.find((s) => s.id === "mixedwritereversed-tenant");
     if (screen?.type !== "configEdit")
       throw new Error('expected configEdit screen "mixedwritereversed-tenant"');
-    expect(screen.access).toEqual({ openToAll: true });
+    expect(screen.access).toEqual({
+      openToAll: {
+        reason:
+          'config key declares the "all" role, so every signed-in user of the tenant may read/write it',
+      },
+    });
   });
 
   test("returns empty (no workspace) when no key opts into the hub via mask", () => {
@@ -343,7 +367,12 @@ describe("buildConfigFeatureSchema — access + workspace", () => {
   test("workspace access is the union of write roles across all hub keys", () => {
     // billing/notify tenant keys → admin write; notify-user digest → write all.
     // Any `all`-writable key collapses the whole switcher entry to openToAll.
-    expect(schema.workspace?.definition.access).toEqual({ openToAll: true });
+    expect(schema.workspace?.definition.access).toEqual({
+      openToAll: {
+        reason:
+          'config key declares the "all" role, so every signed-in user of the tenant may read/write it',
+      },
+    });
   });
 
   test("workspace access stays role-gated when no hub key is world-writable", () => {

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

@@ -87,7 +87,7 @@ describe("defineFeature", () => {
           const _email: string = event.payload.email;
           return { isSuccess: true, data: { id: 1 } };
         },
-        { access: { openToAll: true } },
+        { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
       );
     });
 
@@ -105,7 +105,7 @@ describe("defineFeature", () => {
           isSuccess: true,
           data: null,
         }),
-        { access: { openToAll: true } },
+        { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
       );
     });
     expect(ref?.name).toBe("order:create");
@@ -115,7 +115,7 @@ describe("defineFeature", () => {
     let ref: { name: string } | undefined;
     defineFeature("test", (r) => {
       ref = r.queryHandler("order:list", z.object({}), async () => [], {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
     });
     expect(ref?.name).toBe("order:list");
@@ -130,13 +130,15 @@ describe("defineFeature", () => {
         async function* (query) {
           yield `echo:${query.payload.prompt}`;
         },
-        { access: { openToAll: true } },
+        { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
       );
     });
     expect(ref?.name).toBe("chat:complete");
 
     const stored = feature.streamHandlers["chat:complete"];
-    expect(stored?.access).toEqual({ openToAll: true });
+    expect(stored?.access).toEqual({
+      openToAll: { reason: "test handler callable by any signed-in test user" },
+    });
 
     const chunks: string[] = [];
     for await (const chunk of stored!.handler(
@@ -225,7 +227,7 @@ describe("defineFeature", () => {
           const _id: number = query.payload.userId;
           return { id: _id, email: "test@test.de" };
         },
-        { access: { openToAll: true } },
+        { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
       );
     });
 
@@ -239,7 +241,7 @@ describe("defineFeature", () => {
       handler: async () => {
         return [{ id: 1, email: "test@test.de" }];
       },
-      access: { openToAll: true },
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
     });
 
     const feature = defineFeature("test", (r) => {
@@ -402,12 +404,12 @@ describe("createRegistry", () => {
   test("looks up handlers across features", () => {
     const f1 = defineFeature("admin", (r) => {
       r.writeHandler("user:invite", z.object({}), async () => ({ isSuccess: true, data: null }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
     });
     const f2 = defineFeature("profile", (r) => {
       r.queryHandler("profile:me", z.object({}), async () => ({ id: 1 }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
     });
 
@@ -442,12 +444,12 @@ describe("createRegistry", () => {
   test("different features can have same handler short name (prefixed differently)", () => {
     const f1 = defineFeature("a", (r) => {
       r.writeHandler("user:invite", z.object({}), async () => ({ isSuccess: true, data: null }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
     });
     const f2 = defineFeature("b", (r) => {
       r.writeHandler("user:invite", z.object({}), async () => ({ isSuccess: true, data: null }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
     });
 
@@ -513,7 +515,7 @@ describe("createRegistry", () => {
       );
       // Handler name "promote" has no entity prefix → can't be mapped
       r.writeHandler("promote", z.object({}), async () => ({ isSuccess: true, data: null }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
     });
 
@@ -531,7 +533,7 @@ describe("createRegistry", () => {
       );
       // No field-access rules on entity → "reset" without entity prefix is fine
       r.writeHandler("reset", z.object({}), async () => ({ isSuccess: true, data: null }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
     });
 
@@ -562,7 +564,7 @@ describe("createRegistry", () => {
           isSuccess: true,
           data: null,
         }),
-        { access: { openToAll: true } },
+        { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
       );
     });
 
@@ -591,10 +593,12 @@ describe("createRegistry", () => {
           isSuccess: true,
           data: null,
         }),
-        { access: { openToAll: true } },
+        { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
       );
       // Typo: "emp" instead of "employee"
-      r.queryHandler("emp:list", z.object({}), async () => [], { access: { openToAll: true } });
+      r.queryHandler("emp:list", z.object({}), async () => [], {
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+      });
     });
 
     expect(() => createRegistry([feature])).toThrow(/emp:list.*entity-bound.*no matching entity/i);
@@ -622,13 +626,15 @@ describe("createRegistry", () => {
           isSuccess: true,
           data: null,
         }),
-        { access: { openToAll: true } },
+        { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
       );
       // Standalone queries — no dot, intentionally not entity-bound
       r.queryHandler("dashboard", z.object({}), async () => ({ total: 42 }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+      });
+      r.queryHandler("orgChart", z.object({}), async () => [], {
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
-      r.queryHandler("orgChart", z.object({}), async () => [], { access: { openToAll: true } });
     });
 
     expect(() => createRegistry([feature])).not.toThrow();
@@ -924,12 +930,20 @@ describe("hasAccess", () => {
 
   test("openToAll grants access to any authenticated user", () => {
     const user = createTestUser({ roles: ["Employee"] });
-    expect(hasAccess(user, { openToAll: true })).toBe(true);
+    expect(
+      hasAccess(user, {
+        openToAll: { reason: "test handler callable by any signed-in test user" },
+      }),
+    ).toBe(true);
   });
 
   test("openToAll grants access even to user with no roles", () => {
     const user = createTestUser({ roles: [] });
-    expect(hasAccess(user, { openToAll: true })).toBe(true);
+    expect(
+      hasAccess(user, {
+        openToAll: { reason: "test handler callable by any signed-in test user" },
+      }),
+    ).toBe(true);
   });
 
   test.each([{ openToAll: false }, { openToAll: {} }])(
@@ -2105,10 +2119,10 @@ describe("registry boot validation", () => {
     const feature = defineFeature("shop", (r) => {
       r.entity("order", createEntity({ table: "Orders", fields: {} }));
       r.writeHandler("order:create", z.object({}), async () => ({ isSuccess: true, data: null }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
       r.writeHandler("order:cancel", z.object({}), async () => ({ isSuccess: true, data: null }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
       // Ein Job-Body, zwei Trigger — DRY-Pattern für Fanout-Cases.
       r.job(
@@ -2129,7 +2143,7 @@ describe("registry boot validation", () => {
     const feature = defineFeature("shop", (r) => {
       r.entity("order", createEntity({ table: "Orders", fields: {} }));
       r.writeHandler("order:create", z.object({}), async () => ({ isSuccess: true, data: null }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
       // create existiert, cancel nicht — zweiter Trigger ist Geist
       r.job(
@@ -2153,7 +2167,7 @@ describe("registry boot validation", () => {
     const feature = defineFeature("test", (r) => {
       r.entity("item", createEntity({ table: "Items", fields: {} }));
       r.writeHandler("item.create", z.object({}), async () => ({ isSuccess: true, data: null }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
       r.hook("postSave", "item.create", async () => {});
     });

package/src/engine/__tests__/entity-handlers.test.ts

@@ -149,9 +149,11 @@ describe("defineEntityQueryHandler", () => {
 
   test("access option is forwarded", () => {
     const def = defineEntityListHandler("note", noteEntity, {
-      access: { openToAll: true },
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+    });
+    expect(def.access).toEqual({
+      openToAll: { reason: "test handler callable by any signed-in test user" },
     });
-    expect(def.access).toEqual({ openToAll: true });
   });
 });
 
@@ -180,10 +182,12 @@ describe("defineProjectionQueryHandler", () => {
     const def = defineProjectionQueryHandler(
       "revenue:list",
       "showcase:projection:customer-revenue",
-      { access: { openToAll: true } },
+      { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
     );
     expect(def.name).toBe("revenue:list");
-    expect(def.access).toEqual({ openToAll: true });
+    expect(def.access).toEqual({
+      openToAll: { reason: "test handler callable by any signed-in test user" },
+    });
     // Empty-object schema — handler takes no payload fields.
     expect(def.schema.safeParse({}).success).toBe(true);
   });
@@ -192,7 +196,7 @@ describe("defineProjectionQueryHandler", () => {
     const def = defineProjectionQueryHandler(
       "revenue:list",
       "showcase:projection:customer-revenue",
-      { access: { openToAll: true } },
+      { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
     );
     const fakeRows = [{ customer: "a", totalCents: 100 }];
     const ctx = {
@@ -215,7 +219,10 @@ describe("defineProjectionQueryHandler", () => {
     const def = defineProjectionQueryHandler(
       "revenue:list",
       "showcase:projection:customer-revenue",
-      { access: { openToAll: true }, unsafeAllTenants: true },
+      {
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+        unsafeAllTenants: true,
+      },
     );
     const ctx = { queryProjection: mock().mockResolvedValue([]) };
     await def.handler(
@@ -328,7 +335,9 @@ describe("registerEntityCrud", () => {
     const { r, entities, writes, queries } = createCrudRegistrarMock();
     registerEntityCrud(r, "note", noteEntitySoftDelete, {
       write: { access: { roles: ["Admin"] } },
-      read: { access: { openToAll: true } },
+      read: {
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+      },
     });
     expect(entities["note"]).toBe(noteEntitySoftDelete);
     expect(writes.map((w) => w.name)).toEqual([
@@ -339,7 +348,9 @@ describe("registerEntityCrud", () => {
     ]);
     expect(queries.map((q) => q.name)).toEqual(["note:list", "note:detail"]);
     expect(writes[0]?.access).toEqual({ roles: ["Admin"] });
-    expect(queries[0]?.access).toEqual({ openToAll: true });
+    expect(queries[0]?.access).toEqual({
+      openToAll: { reason: "test handler callable by any signed-in test user" },
+    });
   });
 
   test("verbs.delete: false skips delete handler", () => {

package/src/engine/__tests__/entity-presave-wiring.integration.test.ts

@@ -50,7 +50,7 @@ const throwOnPreSave: import("../types").PreSaveHookFn = async () => {
 const contactFeature = defineFeature("presave-wiring", (r) => {
   r.crud("contact", contactEntity, {
     write: { access: { roles: ["User"] } },
-    read: { access: { openToAll: true } },
+    read: { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   });
 
   // preSave has no entity-wide `{ allOf }` shorthand (unlike postSave/
@@ -70,7 +70,7 @@ const throwingEntity = createEntity({
 const throwingFeature = defineFeature("presave-wiring-throw", (r) => {
   r.crud("thing", throwingEntity, {
     write: { access: { roles: ["User"] } },
-    read: { access: { openToAll: true } },
+    read: { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   });
   r.hook("preSave", "thing:create", throwOnPreSave);
 });