@cosmicdrift/kumiko-framework 0.327.0 → 0.328.1

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

@@ -0,0 +1,204 @@
+import { PII_DIRECT_NAME_HINTS, PII_USER_OWNED_NAME_HINTS, PII_USER_REFERENCE_NAME_HINTS, } from "./entity-handler.js";
+// Framework-managed Timestamp-Spalten — dürfen als retention.reference
+// genutzt werden auch wenn nicht in entity.fields deklariert.
+const FRAMEWORK_TIMESTAMP_FIELDS = new Set([
+    "createdAt",
+    "updatedAt",
+    "lastSeenAt",
+    "deletedAt",
+]);
+// Erlaubtes Format fuer retention.keepFor — Zahlen + Suffix (h/d/w/m/y).
+// Echtes Parsen kommt mit dem Cleanup-Job in Sprint 2; Boot-Validator
+// macht nur den Sanity-Check damit Tippfehler ("30days") frueh sichtbar
+// werden statt erst beim ersten Cleanup-Run.
+const KEEP_FOR_PATTERN = /^\d+[hdwmy]$/;
+// Excludes subjectRef: its `personal: "ref"` union member structurally
+// forbids `anonymize` (packages/types/src/fields.ts) — #2336.
+function hasAnonymizableSubjectField(annot) {
+    return Boolean(annot.pii || annot.userOwned || annot.tenantOwned || annot.recordOwned);
+}
+function ownerFieldNamesReferencedByPersonalOf(fieldsByName) {
+    const ownerFieldNames = new Set();
+    for (const field of Object.values(fieldsByName)) {
+        const ownerFieldName = field.userOwned?.ownerField; // @cast-boundary schema-walk
+        if (typeof ownerFieldName === "string")
+            ownerFieldNames.add(ownerFieldName);
+    }
+    return ownerFieldNames;
+}
+// --- PII / Subject-Key Annotations + Retention validation ---
+//
+// Drei Klassen von Checks:
+//
+// 1. Mutual exclusion: pro Field nur EINE der drei Subject-Annotations
+//    (pii / userOwned / tenantOwned). Mehr ist semantisch widersprüchlich
+//    weil pro Field genau ein Subject-Key gehört.
+//
+// 2. Reference-Integrity: userOwned.ownerField muss auf ein existierendes
+//    reference-Field zeigen (das auf user-Entity zeigen sollte). Erkennt
+//    Tippfehler und Drop-Refactorings beim Boot statt beim ersten
+//    Encrypt-Aufruf.
+//
+// 3. Heuristik-Warnings: Field-Namen die typischerweise PII enthalten
+//    (email, name, phone, body, etc.) ohne Annotation → Boot-Warning.
+//    Mit `{ personal: false, reason: "<reason>" }` unterdrückbar (geht in Audit).
+//
+// 4. Retention-Integrity: retention.reference (wenn gesetzt) muss auf
+//    ein bestehendes Field zeigen (oder Framework-Timestamp). retention.
+//    strategy="blockDelete" ohne anonymize-Felder ist sinnlos — User-
+//    Forget kann nichts machen, Warning.
+//
+// Encrypt/Decrypt-Mechanik landet in Sprint 3 (crypto-shredding); diese
+// Validation greift schon ab Sprint 0 damit Schema-Drift früh auffällt.
+export function validatePiiAndRetention(feature) {
+    for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
+        const fieldsByName = entity.fields;
+        const personalOfOwnerFieldNames = ownerFieldNamesReferencedByPersonalOf(fieldsByName);
+        for (const [fieldName, field] of Object.entries(fieldsByName)) {
+            // ResolvedPiiFlags properties are type-level optional. On field defs
+            // not extended via "& ResolvedPiiFlags" (Boolean, Money, Reference,
+            // Embedded), property access returns undefined at runtime. TS
+            // compile-time validation already rejected that case elsewhere →
+            // the cast is safe.
+            const annot = field; // @cast-boundary schema-walk
+            const hasPii = Boolean(annot.pii);
+            const hasUserOwned = Boolean(annot.userOwned);
+            const hasTenantOwned = Boolean(annot.tenantOwned);
+            const hasRecordOwned = Boolean(annot.recordOwned);
+            const annotCount = (hasPii ? 1 : 0) +
+                (hasUserOwned ? 1 : 0) +
+                (hasTenantOwned ? 1 : 0) +
+                (hasRecordOwned ? 1 : 0);
+            if (annotCount > 1) {
+                throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has multiple subject-key annotations (personal: "self" / "tenant" / { of: "<field>" }). Pick one — each field belongs to exactly one subject.`);
+            }
+            // lookupable (#818): nur text + nur MIT Subject-Annotation. Ohne
+            // Subject bleibt der Wert eh Klartext — der Blind-Index wäre eine
+            // zweite (deterministische!) Kopie ohne Nutzen.
+            if (annot.lookupable === true) {
+                if (field.type !== "text") {
+                    throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares find: "exact" (or "fuzzy") but has type "${field.type}" — blind-index equality lookups only apply to text fields.`);
+                }
+                if (annotCount === 0) {
+                    throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares find: "exact" (or "fuzzy") without a subject annotation (personal: "self" / "tenant" / { of: "<field>" }). Plaintext fields don't need a blind index — add personal or set find: "none".`);
+                }
+            }
+            // sensitive-Felder liegen seit #967 als Tabellen-Ciphertext im Event-
+            // Log — ohne ciphertext-at-rest würde der Append Klartext in die
+            // immutable History schreiben.
+            const sensitiveFlags = field; // @cast-boundary schema-walk
+            if (sensitiveFlags.sensitive === true &&
+                annotCount === 0 &&
+                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 }.`);
+            }
+            // 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).
+            {
+                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.`);
+                }
+            }
+            if (annot.userOwned) {
+                const ownerName = annot.userOwned.ownerField;
+                if (!ownerName || typeof ownerName !== "string") {
+                    throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has personal: { of: ... } without an owner field name`);
+                }
+                const ownerField = fieldsByName[ownerName];
+                if (!ownerField) {
+                    const known = Object.keys(fieldsByName).sort().join(", ");
+                    throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" references personal.of "${ownerName}" but no such field exists. Known fields: ${known}`);
+                }
+                // Text is accepted alongside reference: the ES-framework carries
+                // user ids as plain text columns throughout the bundled features
+                // (user-session.userId, invitation.invitedBy) — there is no
+                // relational FK to point a reference at. Self-referencing
+                // ownerField (the field's own value IS the owner id) rides on this.
+                if (ownerField.type !== "reference" && ownerField.type !== "text") {
+                    throw new Error(`[Feature ${feature.name}] personal.of "${ownerName}" on entity "${entityName}" must be a reference or text (userId) field, got type "${ownerField.type}"`);
+                }
+                // Soft-Warning wenn das reference-target nicht offensichtlich user
+                // ist — custom subject-entities (HR-Mitarbeiter, Patient) sind
+                // erlaubt, müssen aber bewusste Wahl sein.
+                if (ownerField.type === "reference") {
+                    const refTarget = ownerField.entity;
+                    const targetEntity = refTarget.includes(":") ? refTarget.split(":")[1] : refTarget;
+                    if (targetEntity !== "user") {
+                        // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+                        console.warn(`[kumiko:boot] [Feature ${feature.name}] personal.of "${ownerName}" on entity "${entityName}" targets reference "${refTarget}" — typically should be a user reference. If intentional (custom subject-entity like employee/patient), ignore.`);
+                    }
+                }
+            }
+            // PII-Heuristik: nur wenn keine Annotation gesetzt UND kein
+            // allowPlaintext-Marker. Ergibt false positives auf Geschäftsdaten
+            // mit personenartigem Namen (z.B. company.legalName) — Author
+            // unterdrückt mit { personal: false, reason: "is_business_data" }.
+            const noAnnotation = annotCount === 0 && !annot.allowPlaintext;
+            if (noAnnotation) {
+                const lower = fieldName.toLowerCase();
+                if (PII_DIRECT_NAME_HINTS.has(lower)) {
+                    // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+                    console.warn(`[kumiko:boot] [Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has a PII-typical name but no personal annotation. If this is PII, mark it { personal: "self", find: ... }. If business data, set { personal: false, reason: "is_business_data" } to silence.`);
+                }
+                else if (PII_USER_OWNED_NAME_HINTS.has(lower)) {
+                    // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+                    console.warn(`[kumiko:boot] [Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has a user-content-typical name but no personal annotation. If this contains user-generated content, mark it { personal: { of: "<authorIdField>" }, find: ... }. If business data, set { personal: false, reason: "..." } to silence.`);
+                }
+                else if (PII_USER_REFERENCE_NAME_HINTS.has(lower) &&
+                    !annot.subjectRef &&
+                    !personalOfOwnerFieldNames.has(fieldName)) {
+                    // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+                    console.warn(`[kumiko:boot] [Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has a user-reference-typical name but no personal annotation — a foreign key into \`user\` carries Art.17 obligations even with no annotated content on the entity. Mark it { personal: "ref" } AND register r.useExtension(EXT_USER_DATA, "${entityName}", …) for Art.17 coverage — this warning is the only boot-time check for that, registering the hook is not enforced. Or { personal: { of: "${fieldName}" } } on the field it owns. If business data, set { personal: false, reason: "..." } to silence.`);
+                }
+            }
+        }
+        // --- Entity-level retention ---
+        const retention = entity.retention;
+        if (retention) {
+            if (!KEEP_FOR_PATTERN.test(retention.keepFor)) {
+                // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+                console.warn(`[kumiko:boot] [Feature ${feature.name}] Entity "${entityName}" retention.keepFor="${retention.keepFor}" hat ungueltiges Format. Erwartet: <Zahl><h|d|w|m|y> (z.B. "30d", "10y", "6m"). Cleanup-Job (Sprint 2) wird das nicht parsen koennen.`);
+            }
+            if (retention.reference !== undefined) {
+                const refName = retention.reference;
+                if (!fieldsByName[refName] && !FRAMEWORK_TIMESTAMP_FIELDS.has(refName)) {
+                    const known = Object.keys(fieldsByName).sort().join(", ");
+                    const framework = [...FRAMEWORK_TIMESTAMP_FIELDS].sort().join(", ");
+                    throw new Error(`[Feature ${feature.name}] Entity "${entityName}" retention.reference "${refName}" does not exist. Known fields: ${known} — framework-managed timestamps also accepted: ${framework}`);
+                }
+            }
+            if (retention.strategy === "blockDelete") {
+                // 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 hasAnonymize = Object.values(fieldsByName).some((f) => {
+                    const a = f; // @cast-boundary schema-walk
+                    return Boolean(a.anonymize);
+                });
+                if (entityHasAnonymizableSubjectField && !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.`);
+                }
+                else if (!entityHasAnonymizableSubjectField) {
+                    const hasSubjectRef = Object.values(fieldsByName).some((f) => {
+                        const a = f; // @cast-boundary schema-walk
+                        return Boolean(a.subjectRef);
+                    });
+                    if (hasSubjectRef) {
+                        // 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" with subjectRef-only PII relies on the EXT_USER_DATA delete hook for Art.17 — make sure it is not a no-op.`);
+                    }
+                }
+            }
+        }
+    }
+}

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

