@cosmicdrift/kumiko-framework 0.269.1 → 0.270.0

package/src/__tests__/upgrade-cli.test.ts

@@ -3,8 +3,10 @@ import {
   existsSync,
   mkdirSync,
   mkdtempSync,
+  readdirSync,
   readFileSync,
   rmSync,
+  statSync,
   symlinkSync,
   writeFileSync,
 } from "node:fs";
@@ -12,6 +14,8 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
   findCodemodScriptsRoot,
+  findCoreChangelogFile,
+  findFeaturesDirs,
   resolveCodemodScript,
   runUpgradeCli,
   type UpgradeCliOut,
@@ -592,3 +596,53 @@ describe("upgrade command — filter baseline is the marker, not the installed v
     expect(result.pending.map((e) => e.title)).toEqual(["explicit-from-test-entry"]);
   });
 });
+
+describe("changes.json codemod fields resolve to real published scripts", () => {
+  function findChangesJsonFiles(dir: string): string[] {
+    const found: string[] = [];
+    for (const name of readdirSync(dir)) {
+      if (name === "node_modules") continue;
+      const full = join(dir, name);
+      if (statSync(full).isDirectory()) {
+        found.push(...findChangesJsonFiles(full));
+      } else if (name === "changes.json") {
+        found.push(full);
+      }
+    }
+    return found;
+  }
+
+  test("every codemod field is a scripts/codemod/*.ts path that resolves to an existing published script", () => {
+    const coreChangelog = findCoreChangelogFile(REAL_REPO_ROOT);
+    const changesJsonFiles = [
+      ...(coreChangelog ? [coreChangelog] : []),
+      ...findFeaturesDirs(REAL_REPO_ROOT).flatMap((dir) => findChangesJsonFiles(dir)),
+    ];
+    expect(changesJsonFiles.length).toBeGreaterThan(0);
+
+    const offenders: string[] = [];
+    for (const file of changesJsonFiles) {
+      const entries = JSON.parse(readFileSync(file, "utf-8")) as ReadonlyArray<{
+        readonly version: string;
+        readonly title: string;
+        readonly codemod?: string;
+      }>;
+      for (const entry of entries) {
+        if (typeof entry.codemod !== "string") continue;
+        if (/\s/.test(entry.codemod)) {
+          offenders.push(
+            `${file} · ${entry.version} "${entry.title}": codemod is a shell command, not a path: "${entry.codemod}"`,
+          );
+          continue;
+        }
+        if (resolveCodemodScript(REAL_REPO_ROOT, entry.codemod) === null) {
+          offenders.push(
+            `${file} · ${entry.version} "${entry.title}": codemod path does not resolve: "${entry.codemod}"`,
+          );
+        }
+      }
+    }
+
+    expect(offenders).toEqual([]);
+  });
+});

package/src/api/__tests__/api.test.ts

