@cosmicdrift/kumiko-framework 0.328.0 → 0.328.1

package/src/engine/registry-validate.ts

@@ -1,810 +0,0 @@
-import { configureEventPiiCatalog } from "../crypto/event-pii";
-import { hasSearchablePlaintext, isSensitiveLabelField } from "../db/entity-field-encryption";
-import { bindHookEscapeHatchGrant } from "../pipeline/system-identity-switch";
-import { resolveName } from "./handler-helpers";
-import { parseRefTargetEntityName } from "./parse-ref-target";
-import type {
-  RegistryState,
-  SearchableReferenceField,
-  SortableReferenceField,
-} from "./registry-state";
-import { buildImplicitProjection, hasFieldAccessRules, qualify } from "./registry-state";
-import {
-  buildSoftDeleteCleanupJob,
-  buildSoftDeleteCleanupSystemJob,
-  SOFT_DELETE_CLEANUP_JOB,
-  SOFT_DELETE_CLEANUP_SYSTEM_JOB,
-  SOFT_DELETE_GRACE_DAYS_KEY,
-  softDeleteGraceDaysConfig,
-} from "./soft-delete-cleanup";
-import type {
-  EntityDefinition,
-  EventPiiFields,
-  EventUpcastFn,
-  FeatureDefinition,
-  PostDeleteHookFn,
-  PostSaveHookFn,
-  PreDeleteHookFn,
-  PreSaveHookFn,
-  ReferenceFieldDef,
-} from "./types";
-import { HookPhases, isRateLimitDisabled } from "./types";
-
-function allHandlerQns(state: RegistryState): ReadonlySet<string> {
-  return new Set([...state.writeHandlerMap.keys(), ...state.queryHandlerMap.keys()]);
-}
-
-// Pass 2 for workspaces: fold any nav-self-assigned QNs into their
-// workspace's member list. Safe now that every feature (and therefore every
-// workspace) is in state.workspaceMap.
-export function finalizeWorkspaceNavMembership(state: RegistryState): void {
-  // workspace's member list. We can do this safely now that every feature
-  // (and therefore every workspace) is in state.workspaceMap. Cross-feature refs
-  // — a nav from feature A self-assigning to a workspace from feature B —
-  // resolve here because B's workspace was registered in pass 1 above.
-  // Dedup: a nav entry that's also in r.workspace({ nav: [...] }) shouldn't
-  // appear twice. Boot-validator catches dangling workspace ids.
-  for (const [navQn, navDef] of state.navMap) {
-    if (!navDef.workspaces || navDef.workspaces.length === 0) continue;
-    for (const wsQn of navDef.workspaces) {
-      const members = state.navsByWorkspace.get(wsQn);
-      if (members === undefined) continue; // dangling — boot-validator reports
-      if (!members.includes(navQn)) members.push(navQn);
-    }
-  }
-}
-
-// Build handler → entity mapping from feature declarations. Must happen before
-// extension processing since extension preSave hooks need entity mappings.
-export function populateHandlerEntityMappings(
-  state: RegistryState,
-  features: readonly FeatureDefinition[],
-): void {
-  // Build handler → entity mapping from feature declarations (filled by tryMapEntity
-  // in defineFeature via the "entityName:verb" colon convention).
-  // Must happen before extension processing since extension preSave hooks need entity mappings.
-  for (const feature of features) {
-    for (const [handlerName, entityName] of Object.entries(feature.handlerEntityMappings ?? {})) {
-      const writeQn = qualify(feature.name, "write", handlerName);
-      const queryQn = qualify(feature.name, "query", handlerName);
-      if (state.writeHandlerMap.has(writeQn)) {
-        state.handlerEntityMap.set(writeQn, entityName);
-      }
-      if (state.queryHandlerMap.has(queryQn)) {
-        state.handlerEntityMap.set(queryQn, entityName);
-      }
-    }
-  }
-}
-
-export function validateExtensionSelectors(state: RegistryState): void {
-  // Selector declarations point into the merged extension + config-key
-  // sets — a typo'd extension or dropped key must fail the boot, not
-  // silently un-gate readiness.
-  for (const [extensionName, qualifiedKey] of state.extensionSelectorMap) {
-    if (!state.extensionMap.has(extensionName)) {
-      throw new Error(
-        `extensionSelector("${extensionName}") declared but no feature ` +
-          `registers that extension via extendsRegistrar.`,
-      );
-    }
-    if (!state.configKeyMap.has(qualifiedKey)) {
-      throw new Error(
-        `extensionSelector("${extensionName}") points at unknown config key ` +
-          `"${qualifiedKey}" — no mounted feature declares it.`,
-      );
-    }
-  }
-}
-
-// Process extension usages: call onRegister, apply extendSchema, register hooks.
-export function applyExtensionUsages(state: RegistryState): void {
-  // Process extension usages: call onRegister, apply extendSchema, register hooks
-  for (const usage of state.extensionUsages) {
-    const ext = state.extensionMap.get(usage.extensionName);
-    if (!ext) continue;
-
-    if (ext.onRegister) {
-      ext.onRegister(usage.entityName, usage.options);
-    }
-
-    // extendSchema: merge extra fields into entity definition
-    if (ext.extendSchema) {
-      const entity = state.entityMap.get(usage.entityName);
-      if (entity) {
-        const extraFields = ext.extendSchema(usage.entityName);
-        const merged = { ...entity, fields: { ...entity.fields, ...extraFields } };
-        state.entityMap.set(usage.entityName, merged);
-      }
-    }
-
-    // Extension hooks → entity hooks (fire for all writes on the entity).
-    // Extensions default to afterCommit phase (same default as r.hook).
-    //
-    // Owner "*" = always-enabled, not gated by feature-toggles. Extensions
-    // are plumbing (e.g. ownership) — the feature that declared them might
-    // itself be toggleable, but the extension-hook is conceptually part of
-    // the entity's invariants. If future requirements need extension hooks
-    // to also be gated, store the registering-feature on
-    // RegistrarExtensionRegistration and use that here.
-    const extOwner = "*";
-    // Unlike export/forget hooks (escapeHatch on r.useExtension(...)), these
-    // entity-lifecycle wrappers (postSave/preDelete/postDelete/preSave) have no
-    // escapeHatch declaration site, so SYSTEM stays denied here (system-identity-switch.ts).
-    if (ext.hooks) {
-      if (ext.hooks.postSave) {
-        const wrapped = bindHookEscapeHatchGrant(
-          ext.hooks.postSave,
-          `postSave hook of extension "${usage.extensionName}"`,
-          undefined,
-        ) as PostSaveHookFn; // @cast-boundary engine-bridge
-        const existing = state.entityPostSaveHooks.get(usage.entityName) ?? [];
-        existing.push({
-          fn: wrapped,
-          phase: HookPhases.afterCommit,
-          featureName: extOwner,
-        });
-        state.entityPostSaveHooks.set(usage.entityName, existing);
-      }
-      if (ext.hooks.preDelete) {
-        const wrapped = bindHookEscapeHatchGrant(
-          ext.hooks.preDelete,
-          `preDelete hook of extension "${usage.extensionName}"`,
-          undefined,
-        ) as PreDeleteHookFn; // @cast-boundary engine-bridge
-        const existing = state.entityPreDeleteHooks.get(usage.entityName) ?? [];
-        existing.push({
-          fn: wrapped,
-          phase: HookPhases.afterCommit,
-          featureName: extOwner,
-        });
-        state.entityPreDeleteHooks.set(usage.entityName, existing);
-      }
-      if (ext.hooks.postDelete) {
-        const wrapped = bindHookEscapeHatchGrant(
-          ext.hooks.postDelete,
-          `postDelete hook of extension "${usage.extensionName}"`,
-          undefined,
-        ) as PostDeleteHookFn; // @cast-boundary engine-bridge
-        const existing = state.entityPostDeleteHooks.get(usage.entityName) ?? [];
-        existing.push({
-          fn: wrapped,
-          phase: HookPhases.afterCommit,
-          featureName: extOwner,
-        });
-        state.entityPostDeleteHooks.set(usage.entityName, existing);
-      }
-      // preSave on extensions: store as handler hook for all CRUD handlers of this entity
-      if (ext.hooks.preSave) {
-        const wrapped = bindHookEscapeHatchGrant(
-          ext.hooks.preSave,
-          `preSave hook of extension "${usage.extensionName}"`,
-          undefined,
-        ) as PreSaveHookFn; // @cast-boundary engine-bridge
-        for (const qualifiedHandler of state.writeHandlerMap.keys()) {
-          if (state.handlerEntityMap.get(qualifiedHandler) === usage.entityName) {
-            const existing = state.preSaveHooks.get(qualifiedHandler) ?? [];
-            existing.push({ fn: wrapped, featureName: extOwner });
-            state.preSaveHooks.set(qualifiedHandler, existing);
-          }
-        }
-      }
-    }
-  }
-}
-
-// fw#2660: labelField defaults to "id" (a UUID column) elsewhere, but a
-// searchable reference ILIKEs the label column — an implicit or explicit
-// "id" default would 500 on every search request. Fail at boot.
-function buildSearchableReferenceField(
-  entityName: string,
-  fieldName: string,
-  field: ReferenceFieldDef,
-  entityMap: ReadonlyMap<string, EntityDefinition>,
-): SearchableReferenceField {
-  if (field.labelField === undefined || field.labelField === "id") {
-    throw new Error(
-      `[Entity ${entityName}] field "${fieldName}": searchable reference fields require an ` +
-        `explicit, non-"id" labelField. "id" is a UUID column — ILIKE against it fails ` +
-        `at request time. Set labelField to a human-readable field on the referenced entity.`,
-    );
-  }
-  if (field.multiple === true) {
-    throw new Error(
-      `[Entity ${entityName}] field "${fieldName}": searchable is not supported on multiple ` +
-        `(array) reference fields — remove "multiple" or "searchable".`,
-    );
-  }
-  const targetEntityName = parseRefTargetEntityName(field.entity);
-  const targetEntity = entityMap.get(targetEntityName);
-  if (targetEntity !== undefined) {
-    if (
-      isSensitiveLabelField(targetEntity, field.labelField) &&
-      !hasSearchablePlaintext(targetEntity, field.labelField)
-    ) {
-      throw new Error(
-        `[Entity ${entityName}] field "${fieldName}": searchable reference targets ` +
-          `"${targetEntityName}.${field.labelField}", which is encrypted/PII and not itself ` +
-          `searchable — there is no plaintext anywhere to match a search term against. Mark ` +
-          `"${targetEntityName}.${field.labelField}" searchable: true (add find: "fuzzy" if it ` +
-          `also carries a personal annotation, so it lands in the derived search index) or ` +
-          `remove searchable from "${fieldName}".`,
-      );
-    }
-  }
-  return {
-    fieldName,
-    targetEntityName,
-    labelField: field.labelField,
-  };
-}
-
-// fw#2741: ORDER BY runs against the referenced row's label column, so the
-// same explicit-labelField requirement as searchable applies — ordering by the
-// "id" default would be a UUID order that looks deliberate to the user.
-function buildSortableReferenceField(
-  entityName: string,
-  fieldName: string,
-  field: ReferenceFieldDef,
-): SortableReferenceField {
-  if (field.labelField === undefined || field.labelField === "id") {
-    throw new Error(
-      `[Entity ${entityName}] field "${fieldName}": sortable reference fields require an ` +
-        `explicit, non-"id" labelField. Ordering by "id" is a UUID order — arbitrary to the ` +
-        `user while looking deliberate. Set labelField to a human-readable field on the ` +
-        `referenced entity.`,
-    );
-  }
-  if (field.multiple === true) {
-    throw new Error(
-      `[Entity ${entityName}] field "${fieldName}": sortable is not supported on multiple ` +
-        `(array) reference fields — there is no single label to order by; remove "multiple" ` +
-        `or "sortable".`,
-    );
-  }
-  return {
-    fieldName,
-    targetEntityName: parseRefTargetEntityName(field.entity),
-    labelField: field.labelField,
-  };
-}
-
-// Precompute: searchable/sortable fields, searchable + sortable reference fields.
-export function buildSearchableSortableCaches(state: RegistryState): void {
-  for (const [name, entity] of state.entityMap) {
-    const searchable: string[] = [];
-    const sortable: string[] = [];
-    const searchableReferences: SearchableReferenceField[] = [];
-    const sortableReferences: SortableReferenceField[] = [];
-    for (const [fieldName, field] of Object.entries(entity.fields)) {
-      if (field.type === "text" && field.searchable === true) searchable.push(fieldName);
-      if (field.type === "text" && field.sortable === true) sortable.push(fieldName);
-      if (field.type === "embedded") {
-        for (const [subName, subField] of Object.entries(field.schema)) {
-          if (subField.searchable === true) searchable.push(`${fieldName}_${subName}`);
-        }
-      }
-      if (field.type === "reference" && field.searchable === true) {
-        searchableReferences.push(
-          buildSearchableReferenceField(name, fieldName, field, state.entityMap),
-        );
-      }
-      if (field.type === "reference" && field.sortable === true) {
-        sortableReferences.push(buildSortableReferenceField(name, fieldName, field));
-      }
-    }
-    state.searchableFieldsCache.set(name, searchable);
-    state.sortableFieldsCache.set(name, sortable);
-    state.searchableReferencesCache.set(name, searchableReferences);
-    state.sortableReferencesCache.set(name, sortableReferences);
-  }
-}
-
-// Implicit-Projection pro r.entity — see buildImplicitProjection doc above.
-export function buildImplicitProjections(
-  state: RegistryState,
-  features: readonly FeatureDefinition[],
-): void {
-  // Implicit-Projection pro r.entity. Macht die Entity-Tabelle rebaubar
-  // ohne dass Apps eine explizite r.projection schreiben müssen.
-  // Naming-Convention: `<feature>:projection:<entityName>-entity` — der
-  // "-entity"-Suffix unterscheidet implicit von explicit-Projections und
-  // vermeidet Kollisionen wenn jemand z.B. eine Cross-Aggregate-Projection
-  // mit Entity-Name registriert.
-  for (const feature of features) {
-    // extendEntityProjection targets must exist as r.entity in the SAME
-    // feature — a typo'd entity name would otherwise vanish silently and the
-    // extension's events would still be wiped on rebuild.
-    for (const extEntity of Object.keys(feature.entityProjectionExtensions ?? {})) {
-      if (!feature.entities?.[extEntity]) {
-        throw new Error(
-          `[Feature ${feature.name}] extendEntityProjection("${extEntity}"): no r.entity ` +
-            `with that name in this feature. Declare the entity first — the extension ` +
-            `merges into its implicit projection.`,
-        );
-      }
-    }
-    for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
-      const def = buildImplicitProjection(
-        feature.name,
-        entityName,
-        entity,
-        qualify,
-        feature.entityTables?.[entityName],
-        feature.entityProjectionExtensions?.[entityName] ?? [],
-      );
-      if (state.projectionMap.has(def.name)) {
-        throw new Error(
-          `Implicit projection "${def.name}" kollidiert mit einer explizit registrierten r.projection. ` +
-            `Implicit-Projections werden für jede r.entity mit "-entity"-Suffix angelegt — ` +
-            `benenne deine explicit projection um (z.B. "<entity>-summary") um die Kollision aufzulösen.`,
-        );
-      }
-      state.projectionMap.set(def.name, def);
-      const existing = state.projectionsBySource.get(entityName) ?? [];
-      existing.push(def);
-      state.projectionsBySource.set(entityName, existing);
-    }
-  }
-}
-
-export function buildIncomingRelations(state: RegistryState): void {
-  for (const [entityName, rels] of state.relationMap) {
-    // Build reverse index for incoming relations
-    for (const [relName, rel] of Object.entries(rels)) {
-      const existing = state.incomingRelationsCache.get(rel.target) ?? [];
-      existing.push({ sourceEntity: entityName, relationName: relName, relation: rel });
-      state.incomingRelationsCache.set(rel.target, existing);
-    }
-  }
-}
-
-export function validateFieldAccessHandlersAreEntityMapped(
-  state: RegistryState,
-  features: readonly FeatureDefinition[],
-): void {
-  // Validate: handlers in features with field-access rules must be entity-mapped.
-  // Without entity mapping, field-level access checks are silently skipped (security gap).
-  for (const feature of features) {
-    if (!hasFieldAccessRules(feature)) continue;
-
-    for (const handlerName of Object.keys(feature.writeHandlers ?? {})) {
-      const qualified = qualify(feature.name, "write", handlerName);
-      if (!state.handlerEntityMap.has(qualified)) {
-        throw new Error(
-          `Write handler "${qualified}" is not mapped to any entity, but feature "${feature.name}" has field-level access rules. ` +
-            `Name must follow "entity:verb" convention (e.g. "user:create") or use create/update/delete on a matching entity.`,
-        );
-      }
-    }
-
-    // Query handlers: only those with a colon must resolve (typo protection).
-    for (const handlerName of Object.keys(feature.queryHandlers ?? {})) {
-      if (!handlerName.includes(":")) continue;
-      const qualified = qualify(feature.name, "query", handlerName);
-      if (!state.handlerEntityMap.has(qualified)) {
-        throw new Error(
-          `Query handler "${qualified}" looks entity-bound but no matching entity exists. ` +
-            `Either fix the entity name, or use a name without colons for standalone queries.`,
-        );
-      }
-    }
-  }
-}
-
-export function validateRelationTargetsExist(state: RegistryState): void {
-  // Validate: all relation targets must reference existing entities
-  for (const [entityName, rels] of state.relationMap) {
-    for (const [relName, rel] of Object.entries(rels)) {
-      if (!state.entityMap.has(rel.target)) {
-        throw new Error(
-          `Relation "${entityName}.${relName}" targets entity "${rel.target}" which does not exist`,
-        );
-      }
-    }
-  }
-}
-
-export function validateEventMigrationVersions(
-  state: RegistryState,
-  features: readonly FeatureDefinition[],
-): void {
-  // Build + validate event upcaster chains. Run AFTER all features are
-  // ingested so defineEvent's `migrations` option can reference events from
-  // any feature (same feature in practice, but the check stays lax for
-  // future cross-feature event packs).
-  for (const feature of features) {
-    for (const [shortName, migrations] of Object.entries(feature.eventMigrations ?? {})) {
-      const qualified = qualify(feature.name, "event", shortName);
-      // registerEventMigration only ever runs alongside state.events[name]=def
-      // in the same defineEvent call (feature-config-events-jobs.ts:260-269),
-      // so a migrations entry here guarantees a matching eventMap entry.
-      // biome-ignore lint/style/noNonNullAssertion: invariant proven above
-      const eventDef = state.eventMap.get(qualified)!;
-      for (const m of migrations) {
-        if (m.toVersion > eventDef.version) {
-          throw new Error(
-            `Feature "${feature.name}" declares a migration for event "${shortName}" from v${m.fromVersion} to v${m.toVersion} ` +
-              `but r.defineEvent declares only version ${eventDef.version}. ` +
-              `Bump the version in defineEvent to at least ${m.toVersion}, or remove the migration.`,
-          );
-        }
-      }
-    }
-  }
-}
-
-export function buildEventUpcasterChains(
-  state: RegistryState,
-  features: readonly FeatureDefinition[],
-): void {
-  // Stitch the upcaster chain per qualified event. At this point, gaps in
-  // the chain (e.g. defineEvent version=3 but only a 1→2 migration exists)
-  // are hard errors — they would silently hand a v2-shape payload to a
-  // consumer expecting v3 at runtime, which is the class of bug upcasters
-  // are supposed to prevent.
-  for (const [qualified, eventDef] of state.eventMap) {
-    const chainMap = new Map<number, EventUpcastFn>();
-    // Locate the feature that owns this event (to pick up its migrations).
-    for (const feature of features) {
-      for (const [shortName, migs] of Object.entries(feature.eventMigrations ?? {})) {
-        const candidateQn = qualify(feature.name, "event", shortName);
-        if (candidateQn !== qualified) continue;
-        for (const m of migs) chainMap.set(m.fromVersion, m.transform);
-      }
-    }
-    if (eventDef.version > 1) {
-      for (let v = 1; v < eventDef.version; v++) {
-        if (!chainMap.has(v)) {
-          throw new Error(
-            `Event "${qualified}" declares version ${eventDef.version} but no migration ` +
-              `covers the step v${v} → v${v + 1}. Add { fromVersion: ${v}, toVersion: ${v + 1}, transform } to r.defineEvent("${qualified.split(":").pop() ?? qualified}", ...)'s migrations array ` +
-              `so stored v${v} payloads can be upcast on read.`,
-          );
-        }
-      }
-    }
-    state.eventUpcasterMap.set(qualified, {
-      currentVersion: eventDef.version,
-      chain: chainMap,
-    });
-  }
-}
-
-export function validateProjectionApplyKeys(state: RegistryState): void {
-  // Validate: every projection's source must reference a registered entity.
-  // A typo ("unti" instead of "unit") would otherwise be a silent no-op —
-  // the projection is stored but never fires because no aggregateType ever
-  // matches. Fail at boot so the feature author sees it immediately.
-  //
-  // Same guard extends to apply-keys: a handler for "unit.creatd" (missing
-  // 'e') would silently never fire. Valid apply-keys are the auto-generated
-  // CRUD types per source entity PLUS every domain event registered via
-  // r.defineEvent — an apply-handler for a domain event is how a projection
-  // reacts to ctx.appendEvent writes on the same aggregate stream.
-  const AUTO_EVENT_VERBS = ["created", "updated", "deleted", "restored", "forgotten"] as const;
-  const allDomainEventNames = new Set(state.eventMap.keys());
-  for (const [projName, projDef] of state.projectionMap) {
-    const sources = Array.isArray(projDef.source) ? projDef.source : [projDef.source];
-    // extraSources (r.extendEntityProjection) sit in the rebuild filter, so
-    // their auto-verbs are legitimately observable apply-keys too.
-    const rebuildSources = [...sources, ...(projDef.extraSources ?? [])];
-    const validEventTypes = new Set<string>();
-    // Two source-modes are legal:
-    //
-    //  (a) Registered entity (r.entity(src, ...)) — the "normal" case:
-    //      auto-lifecycle events `<src>.created/.updated/.deleted/.restored`
-    //      fire when the event-store-executor writes, and any domain-event
-    //      (r.defineEvent) appended onto an aggregate of that type is
-    //      observable too.
-    //
-    //  (b) Events-only source — no r.entity registered, but at least one
-    //      apply-key must be a domain-event (not a CRUD-verb on the source
-    //      name). Use-case: features that own an append-only event-stream
-    //      without a CRUD lifecycle, e.g. `deliveryAttempt` (each call to
-    //      the delivery-service produces one event on a fresh aggregate)
-    //      or `jobRun` (BullMQ-callback-driven lifecycle, no executor).
-    //      A "Shape-Anchor"-entity is no longer needed for this case.
-    const isEventsOnlySource = !sources.every((src) => state.entityMap.has(src));
-    for (const src of rebuildSources) {
-      if (state.entityMap.has(src)) {
-        for (const verb of AUTO_EVENT_VERBS) validEventTypes.add(`${src}.${verb}`);
-      }
-    }
-    // Domain events are valid apply-keys for any projection. They arrive via
-    // ctx.appendEvent on a specific aggregate — the runtime matches by event
-    // type, so a projection can observe domain events whose aggregate matches
-    // one of its declared sources.
-    for (const domainEvt of allDomainEventNames) validEventTypes.add(domainEvt);
-
-    // In events-only mode, at least one apply-key MUST be a domain-event —
-    // otherwise the source is simply a typo (no events will ever fire).
-    if (isEventsOnlySource) {
-      const hasAnyDomainEvent = Object.keys(projDef.apply).some((k) => allDomainEventNames.has(k));
-      if (!hasAnyDomainEvent) {
-        const unregistered = sources.filter((src) => !state.entityMap.has(src));
-        throw new Error(
-          `Projection "${projName}" declares source(s) [${unregistered.join(", ")}] that are not registered entities, ` +
-            `and has no domain-event apply-keys. This is either a typo or a missing r.defineEvent registration. ` +
-            `Events-only projections need at least one apply-key from r.defineEvent; ` +
-            `CRUD-style projections need r.entity("${unregistered[0]}", ...).`,
-        );
-      }
-    }
-
-    for (const applyKey of Object.keys(projDef.apply)) {
-      if (!validEventTypes.has(applyKey)) {
-        throw new Error(
-          `Projection "${projName}" has an apply handler for "${applyKey}" but no such event ` +
-            `type exists for its source(s) [${sources.join(", ")}]. ` +
-            `Valid types: ${[...validEventTypes].join(", ")}. ` +
-            `Check for a typo — auto-verbs follow "<entity>.<verb>"; ` +
-            `domain events follow "<feature>:event:<short-name>" (see r.defineEvent).`,
-        );
-      }
-    }
-  }
-}
-
-export function validateRequiredFeatures(
-  state: RegistryState,
-  features: readonly FeatureDefinition[],
-): void {
-  // Validate: all required features must be registered
-  for (const feature of features) {
-    for (const required of feature.requires ?? []) {
-      if (!state.featureMap.has(required)) {
-        throw new Error(
-          `Feature "${feature.name}" requires feature "${required}" which is not registered`,
-        );
-      }
-    }
-  }
-}
-
-export function resolveNotificationTriggersAndRegisterHooks(state: RegistryState): void {
-  // Resolve notification triggers and register postSave hooks
-  // Done after all features are registered so cross-feature triggers work
-  const allHandlerNames = allHandlerQns(state);
-  for (const [qualifiedName, notifDef] of state.notificationMap) {
-    // Both maps are populated in lockstep — same key-set by construction.
-    const featureName = state.notificationFeatureMap.get(qualifiedName) as string; // @cast-boundary engine-bridge
-    // I'll try the easy path first: if the trigger is already a fully qualified QN
-    // (cross-feature), I take it as-is. Otherwise I qualify with the own feature —
-    // as a write handler first (the common case), then as a query. If nothing
-    // matches by then, it was a typo and I'll say so.
-    let triggerOn: string;
-    if (allHandlerNames.has(notifDef.trigger.on)) {
-      triggerOn = notifDef.trigger.on;
-    } else {
-      // Try as write handler first (most common), then query
-      const writeQn = qualify(featureName, "write", notifDef.trigger.on);
-      const queryQn = qualify(featureName, "query", notifDef.trigger.on);
-      if (allHandlerNames.has(writeQn)) {
-        triggerOn = writeQn;
-      } else if (allHandlerNames.has(queryQn)) {
-        triggerOn = queryQn;
-      } else {
-        throw new Error(
-          `Notification "${qualifiedName}" triggers on "${notifDef.trigger.on}" ` +
-            `but no handler with that name exists. ` +
-            `Tried: "${notifDef.trigger.on}", "${writeQn}", and "${queryQn}"`,
-        );
-      }
-    }
-    // Update the stored definition with resolved trigger
-    state.notificationMap.set(qualifiedName, { ...notifDef, trigger: { on: triggerOn } });
-
-    if (!state.postSaveHooks.has(triggerOn)) state.postSaveHooks.set(triggerOn, []);
-    state.postSaveHooks.get(triggerOn)?.push({
-      phase: HookPhases.afterCommit,
-      featureName,
-      fn: async (result, context) => {
-        if (!context.notify) {
-          context.log?.debug(
-            `notification ${qualifiedName}: skipping — no notify function configured on context`,
-          );
-          return;
-        }
-        const to = notifDef.recipient(result);
-        if (to === null) {
-          context.log?.debug(
-            `notification ${qualifiedName}: skipping — recipient resolver returned null for result ${result.id}`,
-          );
-          return;
-        }
-        const data = notifDef.data(result);
-        await context.notify(qualifiedName, { to, data });
-      },
-    });
-  }
-}
-
-export function validateLifecycleHookTargets(state: RegistryState): void {
-  // Validate: lifecycle hook targets must reference existing handlers
-  const allHandlers = allHandlerQns(state);
-  const lifecycleHookMaps = [
-    { map: state.preSaveHooks, phase: "preSave" },
-    { map: state.postSaveHooks, phase: "postSave" },
-    { map: state.preDeleteHooks, phase: "preDelete" },
-    { map: state.postDeleteHooks, phase: "postDelete" },
-    { map: state.preQueryHooks, phase: "preQuery" },
-    { map: state.postQueryHooks, phase: "postQuery" },
-  ] as const;
-
-  // I'd rather warn you now at boot than have you open a ticket three weeks from now
-  // saying "my hook isn't firing". One typo in the target and the thing goes silent.
-  for (const { map, phase } of lifecycleHookMaps) {
-    for (const hookTarget of map.keys()) {
-      if (!allHandlers.has(hookTarget)) {
-        throw new Error(
-          `${phase} hook targets "${hookTarget}" but no handler with that name exists. ` +
-            `Check for typos — the hook will never fire.`,
-        );
-      }
-    }
-  }
-}
-
-export function validateEntityHookTargets(
-  state: RegistryState,
-  features: readonly FeatureDefinition[],
-): void {
-  // Same logic for entity-keyed hooks — targets must reference existing entities.
-  // Memory `feedback_dead_hook_needs_second_consumer`: a typo silently registers
-  // and never fires. Validates all four entity-hook types (postSave/preDelete/
-  // postDelete/postQuery) — net cleanup of an existing antipattern, not a
-  // postQuery-special.
-  const allEntities = new Set<string>();
-  for (const feature of features) {
-    for (const entityName of Object.keys(feature.entities ?? {})) {
-      allEntities.add(entityName);
-    }
-  }
-  const entityHookMaps = [
-    { map: state.entityPostSaveHooks, phase: "postSave (entityHook)", kind: "hook" },
-    { map: state.entityPreDeleteHooks, phase: "preDelete (entityHook)", kind: "hook" },
-    { map: state.entityPostDeleteHooks, phase: "postDelete (entityHook)", kind: "hook" },
-    { map: state.entityPostQueryHooks, phase: "postQuery (entityHook)", kind: "hook" },
-    { map: state.searchPayloadExtensions, phase: "searchPayloadExtension", kind: "extension" },
-  ] as const;
-  for (const { map, phase, kind } of entityHookMaps) {
-    for (const entityName of map.keys()) {
-      if (!allEntities.has(entityName)) {
-        throw new Error(
-          `${phase} ${kind} targets entity "${entityName}" but no entity with that name exists. ` +
-            `Check for typos — the ${kind} will never fire.`,
-        );
-      }
-    }
-  }
-}
-
-export function validateJobTriggers(state: RegistryState): void {
-  // Validate: job event triggers must reference an existing write/query
-  // handler OR an existing r.defineEvent registration. The latter is
-  // delivered async via the job-trigger event-consumer (server.ts), not
-  // the synchronous write-handler dispatch path — see
-  // createJobTriggerEventConsumer in pipeline/system-hooks.ts.
-  // Multi-Trigger-Form: jeden Eintrag im Array gegen allHandlers prüfen,
-  // auch wenn nur einer fehlt fail-fast.
-  const allHandlers = allHandlerQns(state);
-  for (const [jobName, jobDef] of state.jobMap) {
-    if (!("on" in jobDef.trigger)) continue;
-    const triggerOn = jobDef.trigger.on;
-    const triggers = Array.isArray(triggerOn) ? triggerOn : [triggerOn];
-    for (const t of triggers) {
-      const rawName = resolveName(t);
-      if (allHandlers.has(rawName)) continue;
-      if (state.eventMap.has(rawName)) continue;
-      throw new Error(
-        `Job "${jobName}" triggers on "${rawName}" but no handler or event with that name exists`,
-      );
-    }
-  }
-}
-
-export function validateBootGates(state: RegistryState): void {
-  // Boot gates run inline in JobRunner.start(), which has neither the
-  // per-tenant fan-out (that re-enqueues) nor the sequential lock's
-  // re-enqueue-and-return path. Both would make the gate pass silently
-  // without ever running the handler.
-  for (const [jobName, jobDef] of state.jobMap) {
-    if (!jobDef.bootGate) continue;
-    if (jobDef.perTenant) {
-      throw new Error(`Job "${jobName}" cannot combine bootGate with perTenant`);
-    }
-    if (jobDef.concurrency === "sequential") {
-      throw new Error(`Job "${jobName}" cannot combine bootGate with concurrency "sequential"`);
-    }
-  }
-}
-
-export function validateJobBackoff(state: RegistryState): void {
-  // Object-form backoff carries an explicit delayMs base — catch a bad value
-  // at boot instead of letting BullMQ silently compute NaN/undefined delays.
-  for (const [jobName, jobDef] of state.jobMap) {
-    if (typeof jobDef.backoff !== "object") continue;
-    const { delayMs } = jobDef.backoff;
-    if (delayMs === undefined) continue;
-    if (!Number.isInteger(delayMs) || delayMs <= 0) {
-      throw new Error(
-        `Job "${jobName}" backoff.delayMs must be a positive integer (got ${delayMs})`,
-      );
-    }
-  }
-}
-
-export function validateExtensionUsageTargets(state: RegistryState): void {
-  // Validate: extension usages must reference existing extensions
-  for (const usage of state.extensionUsages) {
-    if (!state.extensionMap.has(usage.extensionName)) {
-      throw new Error(
-        `Extension usage "${usage.extensionName}" on entity "${usage.entityName}" references an extension that does not exist`,
-      );
-    }
-  }
-}
-
-// Pre-compute: any handler with a rateLimit option?
-export function computeHasRateLimitedHandler(state: RegistryState): void {
-  // Pre-compute: any handler with a rateLimit option? Keeps the boot
-  // path able to short-circuit the RateLimitResolver wiring (and its
-  // Lua-script registration on Redis) when nobody opted in. Deliberately
-  // stays limited to explicit, non-disabled `rateLimit` declarations —
-  // `{ disabled: true }` must not auto-wire a resolver for an app that only
-  // opted OUT, and fw#2861's systemScope default only fires once a resolver
-  // already exists, so it must not force wantsL3 either.
-  state.hasRateLimitedHandlerCached = (() => {
-    for (const h of state.writeHandlerMap.values()) {
-      if (h.rateLimit !== undefined && !isRateLimitDisabled(h.rateLimit)) return true;
-    }
-    for (const h of state.queryHandlerMap.values()) {
-      if (h.rateLimit !== undefined && !isRateLimitDisabled(h.rateLimit)) return true;
-    }
-    return false;
-  })();
-}
-
-export function publishEventPiiCatalog(state: RegistryState): void {
-  // Publish the event-PII catalog (#799): append() — the single write funnel
-  // into kumiko_events — encrypts catalogued payload fields regardless of
-  // which path produced the event (ctx.appendEvent, MSP-apply, low-level
-  // append in delivery/jobs loggers).
-  //
-  // Defense-in-depth (fw#2558): defineEvent is the only producer of
-  // EventDef.piiFields and already fails closed without a stance, but this
-  // boot gate re-checks every registered event — a future producer that
-  // forgets to run through defineEvent would otherwise leave a hole where
-  // append() silently ships plaintext instead of refusing to boot.
-  const eventPiiCatalog = new Map<string, EventPiiFields>();
-  for (const [qualified, def] of state.eventMap) {
-    if (def.piiFields === undefined) {
-      throw new Error(
-        `Registered event "${qualified}" has no PII stance. Every r.defineEvent(...) call must pass { piiFields: { ... } } or { piiFields: "none" }.`,
-      );
-    }
-    if (def.piiFields === "none") continue;
-    eventPiiCatalog.set(qualified, def.piiFields);
-  }
-  configureEventPiiCatalog(eventPiiCatalog);
-}
-
-export function autoWireSoftDeleteJobs(state: RegistryState): void {
-  // Auto-wire the soft-delete cleanup cron + its grace-days config key when ANY
-  // entity opts into softDelete — the framework owns this machinery, no feature
-  // declares it (mirrors the auto restore-handler). Job-runner reads getAllJobs
-  // ungated; config-resolver reads getConfigKey → default. Reserved owner
-  // segment, guarded against a real-feature collision.
-  if ([...state.entityMap.values()].some((e) => e.softDelete)) {
-    if (!state.jobMap.has(SOFT_DELETE_CLEANUP_JOB)) {
-      state.jobMap.set(SOFT_DELETE_CLEANUP_JOB, buildSoftDeleteCleanupJob());
-    }
-    if (!state.jobMap.has(SOFT_DELETE_CLEANUP_SYSTEM_JOB)) {
-      state.jobMap.set(SOFT_DELETE_CLEANUP_SYSTEM_JOB, buildSoftDeleteCleanupSystemJob());
-    }
-    if (!state.configKeyMap.has(SOFT_DELETE_GRACE_DAYS_KEY)) {
-      state.configKeyMap.set(SOFT_DELETE_GRACE_DAYS_KEY, softDeleteGraceDaysConfig);
-    }
-  }
-}