@cosmicdrift/kumiko-framework 0.333.0 → 0.335.0

package/dist/engine/boot-validator/access-declarations.js

@@ -81,19 +81,28 @@ function validatePersonalDataValue(feature, handlerName, access) {
             `access.personalData ${JSON.stringify(declared)} — the only supported value is "public-intake".`);
     }
     // skip: roles include "anonymous", which personalData: "public-intake" requires
-    if (Array.isArray(access.roles) && access.roles.includes(ANONYMOUS_ROLE))
+    if (accessAllowsAnonymous(access))
         return;
     throw new Error(`[Feature ${feature.name}] write handler "${handlerName}" declares ` +
         'access.personalData: "public-intake" but its roles do not include ' +
         `"${ANONYMOUS_ROLE}" — personalData: "public-intake" only applies to handlers ` +
         "that allow anonymous callers.");
 }
+function handlerInputKeys(feature, handlerName, handler) {
+    try {
+        return collectZodObjectKeys(handler.schema);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`[Feature ${feature.name}] write handler "${handlerName}": ${reason}`);
+    }
+}
 function validateOpenToAllPersonalData(feature, handlerName, handler) {
     const access = handler.access;
     // skip: no openToAll declared, or the handler declares tenant members may write personal data
     if (!hasOpenToAll(access) || declaresTenantMembersPersonalData(access))
         return;
-    const inputKeys = collectZodObjectKeys(handler.schema);
+    const inputKeys = handlerInputKeys(feature, handlerName, handler);
     const personalNames = candidatePersonalFieldNames(feature, handlerName, handler);
     const offending = [...inputKeys].filter((key) => personalNames.has(key));
     // skip: no personal-data fields in the handler's input
@@ -114,7 +123,7 @@ function validateAnonymousPersonalData(feature, handlerName, handler) {
     // skip: not reachable by an anonymous caller, or already declares public-intake
     if (!accessAllowsAnonymous(access) || declaredPersonalData(access) === "public-intake")
         return;
-    const inputKeys = collectZodObjectKeys(handler.schema);
+    const inputKeys = handlerInputKeys(feature, handlerName, handler);
     const personalNames = candidatePersonalFieldNames(feature, handlerName, handler, false);
     const offending = [...inputKeys].filter((key) => personalNames.has(key));
     // skip: no personal-data fields in the handler's input

package/dist/engine/boot-validator/config-deps.js

@@ -1,3 +1,4 @@
+import { optionsQueryFieldRefs } from "@cosmicdrift/kumiko-types/fields";
 import { isEncryptedAtRest } from "../config-helpers.js";
 // --- Toggleable-dependency warnings ---
 //
@@ -123,6 +124,18 @@ export function validateConfigKeyOptionsQuery(feature) {
         if (keyDef.allowPerRequest) {
             throw new Error(`${prefix} has optionsQuery AND allowPerRequest=true — a per-request value would bypass the option set unchecked`);
         }
+        validateOptionsQueryKeyRefs(feature, keyName, keyDef);
+    }
+}
+function validateOptionsQueryKeyRefs(feature, keyName, keyDef) {
+    const prefix = `[Feature ${feature.name}] Config key "${keyName}"`;
+    for (const ref of optionsQueryFieldRefs(keyDef.optionsQueryPayload)) {
+        if (ref === keyName) {
+            throw new Error(`${prefix} optionsQueryPayload references itself ({ field: "${ref}" })`);
+        }
+        if (feature.configKeys[ref] === undefined) {
+            throw new Error(`${prefix} optionsQueryPayload references unknown config key "${ref}" of feature "${feature.name}"`);
+        }
     }
 }
 // --- Config key storage backing × scope matrix ---

package/dist/engine/boot-validator/entity-handler.js

@@ -1,5 +1,6 @@
 import { isRateLimitDisabled } from "@cosmicdrift/kumiko-types/handlers";
 import { VARIANT_NAME_PATTERN } from "../../derivatives/variant-key.js";
+import { access as accessPresets } from "../config-helpers.js";
 import { parseRefTarget } from "../parse-ref-target.js";
 export const FILE_FIELD_TYPES = new Set(["file", "image", "files", "images"]);
 // Field-Namen die typischerweise PII enthalten. Ohne `pii: true` /
@@ -150,7 +151,7 @@ export function validateNoAllRoleInHandlerAccess(featureName, kind, handlerName,
     if (!("roles" in access))
         return;
     // skip: no "all" in the roles list, nothing unreachable to report
-    if (!access.roles.includes("all"))
+    if (!accessPresets.all.some((role) => access.roles.includes(role)))
         return;
     throw new Error(`${kind} handler "${featureName}:${kind}:${handlerName}" declares access: { roles: ["all"] } — ` +
         `no session ever carries the role "all", so this handler is unreachable by any caller. ` +
@@ -578,8 +579,19 @@ function validateEmbeddedListMetadata(fieldName, entityName, field, entity) {
 // default — wenn gesetzt — ist eine Teilmenge der options. Beides würde
 // auch im Zod-Schema bei runtime fehlschlagen, der Boot-Catch ist nur
 // die früheste Stelle für klare Fehlermeldungen.
+// Exhaustive over MultiSelectFieldDef["columns"] (the compiler flags a union
+// change); the TS union is gone at runtime for JS/JSON-sourced definitions.
+const CHECKBOX_COLUMN_COUNTS = {
+    1: true,
+    2: true,
+    3: true,
+    4: true,
+};
 function validateCheckboxDisplayOptions(field, fieldName, entityName) {
     if (field.display === "checkboxes") {
+        if (field.columns !== undefined && !(field.columns in CHECKBOX_COLUMN_COUNTS)) {
+            throw new Error(`MultiSelect field "${fieldName}" on entity "${entityName}" has invalid columns "${field.columns}" — must be ${Object.keys(CHECKBOX_COLUMN_COUNTS).join(", ")}.`);
+        }
         if (field.maxRows !== undefined && (!Number.isInteger(field.maxRows) || field.maxRows < 1)) {
             throw new Error(`MultiSelect field "${fieldName}" on entity "${entityName}" has invalid maxRows "${field.maxRows}" — must be a positive integer.`);
         }

package/dist/engine/boot-validator/entity-list-screens.d.ts

@@ -1,4 +1,5 @@
 import type { FeatureDefinition } from "../types/index.js";
 /** Operator lists default searchable; low-cardinality audit trails stay opt-out. */
 export declare const SEARCHABLE_FALSE_WHITELIST: Set<string>;
+export declare const LIST_ROW_META_COLUMN_NAMES: Set<string>;
 export declare function validateEntityListScreens(features: readonly FeatureDefinition[]): void;

package/dist/engine/boot-validator/entity-list-screens.js

@@ -1,13 +1,13 @@
 import { LIST_ROW_META_COLUMNS } from "../../ui-types/list-row-meta.js";
 import { normalizeListColumn } from "../screen-helpers.js";
 /** Operator lists default searchable; low-cardinality audit trails stay opt-out. */
-export const SEARCHABLE_FALSE_WHITELIST = new Set(["download-attempt-list"]);
+export const SEARCHABLE_FALSE_WHITELIST = new Set(["download-attempt-list", "cap-list"]);
 // Same set computeListViewModel (headless) can actually render — NOT
 // db/table-builder's rowMetaFieldNames(softDelete), which also carries
 // isDeleted/deletedAt/deletedById. Accepting those here would let a
 // softDelete column pass the boot gate and then throw at render-time
 // because the renderer's LIST_ROW_META_COLUMNS doesn't know them.
-const LIST_ROW_META_COLUMN_NAMES = new Set(Object.keys(LIST_ROW_META_COLUMNS));
+export const LIST_ROW_META_COLUMN_NAMES = new Set(Object.keys(LIST_ROW_META_COLUMNS));
 function hasFilterableFields(feature, entityName) {
     const entities = feature.entities;
     if (!entities)

package/dist/engine/boot-validator/index.js

@@ -60,11 +60,11 @@ export function validateBoot(rawFeatures, options) {
     // `…:config:branding-title`; ohne toKebab failt jeder configEdit-Screen mit
     // multi-word Config-Key fälschlich. allConfigKeys oben nutzt das ältere
     // `feature.short`-Format für validateConfigReads.
-    const allConfigKeyQns = new Set();
+    const configKeyDefsByQn = new Map();
     for (const f of features) {
-        for (const key of Object.keys(f.configKeys)) {
+        for (const [key, def] of Object.entries(f.configKeys)) {
             allConfigKeys.add(`${f.name}.${key}`);
-            allConfigKeyQns.add(qualifyEntityName(f.name, QnTypes.config, key));
+            configKeyDefsByQn.set(qualifyEntityName(f.name, QnTypes.config, key), def);
         }
     }
     // Collect all claim keys — the ownership-rule validator below resolves
@@ -153,7 +153,7 @@ export function validateBoot(rawFeatures, options) {
         // Function-Check hier überhaupt liefe.
         validateActionWiring(feature);
         validateFieldWiring(feature);
-        validateScreens(feature, featureMap, allWriteHandlerQns, allScreenQns, allConfigKeyQns, screensByShortId, detailForScreens);
+        validateScreens(feature, featureMap, allWriteHandlerQns, allScreenQns, configKeyDefsByQn, screensByShortId, detailForScreens);
         validateNavs(feature, allScreenQns, allNavQns, allWorkspaceQns);
         validateWorkspaces(feature, allNavQns);
     }
@@ -161,7 +161,7 @@ export function validateBoot(rawFeatures, options) {
     warnOnNavAccessInversion(allNavQns);
     const effectiveNavAllowlist = resolveNavAllowlist(options?.navAllowlist, allNavQns, allWorkspaceQns);
     if (effectiveNavAllowlist !== undefined) {
-        warnOnUnreachableNavScreens(allNavQns, effectiveNavAllowlist, options?.navAllowlistExempt);
+        warnOnUnreachableNavScreens(allNavQns, effectiveNavAllowlist, options?.navAllowlistExempt, options?.navAllowlist === undefined ? "workspaces" : "explicit");
     }
     validateDefaultWorkspaceUniqueness(allWorkspaceQns);
     validateI18nSurfaceKeys(features);
@@ -188,7 +188,7 @@ export function validateBoot(rawFeatures, options) {
         // custom KMS provider) satisfies the requirement without env keys.
         validateEntityFieldEncryptionAvailable(options?.env);
     }
-    if (hasFileFields && !process.env[FILE_STORAGE_PROVIDER_ENV]) {
+    if (hasFileFields && !(options?.env ?? process.env)[FILE_STORAGE_PROVIDER_ENV]) {
         throw new Error(`${FILE_STORAGE_PROVIDER_ENV} environment variable is required (file/image fields in use)`);
     }
     validateConfigReads(features, allConfigKeys);

package/dist/engine/boot-validator/nav.d.ts

@@ -14,7 +14,8 @@ export declare function validateNavCycles(allNavQns: ReadonlyMap<string, NavDefi
 export declare function warnOnNavAccessInversion(allNavQns: ReadonlyMap<string, NavDefinition & {
     readonly featureName: string;
 }>): void;
+export type NavAllowlistSource = "explicit" | "workspaces";
 export declare function warnOnUnreachableNavScreens(allNavQns: ReadonlyMap<string, NavDefinition & {
     readonly featureName: string;
-}>, allowedNavQns: ReadonlySet<string>, navAllowlistExempt?: ReadonlySet<string>): void;
+}>, allowedNavQns: ReadonlySet<string>, navAllowlistExempt?: ReadonlySet<string>, allowlistSource?: NavAllowlistSource): void;
 export declare function collectKnownRoles(features: readonly FeatureDefinition[]): Set<string>;

package/dist/engine/boot-validator/nav.js

@@ -125,6 +125,8 @@ export function warnOnNavAccessInversion(allNavQns) {
         const leafRoles = navViewerRoles(navDef.access);
         if (parentRoles === undefined || leafRoles === undefined)
             continue;
+        if (leafRoles.length === 0)
+            continue; // leaf visible to nobody (empty roles or invalid openToAll) — not an inversion
         if (parentRoles.length === 0)
             continue; // parent already visible to nobody — a different problem
         if (leafRoles.some((role) => parentRoles.includes(role)))
@@ -136,41 +138,29 @@ export function warnOnNavAccessInversion(allNavQns) {
             `otherwise align the role sets.`);
     }
 }
-// `NavDefinition.screen` is authored already-qualified ("<feature>:screen:
-// <id>", see packages/types/src/nav.ts) — this only guards a short id
-// slipping through, since a wrong qualification here would make every nav
-// look orphaned (28 false positives on the real offlot-app schema instead
-// of the intended 8, see fw#3019 measurement).
-function qualifyNavScreenQn(featureName, screen) {
-    return screen.includes(":screen:") ? screen : `${featureName}:screen:${screen}`;
-}
-// fw#3019: warn (never throw — a screen deliberately left out of the app's
-// sidebar is legitimate) when a declared nav's screen isn't reachable from
-// any allowlisted nav entry. Checking "nav QN not in allowlist" directly
-// warned 28x on the real offlot-app schema (58 navs, 30 allowed) — most of
-// them app-shell leaves that intentionally re-target a screen another,
-// allowlisted nav already reaches. Reachability warns only for a screen no
-// allowlisted nav points at, which is the actual "unreachable via sidebar"
-// bug (solon#113, offlot's VIN screen in pilot).
-export function warnOnUnreachableNavScreens(allNavQns, allowedNavQns, navAllowlistExempt = new Set()) {
+export function warnOnUnreachableNavScreens(allNavQns, allowedNavQns, navAllowlistExempt = new Set(), allowlistSource = "explicit") {
     const reachableScreenQns = new Set();
     for (const [qn, navDef] of allNavQns) {
         if (!allowedNavQns.has(qn) || navDef.screen === undefined)
             continue;
-        reachableScreenQns.add(qualifyNavScreenQn(navDef.featureName, navDef.screen));
+        reachableScreenQns.add(navDef.screen);
     }
     for (const [qn, navDef] of allNavQns) {
         if (allowedNavQns.has(qn) || navDef.screen === undefined || navAllowlistExempt.has(qn)) {
             continue;
         }
-        const screenQn = qualifyNavScreenQn(navDef.featureName, navDef.screen);
+        // validateNavs already guarantees a registered, qualified screen QN
+        const screenQn = navDef.screen;
         if (reachableScreenQns.has(screenQn))
             continue;
+        const remedy = allowlistSource === "workspaces"
+            ? "add it to a workspace's `nav` array or set `workspaces` on the nav"
+            : "add it to the allowlist";
         // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
         console.warn(`[kumiko:boot] Nav entry "${qn}" declared by feature "${navDef.featureName}" points at ` +
             `screen "${screenQn}", which no allowlisted nav entry reaches — it is unreachable via ` +
             `the sidebar. If this is intentional (e.g. reachable through a generated hub), add ` +
-            `"${qn}" to navAllowlistExempt; otherwise add it to the allowlist.`);
+            `"${qn}" to navAllowlistExempt; otherwise ${remedy}.`);
     }
 }
 // Roles we recognise at boot time. The framework has no explicit

package/dist/engine/boot-validator/ownership.d.ts

@@ -1,4 +1,4 @@
-import type { OwnershipMap, WhereRule } from "../ownership.js";
+import { type OwnershipMap, type WhereRule } from "../ownership.js";
 import type { ClaimKeyDefinition, FeatureDefinition } from "../types/index.js";
 export type WhereRuleProbe = {
     readonly table: unknown;

package/dist/engine/boot-validator/ownership.js

@@ -1,4 +1,5 @@
 import { buildEntityTable } from "../../db/table-builder.js";
+import { tableNameOf, } from "../ownership.js";
 import { SYSTEM_USER_ID } from "../system-user.js";
 import { SYSTEM_TENANT_ID } from "../types/identifiers.js";
 import { assertQualifiedWhereFragment, tableColumnSqlNames } from "../where-rule-lint.js";
@@ -68,7 +69,7 @@ export function validateOwnershipRules(feature, allClaimKeys, knownRoles) {
             const table = buildEntityTable(entityName, entity);
             const columns = tableColumnSqlNames(table);
             if (columns.size > 0) {
-                probe = { table, tableName: entity.table ?? entityName, columns };
+                probe = { table, tableName: tableNameOf(table), columns };
             }
         }
         catch {

package/dist/engine/boot-validator/pii-retention.d.ts

@@ -1,2 +1,4 @@
+import type { EntityDefinition } from "../types/fields.js";
 import type { FeatureDefinition } from "../types/index.js";
+export declare function entityHasAnonymizableSubjectField(fields: EntityDefinition["fields"]): boolean;
 export declare function validatePiiAndRetention(feature: FeatureDefinition): void;

package/dist/engine/boot-validator/pii-retention.js

@@ -17,6 +17,9 @@ const KEEP_FOR_PATTERN = /^\d+[hdwmy]$/;
 function hasAnonymizableSubjectField(annot) {
     return Boolean(annot.pii || annot.userOwned || annot.tenantOwned || annot.recordOwned);
 }
+export function entityHasAnonymizableSubjectField(fields) {
+    return Object.values(fields).some((f) => hasAnonymizableSubjectField(f));
+}
 function ownerFieldNamesReferencedByPersonalOf(fieldsByName) {
     const ownerFieldNames = new Set();
     for (const field of Object.values(fieldsByName)) {
@@ -26,6 +29,42 @@ function ownerFieldNamesReferencedByPersonalOf(fieldsByName) {
     }
     return ownerFieldNames;
 }
+const WRITE_ONLY_FORBIDDEN_FLAGS = [
+    "default",
+    "searchable",
+    "sortable",
+    "filterable",
+    "lookupable",
+];
+function validateWriteOnlyField(featureName, entityName, fieldName, field) {
+    const where = `[Feature ${featureName}] Field "${fieldName}" on entity "${entityName}"`;
+    if (field.type === "embedded") {
+        for (const [subName, subField] of Object.entries(field.schema)) {
+            if (subField.writeOnly === true) {
+                // @cast-boundary schema-walk
+                throw new Error(`${where} declares writeOnly on embedded sub-field "${subName}" — writeOnly is only supported on top-level text fields.`);
+            }
+        }
+        // skip: embedded fields carry no writeOnly of their own; sub-fields are checked above
+        return;
+    }
+    const flags = field; // @cast-boundary schema-walk
+    // skip: only writeOnly fields have constraints to validate
+    if (flags.writeOnly !== true)
+        return;
+    if (field.type !== "text") {
+        throw new Error(`${where} declares { writeOnly: true } but has type "${field.type}" — writeOnly only applies to text fields.`);
+    }
+    if (field.sensitive !== true) {
+        throw new Error(`${where} declares { writeOnly: true } without { sensitive: true } — add find: "secret" (ciphertext at rest, stripped from event echoes).`);
+    }
+    for (const flag of WRITE_ONLY_FORBIDDEN_FLAGS) {
+        const value = flags[flag];
+        if (value !== undefined && value !== false) {
+            throw new Error(`${where} combines { writeOnly: true } with { ${flag} } — a value that is never returned cannot be defaulted, searched, sorted, filtered or looked up.`);
+        }
+    }
+}
 // --- PII / Subject-Key Annotations + Retention validation ---
 //
 // Drei Klassen von Checks:
@@ -92,19 +131,20 @@ export function validatePiiAndRetention(feature) {
                 sensitiveFlags.encrypted !== true) {
                 throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares { sensitive: true } without ciphertext-at-rest. Since #967 the event log stores sensitive fields as table ciphertext — add a subject annotation (personal: "self" / "tenant" / { of: "<field>" }) or { encrypted: true }.`);
             }
+            validateWriteOnlyField(feature.name, entityName, fieldName, field);
             // Sorting reads the projection column — that stays ciphertext, so
             // sortable + subject annotation stays a boot-fail. searchable has
             // been allowed since #1610: the search consumer decrypts into the
             // derived index and forget purges those docs (see
             // createSearchEventConsumer). sensitive + searchable stays forbidden
-            // (nobody-may-read-back).
+            // (never searchable).
             {
                 const flags = field; // @cast-boundary schema-walk
                 if (annotCount > 0 && flags.sortable === true) {
                     throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" combines a subject-key annotation with { sortable: true } — sorting reads the projection column, which is ciphertext at rest. For equality lookups use find: "exact"; drop sortable or keep the field plaintext (personal: false).`);
                 }
                 if (flags.sensitive === true && flags.searchable === true) {
-                    throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" combines { sensitive: true } with { searchable: true } — sensitive means nobody may read the value back (passwords, tokens, tax IDs). Subject-annotated identity fields may be searchable (#1610); sensitive fields may not.`);
+                    throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" combines { sensitive: true } with { searchable: true } — sensitive means ciphertext at rest, never searchable, stripped from event echoes — authorized readers can still read it back (passwords, tokens, tax IDs). Subject-annotated identity fields may be searchable (#1610); sensitive fields may not. To never return the value at all, add { writeOnly: true }.`);
                 }
             }
             if (annot.userOwned) {
@@ -179,12 +219,12 @@ export function validatePiiAndRetention(feature) {
                 // blockDelete with no field that can carry `anonymize` is fine;
                 // subjectRef-only entities are covered by the V3 EXT_USER_DATA guard
                 // instead (#1622, #2336).
-                const entityHasAnonymizableSubjectField = Object.values(fieldsByName).some((f) => hasAnonymizableSubjectField(f));
+                const entityHasAnonymizableField = entityHasAnonymizableSubjectField(fieldsByName);
                 const hasAnonymize = Object.values(fieldsByName).some((f) => {
                     const a = f; // @cast-boundary schema-walk
                     return Boolean(a.anonymize);
                 });
-                if (entityHasAnonymizableSubjectField && !hasAnonymize) {
+                if (entityHasAnonymizableField && !hasAnonymize) {
                     // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
                     console.warn(`[kumiko:boot] [Feature ${feature.name}] Entity "${entityName}" retention.strategy="blockDelete" but no field has an anonymize-function. User-Forget cannot anonymize — Forget will return error. Add { anonymize: () => null } or () => "[ANONYMIZED]" to PII fields.`);
                 }

package/dist/engine/boot-validator/projection-list-screens.js

@@ -88,6 +88,9 @@ const RESERVED_LIST_PAYLOAD_KEYS = new Set([
     "filters",
 ]);
 function validateProjectionListDateRangeFacets(prefix, screen, schema) {
+    // Shared params overwrite each other in the payload, silently dropping the first pick.
+    // (Two facets on one field are already rejected by the generic duplicate-facet check.)
+    const usedParams = new Set();
     for (const facet of screen.facets ?? []) {
         if (facet.type !== "dateRange")
             continue;
@@ -100,6 +103,11 @@ function validateProjectionListDateRangeFacets(prefix, screen, schema) {
                 throw new Error(`${prefix}: dateRange facet on "${facet.field}" names "${param}" as a bound, ` +
                     `which is a reserved list-payload key — pick the query's own time-bound param names.`);
             }
+            if (usedParams.has(param)) {
+                throw new Error(`${prefix}: dateRange facet on "${facet.field}" names "${param}" which another dateRange ` +
+                    `facet on this screen already uses — the facets would overwrite each other's bound.`);
+            }
+            usedParams.add(param);
             if (schemaAccepts(schema, param))
                 continue;
             throw new Error(`${prefix}: dateRange facet on "${facet.field}" sends "${param}" but query ` +

package/dist/engine/boot-validator/query-output-columns.js

@@ -1,5 +1,5 @@
 import { isPagedQueryHandler } from "../define-handler.js";
-import { normalizeListColumn } from "../screen-helpers.js";
+import { normalizeListColumn, sectionFieldSpecs } from "../screen-helpers.js";
 import { metricField } from "../types/index.js";
 import { buildQueryHandlerMap } from "./projection-list-screens.js";
 import { validateActionFieldRefs } from "./screens.js";
@@ -37,8 +37,23 @@ function checkPagedHandlerOutputSchemaShape(queryHandlers) {
         throw new Error(`Query handler "${qn}" is a paged handler (definePagedQueryHandler) but its outputSchema does not describe the paged envelope { rows: [...], nextCursor, total? } — it has no "rows" field. Did you pass the row schema instead of wrapping it in the envelope?`);
     }
 }
+// Usage-site twin of checkPagedHandlerOutputSchemaShape: a plain
+// r.queryHandler/defineQueryHandler feeding a list surface has no paged
+// brand, so declaring the row shape instead of the `{ rows, ... }` envelope
+// would otherwise make every column check below a silent no-op.
+function resolveListRowShape(queryHandlers, queryQn, usage) {
+    const outputSchema = queryHandlers.get(queryQn)?.outputSchema;
+    const rowShape = getZodRowShape(outputSchema);
+    if (rowShape !== undefined)
+        return rowShape;
+    const envelopeShape = getZodObjectShape(outputSchema);
+    // skip: no introspectable object schema (absent / union) — capability absent per module policy
+    if (envelopeShape === undefined || "rows" in envelopeShape)
+        return undefined;
+    throw new Error(`${usage} uses query "${queryQn}" as a list source, but its outputSchema does not describe the paged envelope { rows: [...], nextCursor, total? } — it has no "rows" field. Did you pass the row schema instead of wrapping it in the envelope?`);
+}
 function checkProjectionListOutputColumns(queryHandlers, featureName, screenId, screen) {
-    const rowShape = getZodRowShape(queryHandlers.get(screen.query)?.outputSchema);
+    const rowShape = resolveListRowShape(queryHandlers, screen.query, `[Feature ${featureName}] Screen "${screenId}" (projectionList)`);
     for (const column of screen.columns) {
         checkColumnField(rowShape, column, (field) => `[Feature ${featureName}] Screen "${screenId}" (projectionList) column "${field}" is not present in query "${screen.query}"'s outputSchema — check for a typo, or add a "label" to mark it a virtual/computed column.`);
     }
@@ -47,7 +62,7 @@ function checkEditLayoutOutputColumns(queryHandlers, featureName, screenId, scre
     for (const section of layout.sections) {
         if (section.kind !== "relatedList")
             continue;
-        const rowShape = getZodRowShape(queryHandlers.get(section.query)?.outputSchema);
+        const rowShape = resolveListRowShape(queryHandlers, section.query, `[Feature ${featureName}] Screen "${screenId}" (${screenType}) relatedList section "${section.title}"`);
         for (const column of section.columns) {
             checkColumnField(rowShape, column, (field) => `[Feature ${featureName}] Screen "${screenId}" (${screenType}) relatedList section "${section.title}" column "${field}" is not present in query "${section.query}"'s outputSchema — check for a typo, or add a "label" to mark it a virtual/computed column.`);
         }
@@ -77,6 +92,9 @@ function checkProjectionDetailOutputFields(queryHandlers, featureName, screenId,
                 }
             }
         }
+        if (screen.header.subtitleHref !== undefined) {
+            checkHeaderField("subtitleHref", screen.header.subtitleHref);
+        }
         if (screen.header.status !== undefined)
             checkHeaderField("status", screen.header.status);
     }
@@ -88,8 +106,26 @@ function checkProjectionDetailOutputFields(queryHandlers, featureName, screenId,
         const field = metricField(metric);
         checkFieldExists(recordShape, field, () => `${prefix} metrics references field "${field}" which is not present in query "${screen.query}"'s outputSchema.`);
     }
+    checkDetailSectionFields(recordShape, prefix, screen);
     checkRelatedListToolbarActionFields(recordShape, featureName, screenId, screen);
 }
+// Field-grid sections read the enclosing record (the query result), so a typo
+// is a silently-empty cell. writeForm sections are skipped on purpose: their
+// fields are form inputs defined by `fieldDefs`, not necessarily record keys.
+function checkDetailSectionFields(recordShape, prefix, screen) {
+    for (const section of screen.layout.sections) {
+        const countField = "countField" in section ? section.countField : undefined;
+        if (countField !== undefined) {
+            checkFieldExists(recordShape, countField, () => `${prefix} section "${section.title ?? "(untitled)"}" countField references field "${countField}" which is not present in query "${screen.query}"'s outputSchema.`);
+        }
+        if (section.kind !== undefined && section.kind !== "fields")
+            continue;
+        for (const entry of sectionFieldSpecs(section)) {
+            const field = typeof entry === "string" ? entry : entry.field;
+            checkFieldExists(recordShape, field, () => `${prefix} section "${section.title ?? section.id ?? "(untitled)"}" references field "${field}" which is not present in query "${screen.query}"'s outputSchema.`);
+        }
+    }
+}
 // relatedList toolbarActions' visible/params evaluate against the ENCLOSING
 // projectionDetail's record, not the relatedList's own row — reuses the
 // same per-action field-ref check as rowActions/toolbarActions elsewhere
@@ -139,7 +175,7 @@ function checkDashboardOutputFields(queryHandlers, featureName, screenId, screen
             }
         }
         else if (panel.kind === "list") {
-            const rowShape = getZodRowShape(queryHandlers.get(panel.query)?.outputSchema);
+            const rowShape = resolveListRowShape(queryHandlers, panel.query, `[Feature ${featureName}] Screen "${screenId}" (dashboard) panel "${panel.id}"`);
             for (const column of panel.columns) {
                 checkColumnField(rowShape, column, (field) => `[Feature ${featureName}] Screen "${screenId}" (dashboard) panel "${panel.id}" column "${field}" is not present in query "${panel.query}"'s outputSchema — check for a typo, or add a "label" to mark it a virtual/computed column.`);
             }
@@ -154,7 +190,7 @@ function checkScreenOutputColumns(queryHandlers, featureName, screenId, screen)
     }
     else if (screen.type === "entityList") {
         if (screen.expandableRow !== undefined) {
-            const rowShape = getZodRowShape(queryHandlers.get(screen.expandableRow.query)?.outputSchema);
+            const rowShape = resolveListRowShape(queryHandlers, screen.expandableRow.query, `[Feature ${featureName}] Screen "${screenId}" (entityList) expandableRow "${screen.expandableRow.title}"`);
             for (const column of screen.expandableRow.columns) {
                 checkColumnField(rowShape, column, (field) => `[Feature ${featureName}] Screen "${screenId}" (entityList) expandableRow "${screen.expandableRow?.title}" column "${field}" is not present in query "${screen.expandableRow?.query}"'s outputSchema — check for a typo, or add a "label" to mark it a virtual/computed column.`);
             }

package/dist/engine/boot-validator/screens.d.ts

@@ -1,5 +1,5 @@
 import type { IconKey } from "@cosmicdrift/kumiko-types/nav-icon";
-import type { FeatureDefinition } from "../types/index.js";
+import type { ConfigKeyDefinition, FeatureDefinition } from "../types/index.js";
 import type { DashboardCustomPanel, DashboardScreenPanel, RelatedListToolbarAction, RowAction, RowFieldExtractor, ScreenDefinition, ToolbarAction } from "../types/screen.js";
 export declare function rowFieldExtractorKeys(params: RowFieldExtractor): readonly string[];
 export declare function readsNavigateParamsAsFormPrefill(target: ScreenDefinition, explicitEntityId: string | undefined, sourceScreenEntity: string | undefined): boolean;
@@ -13,7 +13,7 @@ export declare function validateScreenShortIdCollisions(screensByShortId: Readon
     readonly screen: ScreenDefinition;
 }>>): void;
 export declare function resolveScreenTargetQn(featureName: string, target: string): string;
-export declare function validateScreens(feature: FeatureDefinition, featureMap: ReadonlyMap<string, FeatureDefinition>, allWriteHandlerQns: ReadonlySet<string>, allScreenQns: ReadonlySet<string>, allConfigKeyQns: ReadonlySet<string>, screensByShortId: ReadonlyMap<string, ReadonlyArray<{
+export declare function validateScreens(feature: FeatureDefinition, featureMap: ReadonlyMap<string, FeatureDefinition>, allWriteHandlerQns: ReadonlySet<string>, allScreenQns: ReadonlySet<string>, configKeyDefsByQn: ReadonlyMap<string, ConfigKeyDefinition>, screensByShortId: ReadonlyMap<string, ReadonlyArray<{
     readonly featureName: string;
     readonly screen: ScreenDefinition;
 }>>, detailForScreens: ReadonlyMap<string, {