@cosmicdrift/kumiko-framework 0.334.0 → 0.336.0

package/dist/db/queries/backfill-pii.js

@@ -249,11 +249,21 @@ export async function backfillEventPiiEncryptionBatch(db, registry, options = {}
         const catalogFields = eventCatalog.get(row.type);
         if (catalogFields) {
             for (const [field, spec] of Object.entries(catalogFields)) {
-                const subject = resolveEventSubject(field, spec, payload, {
-                    tenantId: row.tenant_id, // @cast-boundary db-read — tenant_id column is the branded TenantId
-                    aggregateType: row.aggregate_type,
-                    aggregateId: row.aggregate_id,
-                });
+                let subject;
+                try {
+                    subject = resolveEventSubject(field, spec, payload, {
+                        tenantId: row.tenant_id, // @cast-boundary db-read — tenant_id column is the branded TenantId
+                        aggregateType: row.aggregate_type,
+                        aggregateId: row.aggregate_id,
+                    });
+                }
+                catch (e) {
+                    // Re-thrown as a plain Error: the owner-resolution retry hint added for
+                    // SubjectResolutionError only applies to entity events.
+                    if (!(e instanceof SubjectResolutionError))
+                        throw e;
+                    throw new Error(`catalog event subject unresolvable: ${e.message} (fix aggregate_type/tenant_id or the piiFields declaration)`);
+                }
                 if (subject === null)
                     continue;
                 const outcome = await encryptField(payload, field, subject);

package/dist/db/queries/shadow-swap.js

@@ -109,8 +109,8 @@ export async function assertLiveTableHasNoRowLevelSecurity(tx, tableName, projec
     throw new Error(`${context}: live table "${tableName}" has row level security (enabled: ${row.rls_enabled}, ` +
         `forced: ${row.rls_forced}, policies: ${row.policy_count}). The shadow swap rebuilds the table ` +
         "from EntityTableMeta and would silently drop RLS and every policy. Kumiko does not support RLS " +
-        "on rebuildable tables — see kumiko-platform docs/plans/rls-evaluation.md. Rebuild aborted; live " +
-        "table untouched.");
+        "on rebuildable tables: drop the RLS flags/policies on this table or exclude it from online " +
+        "rebuild. Rebuild aborted; live table untouched.");
 }
 // Runs INSIDE the rebuild tx, AFTER the state/consumer row lock is taken.
 // Points search_path at the shadow schema (SET LOCAL → auto-reset on commit or
@@ -227,8 +227,9 @@ export async function assertNoBlindIndexLoss(tx, tableName, meta, projectionName
     throw new Error(`projection-rebuild "${projectionName}": "${tableName}" has ${count} row(s) with a populated ` +
         `blind-index column, but KUMIKO_BLIND_INDEX_KEY is not configured in this process. The rebuild ` +
         `would recompute those columns to NULL, and equality lookups on that field (login, password ` +
-        `reset) would stop matching afterward. Configure the blind-index key before this apply/rebuild ` +
-        `runs. See fw#3091. Rebuild aborted; live table untouched.`);
+        `reset) would stop matching afterward. Configure the complete KMS wiring (PLATFORM_KEK, ` +
+        `SUBJECT_KEYS_DATABASE_URL, KUMIKO_BLIND_INDEX_KEY, all-or-none) in the process running this ` +
+        `apply/rebuild. See fw#3091. Rebuild aborted; live table untouched.`);
 }
 // Columns ignored by countColumnDrift — the one PROVABLY legitimate class of
 // live-vs-shadow divergence. A blind-index column (`<field>_bidx`) is

package/dist/db/table-builder.d.ts

@@ -5,6 +5,7 @@ import type { EntityDefinition, EntityRelations, FieldDefinition, FieldsMap } fr
 import type { Table } from "./event-store-executor-context.js";
 export { toSnakeCase } from "../utils/case.js";
 import { type ColumnBuilder, type ColumnHandle, type SchemaTable, type TableColumns } from "./dialect.js";
+export declare const SOFT_DELETE_LIVE_ROW_PREDICATE = "\"is_deleted\" = false";
 export declare function physicalColumnName(table: Table, field: string): string;
 export type AnyPgColumn = ColumnHandle;
 export declare const READ_MODEL_PREFIX = "read_";

package/dist/db/table-builder.js

@@ -2,7 +2,10 @@ import { KUMIKO_META_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types
 import { toSnakeCase } from "../utils/case.js";
 import { assertUnreachable } from "../utils/index.js";
 export { toSnakeCase } from "../utils/case.js";
-import { bigint, boolean, decimalColumn, doublePrecision, index, instant, integer, jsonb, moneyAmount, table as pgTable, plainDate, SQL_EXPR_BRAND, serial, sql, text, uniqueIndex, uuid, } from "./dialect.js";
+import { bigint, boolean, decimalColumn, doublePrecision, index, instant, integer, jsonb, moneyAmount, table as pgTable, plainDate, serial, sql, text, uniqueIndex, uuid, } from "./dialect.js";
+// Partial-index predicate for soft-delete entities; table-builder and
+// entity-table-meta must render identical index definitions.
+export const SOFT_DELETE_LIVE_ROW_PREDICATE = `"is_deleted" = false`;
 // Shared by the CRUD executor and the parent-ref read-gate — a field's
 // declared column name if it has one, else its snake_case default.
 export function physicalColumnName(table, field) {
@@ -382,13 +385,7 @@ export function buildEntityTable(entityName, entity, options) {
             else if (def.unique === true && entity.softDelete === true) {
                 // Soft-deleted rows keep their value, so a full unique index would
                 // permanently block reuse; kept in lock-step with entity-table-meta.ts (framework#2593).
-                const softDeleteWhere = {
-                    kind: "sql-expr",
-                    text: `"is_deleted" = false`,
-                    params: [],
-                    [SQL_EXPR_BRAND]: true,
-                };
-                chain = chain.where(softDeleteWhere);
+                chain = chain.where(sql.raw(SOFT_DELETE_LIVE_ROW_PREDICATE));
             }
             indexes[indexName] = chain;
             // Partielles bidx-Pendant für unique-Indices über lookupable-Spalten
@@ -407,14 +404,9 @@ export function buildEntityTable(entityName, entity, options) {
                         // restored row can't reuse a value a soft-deleted sibling still
                         // holds (framework#2464).
                         const whereText = (entity.softDelete === true
-                            ? [...notNullParts, `"is_deleted" = false`]
+                            ? [...notNullParts, SOFT_DELETE_LIVE_ROW_PREDICATE]
                             : notNullParts).join(" AND ");
-                        const partialWhere = {
-                            kind: "sql-expr",
-                            text: whereText,
-                            params: [],
-                            [SQL_EXPR_BRAND]: true,
-                        };
+                        const partialWhere = sql.raw(whereText);
                         indexes[`${indexName}_bidx`] = uniqueIndex(`${indexName}_bidx`)
                             .on(...bidxCols)
                             .where(partialWhere);

package/dist/db/tenant-db.js

@@ -3,8 +3,7 @@ import { SYSTEM_SCOPE_CHECK_BRAND, } from "@cosmicdrift/kumiko-types/tenant-db-t
 import { asEntityTableMeta, asRawClient, aggregateWhere as bunAggregateWhere, countWhere as bunCountWhere, deleteMany as bunDeleteMany, fetchOne as bunFetchOne, insertOne as bunInsertOne, selectMany as bunSelectMany, updateMany as bunUpdateMany, runInNewTransaction, } from "../db/query.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
 import { AccessDeniedError, InternalError, memberResolutionReadOnlyDenied, } from "../errors/index.js";
-import { fallbackEscapeHatchReporter } from "../observability/escape-hatch-report.js";
-import { emitDbQuery, registerStandardMetrics, } from "../observability/index.js";
+import { emitDbQuery, fallbackEscapeHatchReporter, registerStandardMetrics, } from "../observability/index.js";
 import { bindTenantDbRunner, tenantDbRunner } from "./tenant-db-runner.js";
 export { SYSTEM_SCOPE_CHECK_BRAND, } from "@cosmicdrift/kumiko-types/tenant-db-types";
 const declaredUnsafeRawRunners = new WeakMap();
@@ -361,6 +360,17 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
             return undefined;
         return new AccessDeniedError({ message });
     }
+    // A tenant-mode write against a "global" table can never match (rows carry SYSTEM_TENANT_ID, writeWhere pins the caller's tenant), so reject loudly instead of silently affecting zero rows.
+    function tenantWriteOnGlobalTable(table, method) {
+        if (mode !== "tenant" || !hasTenantColumn(table))
+            return undefined;
+        if (asEntityTableMeta(table)?.tenancy !== "global")
+            return undefined;
+        return new AccessDeniedError({
+            message: `${method}(${tableNameOf(table)}): "global" table rows carry SYSTEM_TENANT_ID and never match the caller's tenant; ` +
+                "use db.global(table) with escapeHatch instead.",
+        });
+    }
     function globalTable(table) {
         const meta = asEntityTableMeta(table);
         if (meta?.tenancy !== "global") {
@@ -466,6 +476,9 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
             if (!where || Object.keys(where).length === 0) {
                 return Promise.reject(new Error("TenantDb.updateMany without where would mass-update all tenant rows. Pass at least one where condition."));
             }
+            const globalDenied = tenantWriteOnGlobalTable(table, "updateMany");
+            if (globalDenied)
+                return Promise.reject(globalDenied);
             const personalDenied = personalDataDenied(table, Object.keys(set));
             if (personalDenied)
                 return Promise.reject(personalDenied);
@@ -476,6 +489,9 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
             if (!where || Object.keys(where).length === 0) {
                 return Promise.reject(new Error("TenantDb.deleteMany without where would mass-delete all tenant rows. Pass at least one where condition."));
             }
+            const globalDenied = tenantWriteOnGlobalTable(table, "deleteMany");
+            if (globalDenied)
+                return Promise.reject(globalDenied);
             const filter = writeWhere(table, where);
             return withDbSpan("delete", table, async () => bunDeleteMany(db, table, filter));
         },

package/dist/derivatives/variant-key.js

@@ -34,7 +34,9 @@ export function variantSuffix(name, spec) {
 // A full derivative-suffix segment is `<name>-<16 hex chars>` — mirrors
 // VARIANT_NAME_PATTERN (name grammar) + specHash's fixed 16-char slice.
 // Keep in sync with both if either changes.
-const DERIVATIVE_SUFFIX_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}-[0-9a-f]{16}$/i;
+// The hash part stays case-sensitive (specHash emits lowercase hex only), so
+// the erasure sweep never matches a differently-cased sibling file.
+const DERIVATIVE_SUFFIX_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9-]{0,31}-[0-9a-f]{16}$/;
 // Mirrors deriveKey's own split so callers get the exact same base/ext this
 // key's derivatives were built from.
 function splitKey(key) {

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/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)) {
@@ -216,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
@@ -128,6 +164,15 @@ function checkDashboardStatPanelFields(queryHandlers, featureName, screenId, pan
     checkPanelField("deltaDirectionField", panel.deltaDirectionField);
     checkPanelField("deltaToneField", panel.deltaToneField);
 }
+// visibleWhen reads a flat record like stat panels; a typo'd field would hide
+// the panel forever without any message.
+function checkScreenPanelVisibleWhenField(queryHandlers, featureName, screenId, panel) {
+    // skip: panel is always visible, no field to check
+    if (panel.visibleWhen === undefined)
+        return;
+    const { query, field } = panel.visibleWhen;
+    checkFieldExists(getZodObjectShape(queryHandlers.get(query)?.outputSchema), field, () => `[Feature ${featureName}] Screen "${screenId}" (dashboard) screen-panel "${panel.id}" visibleWhen references field "${field}" which is not present in query "${query}"'s outputSchema.`);
+}
 function checkDashboardOutputFields(queryHandlers, featureName, screenId, screen) {
     for (const panel of screen.panels) {
         if (panel.kind === "stat") {
@@ -138,8 +183,11 @@ function checkDashboardOutputFields(queryHandlers, featureName, screenId, screen
                 checkDashboardStatPanelFields(queryHandlers, featureName, screenId, stat);
             }
         }
+        else if (panel.kind === "screen") {
+            checkScreenPanelVisibleWhenField(queryHandlers, featureName, screenId, panel);
+        }
         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 +202,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, {