@@ -37,7 +37,7 @@ const testFeature = defineFeature("test", (r) => {
     "item:list",
     z.object({ search: z.string().optional() }),
     async () => [{ id: 1, name: "Test" }],
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 
   r.streamHandler(
@@ -750,7 +750,7 @@ describe("feature-declared HTTP routes (r.httpRoute)", () => {
       }),
     );
     r.queryHandler("item:list", z.object({}), async () => [{ id: 7 }], {
-      access: { openToAll: true },
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
     });
     r.httpRoute({
       method: "GET",

package/src/api/__tests__/body-limit.test.ts

@@ -18,7 +18,7 @@ const testFeature = defineFeature("blob", (r) => {
     "note:create",
     z.object({ body: z.string() }),
     async (event) => ({ isSuccess: true, data: { body: event.payload.body } }),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 });
 

package/src/api/__tests__/pii-leak-guard.integration.test.ts

@@ -18,7 +18,7 @@ const leakyFeature = defineFeature("leaky", (r) => {
     defineQueryHandler({
       name: "raw",
       schema: z.object({}),
-      access: { openToAll: true },
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       handler: async () => ({ email: CIPHERTEXT, note: "plain" }),
     }),
   );
@@ -26,7 +26,7 @@ const leakyFeature = defineFeature("leaky", (r) => {
     defineQueryHandler({
       name: "clean",
       schema: z.object({}),
-      access: { openToAll: true },
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       handler: async () => ({ email: "marc@example.com" }),
     }),
   );

package/src/api/__tests__/request-locale.integration.test.ts

@@ -18,7 +18,7 @@ const localeProbe = defineFeature("locale-probe", (r) => {
     "read-locale",
     z.object({}),
     async (_event, ctx) => ({ isSuccess: true, data: { locale: ctx.locale } }),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 });
 

package/src/api/__tests__/server-error-logging.test.ts

@@ -20,7 +20,7 @@ const boomFeature = defineFeature("boom", (r) => {
     async () => {
       throw new Error("disk on fire");
     },
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 });
 

package/src/changes.json

@@ -1,4 +1,12 @@
 [
+  {
+    "version": "0.269.0",
+    "type": "breaking",
+    "title": "`openToAll: true` is removed — every openToAll grant now requires { reason } (fw#2858).",
+    "detail": "`OpenToAllAccessRule` (`@cosmicdrift/kumiko-types/handlers`) no longer accepts `true`; only `OpenToAllDeclaration` (`{ reason: string; personalData?: \"tenant-members\" }`) satisfies it, so `{ openToAll: true }` no longer type-checks. `isOpenToAllGranted` denies `true` from untyped sources (pattern JSON, Designer) the same way it already denied a malformed object — a bare `true` reaching it now returns `false` instead of granting access. The boot validator (`engine/boot-validator/access-declarations.ts`) rejects an untyped `openToAll: true` access declaration with an error pointing at `{ reason }` instead of registering the handler. The pattern-library Designer access field (`shared-fields.ts` `accessRuleField`) is now a required text input on `access.openToAll.reason` instead of a boolean toggle, so the Designer can only ever produce the object form. `build-config-feature-schema.ts` synthesizes `{ openToAll: { reason: \"config key declares the \\\"all\\\" role, so every signed-in user of the tenant may read/write it\" } }` for a config key whose roles include `\"all\"`, instead of `{ openToAll: true }`. `boot-validator/nav.ts` and `renderer-web/app/create-app.tsx` switched from `\"openToAll\" in access` to `isOpenToAllGranted(access)`, so a malformed or `true` rule is no longer treated as a visible screen/workspace. The feature-AST extractor now also extracts `escapeHatch: { reason }` on write/query handlers (`extractors/handlers.ts`) and on `r.hook` options (`extractors/hooks.ts`), round-tripped through render/patch the same way `access`/`rateLimit` already were.",
+    "migration": "Replace every `openToAll: true` with `openToAll: { reason: \"<who may call it and why that is safe without a role>\" }`, adding `personalData: \"tenant-members\"` where the boot validator requires it for a write handler accepting unbound personal data. Pattern-library or Designer-authored JSON that still has `openToAll: true` must be re-saved with a reason before it type-checks or passes boot. `kumiko-upgrade --apply` runs the migrate-open-to-all codemod automatically, rewriting test files to the default reason and listing every non-test site for manual review; run `bun packages/framework/src/scripts/codemod/migrate-open-to-all.ts --test-reason \"<text>\" <paths>` directly to override the default test reason.",
+    "codemod": "scripts/codemod/migrate-open-to-all.ts"
+  },
   {
     "version": "0.269.0",
     "type": "breaking",
@@ -17,8 +25,8 @@
     "type": "breaking",
     "title": "ctx.db.unsafeRaw(reason) gated by escapeHatch, tenancy: \"global\" invariants, bundled features migrated off ctx.db.raw (fw#2858).",
     "detail": "`TenantDb.unsafeRaw(reason)` returns the unfiltered `DbRunner` only when the calling write or query handler declares `escapeHatch: { reason }` (lifecycle hooks: `r.hook(..., { escapeHatch })`; a hook no longer inherits the handler's grant, same as the #2859 SYSTEM identity-switch gate). Without a declaration it throws `AccessDeniedError`; an empty reason throws `Error`. `r.systemScope()` features keep using `ctx.systemDb.unsafeRaw(reason)`. `TenantDb.raw` stays deprecated until fw#2860. `createTenantDb`'s 7th parameter changed from an `EscapeHatchDeclaration` to `TenantDbGrants` `{ globalWrites?, unsafeRaw? }`; `withUnsafeRawGrant(tenantDb, grant)` rebinds the unsafeRaw grant. `bindHookIdentitySwitchGrant`/`withHookIdentitySwitchGrant` are renamed to `bindHookEscapeHatchGrant`/`withHookEscapeHatchGrant`. Global tenancy: a `tenancy: \"global\"` entity must declare `systemStream: true` (boot validator + executor) and its create/update payloads may not carry a non-SYSTEM `tenantId`; tenant-mode `insertOne` into a global table with a `tenant_id` column and `db.global(table)` writes with a non-SYSTEM `tenantId` are rejected; `defineUnmanagedTable({ tenancy: \"global\" })` rejects a `tenant_id` column; new `declareGlobalTenancy(table)` declares a plain `table()` store without `tenant_id` as global. Bundled features: `userEntity` is `tenancy: \"global\"`, `store_global_feature_state` is declared global, and every bundled `ctx.db.raw` call site now uses `ctx.db.global(table)`, a filtered `ctx.db` method, or `ctx.db.unsafeRaw(reason)` with an `escapeHatch` on the handler. Handlers that call the auth-mfa `mfaStatusChecker`/MFA code verifier callbacks, handlers wrapped by cap-counter `withStockCap` (declares it automatically) and callers of the custom-fields quota/field-access query helpers now need that declaration.",
-    "migration": "Replace each `ctx.db.raw` use: reads of a `tenancy: \"global\"` table → `ctx.db.global(table).selectMany/fetchOne(...)`; reads/inserts whose where/values only use the caller's own tenantId → `ctx.db.selectMany/fetchOne/insertOne(table, ...)` (method form); everything else → `ctx.db.unsafeRaw(\"<what is read/written and why the tenant filter cannot apply>\")` plus `escapeHatch: { reason }` on the write/query handler definition or in the `r.hook` options. Generic reasons (todo, legacy, migration) fail infra#788. `bun scripts/migrate-db-raw.ts --dry-run <paths>` rewrites the global-table and own-tenant cases and lists the remaining sites; drop `--dry-run` to apply. Custom handlers calling `mfaStatusChecker`/the MFA code verifier or the custom-fields query helpers must declare `escapeHatch`. Direct `createTenantDb(..., escapeHatch)` calls pass `{ globalWrites: escapeHatch }` (and `unsafeRaw` if needed). Rename imports of `bindHookIdentitySwitchGrant`/`withHookIdentitySwitchGrant`. `defineUnmanagedTable({ tenancy: \"global\" })` definitions must drop their `tenant_id` column; `tenancy: \"global\"` entities must add `systemStream: true`.",
-    "codemod": "bun scripts/migrate-db-raw.ts --dry-run <paths>"
+    "migration": "Replace each `ctx.db.raw` use: reads of a `tenancy: \"global\"` table → `ctx.db.global(table).selectMany/fetchOne(...)`; reads/inserts whose where/values only use the caller's own tenantId → `ctx.db.selectMany/fetchOne/insertOne(table, ...)` (method form); everything else → `ctx.db.unsafeRaw(\"<what is read/written and why the tenant filter cannot apply>\")` plus `escapeHatch: { reason }` on the write/query handler definition or in the `r.hook` options. Generic reasons (todo, legacy, migration) fail infra#788. `kumiko-upgrade --apply` runs the migrate-db-raw codemod automatically, rewriting the global-table and own-tenant cases and listing the remaining sites for manual review. Custom handlers calling `mfaStatusChecker`/the MFA code verifier or the custom-fields query helpers must declare `escapeHatch`. Direct `createTenantDb(..., escapeHatch)` calls pass `{ globalWrites: escapeHatch }` (and `unsafeRaw` if needed). Rename imports of `bindHookIdentitySwitchGrant`/`withHookIdentitySwitchGrant`. `defineUnmanagedTable({ tenancy: \"global\" })` definitions must drop their `tenant_id` column; `tenancy: \"global\"` entities must add `systemStream: true`.",
+    "codemod": "scripts/codemod/migrate-db-raw.ts"
   },
   {
     "version": "0.267.0",

package/src/db/__tests__/list-filter-field-access.integration.test.ts

@@ -36,7 +36,7 @@ const LIST_QN = "filternotes:query:note:list";
 const filterNotesFeature = defineFeature("filternotes", (r) => {
   r.crud("note", filterNoteEntity, {
     write: { access: { roles: ["Admin"] } },
-    read: { access: { openToAll: true } },
+    read: { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   });
 });
 

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/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-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" } },
   });
 }
 

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

@@ -7,7 +7,7 @@ describe("validateBoot — projectionList screens", () => {
   test("rejects hand-written searchable:true when the query schema has no search param (3a)", () => {
     const feature = 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",
@@ -29,7 +29,7 @@ describe("validateBoot — projectionList screens", () => {
         "schedule: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: "schedule-list",
@@ -50,7 +50,7 @@ describe("validateBoot — projectionList screens", () => {
         "schedule:list",
         z.object({ sort: 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",
@@ -71,7 +71,7 @@ describe("validateBoot — projectionList screens", () => {
         "schedule:list",
         z.object({ search: z.string().optional(), sort: 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",
@@ -91,7 +91,7 @@ describe("validateBoot — projectionList screens", () => {
   test("passes when the schema offers neither search nor sort and no defaultSort is set", () => {
     const feature = 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",
@@ -112,7 +112,7 @@ describe("validateBoot — projectionList screens", () => {
         "schedule: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: "schedule-list",
@@ -135,7 +135,7 @@ describe("validateBoot — projectionList screens", () => {
         "schedule: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: "download-attempt-list",
@@ -154,7 +154,7 @@ describe("validateBoot — projectionList screens", () => {
   test("rejects hand-authored sortable on a projectionList screen (fw#2165 review)", () => {
     const feature = 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",
@@ -173,7 +173,7 @@ describe("validateBoot — projectionList screens", () => {
   test("rejects hand-authored paginated on a projectionList screen (fw#2165 review)", () => {
     const feature = 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",
@@ -202,7 +202,7 @@ describe("validateBoot — projectionList screens", () => {
           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-detail", type: "custom", renderer: { react: "stub" } });
@@ -251,7 +251,7 @@ describe("validateBoot — projectionList screens", () => {
           "schedule:list",
           z.object({ filter: z.unknown().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",
@@ -274,7 +274,7 @@ describe("validateBoot — projectionList screens", () => {
           z.object({}),
           async () => ({ rows: [], nextCursor: null }),
           {
-            access: { openToAll: true },
+            access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
           },
         );
         r.screen({
@@ -297,7 +297,7 @@ describe("validateBoot — projectionList screens", () => {
           "schedule:list",
           z.object({ filters: z.unknown().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",
@@ -326,7 +326,7 @@ describe("validateBoot — projectionList screens", () => {
           "schedule:list",
           z.object({ filters: z.unknown().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",
@@ -363,7 +363,7 @@ describe("validateBoot — projectionList screens", () => {
           "schedule:list",
           z.object({ filters: z.unknown().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",
@@ -386,7 +386,7 @@ describe("validateBoot — projectionList screens", () => {
           z.object({}),
           async () => ({ rows: [], nextCursor: null }),
           {
-            access: { openToAll: true },
+            access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
           },
         );
         r.screen({
@@ -417,7 +417,7 @@ describe("validateBoot — projectionList screens", () => {
           "schedule:list",
           z.object({ filter: z.unknown().optional(), filters: z.unknown().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",

package/src/engine/__tests__/boot-validator-query-output-schema.test.ts

@@ -20,7 +20,7 @@ describe("validateBoot — query output schema column refs (fw#2493)", () => {
   test("projectionList column not in the paged query's row shape throws", () => {
     const feature = 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" } },
         outputSchema: pagedSchema,
       });
       r.screen({
@@ -39,7 +39,7 @@ describe("validateBoot — query output schema column refs (fw#2493)", () => {
   test("projectionList column present in the row shape does not throw", () => {
     const feature = 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" } },
         outputSchema: pagedSchema,
       });
       r.screen({
@@ -56,7 +56,7 @@ describe("validateBoot — query output schema column refs (fw#2493)", () => {
   test("projectionList column with a label is exempt as a virtual/computed column", () => {
     const feature = 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" } },
         outputSchema: pagedSchema,
       });
       r.screen({
@@ -78,7 +78,7 @@ describe("validateBoot — query output schema column refs (fw#2493)", () => {
   test("projectionList without a declared outputSchema skips the column check entirely", () => {
     const feature = 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.screen({
         id: "items",
@@ -94,7 +94,7 @@ describe("validateBoot — query output schema column refs (fw#2493)", () => {
   test("projectionList outputSchema that isn't a ZodObject (e.g. a union) skips the column check", () => {
     const feature = 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" } },
         outputSchema: z.union([pagedSchema, z.null()]),
       });
       r.screen({
@@ -111,11 +111,11 @@ describe("validateBoot — query output schema column refs (fw#2493)", () => {
   test("relatedList column not in the query's row shape throws", () => {
     const feature = defineFeature("app", (r) => {
       r.queryHandler("rent:detail", z.object({}), async () => ({ description: "x" }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         outputSchema: z.object({ description: z.string() }),
       });
       r.queryHandler("rent:payments", z.object({}), async () => ({ rows: [], nextCursor: null }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         outputSchema: z.object({
           rows: z.array(z.object({ amount: z.number() })),
           nextCursor: z.string().nullable(),
@@ -145,7 +145,7 @@ describe("validateBoot — query output schema column refs (fw#2493)", () => {
   test("projectionDetail header.title referencing an unknown field throws", () => {
     const feature = defineFeature("app", (r) => {
       r.queryHandler("tenant:detail", z.object({}), async () => ({ id: "1", name: "x" }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         outputSchema: z.object({ id: z.string(), name: z.string() }),
       });
       r.screen({
@@ -164,7 +164,7 @@ describe("validateBoot — query output schema column refs (fw#2493)", () => {
   test("projectionDetail header.status referencing an unknown field throws", () => {
     const feature = defineFeature("app", (r) => {
       r.queryHandler("tenant:detail", z.object({}), async () => ({ id: "1", name: "x" }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         outputSchema: z.object({ id: z.string(), name: z.string() }),
       });
       r.screen({
@@ -181,7 +181,7 @@ describe("validateBoot — query output schema column refs (fw#2493)", () => {
   test("projectionDetail metrics referencing an unknown field throws", () => {
     const feature = defineFeature("app", (r) => {
       r.queryHandler("tenant:detail", z.object({}), async () => ({ id: "1", balance: 0 }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         outputSchema: z.object({ id: z.string(), balance: z.number() }),
       });
       r.screen({
@@ -214,7 +214,7 @@ describe("validateBoot — query output schema column refs (fw#2493)", () => {
         z.object({}),
         async () => ({ id: "1", name: "x", balance: 0 }),
         {
-          access: { openToAll: true },
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
           outputSchema: z.object({
             id: z.string(),
             name: z.string(),
@@ -241,7 +241,7 @@ describe("validateBoot — query output schema column refs (fw#2493)", () => {
   test("dashboard stat panel valueField referencing an unknown field throws", () => {
     const feature = defineFeature("demo", (r) => {
       r.queryHandler("open-count", z.object({}), async () => ({ value: "0" }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         outputSchema: z.object({ value: z.string() }),
       });
       r.screen({
@@ -269,7 +269,7 @@ describe("validateBoot — query output schema column refs (fw#2493)", () => {
   test("dashboard stat-group child deltaField referencing an unknown field throws", () => {
     const feature = defineFeature("demo", (r) => {
       r.queryHandler("net-worth", z.object({}), async () => ({ value: "0" }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         outputSchema: z.object({ value: z.string() }),
       });
       r.screen({
@@ -308,7 +308,7 @@ describe("validateBoot — query output schema column refs (fw#2493)", () => {
   test("dashboard list panel column not in the query's row shape throws", () => {
     const feature = defineFeature("demo", (r) => {
       r.queryHandler("next-events", z.object({}), async () => ({ rows: [], nextCursor: null }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         outputSchema: z.object({
           rows: z.array(z.object({ title: z.string() })),
           nextCursor: z.string().nullable(),
@@ -342,7 +342,7 @@ describe("validateBoot — query output schema column refs (fw#2493)", () => {
         defineQueryHandler({
           name: "items:detail",
           schema: z.object({ id: z.string() }),
-          access: { openToAll: true },
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
           outputSchema: z.object({ id: z.string(), name: z.string() }),
           handler: async () => ({ id: "1", name: "x" }),
         }),
@@ -366,7 +366,7 @@ describe("validateBoot — query output schema column refs (fw#2493)", () => {
         definePagedQueryHandler({
           name: "items:list",
           schema: z.object({}),
-          access: { openToAll: true },
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
           outputSchema: pagedSchema,
           handler: async () => ({ rows: [], nextCursor: null }),
         }),
@@ -390,7 +390,7 @@ describe("validateBoot — query output schema column refs (fw#2493)", () => {
         definePagedQueryHandler({
           name: "items:list",
           schema: z.object({}),
-          access: { openToAll: true },
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
           // Row schema passed directly instead of wrapping it in
           // { rows: [...], nextCursor } — the mistake fw#2493's follow-up
           // check catches instead of silently skipping every column check.
@@ -417,7 +417,7 @@ describe("validateBoot — query output schema column refs (fw#2493)", () => {
         definePagedQueryHandler({
           name: "items:list",
           schema: z.object({}),
-          access: { openToAll: true },
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
           outputSchema: pagedSchema,
           handler: async () => ({ rows: [], nextCursor: null }),
         }),

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

@@ -36,7 +36,7 @@ describe("validateBoot — query QN refs (fw#2178)", () => {
   test("projectionDetail relatedList section with a dead query QN throws (b)", () => {
     const feature = defineFeature("app", (r) => {
       r.queryHandler("rent:detail", z.object({}), async () => ({ description: "x" }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
       r.screen({
         id: "rent-detail",
@@ -96,7 +96,7 @@ describe("validateBoot — query QN refs (fw#2178)", () => {
   test("dashboard filter optionsQuery with a dead query QN throws", () => {
     const feature = defineFeature("demo", (r) => {
       r.queryHandler("open-count", z.object({}), async () => ({ value: "0" }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
       r.screen({
         id: "overview",
@@ -132,7 +132,7 @@ describe("validateBoot — query QN refs (fw#2178)", () => {
   test("a screen referencing a query registered by a different mounted feature does not throw (d)", () => {
     const provider = 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" } },
       });
     });
     const consumer = defineFeature("storefront", (r) => {

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

@@ -44,7 +44,7 @@ describe("S0 Integration — full surface stack", () => {
         name: "compliance:query:for-tenant",
         schema: z.object({}),
         handler: async () => ({ profile: "eu-dsgvo" }) as never,
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
     });
 
@@ -101,7 +101,7 @@ describe("S0 Integration — full surface stack", () => {
         name: "user: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" } },
       });
 
       r.useExtension(EXT_USER_DATA, "user", {});