@cosmicdrift/kumiko-framework 0.328.0 → 0.328.1

package/src/engine/boot-validator/pii-retention.ts

@@ -1,272 +0,0 @@
-import type { FeatureDefinition } from "../types";
-import type { EntityDefinition, ResolvedPiiFlags } from "../types/fields";
-import {
-  PII_DIRECT_NAME_HINTS,
-  PII_USER_OWNED_NAME_HINTS,
-  PII_USER_REFERENCE_NAME_HINTS,
-} from "./entity-handler";
-
-// Framework-managed Timestamp-Spalten — dürfen als retention.reference
-// genutzt werden auch wenn nicht in entity.fields deklariert.
-const FRAMEWORK_TIMESTAMP_FIELDS: ReadonlySet<string> = 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: ResolvedPiiFlags): boolean {
-  return Boolean(annot.pii || annot.userOwned || annot.tenantOwned || annot.recordOwned);
-}
-
-function ownerFieldNamesReferencedByPersonalOf(
-  fieldsByName: EntityDefinition["fields"],
-): ReadonlySet<string> {
-  const ownerFieldNames = new Set<string>();
-  for (const field of Object.values(fieldsByName)) {
-    const ownerFieldName = (field as ResolvedPiiFlags).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: FeatureDefinition): void {
-  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 as ResolvedPiiFlags; // @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 as {
-        readonly sensitive?: boolean;
-        readonly encrypted?: boolean;
-      }; // @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 as {
-          readonly searchable?: boolean;
-          readonly sortable?: boolean;
-          readonly sensitive?: boolean;
-        }; // @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 as ResolvedPiiFlags), // @cast-boundary schema-walk
-        );
-        const hasAnonymize = Object.values(fieldsByName).some((f) => {
-          const a = f as ResolvedPiiFlags; // @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 as ResolvedPiiFlags; // @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/src/engine/boot-validator/projection-list-screens.ts

@@ -1,293 +0,0 @@
-import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handlers";
-import { parseQn, QnTypes, qualifyEntityName } from "../qualified-name";
-import { isEditLayoutScreen } from "../screen-helpers";
-import type {
-  EditRelatedListSection,
-  EntityDefinition,
-  FeatureDefinition,
-  ProjectionListScreenDefinition,
-  QueryHandlerDef,
-} from "../types";
-import { SEARCHABLE_FALSE_WHITELIST } from "./entity-list-screens";
-import { findEntity } from "./parent-ref";
-import { getZodObjectShape } from "./zod-shape";
-
-// 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: readonly FeatureDefinition[],
-): ReadonlyMap<string, QueryHandlerDef> {
-  const out = new Map<string, QueryHandlerDef>();
-  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: QueryHandlerDef["schema"] | undefined, key: string): boolean {
-  const shape = getZodObjectShape(schema);
-  return shape !== undefined && key in shape;
-}
-
-function validateOneProjectionListScreen(
-  feature: FeatureDefinition,
-  screen: ProjectionListScreenDefinition,
-  queryHandlers: ReadonlyMap<string, QueryHandlerDef>,
-): void {
-  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: string,
-  screen: ProjectionListScreenDefinition,
-  schema: QueryHandlerDef["schema"] | undefined,
-): void {
-  // 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: ReadonlySet<string> = new Set([
-  "limit",
-  "search",
-  "sort",
-  "sortDirection",
-  "offset",
-  "totalCount",
-  "cursor",
-  "filter",
-  "filters",
-]);
-
-function validateProjectionListDateRangeFacets(
-  prefix: string,
-  screen: ProjectionListScreenDefinition,
-  schema: QueryHandlerDef["schema"] | undefined,
-): void {
-  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: string,
-  screen: ProjectionListScreenDefinition,
-  schema: QueryHandlerDef["schema"] | undefined,
-): void {
-  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: readonly FeatureDefinition[]): void {
-  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: string,
-  section: EditRelatedListSection,
-  schema: QueryHandlerDef["schema"] | undefined,
-): void {
-  // 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: string,
-  section: EditRelatedListSection,
-  schema: QueryHandlerDef["schema"] | undefined,
-): void {
-  // 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: string,
-  handler: QueryHandlerDef | undefined,
-  featureMap: ReadonlyMap<string, FeatureDefinition>,
-): EntityDefinition | undefined {
-  if (handler === undefined || handler[ENTITY_CONVENTION_QUERY_BRAND] !== true) return undefined;
-  let entityName: string;
-  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: string,
-  section: EditRelatedListSection,
-  schema: QueryHandlerDef["schema"] | undefined,
-  handler: QueryHandlerDef | undefined,
-  featureMap: ReadonlyMap<string, FeatureDefinition>,
-): void {
-  // 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: readonly FeatureDefinition[]): void {
-  const queryHandlers = buildQueryHandlerMap(features);
-  const featureMap = new Map(features.map((f) => [f.name, f] as const));
-  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);
-      }
-    }
-  }
-}