@@ -0,0 +1,4 @@
+import type { FeatureDefinition, QueryHandlerDef } from "../types/index.js";
+export declare function buildQueryHandlerMap(features: readonly FeatureDefinition[]): ReadonlyMap<string, QueryHandlerDef>;
+export declare function validateProjectionListScreens(features: readonly FeatureDefinition[]): void;
+export declare function validateRelatedListSectionQueries(features: readonly FeatureDefinition[]): void;

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

@@ -0,0 +1,219 @@
+import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handlers";
+import { parseQn, QnTypes, qualifyEntityName } from "../qualified-name.js";
+import { isEditLayoutScreen } from "../screen-helpers.js";
+import { SEARCHABLE_FALSE_WHITELIST } from "./entity-list-screens.js";
+import { findEntity } from "./parent-ref.js";
+import { getZodObjectShape } from "./zod-shape.js";
+// Sibling to entity-list-screens.ts rather than an extension of it:
+// validateOneEntityListScreen is typed to EntityListScreenDefinition and
+// reaches into feature.entities[screen.entity] — a projectionList has no
+// entity, so sharing the function would mean threading a discriminated
+// union through every entity-bound helper it calls.
+// Exported for query-refs.ts (fw#2178) — one source for the QN-derivation
+// logic instead of duplicating it in both boot-validators.
+export function buildQueryHandlerMap(features) {
+    const out = new Map();
+    for (const feature of features) {
+        for (const [name, handler] of Object.entries(feature.queryHandlers ?? {})) {
+            out.set(qualifyEntityName(feature.name, QnTypes.query, name), handler);
+        }
+    }
+    return out;
+}
+// Non-ZodObject schemas (e.g. a z.union across payload shapes) and
+// unresolved query handlers both fall through to "capability absent" —
+// consistent with buildAppSchema's derivation, no throw either way.
+function schemaAccepts(schema, key) {
+    const shape = getZodObjectShape(schema);
+    return shape !== undefined && key in shape;
+}
+function validateOneProjectionListScreen(feature, screen, queryHandlers) {
+    const prefix = `[projectionList] Feature "${feature.name}" screen "${screen.id}"`;
+    const schema = queryHandlers.get(screen.query)?.schema;
+    if (screen.searchable === true && !schemaAccepts(schema, "search")) {
+        throw new Error(`${prefix}: searchable: true but query "${screen.query}" has no "search" parameter in its Zod schema`);
+    }
+    if (screen.searchable === false &&
+        schemaAccepts(schema, "search") &&
+        !SEARCHABLE_FALSE_WHITELIST.has(screen.id)) {
+        throw new Error(`${prefix}: query "${screen.query}" accepts "search" but searchable: false disables it — remove searchable: false or add "${screen.id}" to SEARCHABLE_FALSE_WHITELIST`);
+    }
+    // sortable/paginated are derived by buildAppSchema from the query's Zod
+    // schema (fw#2165) — there is no separate wire type from the author-facing
+    // ProjectionListScreenDefinition, so hand-authoring them would otherwise be
+    // silently overwritten with no signal to the author. Reject outright.
+    if (screen.sortable !== undefined) {
+        throw new Error(`${prefix}: sortable is derived from the query's Zod schema, don't set it`);
+    }
+    if (screen.paginated !== undefined) {
+        throw new Error(`${prefix}: paginated is derived from the query's Zod schema, don't set it`);
+    }
+    const searchActive = screen.searchable !== false && schemaAccepts(schema, "search");
+    const sortActive = schemaAccepts(schema, "sort");
+    if ((searchActive || sortActive) && screen.defaultSort === undefined) {
+        throw new Error(`${prefix}: defaultSort required when search or sort is active`);
+    }
+    validateProjectionListFilterSchemaAcceptance(prefix, screen, schema);
+    validateProjectionListFacetsSchemaAcceptance(prefix, screen, schema);
+}
+// filter (fw#2224) sends `payload.filter` — same 422 footgun as facets below
+// if the handler's schema doesn't accept it.
+function validateProjectionListFilterSchemaAcceptance(prefix, screen, schema) {
+    // skip: no filter declared, or the schema already accepts it — nothing to reject.
+    if (screen.filter === undefined || schemaAccepts(schema, "filter"))
+        return;
+    throw new Error(`${prefix}: declares filter but query "${screen.query}" has no "filter" parameter in its Zod ` +
+        `schema — add filter: z.object({ field: z.string(), op: z.enum(["eq","ne","lt","gt","lte","gte","in"]), ` +
+        `value: z.unknown() }).optional() (or reuse entityListSchema's shape) to the handler's schema.`);
+}
+// facets (fw#2224) send `payload.filters` — same failure mode as search/sort
+// (fw#2165): definePagedQueryHandler doesn't auto-merge params into the
+// handler's own Zod schema, so a declared facet would 422 on every query
+// unless the author added `filters` themselves.
+// A dateRange facet (fw#3104) sends its two bounds as the top-level payload
+// keys it names in `params`, not as a `filters` entry — so the query has to
+// accept exactly those keys. Catches the facet pointed at a field the query
+// can't narrow by, which would otherwise 422 on the first date the user picks.
+// Keys buildListQueryPayload owns — a facet param naming one of them would
+// silently replace the list's own paging/sorting on every pick.
+const RESERVED_LIST_PAYLOAD_KEYS = new Set([
+    "limit",
+    "search",
+    "sort",
+    "sortDirection",
+    "offset",
+    "totalCount",
+    "cursor",
+    "filter",
+    "filters",
+]);
+function validateProjectionListDateRangeFacets(prefix, screen, schema) {
+    for (const facet of screen.facets ?? []) {
+        if (facet.type !== "dateRange")
+            continue;
+        if (facet.params.from === facet.params.to) {
+            throw new Error(`${prefix}: dateRange facet on "${facet.field}" names the same param ` +
+                `"${facet.params.from}" for both bounds.`);
+        }
+        for (const param of [facet.params.from, facet.params.to]) {
+            if (RESERVED_LIST_PAYLOAD_KEYS.has(param)) {
+                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 (schemaAccepts(schema, param))
+                continue;
+            throw new Error(`${prefix}: dateRange facet on "${facet.field}" sends "${param}" but query ` +
+                `"${screen.query}" has no "${param}" parameter in its Zod schema — add ` +
+                `${param}: z.iso.datetime().optional() to the handler's schema, or point ` +
+                `params at the keys it already accepts.`);
+        }
+    }
+}
+function validateProjectionListFacetsSchemaAcceptance(prefix, screen, schema) {
+    validateProjectionListDateRangeFacets(prefix, screen, schema);
+    // skip: no facets that travel via `filters` — nothing to reject.
+    if (screen.facets === undefined || !screen.facets.some((f) => f.type !== "dateRange"))
+        return;
+    // skip: the schema already accepts filters — nothing to reject.
+    if (schemaAccepts(schema, "filters"))
+        return;
+    throw new Error(`${prefix}: declares facets but query "${screen.query}" has no "filters" parameter in its ` +
+        `Zod schema — add filters: z.array(z.object({ field: z.string(), op: z.literal("in"), ` +
+        `value: z.unknown() })).optional() (or reuse entityListSchema's shape) to the handler's schema.`);
+}
+export function validateProjectionListScreens(features) {
+    const queryHandlers = buildQueryHandlerMap(features);
+    for (const feature of features) {
+        for (const screen of Object.values(feature.screens)) {
+            if (screen.type !== "projectionList")
+                continue;
+            validateOneProjectionListScreen(feature, screen, queryHandlers);
+        }
+    }
+}
+function validateRelatedListSearchable(prefix, section, schema) {
+    // skip: not searchable, or the schema already accepts search — nothing to reject.
+    if (section.searchable !== true || schemaAccepts(schema, "search"))
+        return;
+    throw new Error(`${prefix}: searchable: true but query "${section.query}" has no "search" parameter in its Zod schema`);
+}
+function validateRelatedListFacets(prefix, section, schema) {
+    // skip: no facets declared — nothing to reject.
+    if (section.facets === undefined || section.facets.length === 0)
+        return;
+    // skip: the schema already accepts filters — nothing to reject.
+    if (schemaAccepts(schema, "filters"))
+        return;
+    throw new Error(`${prefix}: declares facets but query "${section.query}" has no "filters" parameter in its Zod schema — add filters: z.array(z.object({ field: z.string(), op: z.literal("in"), value: z.unknown() })).optional() (or reuse entityListSchema's shape) to the handler's schema.`);
+}
+// parentFilter resolves an entity field map to
+// check `field` against ONLY when the query is one of the entity-convention
+// factories (defineEntityListHandler et al., branded by
+// ENTITY_CONVENTION_QUERY_BRAND) — a hand-written handler carries no entity,
+// same "capability absent, no throw" policy as schemaAccepts above. The
+// entity name comes from the handler's own `<entityName>:list` naming
+// convention (parseHandlerName in entity-handlers.ts), recovered here from
+// the query's fully qualified name.
+function resolveEntityBehindQuery(queryQn, handler, featureMap) {
+    if (handler === undefined || handler[ENTITY_CONVENTION_QUERY_BRAND] !== true)
+        return undefined;
+    let entityName;
+    try {
+        entityName = parseQn(queryQn).name.split(":")[0] ?? "";
+    }
+    catch {
+        return undefined;
+    }
+    return entityName === "" ? undefined : findEntity(featureMap, entityName);
+}
+// parentFilter lets a relatedList reuse the
+// generic `<entity>:list` query instead of a bespoke child-rows handler —
+// same 422 footgun as facets/filter above, plus its own mutual-exclusivity
+// and field-existence checks.
+function validateRelatedListParentFilter(prefix, section, schema, handler, featureMap) {
+    // skip: no parentFilter declared — nothing to reject.
+    if (section.parentFilter === undefined)
+        return;
+    if (section.parentParam !== undefined) {
+        throw new Error(`${prefix}: declares both parentFilter and parentParam — parentFilter replaces the implicit ` +
+            `{ [parentParam]: parentId } payload key with a server-side "filter" clause, so the two can't ` +
+            `be combined. Remove parentParam or drop parentFilter.`);
+    }
+    if (!schemaAccepts(schema, "filter")) {
+        throw new Error(`${prefix}: declares parentFilter but query "${section.query}" has no "filter" parameter in its ` +
+            `Zod schema — add filter: z.object({ field: z.string(), op: z.enum(["eq","ne","lt","gt","lte","gte","in"]), ` +
+            `value: z.unknown() }).optional() (or reuse entityListSchema's shape) to the handler's schema.`);
+    }
+    const entity = resolveEntityBehindQuery(section.query, handler, featureMap);
+    if (entity !== undefined && entity.fields[section.parentFilter.field] === undefined) {
+        throw new Error(`${prefix}: parentFilter.field "${section.parentFilter.field}" is not a declared field on the ` +
+            `entity behind query "${section.query}". Known fields: ${Object.keys(entity.fields).sort().join(", ")}.`);
+    }
+}
+// relatedList sections declare search/facets the same way a projectionList
+// screen does, and hit the same 422 footgun: definePagedQueryHandler doesn't
+// auto-merge params into the handler's own Zod schema (fw#2165/#2224), so an
+// undeclared param would fail every query instead of failing at boot.
+// Reachable on projectionDetail only (screens.ts rejects relatedList
+// elsewhere), but the layout walk stays uniform so lifting that restriction
+// doesn't quietly skip these checks.
+export function validateRelatedListSectionQueries(features) {
+    const queryHandlers = buildQueryHandlerMap(features);
+    const featureMap = new Map(features.map((f) => [f.name, f]));
+    for (const feature of features) {
+        for (const screen of Object.values(feature.screens)) {
+            if (!isEditLayoutScreen(screen))
+                continue;
+            for (const section of screen.layout.sections) {
+                if (section.kind !== "relatedList")
+                    continue;
+                const prefix = `[Feature ${feature.name}] Screen "${screen.id}" (${screen.type}) relatedList section "${section.title}"`;
+                const handler = queryHandlers.get(section.query);
+                const schema = handler?.schema;
+                validateRelatedListSearchable(prefix, section, schema);
+                validateRelatedListFacets(prefix, section, schema);
+                validateRelatedListParentFilter(prefix, section, schema, handler, featureMap);
+            }
+        }
+    }
+}

package/dist/engine/boot-validator/query-output-columns.d.ts

@@ -0,0 +1,2 @@
+import type { FeatureDefinition } from "../types/index.js";
+export declare function validateQueryOutputColumns(features: readonly FeatureDefinition[]): void;

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

@@ -0,0 +1,160 @@
+import { isPagedQueryHandler } from "../define-handler.js";
+import { normalizeListColumn } from "../screen-helpers.js";
+import { metricField } from "../types/index.js";
+import { buildQueryHandlerMap } from "./projection-list-screens.js";
+import { validateActionFieldRefs } from "./screens.js";
+import { getZodObjectShape, getZodRowShape } from "./zod-shape.js";
+function checkFieldExists(shape, field, buildMessage) {
+    // skip: capability absent (no introspectable shape) or field already present — nothing to validate
+    if (shape === undefined || field in shape)
+        return;
+    throw new Error(buildMessage());
+}
+// Mirrors entity-list-screens.ts's "unlabeled unknown column" convention: a
+// column with its own `label` is a virtual/computed cell drawn by a
+// renderer, not a row field — exempt from the shape check.
+function checkColumnField(rowShape, column, buildMessage) {
+    const normalized = normalizeListColumn(column);
+    // skip: labeled column is a virtual/computed cell drawn by a renderer, not a row field
+    if (normalized.label !== undefined)
+        return;
+    checkFieldExists(rowShape, normalized.field, () => buildMessage(normalized.field));
+}
+// A paged handler (definePagedQueryHandler) whose outputSchema describes the
+// row shape directly instead of the `{ rows, nextCursor, total? }` envelope
+// would otherwise fail silently: getZodRowShape finds no "rows" key and every
+// column check above just no-ops, so the author believes columns are checked
+// when none are. Catches only the realistic mistake (envelope has no "rows"
+// field at all) — an introspectable schema that isn't even a ZodObject is
+// still "capability absent" per the module policy above.
+function checkPagedHandlerOutputSchemaShape(queryHandlers) {
+    for (const [qn, handler] of queryHandlers) {
+        if (!isPagedQueryHandler(handler) || handler.outputSchema === undefined)
+            continue;
+        const shape = getZodObjectShape(handler.outputSchema);
+        if (shape === undefined || "rows" in shape)
+            continue;
+        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?`);
+    }
+}
+function checkProjectionListOutputColumns(queryHandlers, featureName, screenId, screen) {
+    const rowShape = getZodRowShape(queryHandlers.get(screen.query)?.outputSchema);
+    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.`);
+    }
+}
+function checkEditLayoutOutputColumns(queryHandlers, featureName, screenId, screenType, layout) {
+    for (const section of layout.sections) {
+        if (section.kind !== "relatedList")
+            continue;
+        const rowShape = getZodRowShape(queryHandlers.get(section.query)?.outputSchema);
+        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.`);
+        }
+    }
+}
+function checkProjectionDetailOutputFields(queryHandlers, featureName, screenId, screen) {
+    const recordShape = getZodObjectShape(queryHandlers.get(screen.query)?.outputSchema);
+    const prefix = `[Feature ${featureName}] Screen "${screenId}" (projectionDetail)`;
+    // @wrapper-known semantic-alias
+    const checkHeaderField = (part, field) => {
+        checkFieldExists(recordShape, field, () => `${prefix} header.${part} references field "${field}" which is not present in query "${screen.query}"'s outputSchema.`);
+    };
+    if (screen.header !== undefined) {
+        checkHeaderField("title", screen.header.title);
+        if (screen.header.subtitle !== undefined)
+            checkHeaderField("subtitle", screen.header.subtitle);
+        if (screen.header.status !== undefined)
+            checkHeaderField("status", screen.header.status);
+    }
+    for (const metric of screen.metrics ?? []) {
+        const field = metricField(metric);
+        checkFieldExists(recordShape, field, () => `${prefix} metrics references field "${field}" which is not present in query "${screen.query}"'s outputSchema.`);
+    }
+    checkRelatedListToolbarActionFields(recordShape, featureName, screenId, screen);
+}
+// 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
+// (validateActionFieldRefs), pinned to this screen's own outputSchema shape
+// instead of an entity's field map. Same additive policy as the rest of this
+// module: no introspectable outputSchema → no-op, not a throw.
+function checkRelatedListToolbarActionFields(recordShape, featureName, screenId, screen) {
+    // skip: no introspectable outputSchema — same additive policy as the rest of this module.
+    if (recordShape === undefined)
+        return;
+    const fieldNames = new Set(Object.keys(recordShape));
+    for (const section of screen.layout.sections) {
+        if (section.kind !== "relatedList")
+            continue;
+        for (const action of section.toolbarActions ?? []) {
+            validateActionFieldRefs(featureName, screenId, "toolbarAction", action.id, action, fieldNames, new Set());
+        }
+    }
+}
+// Stat panels' query contract is a flat record (not the paged `{ rows }`
+// envelope) — see DashboardStatPanel's doc in screen.ts — so this checks
+// the handler's outputSchema shape directly, not its row shape.
+function checkDashboardStatPanelFields(queryHandlers, featureName, screenId, panel) {
+    const recordShape = getZodObjectShape(queryHandlers.get(panel.query)?.outputSchema);
+    const prefix = `[Feature ${featureName}] Screen "${screenId}" (dashboard) panel "${panel.id}"`;
+    const checkPanelField = (part, field) => {
+        // skip: this stat-panel field slot is optional and wasn't declared — nothing to validate
+        if (field === undefined)
+            return;
+        checkFieldExists(recordShape, field, () => `${prefix} ${part} references field "${field}" which is not present in query "${panel.query}"'s outputSchema.`);
+    };
+    checkPanelField("valueField", panel.valueField);
+    checkPanelField("subField", panel.subField);
+    checkPanelField("toneField", panel.toneField);
+    checkPanelField("deltaField", panel.deltaField);
+    checkPanelField("deltaDirectionField", panel.deltaDirectionField);
+    checkPanelField("deltaToneField", panel.deltaToneField);
+}
+function checkDashboardOutputFields(queryHandlers, featureName, screenId, screen) {
+    for (const panel of screen.panels) {
+        if (panel.kind === "stat") {
+            checkDashboardStatPanelFields(queryHandlers, featureName, screenId, panel);
+        }
+        else if (panel.kind === "stat-group") {
+            for (const stat of panel.stats) {
+                checkDashboardStatPanelFields(queryHandlers, featureName, screenId, stat);
+            }
+        }
+        else if (panel.kind === "list") {
+            const rowShape = getZodRowShape(queryHandlers.get(panel.query)?.outputSchema);
+            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.`);
+            }
+        }
+        // chart/feed/progress-list/custom panels have a fixed query-result
+        // contract with no author-declared field names to check.
+    }
+}
+function checkScreenOutputColumns(queryHandlers, featureName, screenId, screen) {
+    if (screen.type === "projectionList") {
+        checkProjectionListOutputColumns(queryHandlers, featureName, screenId, screen);
+    }
+    else if (screen.type === "projectionDetail") {
+        checkProjectionDetailOutputFields(queryHandlers, featureName, screenId, screen);
+        checkEditLayoutOutputColumns(queryHandlers, featureName, screenId, "projectionDetail", screen.layout);
+    }
+    else if (screen.type === "entityEdit" ||
+        screen.type === "actionForm" ||
+        screen.type === "configEdit" ||
+        screen.type === "secretMint") {
+        checkEditLayoutOutputColumns(queryHandlers, featureName, screenId, screen.type, screen.layout);
+    }
+    else if (screen.type === "dashboard") {
+        checkDashboardOutputFields(queryHandlers, featureName, screenId, screen);
+    }
+}
+export function validateQueryOutputColumns(features) {
+    const queryHandlers = buildQueryHandlerMap(features);
+    checkPagedHandlerOutputSchemaShape(queryHandlers);
+    for (const feature of features) {
+        for (const [screenId, screen] of Object.entries(feature.screens)) {
+            checkScreenOutputColumns(queryHandlers, feature.name, screenId, screen);
+        }
+    }
+}

package/dist/engine/boot-validator/query-refs.d.ts

@@ -0,0 +1,2 @@
+import type { FeatureDefinition } from "../types/index.js";
+export declare function validateQueryRefs(features: readonly FeatureDefinition[]): void;