@cosmicdrift/kumiko-framework 0.269.2 → 0.270.0

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

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", () => {