@cosmicdrift/kumiko-framework 0.327.0 → 0.328.1

package/src/engine/boot-validator/nav.ts

@@ -1,241 +0,0 @@
-// Nav validation + collectKnownRoles (role synthesis for ownership
-// validation in index.ts — thematically adjacent to ownership.ts, kept
-// here since this is a structural move, not a semantic reorg).
-
-import { qualifyEntityName } from "../qualified-name";
-import type { AccessRule, FeatureDefinition, NavDefinition, WorkspaceDefinition } from "../types";
-import { isOpenToAllGranted } from "../types";
-
-export function collectWriteHandlerQns(features: readonly FeatureDefinition[]): Set<string> {
-  const set = new Set<string>();
-  for (const f of features) {
-    for (const handlerName of Object.keys(f.writeHandlers)) {
-      set.add(qualifyEntityName(f.name, "write", handlerName));
-    }
-  }
-  return set;
-}
-
-export function collectNavQns(
-  features: readonly FeatureDefinition[],
-): Map<string, NavDefinition & { readonly featureName: string }> {
-  const map = new Map<string, NavDefinition & { readonly featureName: string }>();
-  for (const f of features) {
-    for (const [navId, navDef] of Object.entries(f.navs)) {
-      const qualified = qualifyEntityName(f.name, "nav", navId);
-      map.set(qualified, { ...navDef, featureName: f.name });
-    }
-  }
-  return map;
-}
-
-// Per-feature ref validation: screen + parent refs point at real QNs. Cycle
-// detection runs once globally afterwards (it's cheaper to do a single DFS
-// over the merged graph than restart it per feature).
-export function validateNavs(
-  feature: FeatureDefinition,
-  allScreenQns: ReadonlySet<string>,
-  allNavQns: ReadonlyMap<string, NavDefinition & { readonly featureName: string }>,
-  allWorkspaceQns: ReadonlyMap<string, WorkspaceDefinition & { readonly featureName: string }>,
-): void {
-  for (const [navId, navDef] of Object.entries(feature.navs)) {
-    if (navDef.screen !== undefined && !allScreenQns.has(navDef.screen)) {
-      throw new Error(
-        `[Feature ${feature.name}] Nav entry "${navId}" references screen "${navDef.screen}" ` +
-          `which is not registered. Expected a qualified name of the form ` +
-          `"<feature>:screen:<id>" pointing at an r.screen() declaration.`,
-      );
-    }
-    if (navDef.parent !== undefined && !allNavQns.has(navDef.parent)) {
-      throw new Error(
-        `[Feature ${feature.name}] Nav entry "${navId}" references parent "${navDef.parent}" ` +
-          `which is not a registered nav entry. Expected a qualified name of the form ` +
-          `"<feature>:nav:<id>".`,
-      );
-    }
-    if (navDef.workspaces !== undefined) {
-      for (const wsQn of navDef.workspaces) {
-        if (!allWorkspaceQns.has(wsQn)) {
-          throw new Error(
-            `[Feature ${feature.name}] Nav entry "${navId}" self-assigns to workspace "${wsQn}" ` +
-              `which is not registered. Expected a qualified name of the form ` +
-              `"<feature>:workspace:<id>" pointing at an r.workspace() declaration.`,
-          );
-        }
-      }
-    }
-    if (navDef.createAction !== undefined) {
-      validateTreeAction(feature.name, navId, "createAction", navDef.createAction, allScreenQns);
-    }
-    for (const [i, action] of (navDef.actions ?? []).entries()) {
-      validateTreeAction(feature.name, navId, `actions[${i}]`, action, allScreenQns);
-    }
-  }
-}
-
-// A TreeAction (createAction or an actions[] entry) navigates via `screen`
-// XOR dispatches via `target` — same polymorphism as the node's own
-// `screen`/`target`. Without this check an action with neither is a
-// Hover-Icon that does nothing; one with both is ambiguous about which
-// click-mode wins.
-function validateTreeAction(
-  featureName: string,
-  navId: string,
-  actionPath: string,
-  action: { readonly screen?: string; readonly target?: unknown },
-  allScreenQns: ReadonlySet<string>,
-): void {
-  const { screen, target } = action;
-  const hasScreen = screen !== undefined;
-  const hasTarget = target !== undefined;
-  if (hasScreen === hasTarget) {
-    throw new Error(
-      `[Feature ${featureName}] Nav entry "${navId}" ${actionPath} must set exactly one of ` +
-        `"screen"/"target" (${hasScreen ? "both are set" : "neither is set"}).`,
-    );
-  }
-  if (screen !== undefined && !allScreenQns.has(screen)) {
-    throw new Error(
-      `[Feature ${featureName}] Nav entry "${navId}" ${actionPath} references screen ` +
-        `"${screen}" which is not registered. Expected a qualified name of the form ` +
-        `"<feature>:screen:<id>" pointing at an r.screen() declaration.`,
-    );
-  }
-}
-
-// Walks parent-refs across ALL nav entries (cross-feature). A cycle here
-// would crash client-side tree assembly — easier to fail loud at boot than
-// to debug a React "Maximum update depth exceeded" stack trace.
-export function validateNavCycles(
-  allNavQns: ReadonlyMap<string, NavDefinition & { readonly featureName: string }>,
-): void {
-  const visited = new Set<string>();
-  const stack = new Set<string>();
-
-  function visit(qualified: string, path: string[]): void {
-    if (stack.has(qualified)) {
-      throw new Error(
-        `[Kumiko Nav] Nav entry parent cycle detected: ${[...path, qualified].join(" → ")}`,
-      );
-    }
-    // skip: already visited — cycle-detection only needs to traverse each
-    // node once, and the `stack` check above catches any actual cycles
-    // reached via a different path.
-    if (visited.has(qualified)) return;
-    visited.add(qualified);
-    stack.add(qualified);
-    const navDef = allNavQns.get(qualified);
-    if (navDef?.parent) {
-      visit(navDef.parent, [...path, qualified]);
-    }
-    stack.delete(qualified);
-  }
-
-  for (const qualified of allNavQns.keys()) {
-    visit(qualified, []);
-  }
-}
-
-// undefined or granted openToAll means visible to everyone (no role-set to compare); malformed/denied openToAll returns `[]`, same as an explicit `roles: []`.
-function navViewerRoles(access: AccessRule | undefined): readonly string[] | undefined {
-  if (access === undefined) return undefined;
-  if ("openToAll" in access) return isOpenToAllGranted(access) ? undefined : [];
-  return access.roles;
-}
-
-// fw#2640: warn (never throw — this is a real UX bug, not a broken ref)
-// when a nav leaf's role gate is disjoint from its parent section's — no
-// user who can see the section could ever see this child, so the section
-// renders with zero visible children for every user who reaches it.
-// Only fires when BOTH sides declare an explicit, non-empty role list:
-// an unset/openToAll side is visible to everyone, so it can't invert.
-export function warnOnNavAccessInversion(
-  allNavQns: ReadonlyMap<string, NavDefinition & { readonly featureName: string }>,
-): void {
-  for (const [qn, navDef] of allNavQns) {
-    if (navDef.parent === undefined) continue;
-    const parentDef = allNavQns.get(navDef.parent);
-    if (parentDef === undefined) continue; // dangling parent ref — validateNavs already throws for this
-    const parentRoles = navViewerRoles(parentDef.access);
-    const leafRoles = navViewerRoles(navDef.access);
-    if (parentRoles === undefined || leafRoles === undefined) continue;
-    if (parentRoles.length === 0) continue; // parent already visible to nobody — a different problem
-    if (leafRoles.some((role) => parentRoles.includes(role))) continue;
-    // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
-    console.warn(
-      `[kumiko:boot] Nav entry "${qn}" requires roles [${leafRoles.join(", ")}] but its parent ` +
-        `"${navDef.parent}" only allows [${parentRoles.join(", ")}] — no user who can see the ` +
-        `parent section could ever see this entry. If this is intentional, ignore this warning; ` +
-        `otherwise align the role sets.`,
-    );
-  }
-}
-
-// `NavDefinition.screen` is authored already-qualified ("<feature>:screen:
-// <id>", see packages/types/src/nav.ts) — this only guards a short id
-// slipping through, since a wrong qualification here would make every nav
-// look orphaned (28 false positives on the real offlot-app schema instead
-// of the intended 8, see fw#3019 measurement).
-function qualifyNavScreenQn(featureName: string, screen: string): string {
-  return screen.includes(":screen:") ? screen : `${featureName}:screen:${screen}`;
-}
-
-// fw#3019: warn (never throw — a screen deliberately left out of the app's
-// sidebar is legitimate) when a declared nav's screen isn't reachable from
-// any allowlisted nav entry. Checking "nav QN not in allowlist" directly
-// warned 28x on the real offlot-app schema (58 navs, 30 allowed) — most of
-// them app-shell leaves that intentionally re-target a screen another,
-// allowlisted nav already reaches. Reachability warns only for a screen no
-// allowlisted nav points at, which is the actual "unreachable via sidebar"
-// bug (solon#113, offlot's VIN screen in pilot).
-export function warnOnUnreachableNavScreens(
-  allNavQns: ReadonlyMap<string, NavDefinition & { readonly featureName: string }>,
-  allowedNavQns: ReadonlySet<string>,
-  navAllowlistExempt: ReadonlySet<string> = new Set(),
-): void {
-  const reachableScreenQns = new Set<string>();
-  for (const [qn, navDef] of allNavQns) {
-    if (!allowedNavQns.has(qn) || navDef.screen === undefined) continue;
-    reachableScreenQns.add(qualifyNavScreenQn(navDef.featureName, navDef.screen));
-  }
-
-  for (const [qn, navDef] of allNavQns) {
-    if (allowedNavQns.has(qn) || navDef.screen === undefined || navAllowlistExempt.has(qn)) {
-      continue;
-    }
-    const screenQn = qualifyNavScreenQn(navDef.featureName, navDef.screen);
-    if (reachableScreenQns.has(screenQn)) continue;
-    // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
-    console.warn(
-      `[kumiko:boot] Nav entry "${qn}" declared by feature "${navDef.featureName}" points at ` +
-        `screen "${screenQn}", which no allowlisted nav entry reaches — it is unreachable via ` +
-        `the sidebar. If this is intentional (e.g. reachable through a generated hub), add ` +
-        `"${qn}" to navAllowlistExempt; otherwise add it to the allowlist.`,
-    );
-  }
-}
-
-// Roles we recognise at boot time. The framework has no explicit
-// role-registry (r.defineRoles is a type helper only), so we synthesise
-// one from every handler-access rule plus the "all"/"system" built-ins.
-export function collectKnownRoles(features: readonly FeatureDefinition[]): Set<string> {
-  const roles = new Set<string>(["all", "system"]);
-  for (const f of features) {
-    for (const def of Object.values(f.writeHandlers)) {
-      if (def.access && "roles" in def.access) {
-        for (const r of def.access.roles) roles.add(r);
-      }
-    }
-    for (const def of Object.values(f.queryHandlers)) {
-      if (def.access && "roles" in def.access) {
-        for (const r of def.access.roles) roles.add(r);
-      }
-    }
-    for (const def of Object.values(f.streamHandlers)) {
-      if (def.access && "roles" in def.access) {
-        for (const r of def.access.roles) roles.add(r);
-      }
-    }
-  }
-  return roles;
-}

