ai-delivery-workflow 0.2.2 → 0.4.0

package/lib/prototype-revision.mjs

@@ -0,0 +1,812 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import {
+  readYamlMapping as readYaml,
+  requireSha256 as requireChecksum,
+  resolveContainedPath as containedPath,
+  sha256File,
+} from "./artifact-files.mjs";
+
+export const PROTOTYPE_REVISION_CATALOG_SCHEMA_VERSION = "prototype-revision-catalog.v2";
+
+export const COMPONENT_CANDIDATE_LIFECYCLE_STATES = Object.freeze([
+  "candidate",
+  "under-review",
+  "registered",
+  "modified",
+  "deprecated",
+  "replaced",
+]);
+
+export const COMPONENT_CANDIDATE_LIFECYCLE_TRANSITIONS = Object.freeze({
+  candidate: Object.freeze(["under-review"]),
+  "under-review": Object.freeze(["registered"]),
+  registered: Object.freeze(["modified", "deprecated", "replaced"]),
+  modified: Object.freeze([]),
+  deprecated: Object.freeze([]),
+  replaced: Object.freeze([]),
+});
+
+export const COMPONENT_CANDIDATE_BINDING_STATUS = Object.freeze({
+  candidate: "pending-review",
+  "under-review": "pending-review",
+  registered: "active",
+  modified: "pending-review",
+  deprecated: "stale",
+  replaced: "stale",
+});
+
+export const prototypeRevisionCatalogContracts = Object.freeze({
+  terminals: "terminal_id,terminal_name,source_entrypoint,build_command,review_base_path,production_base_path,compatibility_group,lifecycle_status",
+  pages: "page_id,terminal_id,page_name,display_label,parent_page_id,lifecycle_status",
+  review_scenes: "review_scene_id,page_id,terminal_id,scene_name,scene_type,trigger_condition_id,lifecycle_status",
+  trigger_conditions: "trigger_condition_id,trigger_kind,condition,fixture_ref,notes",
+  routes: "route_id,terminal_id,route_kind,path,page_id,review_scene_id,lifecycle_status",
+  ui_mapping: "ui_mapping_id,target_kind,target_id,terminal_id,page_id,review_scene_id,prototype_route_id,production_route_id,frontend_source_ref,acceptance_id,lifecycle_status",
+  review_units: "review_unit_id,unit_kind,target_id,source_ref,checksum,lifecycle_status",
+  review_unit_pages: "review_unit_id,page_id",
+  components: "component_id,name,layer,base_component,variants,states,owner,lifecycle_status",
+  data_contracts: "data_contract_id,entity,source,stable_id,fields,context,permission,sort,default_value,url_param,states,version,supersedes,compatibility,lifecycle_status",
+  component_candidates: "component_id,name,layer,base_component,variants,states,owner,lifecycle,source_page_id,source_scene_ids,proposed_implementation_entry,data_contract_id,compatibility,migration_note,review_comment",
+  component_bindings: "page_id,scene_ids,terminal_id,component_id,variant,data_contract_id,context,status",
+  implementation_bindings: "component_id,implementation_entry,data_contract_id",
+  source_inspection_snapshots: "source_snapshot_id,asset_kind,page_id,review_scene_id,terminal_id,source_ref,checksum,language,scene_branch,lifecycle_status",
+});
+
+function listFiles(directory) {
+  const files = [];
+  const visit = (current) => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const absolute = path.join(current, entry.name);
+      if (entry.isDirectory()) visit(absolute);
+      else if (entry.isFile()) files.push(absolute);
+      else if (entry.isSymbolicLink()) {
+        throw new Error(`Prototype revision trees must not contain symbolic links: ${absolute}.`);
+      } else throw new Error(`Prototype revision trees contain an unsupported filesystem entry: ${absolute}.`);
+    }
+  };
+  visit(directory);
+  return files.sort((left, right) => left.localeCompare(right));
+}
+
+export function prototypeRevisionTreeDigest(directory) {
+  if (!fs.existsSync(directory) || !fs.statSync(directory).isDirectory()) {
+    throw new Error(`Checksummed directory is missing: ${directory}`);
+  }
+  const digest = crypto.createHash("sha256");
+  for (const file of listFiles(directory)) {
+    digest.update(path.relative(directory, file).replaceAll("\\", "/"));
+    digest.update("\0");
+    digest.update(fs.readFileSync(file));
+    digest.update("\0");
+  }
+  return digest.digest("hex");
+}
+
+export function parsePrototypeCatalogCsv(text, label) {
+  const rows = [];
+  let row = [];
+  let field = "";
+  let state = "unquoted";
+  const pushField = () => {
+    row.push(field);
+    field = "";
+    state = "unquoted";
+  };
+  const pushRow = () => {
+    pushField();
+    rows.push(row);
+    row = [];
+  };
+  for (let index = 0; index < text.length; index += 1) {
+    const character = text[index];
+    if (state === "quoted") {
+      if (character === '"' && text[index + 1] === '"') {
+        field += '"';
+        index += 1;
+      } else if (character === '"') state = "after-quote";
+      else field += character;
+    } else if (state === "after-quote") {
+      if (character === ",") pushField();
+      else if (character === "\n") pushRow();
+      else if (character === "\r" && text[index + 1] === "\n") {
+        index += 1;
+        pushRow();
+      } else throw new Error(`${label} contains an invalid character after closing quote.`);
+    } else if (character === '"') {
+      if (field.length !== 0) throw new Error(`${label} contains a quote inside an unquoted field.`);
+      state = "quoted";
+    }
+    else if (character === ",") {
+      pushField();
+    } else if (character === "\n") pushRow();
+    else if (character === "\r" && text[index + 1] === "\n") {
+      index += 1;
+      pushRow();
+    } else field += character;
+  }
+  if (state === "quoted") throw new Error(`${label} contains an unterminated quoted field.`);
+  if (field.length || row.length) {
+    pushRow();
+  }
+  if (!rows.length) throw new Error(`${label} is empty.`);
+  const headers = rows[0];
+  if (headers.some((header) => !header) || new Set(headers).size !== headers.length) {
+    throw new Error(`${label} has empty or duplicate column names.`);
+  }
+  const values = [];
+  for (let index = 1; index < rows.length; index += 1) {
+    if (rows[index].length === 1 && rows[index][0] === "") continue;
+    if (rows[index].length !== headers.length) {
+      throw new Error(`${label} row ${index + 1} has ${rows[index].length} fields; expected ${headers.length}.`);
+    }
+    values.push(Object.fromEntries(headers.map((header, column) => [header, rows[index][column]])));
+  }
+  return { header: headers.join(","), rows: values };
+}
+
+export function serializePrototypeCatalogCsv(headers, rows) {
+  if (!Array.isArray(headers) || !headers.length
+      || headers.some((header) => typeof header !== "string" || !header)) {
+    throw new Error("Prototype catalog CSV headers must be a non-empty string array.");
+  }
+  if (!Array.isArray(rows)) throw new Error("Prototype catalog CSV rows must be an array.");
+  const escape = (value) => {
+    const text = value === undefined || value === null ? "" : String(value);
+    return /[",\r\n]/.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
+  };
+  return `${[
+    headers.map(escape).join(","),
+    ...rows.map((row) => headers.map((header) => escape(row?.[header])).join(",")),
+  ].join("\n")}\n`;
+}
+
+function indexUnique(rows, field, label) {
+  const result = new Map();
+  for (const row of rows) {
+    const identity = String(row[field] || "").trim();
+    if (!identity) throw new Error(`${label} has an empty ${field}.`);
+    if (result.has(identity)) throw new Error(`Duplicate ${field} in ${label}: ${identity}.`);
+    result.set(identity, row);
+  }
+  return result;
+}
+
+function requireCatalogFields(rows, identityField, label, fields) {
+  for (const row of rows) {
+    const identity = String(row[identityField] || "").trim() || "<unknown>";
+    for (const field of fields) {
+      if (!String(row[field] || "").trim()) {
+        throw new Error(`${label} ${identity} is missing ${field}.`);
+      }
+    }
+  }
+}
+
+function active(rows) {
+  return rows.filter((row) => row.lifecycle_status === "active");
+}
+
+function validateLifecycle(collection, identityField, label) {
+  for (const row of collection.values()) {
+    if (!new Set(["active", "retired"]).has(row.lifecycle_status)) {
+      throw new Error(`${label} ${row[identityField]} has invalid lifecycle_status ${row.lifecycle_status || "<empty>"}.`);
+    }
+  }
+}
+
+function requireReference(collection, identity, label) {
+  if (!collection.has(identity)) throw new Error(`${label} references unknown identity: ${identity}.`);
+  return collection.get(identity);
+}
+
+function requireActiveReference(collection, identity, label, type) {
+  const referenced = requireReference(collection, identity, label);
+  if (referenced.lifecycle_status !== "active") {
+    throw new Error(`${label} is active but references retired ${type}: ${identity}.`);
+  }
+  return referenced;
+}
+
+function requireTypedReference(collection, identity, label, type) {
+  const referenced = collection.get(identity);
+  if (!referenced) throw new Error(`${label} references unknown ${type}: ${identity || "<empty>"}.`);
+  return referenced;
+}
+
+function pipeReferences(value, label) {
+  const source = String(value || "").trim();
+  if (!source) return [];
+  const identities = source.split("|").map((identity) => identity.trim());
+  if (identities.some((identity) => !identity)) throw new Error(`${label} has an empty pipe-delimited reference.`);
+  if (new Set(identities).size !== identities.length) throw new Error(`${label} has duplicate pipe-delimited references.`);
+  return identities;
+}
+
+function validateCatalogs(catalogRows, sourceRoot) {
+  const terminals = indexUnique(catalogRows.terminals, "terminal_id", "terminal catalog");
+  const pages = indexUnique(catalogRows.pages, "page_id", "page catalog");
+  const scenes = indexUnique(catalogRows.review_scenes, "review_scene_id", "Review Scene catalog");
+  const triggers = indexUnique(catalogRows.trigger_conditions, "trigger_condition_id", "trigger-condition catalog");
+  const routes = indexUnique(catalogRows.routes, "route_id", "route catalog");
+  const mappings = indexUnique(catalogRows.ui_mapping, "ui_mapping_id", "UI Mapping catalog");
+  const reviewUnits = indexUnique(catalogRows.review_units, "review_unit_id", "Review Unit catalog");
+  const components = indexUnique(
+    catalogRows.components,
+    "component_id",
+    "Component Registration catalog",
+  );
+  const dataContracts = indexUnique(
+    catalogRows.data_contracts,
+    "data_contract_id",
+    "Data Contract catalog",
+  );
+  const implementationBindings = indexUnique(
+    catalogRows.implementation_bindings,
+    "component_id",
+    "Implementation Binding catalog",
+  );
+  const componentCandidates = indexUnique(
+    catalogRows.component_candidates,
+    "component_id",
+    "Component Candidate catalog",
+  );
+  const sourceInspectionSnapshots = indexUnique(
+    catalogRows.source_inspection_snapshots,
+    "source_snapshot_id",
+    "Source Inspection Snapshot catalog",
+  );
+  requireCatalogFields(catalogRows.components, "component_id", "Component Registration", [
+    "component_id", "name", "layer", "base_component", "variants", "states", "owner", "lifecycle_status",
+  ]);
+  requireCatalogFields(catalogRows.data_contracts, "data_contract_id", "Data Contract", [
+    "data_contract_id", "entity", "source", "stable_id", "fields", "context", "permission", "sort",
+    "default_value", "url_param", "states", "version", "compatibility", "lifecycle_status",
+  ]);
+  requireCatalogFields(catalogRows.component_candidates, "component_id", "Component Candidate", [
+    "component_id", "name", "layer", "base_component", "variants", "states", "owner", "lifecycle",
+    "source_page_id", "source_scene_ids", "proposed_implementation_entry", "data_contract_id", "compatibility",
+    "migration_note", "review_comment",
+  ]);
+  requireCatalogFields(catalogRows.component_bindings, "page_id", "Component Binding", [
+    "page_id", "scene_ids", "terminal_id", "component_id", "variant", "data_contract_id", "context", "status",
+  ]);
+  requireCatalogFields(catalogRows.implementation_bindings, "component_id", "Implementation Binding", [
+    "component_id", "implementation_entry", "data_contract_id",
+  ]);
+  requireCatalogFields(catalogRows.source_inspection_snapshots, "source_snapshot_id", "Source Inspection Snapshot", [
+    "source_snapshot_id", "asset_kind", "page_id", "terminal_id", "source_ref", "checksum", "language",
+    "scene_branch", "lifecycle_status",
+  ]);
+  const reviewUnitPages = new Map();
+  const reviewUnitPagePairs = new Set();
+  for (const relation of catalogRows.review_unit_pages) {
+    const unit = requireReference(
+      reviewUnits,
+      relation.review_unit_id,
+      "Review Unit Page relation",
+    );
+    const page = requireReference(
+      pages,
+      relation.page_id,
+      `Review Unit ${relation.review_unit_id}`,
+    );
+    const pair = `${unit.review_unit_id}\0${page.page_id}`;
+    if (reviewUnitPagePairs.has(pair)) {
+      throw new Error(`Duplicate Review Unit Page relation: ${unit.review_unit_id}/${page.page_id}.`);
+    }
+    reviewUnitPagePairs.add(pair);
+    const related = reviewUnitPages.get(unit.review_unit_id) || [];
+    related.push(page.page_id);
+    reviewUnitPages.set(unit.review_unit_id, related);
+  }
+  validateLifecycle(terminals, "terminal_id", "Terminal");
+  validateLifecycle(pages, "page_id", "Page");
+  validateLifecycle(scenes, "review_scene_id", "Review Scene");
+  validateLifecycle(routes, "route_id", "Route");
+  validateLifecycle(mappings, "ui_mapping_id", "UI Mapping");
+  validateLifecycle(reviewUnits, "review_unit_id", "Review Unit");
+  validateLifecycle(components, "component_id", "Component Registration");
+  validateLifecycle(dataContracts, "data_contract_id", "Data Contract");
+  validateLifecycle(sourceInspectionSnapshots, "source_snapshot_id", "Source Inspection Snapshot");
+
+  for (const terminal of terminals.values()) {
+    for (const field of ["source_entrypoint", "build_command", "review_base_path", "production_base_path"]) {
+      if (!String(terminal[field] || "").trim()) throw new Error(`Terminal ${terminal.terminal_id} is missing ${field}.`);
+    }
+  }
+  for (const page of pages.values()) {
+    if (!/^P[0-9]{2,}(?:-[0-9]{2,})?$/.test(page.page_id)) {
+      throw new Error(`Page ID is invalid: ${page.page_id}.`);
+    }
+    const terminal = requireReference(terminals, page.terminal_id, `Page ${page.page_id}`);
+    if (page.lifecycle_status === "active" && terminal.lifecycle_status !== "active") {
+      throw new Error(`Page ${page.page_id} is active but references retired Terminal: ${page.terminal_id}.`);
+    }
+    if (page.display_label !== `${page.page_id}-${page.page_name}`) {
+      throw new Error(`Page ${page.page_id} display_label must be derived from its identity and name.`);
+    }
+    if (page.page_id.includes("-")) {
+      const parent = requireReference(pages, page.parent_page_id, `Page ${page.page_id}`);
+      if (parent.page_id.includes("-") || parent.terminal_id !== page.terminal_id) {
+        throw new Error(`Page ${page.page_id} has an invalid parent page.`);
+      }
+      if (page.lifecycle_status === "active" && parent.lifecycle_status !== "active") {
+        throw new Error(`Page ${page.page_id} is active but references retired parent Page: ${parent.page_id}.`);
+      }
+    } else if (page.parent_page_id) throw new Error(`Main Page ${page.page_id} must not have a parent.`);
+  }
+  const allowedSceneTypes = new Set([
+    "default", "loading", "empty", "success", "partial", "error", "permission", "disabled", "recovery",
+  ]);
+  for (const scene of scenes.values()) {
+    if (!/^RS[0-9]{4,}$/.test(scene.review_scene_id)) {
+      throw new Error(`Review Scene ID is invalid: ${scene.review_scene_id}.`);
+    }
+    const page = requireReference(pages, scene.page_id, `Review Scene ${scene.review_scene_id}`);
+    if (page.terminal_id !== scene.terminal_id) {
+      throw new Error(`Review Scene ${scene.review_scene_id} terminal does not match its Page.`);
+    }
+    if (scene.lifecycle_status === "active" && page.lifecycle_status !== "active") {
+      throw new Error(`Review Scene ${scene.review_scene_id} is active but references retired Page: ${page.page_id}.`);
+    }
+    if (!allowedSceneTypes.has(scene.scene_type)) {
+      throw new Error(`Review Scene ${scene.review_scene_id} has invalid scene_type ${scene.scene_type}.`);
+    }
+    requireReference(triggers, scene.trigger_condition_id, `Review Scene ${scene.review_scene_id}`);
+  }
+  const routePaths = new Set();
+  for (const route of routes.values()) {
+    if (!new Set(["prototype", "production"]).has(route.route_kind)) {
+      throw new Error(`Route ${route.route_id} has invalid route_kind ${route.route_kind}.`);
+    }
+    const terminal = requireReference(terminals, route.terminal_id, `Route ${route.route_id}`);
+    const page = requireReference(pages, route.page_id, `Route ${route.route_id}`);
+    if (page.terminal_id !== route.terminal_id) throw new Error(`Route ${route.route_id} terminal does not match its Page.`);
+    if (!route.path.startsWith("/")) throw new Error(`Route ${route.route_id} path must start with '/'.`);
+    const pathIdentity = `${route.terminal_id}:${route.route_kind}:${route.path}`;
+    if (routePaths.has(pathIdentity)) throw new Error(`Duplicate route path: ${pathIdentity}.`);
+    routePaths.add(pathIdentity);
+    if (route.route_kind === "production" && route.review_scene_id) {
+      throw new Error(`Production route ${route.route_id} must not target a Review Scene.`);
+    }
+    if (route.review_scene_id) {
+      const scene = requireReference(scenes, route.review_scene_id, `Route ${route.route_id}`);
+      if (scene.page_id !== route.page_id) throw new Error(`Route ${route.route_id} Review Scene does not belong to its Page.`);
+      if (route.lifecycle_status === "active" && scene.lifecycle_status !== "active") {
+        throw new Error(`Route ${route.route_id} is active but references retired Review Scene: ${scene.review_scene_id}.`);
+      }
+    }
+    if (route.lifecycle_status === "active"
+        && (terminal.lifecycle_status !== "active" || page.lifecycle_status !== "active")) {
+      throw new Error(`Route ${route.route_id} is active but references a retired Terminal or Page.`);
+    }
+  }
+
+  const mappedPages = new Set();
+  const mappedScenes = new Set();
+  for (const mapping of active(catalogRows.ui_mapping)) {
+    const page = requireActiveReference(
+      pages, mapping.page_id, `Active UI Mapping ${mapping.ui_mapping_id}`, "Page",
+    );
+    if (page.terminal_id !== mapping.terminal_id) throw new Error(`UI Mapping ${mapping.ui_mapping_id} terminal does not match its Page.`);
+    const prototypeRoute = requireActiveReference(
+      routes, mapping.prototype_route_id, `Active UI Mapping ${mapping.ui_mapping_id}`, "route",
+    );
+    const productionRoute = requireActiveReference(
+      routes, mapping.production_route_id, `Active UI Mapping ${mapping.ui_mapping_id}`, "route",
+    );
+    if (prototypeRoute.route_kind !== "prototype" || productionRoute.route_kind !== "production") {
+      throw new Error(`UI Mapping ${mapping.ui_mapping_id} must bind prototype and production route kinds.`);
+    }
+    if (prototypeRoute.page_id !== page.page_id || productionRoute.page_id !== page.page_id) {
+      throw new Error(`UI Mapping ${mapping.ui_mapping_id} routes must target the mapped Page.`);
+    }
+    if (!mapping.frontend_source_ref || !mapping.acceptance_id) {
+      throw new Error(`UI Mapping ${mapping.ui_mapping_id} must bind frontend source and acceptance evidence.`);
+    }
+    if (mapping.target_kind === "page") {
+      if (mapping.target_id !== page.page_id || mapping.review_scene_id || prototypeRoute.review_scene_id) {
+        throw new Error(`Page UI Mapping ${mapping.ui_mapping_id} must target a Page-level prototype route.`);
+      }
+      if (mappedPages.has(page.page_id)) throw new Error(`Page ${page.page_id} has duplicate active UI Mapping rows.`);
+      mappedPages.add(page.page_id);
+    } else if (mapping.target_kind === "review-scene") {
+      const scene = requireActiveReference(
+        scenes, mapping.review_scene_id, `Active UI Mapping ${mapping.ui_mapping_id}`, "Review Scene",
+      );
+      if (mapping.target_id !== scene.review_scene_id || scene.page_id !== page.page_id
+          || prototypeRoute.review_scene_id !== scene.review_scene_id) {
+        throw new Error(`Review Scene UI Mapping ${mapping.ui_mapping_id} does not match its direct prototype route.`);
+      }
+      if (mappedScenes.has(scene.review_scene_id)) {
+        throw new Error(`Review Scene ${scene.review_scene_id} has duplicate active UI Mapping rows.`);
+      }
+      mappedScenes.add(scene.review_scene_id);
+    } else throw new Error(`UI Mapping ${mapping.ui_mapping_id} has invalid target_kind ${mapping.target_kind}.`);
+  }
+  for (const page of active([...pages.values()])) {
+    if (!mappedPages.has(page.page_id)) throw new Error(`Page ${page.page_id} has no active UI Mapping.`);
+  }
+  for (const scene of active([...scenes.values()])) {
+    if (!mappedScenes.has(scene.review_scene_id)) {
+      throw new Error(`Review Scene ${scene.review_scene_id} has no directly accessible prototype route.`);
+    }
+  }
+  const coveredPages = new Set();
+  const coveredScenes = new Set();
+  for (const unit of reviewUnits.values()) {
+    if (!new Set(["page", "review-scene", "shared-component"]).has(unit.unit_kind)) {
+      throw new Error(`Review Unit ${unit.review_unit_id} has invalid unit_kind ${unit.unit_kind || "<empty>"}.`);
+    }
+    const sourceFile = containedPath(sourceRoot, unit.source_ref, `Review Unit ${unit.review_unit_id} source`);
+    if (!fs.existsSync(sourceFile) || !fs.statSync(sourceFile).isFile()) {
+      throw new Error(`Review Unit ${unit.review_unit_id} source is missing.`);
+    }
+    if (sha256File(sourceFile) !== requireChecksum(unit.checksum, `Review Unit ${unit.review_unit_id}`)) {
+      throw new Error(`Review Unit ${unit.review_unit_id} checksum does not match its source.`);
+    }
+    const pageIds = reviewUnitPages.get(unit.review_unit_id) || [];
+    if (!pageIds.length) throw new Error(`Review Unit ${unit.review_unit_id} has no affected Page relation.`);
+    for (const pageId of pageIds) {
+      const page = requireReference(pages, pageId, `Review Unit ${unit.review_unit_id}`);
+      if (unit.lifecycle_status === "active" && page.lifecycle_status !== "active") {
+        throw new Error(`Active Review Unit ${unit.review_unit_id} references retired Page: ${pageId}.`);
+      }
+    }
+    if (unit.unit_kind === "page") {
+      const page = requireReference(pages, unit.target_id, `Review Unit ${unit.review_unit_id}`);
+      if (pageIds.length !== 1 || pageIds[0] !== page.page_id) {
+        throw new Error(`Page Review Unit ${unit.review_unit_id} must affect exactly its target Page.`);
+      }
+      if (unit.lifecycle_status === "active") coveredPages.add(page.page_id);
+    } else if (unit.unit_kind === "review-scene") {
+      const scene = requireReference(scenes, unit.target_id, `Review Unit ${unit.review_unit_id}`);
+      if (pageIds.length !== 1 || pageIds[0] !== scene.page_id) {
+        throw new Error(`Review Scene Unit ${unit.review_unit_id} must affect exactly its owning Page.`);
+      }
+      if (unit.lifecycle_status === "active") coveredScenes.add(scene.review_scene_id);
+    } else if (unit.target_id) {
+      throw new Error(`Shared-component Review Unit ${unit.review_unit_id} must not declare target_id.`);
+    }
+  }
+  for (const page of active([...pages.values()])) {
+    if (!coveredPages.has(page.page_id)) throw new Error(`Page ${page.page_id} has no active Page Review Unit.`);
+  }
+  for (const scene of active([...scenes.values()])) {
+    if (!coveredScenes.has(scene.review_scene_id)) {
+      throw new Error(`Review Scene ${scene.review_scene_id} has no active Review Unit.`);
+    }
+  }
+  const implementationEntries = new Map();
+  for (const binding of implementationBindings.values()) {
+    const label = `Implementation Binding ${binding.component_id}`;
+    const candidate = componentCandidates.get(binding.component_id);
+    if (!components.has(binding.component_id) && !candidate) {
+      throw new Error(`${label} references unknown Component Registration or Component Candidate: ${binding.component_id || "<empty>"}.`);
+    }
+    if (candidate && candidate.lifecycle !== "registered") {
+      throw new Error(`${label} requires Component Candidate ${binding.component_id} to be registered.`);
+    }
+    requireTypedReference(dataContracts, binding.data_contract_id, label, "Data Contract");
+    if (candidate && candidate.data_contract_id !== binding.data_contract_id) {
+      throw new Error(
+        `${label} Data Contract ${binding.data_contract_id} conflicts with Component Candidate ${binding.component_id} Data Contract ${candidate.data_contract_id}.`,
+      );
+    }
+    const implementationEntry = String(binding.implementation_entry || "").trim();
+    if (implementationEntries.has(implementationEntry)) {
+      throw new Error(
+        `${label} reuses implementation entry ${implementationEntry} from Component Registration ${implementationEntries.get(implementationEntry)}.`,
+      );
+    }
+    implementationEntries.set(implementationEntry, binding.component_id);
+  }
+  for (const candidate of componentCandidates.values()) {
+    const label = `Component Candidate ${candidate.component_id}`;
+    if (!COMPONENT_CANDIDATE_LIFECYCLE_STATES.includes(candidate.lifecycle)) {
+      throw new Error(`${label} has invalid lifecycle ${candidate.lifecycle || "<empty>"}.`);
+    }
+    const page = requireTypedReference(pages, candidate.source_page_id, label, "Page");
+    requireTypedReference(dataContracts, candidate.data_contract_id, label, "Data Contract");
+    for (const sceneId of pipeReferences(candidate.source_scene_ids, label)) {
+      const scene = requireTypedReference(scenes, sceneId, label, "Review Scene");
+      if (scene.page_id !== page.page_id) {
+        throw new Error(`${label} Review Scene ${sceneId} is outside its source Page.`);
+      }
+    }
+    if (components.has(candidate.component_id) && candidate.lifecycle !== "registered") {
+      throw new Error(`${label} is not registered but duplicates a Component Registration.`);
+    }
+  }
+  for (const binding of catalogRows.component_bindings) {
+    const label = `Component Binding ${binding.page_id || "<unknown>"}`;
+    const page = requireTypedReference(pages, binding.page_id, label, "Page");
+    const terminal = requireTypedReference(terminals, binding.terminal_id, label, "Logical Terminal");
+    if (page.terminal_id !== terminal.terminal_id) {
+      throw new Error(`${label} terminal does not match its Page.`);
+    }
+    const candidate = componentCandidates.get(binding.component_id);
+    const component = components.get(binding.component_id) || candidate;
+    if (!component) {
+      throw new Error(
+        `Component Binding ${binding.page_id || "<unknown>"} references unknown Component Registration or Component Candidate: ${binding.component_id || "<empty>"}.`,
+      );
+    }
+    requireTypedReference(dataContracts, binding.data_contract_id, label, "Data Contract");
+    const variants = pipeReferences(component.variants, `Component ${binding.component_id}`);
+    if (!variants.includes(binding.variant)) {
+      throw new Error(
+        `${label} variant ${binding.variant || "<empty>"} is not registered by Component ${binding.component_id}.`,
+      );
+    }
+    if (!new Set(["active", "pending-review", "stale"]).has(binding.status)) {
+      throw new Error(`${label} has invalid status ${binding.status || "<empty>"}.`);
+    }
+    const expectedCandidateBindingStatus = candidate
+      && COMPONENT_CANDIDATE_BINDING_STATUS[candidate.lifecycle];
+    if (expectedCandidateBindingStatus && binding.status !== expectedCandidateBindingStatus) {
+      throw new Error(
+        `Component Candidate ${candidate.component_id} lifecycle ${candidate.lifecycle} requires ${expectedCandidateBindingStatus} bindings.`,
+      );
+    }
+    const implementation = implementationBindings.get(binding.component_id);
+    if (implementation && implementation.data_contract_id !== binding.data_contract_id) {
+      throw new Error(
+        `${label} Data Contract ${binding.data_contract_id} conflicts with Implementation Binding ${binding.component_id} Data Contract ${implementation.data_contract_id}.`,
+      );
+    }
+    for (const sceneId of pipeReferences(binding.scene_ids, label)) {
+      const scene = requireTypedReference(scenes, sceneId, label, "Review Scene");
+      if (scene.page_id !== page.page_id || scene.terminal_id !== terminal.terminal_id) {
+        throw new Error(`${label} Review Scene ${sceneId} is outside its Page or Logical Terminal.`);
+      }
+    }
+  }
+  for (const snapshot of sourceInspectionSnapshots.values()) {
+    const label = `Source Inspection Snapshot ${snapshot.source_snapshot_id}`;
+    if (!new Set(["implementation", "acceptance"]).has(snapshot.asset_kind)) {
+      throw new Error(`${label} has invalid asset_kind ${snapshot.asset_kind || "<empty>"}.`);
+    }
+    for (const field of ["page_id", "terminal_id", "source_ref", "language", "scene_branch"]) {
+      if (!String(snapshot[field] || "").trim()) {
+        throw new Error(`${label} is missing ${field}.`);
+      }
+    }
+    if (snapshot.source_ref.includes("\\")
+        || path.posix.isAbsolute(snapshot.source_ref)
+        || path.posix.normalize(snapshot.source_ref) !== snapshot.source_ref) {
+      throw new Error(`${label} source_ref must be a normalized relative POSIX path.`);
+    }
+    const terminal = requireTypedReference(terminals, snapshot.terminal_id, label, "Logical Terminal");
+    const page = requireTypedReference(pages, snapshot.page_id, label, "Page");
+    if (page.terminal_id !== terminal.terminal_id) {
+      throw new Error(`${label} Logical Terminal does not match its Page.`);
+    }
+    if (snapshot.review_scene_id) {
+      const scene = requireTypedReference(scenes, snapshot.review_scene_id, label, "Review Scene");
+      if (scene.page_id !== page.page_id || scene.terminal_id !== terminal.terminal_id) {
+        throw new Error(`${label} Review Scene is outside its Page or Logical Terminal.`);
+      }
+    }
+    const sourceFile = containedPath(sourceRoot, snapshot.source_ref, `${label} source`);
+    if (!fs.existsSync(sourceFile) || !fs.statSync(sourceFile).isFile()) {
+      throw new Error(`${label} source is missing.`);
+    }
+    if (sha256File(sourceFile) !== requireChecksum(snapshot.checksum, label)) {
+      throw new Error(`${label} checksum does not match its source.`);
+    }
+  }
+  return {
+    terminalCount: terminals.size,
+    pageCount: pages.size,
+    reviewSceneCount: scenes.size,
+    reviewUnitCount: reviewUnits.size,
+    reviewUnitPageCount: reviewUnitPagePairs.size,
+  };
+}
+
+function containedFrom(base, relative, allowedRoot, label) {
+  if (!relative || path.isAbsolute(relative)) throw new Error(`${label} must be a relative path.`);
+  const absolute = path.resolve(base, relative);
+  const fromAllowedRoot = path.relative(path.resolve(allowedRoot), absolute);
+  return containedPath(allowedRoot, fromAllowedRoot, label);
+}
+
+function readRevisionCatalog(revision, revisionFile, experienceRoot, name) {
+  const bundle = revision.review_bundle;
+  const revisionRoot = path.dirname(revisionFile);
+  const bundleRoot = containedFrom(revisionRoot, bundle?.ref, experienceRoot, "Previous review bundle");
+  if (bundle?.algorithm !== "sha256-tree-v1"
+      || prototypeRevisionTreeDigest(bundleRoot) !== requireChecksum(bundle?.checksum, "Previous review bundle")) {
+    throw new Error("Previous Prototype review bundle checksum mismatch.");
+  }
+  const entry = revision.catalogs?.[name];
+  if (entry?.algorithm !== "sha256") throw new Error(`Previous Prototype ${name} catalog must use sha256.`);
+  const file = containedFrom(bundleRoot, entry?.ref, bundleRoot, `Previous Prototype ${name} catalog`);
+  if (!fs.existsSync(file) || !fs.statSync(file).isFile()) {
+    throw new Error(`Previous Prototype ${name} catalog is missing.`);
+  }
+  if (sha256File(file) !== requireChecksum(entry?.checksum, `Previous Prototype ${name} catalog`)) {
+    throw new Error(`Previous Prototype ${name} catalog checksum mismatch.`);
+  }
+  const parsed = parsePrototypeCatalogCsv(
+    fs.readFileSync(file, "utf8"), `Previous Prototype ${name} catalog`,
+  );
+  if (parsed.header !== prototypeRevisionCatalogContracts[name]) {
+    throw new Error(`Previous Prototype ${name} catalog header is invalid.`);
+  }
+  return parsed.rows;
+}
+
+function readPreviousRevisionLink(revision, revisionFile, experienceRoot) {
+  const previousEntry = revision.previous_revision;
+  if (revision.version === 1) {
+    if (previousEntry !== null && previousEntry !== undefined) {
+      throw new Error("Initial Prototype revision must not declare a previous revision.");
+    }
+    return null;
+  }
+  if (!previousEntry || previousEntry.algorithm !== "sha256") {
+    throw new Error("Prototype revision version greater than one must pin the previous revision and checksum.");
+  }
+  const previousFile = containedFrom(
+    path.dirname(revisionFile), previousEntry.ref, experienceRoot, "Previous Prototype revision",
+  );
+  if (!fs.existsSync(previousFile) || !fs.statSync(previousFile).isFile()) {
+    throw new Error("Previous Prototype revision is missing.");
+  }
+  const previousChecksum = requireChecksum(previousEntry.checksum, "Previous Prototype revision");
+  if (sha256File(previousFile) !== previousChecksum) {
+    throw new Error("Previous Prototype revision checksum mismatch.");
+  }
+  const previous = readYaml(previousFile, "Previous Prototype revision");
+  if (previous.artifact_type !== "prototype-revision" || previous.status !== "frozen"
+      || !previous.artifact_id || previous.prototype_id !== revision.prototype_id
+      || previous.version !== revision.version - 1) {
+    throw new Error("Previous Prototype revision identity, status, or version is invalid.");
+  }
+  return { revision: previous, file: previousFile, checksum: previousChecksum };
+}
+
+function readPrototypeRevisionAncestors(revision, revisionFile, experienceRoot) {
+  const ancestors = [];
+  const seenIds = new Set([revision.artifact_id]);
+  let current = revision;
+  let currentFile = revisionFile;
+  while (true) {
+    const previous = readPreviousRevisionLink(current, currentFile, experienceRoot);
+    if (!previous) return ancestors;
+    if (seenIds.has(previous.revision.artifact_id)) {
+      throw new Error("Prototype revision ancestry contains a repeated identity.");
+    }
+    ancestors.push(previous);
+    seenIds.add(previous.revision.artifact_id);
+    current = previous.revision;
+    currentFile = previous.file;
+  }
+}
+
+function validateStableIdentityHistory(previousLink, experienceRoot, catalogRows) {
+  if (!previousLink) return;
+  const previous = previousLink.revision;
+  const previousFile = previousLink.file;
+  for (const [name, identityField, label, immutableFields] of [
+    ["pages", "page_id", "Page", ["terminal_id", "parent_page_id"]],
+    ["review_scenes", "review_scene_id", "Review Scene", ["terminal_id", "page_id"]],
+  ]) {
+    const previousRows = readRevisionCatalog(previous, previousFile, experienceRoot, name);
+    const prior = indexUnique(previousRows, identityField, `previous ${label} catalog`);
+    const current = indexUnique(catalogRows[name], identityField, `current ${label} catalog`);
+    validateLifecycle(prior, identityField, `Previous ${label}`);
+    for (const [identity, previousRow] of prior) {
+      const currentRow = current.get(identity);
+      if (!currentRow) throw new Error(`Stable ${label} identity ${identity} was removed instead of retired.`);
+      if (previousRow.lifecycle_status === "retired" && currentRow.lifecycle_status !== "retired") {
+        throw new Error(`Retired ${label} identity ${identity} was reactivated or reused.`);
+      }
+      for (const field of immutableFields) {
+        if (previousRow[field] !== currentRow[field]) {
+          throw new Error(`Stable ${label} identity ${identity} changed immutable ${field}.`);
+        }
+      }
+    }
+  }
+}
+
+export function validatePrototypeRevision(projectRoot, options = {}) {
+  const experienceRoot = containedPath(projectRoot, options.experience, "Experience directory");
+  const revisionFile = containedPath(experienceRoot, options.revision, "Prototype revision");
+  const revision = readYaml(revisionFile, "Prototype revision");
+  const current = readYaml(path.join(experienceRoot, "prototype.yaml"), "Current Prototype descriptor");
+  if (current.artifact_type !== "prototype-current" || revision.artifact_type !== "prototype-revision") {
+    throw new Error("Prototype artifacts do not declare the current and revision artifact types.");
+  }
+  if (!current.prototype_id || current.prototype_id !== revision.prototype_id) {
+    throw new Error("Prototype revision must belong to the single current Prototype identity.");
+  }
+  if (revision.status !== "frozen" || !Number.isInteger(revision.version) || revision.version < 1) {
+    throw new Error("Prototype revision must be a frozen positive semantic version.");
+  }
+  if (!revision.artifact_id || !revision.iteration_id || !Number.isFinite(Date.parse(revision.frozen_at || ""))) {
+    throw new Error("Prototype revision must declare artifact, iteration, and frozen-at identities.");
+  }
+  if (!revision.source || revision.source.ref !== current.current_source_ref) {
+    throw new Error("Prototype revision source must bind the single current Prototype source path.");
+  }
+  if (!String(current.current_review_shell_ref || "").trim()) {
+    throw new Error("Current Prototype must declare one current Review Shell path.");
+  }
+  if (!String(revision.source.revision || "").trim() || revision.source.algorithm !== "sha256-tree-v1") {
+    throw new Error("Prototype source must pin an immutable revision and sha256-tree-v1 digest.");
+  }
+  const revisionRelative = path.relative(experienceRoot, revisionFile).replaceAll("\\", "/");
+  const sourceRoot = containedPath(experienceRoot, revision.source.ref, "Current Prototype source");
+  if (prototypeRevisionTreeDigest(sourceRoot) !== requireChecksum(revision.source.checksum, "Prototype source")) {
+    throw new Error("Current Prototype source checksum does not match its selected revision.");
+  }
+  const currentShellRoot = containedPath(
+    experienceRoot, current.current_review_shell_ref, "Current Review Shell",
+  );
+  if (!fs.existsSync(currentShellRoot) || !fs.statSync(currentShellRoot).isDirectory()
+      || listFiles(currentShellRoot).length === 0) {
+    throw new Error("Current Prototype must expose one non-empty current Review Shell directory.");
+  }
+
+  const revisionRoot = path.dirname(revisionFile);
+  const bundleRoot = containedPath(revisionRoot, revision.review_bundle?.ref, "Prototype review bundle");
+  if (revision.review_bundle?.algorithm !== "sha256-tree-v1"
+      || prototypeRevisionTreeDigest(bundleRoot) !== requireChecksum(revision.review_bundle?.checksum, "Prototype review bundle")) {
+    throw new Error("Prototype review bundle checksum mismatch.");
+  }
+  const verifyBundleFile = (entry, label) => {
+    const file = containedPath(bundleRoot, entry?.ref, label);
+    if (!fs.existsSync(file) || !fs.statSync(file).isFile()) throw new Error(`${label} is missing.`);
+    if (sha256File(file) !== requireChecksum(entry?.checksum, label)) throw new Error(`${label} checksum mismatch.`);
+    return file;
+  };
+  const shellFile = containedPath(bundleRoot, revision.review_shell?.entrypoint_in_bundle, "Review Shell entrypoint");
+  if (!fs.existsSync(shellFile) || !fs.statSync(shellFile).isFile()) throw new Error("Review Shell entrypoint is missing from the bundle.");
+  if (sha256File(shellFile) !== requireChecksum(revision.review_shell?.checksum, "Review Shell")) {
+    throw new Error("Review Shell checksum mismatch.");
+  }
+  verifyBundleFile(revision.visual_standard, "Visual Standard evidence");
+  verifyBundleFile(revision.review_evidence, "Prototype review evidence");
+
+  const catalogs = revision.catalogs;
+  if (revision.catalog_schema_version !== PROTOTYPE_REVISION_CATALOG_SCHEMA_VERSION) {
+    throw new Error(`Prototype revision must use ${PROTOTYPE_REVISION_CATALOG_SCHEMA_VERSION}.`);
+  }
+  if (!catalogs || typeof catalogs !== "object" || Array.isArray(catalogs)) {
+    throw new Error("Prototype revision catalogs are missing.");
+  }
+  const catalogRows = {};
+  for (const [name, expectedHeader] of Object.entries(prototypeRevisionCatalogContracts)) {
+    const entry = catalogs[name];
+    if (entry?.algorithm !== "sha256") throw new Error(`Prototype ${name} catalog must use sha256.`);
+    const file = verifyBundleFile(entry, `Prototype ${name} catalog`);
+    const parsed = parsePrototypeCatalogCsv(fs.readFileSync(file, "utf8"), `Prototype ${name} catalog`);
+    if (parsed.header !== expectedHeader) throw new Error(`Prototype ${name} catalog header is invalid.`);
+    catalogRows[name] = parsed.rows;
+  }
+  const counts = validateCatalogs(catalogRows, sourceRoot);
+  const ancestorLinks = readPrototypeRevisionAncestors(revision, revisionFile, experienceRoot);
+  validateStableIdentityHistory(ancestorLinks[0] || null, experienceRoot, catalogRows);
+  return {
+    valid: true,
+    prototype_id: revision.prototype_id,
+    revision_id: revision.artifact_id,
+    catalog_schema_version: revision.catalog_schema_version,
+    terminal_count: counts.terminalCount,
+    page_count: counts.pageCount,
+    review_scene_count: counts.reviewSceneCount,
+    review_unit_count: counts.reviewUnitCount,
+    review_unit_page_count: counts.reviewUnitPageCount,
+    ancestor_revisions: ancestorLinks.map((ancestor) => ({
+      prototype_revision_id: ancestor.revision.artifact_id,
+      prototype_revision_checksum: ancestor.checksum,
+    })),
+    revision: revisionRelative,
+  };
+}