package/src/engine/boot-validator/ownership.ts

@@ -1,352 +0,0 @@
-import { buildEntityTable } from "../../db/table-builder";
-import type { OwnershipMap, OwnershipRule, SqlFragment, WhereRule } from "../ownership";
-import { SYSTEM_USER_ID } from "../system-user";
-import type { ClaimKeyDefinition, FeatureDefinition, SessionUser } from "../types";
-import { SYSTEM_TENANT_ID } from "../types/identifiers";
-import { assertQualifiedWhereFragment, tableColumnSqlNames } from "../where-rule-lint";
-
-// --- Ownership rule validation (H.2) ---
-//
-// Walks every entity.access and every field.access map, resolves each
-// FromRule against the cross-feature claim registry, and confirms the
-// referenced column exists on the entity. Catches typos, renames, and
-// cross-feature-claim-removal scenarios at boot instead of at request time.
-//
-// fw#2639: also probes every `{ kind: "where" }` rule against the where-rule
-// lint (see ../where-rule-lint.ts) so a fail-open unqualified-column bug
-// fails the boot instead of waiting for a request from the right role.
-//
-// fw#2626: `access.write` maps reject `{ kind: "where" }` outright. A
-// where-rule is raw SQL and the write path never reaches SQL — it evaluates
-// rules in memory against the concrete row (userCanCreateFieldRow /
-// userCanWriteFieldRow), and a create has no row to run a predicate against
-// at all. Such a rule can therefore only ever deny, so the boot fails instead
-// of shipping an access map that silently locks the role out.
-
-// A rule that reads real claims off the user can't be evaluated at boot —
-// PROBE_USER carries none — so probing is best-effort: rules that throw on
-// the probe user fall through to the runtime backstop in
-// ownership.ts#ruleToFragment instead.
-const PROBE_USER: SessionUser = {
-  id: SYSTEM_USER_ID,
-  tenantId: SYSTEM_TENANT_ID,
-  roles: [],
-  claims: {},
-};
-
-export type WhereRuleProbe = {
-  readonly table: unknown;
-  readonly tableName: string;
-  readonly columns: ReadonlySet<string>;
-};
-
-// Which half of an access map is being validated. Only "read" ever reaches
-// SQL, so it is the only path on which a where-rule is admissible.
-export type AccessPath = "read" | "write";
-
-// Qualified-name → definition map of every claim key in the mounted feature
-// set. `from("claim:<feature>:<key>")` rules resolve against exactly this.
-export function collectClaimKeys(
-  features: readonly FeatureDefinition[],
-): Map<string, ClaimKeyDefinition> {
-  const claimKeys = new Map<string, ClaimKeyDefinition>();
-  for (const f of features) {
-    for (const def of Object.values(f.claimKeys)) {
-      claimKeys.set(def.qualifiedName, def);
-    }
-  }
-  return claimKeys;
-}
-
-// Subset-safe ownership validation for callers that mount a deliberate slice
-// of the app rather than all of it (setupTestStack). Both cross-feature
-// corpora go in as undefined — a three-feature stack genuinely does not know
-// which roles and claims the whole app declares, and answering that question
-// from a slice produces false "unknown role"/"unknown claim" errors. The
-// subset-invariant checks (#2639 where-lint, #2626 where-on-write, unknown
-// column) run in full: those hold or fail per feature, whatever else is
-// mounted.
-export function validateOwnershipBoot(features: readonly FeatureDefinition[]): void {
-  for (const feature of features) {
-    validateOwnershipRules(feature, undefined, undefined);
-  }
-}
-
-// undefined corpus = "this caller cannot answer that question", not "skip the
-// check" — see validateOwnershipBoot. validateBoot passes the real corpora.
-export function validateOwnershipRules(
-  feature: FeatureDefinition,
-  allClaimKeys: ReadonlyMap<string, ClaimKeyDefinition> | undefined,
-  knownRoles: ReadonlySet<string> | undefined,
-): void {
-  for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
-    const columnNames = new Set<string>(Object.keys(entity.fields));
-    // Framework-managed columns that rules are allowed to reference too.
-    // These are the base columns buildEntityTable adds unconditionally.
-    const frameworkColumns = ["id", "tenantId", "version", "insertedAt", "modifiedAt"];
-    for (const col of frameworkColumns) columnNames.add(col);
-
-    let probe: WhereRuleProbe | undefined;
-    try {
-      const table = buildEntityTable(entityName, entity);
-      const columns = tableColumnSqlNames(table);
-      if (columns.size > 0) {
-        probe = { table, tableName: entity.table ?? entityName, columns };
-      }
-    } catch {
-      // skip: table cannot be built outside the real boot sequence here —
-      // the runtime backstop in ruleToFragment still covers this entity.
-      probe = undefined;
-    }
-
-    // Entity-level access
-    if (entity.access?.read) {
-      checkOwnershipMap({
-        map: entity.access.read,
-        columnNames,
-        allClaimKeys,
-        knownRoles,
-        scope: `entity "${entityName}".access.read`,
-        featureName: feature.name,
-        probe,
-        path: "read",
-      });
-    }
-    if (entity.access?.write) {
-      checkOwnershipMap({
-        map: entity.access.write,
-        columnNames,
-        allClaimKeys,
-        knownRoles,
-        scope: `entity "${entityName}".access.write`,
-        featureName: feature.name,
-        probe,
-        path: "write",
-      });
-    }
-
-    // Field-level access — OwnershipMap form goes through checkOwnershipMap,
-    // legacy string[] through checkLegacyRoleList. Both enforce role-name
-    // existence against knownRoles so typos fail loud.
-    for (const [fieldName, field] of Object.entries(entity.fields)) {
-      checkFieldAccess({
-        access: field.access?.read,
-        columnNames,
-        allClaimKeys,
-        knownRoles,
-        scope: `${entityName}.${fieldName}.access.read`,
-        featureName: feature.name,
-        probe,
-        path: "read",
-      });
-      checkFieldAccess({
-        access: field.access?.write,
-        columnNames,
-        allClaimKeys,
-        knownRoles,
-        scope: `${entityName}.${fieldName}.access.write`,
-        featureName: feature.name,
-        probe,
-        path: "write",
-      });
-    }
-  }
-}
-
-export function checkFieldAccess(args: {
-  readonly access: OwnershipMap | readonly string[] | undefined;
-  readonly columnNames: ReadonlySet<string>;
-  readonly allClaimKeys: ReadonlyMap<string, ClaimKeyDefinition> | undefined;
-  readonly knownRoles: ReadonlySet<string> | undefined;
-  readonly scope: string;
-  readonly featureName: string;
-  readonly probe?: WhereRuleProbe;
-  readonly path: AccessPath;
-}): void {
-  // skip: no access rules on this field, nothing to validate
-  if (!args.access) return;
-  if (Array.isArray(args.access)) {
-    // Legacy string[] form — every entry is a role name. Ref/column
-    // validation is n/a here (no claim refs in this shape), but the
-    // role-existence check applies.
-    checkLegacyRoleList(
-      args.access as readonly string[], // @cast-boundary schema-walk
-      args.knownRoles,
-      args.scope,
-      args.featureName,
-    );
-    // skip: legacy form validated, OwnershipMap check below doesn't apply
-    return;
-  }
-  checkOwnershipMap({
-    map: args.access as OwnershipMap, // @cast-boundary schema-walk
-    columnNames: args.columnNames,
-    allClaimKeys: args.allClaimKeys,
-    knownRoles: args.knownRoles,
-    scope: args.scope,
-    featureName: args.featureName,
-    probe: args.probe,
-    path: args.path,
-  });
-}
-
-export function checkLegacyRoleList(
-  roles: readonly string[],
-  knownRoles: ReadonlySet<string> | undefined,
-  scope: string,
-  featureName: string,
-): void {
-  // skip: corpus cannot answer "is this role real?" — see canValidateRoles
-  if (!canValidateRoles(knownRoles)) return;
-  for (const roleName of roles) {
-    if (!knownRoles.has(roleName)) {
-      throw new Error(buildUnknownRoleMessage(roleName, knownRoles, scope, featureName));
-    }
-  }
-}
-
-// A role corpus can only answer "is this role real?" when it actually holds
-// app-defined roles. undefined means the caller could not derive one at all
-// (a test stack mounts a deliberate subset of the app), and a corpus of
-// nothing but "all"/"system" belongs to an app whose handlers never declare
-// a role — in both cases every app-defined role would flag as unknown.
-export function canValidateRoles(
-  knownRoles: ReadonlySet<string> | undefined,
-): knownRoles is ReadonlySet<string> {
-  if (!knownRoles) return false;
-  for (const r of knownRoles) {
-    if (r !== "all" && r !== "system") return true;
-  }
-  return false;
-}
-
-export function checkOwnershipMap(args: {
-  readonly map: OwnershipMap;
-  readonly columnNames: ReadonlySet<string>;
-  readonly allClaimKeys: ReadonlyMap<string, ClaimKeyDefinition> | undefined;
-  readonly knownRoles: ReadonlySet<string> | undefined;
-  readonly scope: string;
-  readonly featureName: string;
-  readonly probe?: WhereRuleProbe;
-  readonly path: AccessPath;
-}): void {
-  for (const [roleName, rawRule] of Object.entries(args.map)) {
-    // Role-existence check — typos like `{"Admi": "all"}` where no handler
-    // or other map mentions "Admi" would otherwise silently grant nothing.
-    // Cross-feature, so it needs a corpus that can answer the question.
-    if (canValidateRoles(args.knownRoles) && !args.knownRoles.has(roleName)) {
-      throw new Error(
-        buildUnknownRoleMessage(roleName, args.knownRoles, args.scope, args.featureName),
-      );
-    }
-
-    // @cast-boundary schema-walk — extracted from feature-config inspection
-    const rule = rawRule as OwnershipRule;
-    if (rule === "all") continue;
-    if (rule.kind === "where") {
-      if (args.path === "write") {
-        throw new Error(buildWhereOnWritePathMessage(roleName, args.scope, args.featureName));
-      }
-      probeWhereRule(rule, roleName, args.probe, args.scope, args.featureName);
-      continue; // escape hatch — feature author owns the SQL
-    }
-
-    // FromRule — validate ref + column.
-    // Claim-existence is cross-feature: only the whole-app corpus can tell a
-    // typo from a claim declared in a feature this caller did not mount.
-    if (rule.refKind === "claim" && args.allClaimKeys) {
-      // refPath is the qualified claim name ("feature:shortName").
-      const claim = args.allClaimKeys.get(rule.refPath);
-      if (!claim) {
-        const known = [...args.allClaimKeys.keys()].sort().join(", ") || "(none)";
-        throw new Error(
-          `[Kumiko Ownership] ${args.scope} references unknown claim "${rule.refPath}" ` +
-            `(role: "${roleName}", feature: "${args.featureName}"). ` +
-            `Declare it via r.claimKey("...", { type: "..." }) in the owning feature. ` +
-            `Known claims: ${known}`,
-        );
-      }
-      // String-compatible columns accept string and string[] claims equally
-      // (array → inArray). For other claim types we rely on the author
-      // knowing the row-column shape; we can't introspect PG types without
-      // the schema built. This is a best-effort ref-existence check.
-    }
-
-    if (!args.columnNames.has(rule.column)) {
-      const known = [...args.columnNames].sort().join(", ");
-      throw new Error(
-        `[Kumiko Ownership] ${args.scope} references column "${rule.column}" ` +
-          `which does not exist on the entity (role: "${roleName}", feature: ` +
-          `"${args.featureName}"). Available columns: ${known}`,
-      );
-    }
-  }
-}
-
-// Best-effort: run the where-rule lint against the SQL the rule produces
-// for PROBE_USER. A rule that needs real claims throws on that call and is
-// silently skipped — ruleToFragment's runtime backstop is what catches it.
-export function probeWhereRule(
-  rule: WhereRule,
-  roleName: string,
-  probe: WhereRuleProbe | undefined,
-  scope: string,
-  featureName: string,
-): void {
-  // skip: no probe means the entity's column set could not be derived above;
-  // without it there is nothing to check the rule's SQL against, so the
-  // runtime backstop in ruleToFragment is the only line of defense left.
-  if (!probe) return;
-  let fragment: SqlFragment;
-  try {
-    fragment = rule.where(PROBE_USER, {
-      table: probe.table,
-      tableName: probe.tableName,
-      paramStart: 1,
-    });
-  } catch {
-    // skip: a rule that needs real claims cannot be probed at boot; ruleToFragment is the backstop
-    return;
-  }
-  // skip: a rule producing no SQL fragment for the probe user has nothing to
-  // lint here; ruleToFragment still validates it against a real request.
-  if (typeof fragment?.sqlText !== "string") return;
-  assertQualifiedWhereFragment(
-    fragment.sqlText,
-    probe.columns,
-    `${scope} (role "${roleName}", feature: "${featureName}")`,
-  );
-}
-
-export function buildWhereOnWritePathMessage(
-  roleName: string,
-  scope: string,
-  featureName: string,
-): string {
-  return (
-    `[Kumiko Ownership] ${scope} uses a \`{ kind: "where" }\` rule for role ` +
-    `"${roleName}" (feature: "${featureName}"). where-rules are raw SQL and only ` +
-    `the read path runs SQL (buildOwnershipClause); write access is decided in ` +
-    `memory against the concrete row, and a create has no row yet — so the rule ` +
-    `could only ever deny this role. Use a from()-rule (e.g. ` +
-    `from("user:id", "ownerId") or from("claim:<feature>:<key>")) on access.write, ` +
-    `or enforce the condition in the write-handler's preSave hook. ` +
-    `where-rules stay supported on access.read.`
-  );
-}
-
-export function buildUnknownRoleMessage(
-  roleName: string,
-  knownRoles: ReadonlySet<string>,
-  scope: string,
-  featureName: string,
-): string {
-  const known = [...knownRoles].sort().join(", ");
-  return (
-    `[Kumiko Ownership] ${scope} references unknown role "${roleName}" ` +
-    `(feature: "${featureName}"). Roles are collected from handler access ` +
-    `rules across all features plus the "all" and "system" built-ins; if ` +
-    `"${roleName}" is real, make sure at least one handler declares ` +
-    `access.roles: ["${roleName}"]. Known roles: ${known}`
-  );
-}

package/src/engine/boot-validator/parent-ref.ts

@@ -1,96 +0,0 @@
-import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handlers";
-import type { EntityDefinition, FeatureDefinition, QueryHandlerDef } from "../types";
-
-// --- Parent-ref boot validation (fw#2766) ---
-//
-// Join-row entities (EntityDefinition.parentRef) derive both the write-path
-// deny and the read-path SQL gate from one declaration. This is the boot-time
-// half of the fail-closed guarantee: the read gate itself (db/parent-ref-
-// clause.ts) passes an ungated query through when no ParentVisibilityOption
-// was supplied — throwing there would 500 every custom handler and
-// framework-internal detail() call that doesn't wire it, so the enforcement
-// has to happen loudly here instead, once, at boot.
-
-export function findEntity(
-  featureMap: ReadonlyMap<string, FeatureDefinition>,
-  entityName: string,
-): EntityDefinition | undefined {
-  for (const f of featureMap.values()) {
-    const entity = f.entities?.[entityName];
-    if (entity) return entity;
-  }
-  return undefined;
-}
-
-function findQueryHandler(
-  featureMap: ReadonlyMap<string, FeatureDefinition>,
-  handlerName: string,
-): QueryHandlerDef | undefined {
-  for (const f of featureMap.values()) {
-    const handler = f.queryHandlers[handlerName];
-    if (handler) return handler;
-  }
-  return undefined;
-}
-
-export function validateParentRefs(
-  feature: FeatureDefinition,
-  featureMap: ReadonlyMap<string, FeatureDefinition>,
-): void {
-  for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
-    const parentRef = entity.parentRef;
-    if (parentRef === undefined) continue;
-
-    if (entity.fields[parentRef.entityTypeField] === undefined) {
-      throw new Error(
-        `[Kumiko ParentRef] entity "${entityName}".parentRef.entityTypeField references ` +
-          `"${parentRef.entityTypeField}" — which is not a declared field on "${entityName}" ` +
-          `(feature: "${feature.name}"). Fix: point entityTypeField at a real field on the entity.`,
-      );
-    }
-    if (entity.fields[parentRef.entityIdField] === undefined) {
-      throw new Error(
-        `[Kumiko ParentRef] entity "${entityName}".parentRef.entityIdField references ` +
-          `"${parentRef.entityIdField}" — which is not a declared field on "${entityName}" ` +
-          `(feature: "${feature.name}"). Fix: point entityIdField at a real field on the entity.`,
-      );
-    }
-
-    for (const hostName of parentRef.allowedTypes ?? []) {
-      const host = findEntity(featureMap, hostName);
-      if (host === undefined) {
-        throw new Error(
-          `[Kumiko ParentRef] entity "${entityName}".parentRef.allowedTypes names "${hostName}" ` +
-            `— no entity with that name is registered in this feature set (feature: ` +
-            `"${feature.name}"). Fix: remove "${hostName}" from allowedTypes, or register it.`,
-        );
-      }
-      if (host.parentRef !== undefined) {
-        throw new Error(
-          `[Kumiko ParentRef] entity "${entityName}".parentRef.allowedTypes names "${hostName}" ` +
-            `— which itself declares a parentRef (feature: "${feature.name}"). A join-row ` +
-            `entity can't act as a host for another join-row entity (no recursive gating). ` +
-            `Fix: remove "${hostName}" from allowedTypes, or drop its own parentRef.`,
-        );
-      }
-    }
-
-    for (const verb of ["list", "detail"] as const) {
-      const handlerName = `${entityName}:${verb}`;
-      const handler = findQueryHandler(featureMap, handlerName);
-      // skip: no handler registered for this verb — nothing to brand-check
-      if (handler === undefined) continue;
-      if (handler[ENTITY_CONVENTION_QUERY_BRAND] !== true) {
-        throw new Error(
-          `[Kumiko ParentRef] query handler "${handlerName}" does not carry ` +
-            `ENTITY_CONVENTION_QUERY_BRAND, but entity "${entityName}" declares a parentRef ` +
-            `(feature: "${feature.name}"). A hand-written handler bypasses the parent-ref ` +
-            `read-gate unless it explicitly wires parentVisibility. Fix: register "${handlerName}" ` +
-            `via defineEntityListHandler/defineEntityDetailHandler (or defineEntityQueryHandler), ` +
-            `or pass { parentVisibility: { entities: ctx.registry.getAllEntities() } } to ` +
-            `executor.${verb} yourself.`,
-        );
-      }
-    }
-  }
-}