ai-delivery-workflow 0.2.2 → 0.4.0

package/lib/workflow-manager-prototypes.mjs

@@ -0,0 +1,1847 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL, fileURLToPath } from "node:url";
+
+import { buildPrototypeReviewTarget } from "./prototype-review-target.mjs";
+import {
+  COMPONENT_CANDIDATE_BINDING_STATUS,
+  COMPONENT_CANDIDATE_LIFECYCLE_TRANSITIONS,
+  parsePrototypeCatalogCsv,
+  prototypeRevisionCatalogContracts,
+  serializePrototypeCatalogCsv,
+  validatePrototypeRevision,
+} from "./prototype-revision.mjs";
+import {
+  createPrototypePageReviewReceipt,
+  prototypePageReviewReceiptWrite,
+} from "./prototype-page-review.mjs";
+import {
+  commitWorkflowManagerAction,
+  preflightWorkflowManagerAction,
+  prepareWorkflowManagerFormalTransaction,
+} from "./workflow-manager-transaction.mjs";
+import { parse as parseYaml, stringify as stringifyYaml } from "./yaml-runtime.mjs";
+
+const runtimeRoot = path.dirname(fileURLToPath(import.meta.url));
+const installedStateRuntime = path.join(runtimeRoot, "..", "state", "delivery-state.mjs");
+const packageStateRuntime = path.join(runtimeRoot, "delivery-state.mjs");
+const { executeDeliveryStateCommand } = await import(pathToFileURL(
+  fs.existsSync(installedStateRuntime) ? installedStateRuntime : packageStateRuntime,
+).href);
+const yaml = { parse: parseYaml, stringify: (value) => stringifyYaml(value, { lineWidth: 0 }) };
+
+export const WORKFLOW_MANAGER_PROTOTYPES_SCHEMA_VERSION = "workflow-manager.prototypes.v2";
+export const WORKFLOW_MANAGER_PROTOTYPE_SOURCE_SNAPSHOT_SCHEMA_VERSION =
+  "workflow-manager.prototype-source-snapshot.v1";
+
+const REVIEW_ROOT = ".workflow/experience/reviews";
+const REQUEST_ROOT = `${REVIEW_ROOT}/change-requests`;
+const BATCH_ROOT = `${REVIEW_ROOT}/batches`;
+const VISUAL_STANDARD_REVIEW_ROOT = `${REVIEW_ROOT}/visual-standard-reviews`;
+const ATTACHMENT_ROOT = `${REVIEW_ROOT}/attachments`;
+const TOMBSTONE_ROOT = `${REVIEW_ROOT}/discarded`;
+const WRITE_LOCK = `${REVIEW_ROOT}/.prototype-write.lock`;
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const SHA256 = /^[a-f0-9]{64}$/;
+
+export class PrototypeTerminalScopeError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PrototypeTerminalScopeError";
+    this.code = "prototype-terminal-invalid";
+  }
+}
+
+export class PrototypeSourceSnapshotError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "PrototypeSourceSnapshotError";
+    this.code = code;
+  }
+}
+
+function digest(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function inside(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function contained(root, relative, label) {
+  if (typeof relative !== "string" || !relative || relative.includes("\0") || relative.includes("\\")
+      || path.posix.isAbsolute(relative) || path.posix.normalize(relative) !== relative) {
+    throw new Error(`${label} must be a normalized project-relative POSIX path`);
+  }
+  const result = path.resolve(root, ...relative.split("/"));
+  if (!inside(root, result)) throw new Error(`${label} escapes project root`);
+  return result;
+}
+
+function readJson(file, label) {
+  try {
+    const value = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("mapping required");
+    return value;
+  } catch (error) {
+    throw new Error(`${label} is invalid JSON: ${error.message}`);
+  }
+}
+
+function files(root, relative) {
+  const directory = contained(root, relative, `${relative} directory`);
+  if (!fs.existsSync(directory)) return [];
+  if (!fs.statSync(directory).isDirectory()) throw new Error(`${relative} must be a directory`);
+  return fs.readdirSync(directory, { withFileTypes: true }).filter((entry) => {
+    if (entry.isSymbolicLink()) throw new Error(`${relative} must not contain symbolic links`);
+    return entry.isFile() && entry.name.endsWith(".json");
+  }).map((entry) => path.join(directory, entry.name)).sort();
+}
+
+function requestFile(root, changeRequestId) {
+  if (!SAFE_ID.test(String(changeRequestId || ""))) throw new Error("Prototype Change Request identity is invalid");
+  return contained(root, `${REQUEST_ROOT}/${changeRequestId}.json`, "Prototype Change Request path");
+}
+
+function readRequest(root, changeRequestId) {
+  const file = requestFile(root, changeRequestId);
+  if (!fs.existsSync(file)) throw new Error(`Prototype Change Request does not exist: ${changeRequestId}`);
+  const request = readJson(file, "Prototype Change Request");
+  if (request.change_request_id !== changeRequestId || !Number.isInteger(request.revision)) {
+    throw new Error("Prototype Change Request identity or revision is invalid");
+  }
+  return { file, request };
+}
+
+function preflightAction(root, action, input, subject = null) {
+  return preflightWorkflowManagerAction(root, { action, input, subject });
+}
+
+function commitAction(root, action, input, subject, result, writes, timestamp, options = {}) {
+  const terminalId = result?.terminal_id
+    ?? result?.change_request?.terminal_id
+    ?? result?.page_review_receipt?.terminal_id
+    ?? input.terminal_id
+    ?? null;
+  return commitWorkflowManagerAction(root, {
+    action,
+    input,
+    subject,
+    result,
+    writes,
+    receiptPrefix: "WMPR",
+    timestamp,
+    transactionHooks: options.transactionHooks,
+    detail: {
+      terminal_id: terminalId,
+      result_revision: result?.revision ?? result?.change_request?.revision ?? null,
+      result_receipt_id: result?.receipt_id ?? result?.page_review_receipt?.receipt_id ?? null,
+      result_decision: result?.decision ?? result?.page_review_receipt?.decision ?? null,
+      ...(Array.isArray(result?.affected_identities)
+        ? { affected_identities: result.affected_identities } : {}),
+    },
+    eventDetail: { terminal_id: terminalId },
+  });
+}
+
+function withPrototypeWriteLock(root, action) {
+  const lockFile = contained(root, WRITE_LOCK, "Prototype write lock");
+  fs.mkdirSync(path.dirname(lockFile), { recursive: true });
+  let handle;
+  try {
+    handle = fs.openSync(lockFile, "wx");
+    fs.writeFileSync(handle, `${JSON.stringify({ action, pid: process.pid, acquired_at: new Date().toISOString() })}\n`);
+  } catch (error) {
+    if (error.code === "EEXIST") throw new Error("Another Prototype write is in progress; retry with the same idempotency key");
+    throw error;
+  }
+  return () => {
+    try { fs.closeSync(handle); } finally { fs.rmSync(lockFile, { force: true }); }
+  };
+}
+
+function guardedPrototypeWrite(root, action, input, subject, apply) {
+  const initialReplay = preflightAction(root, action, input, subject);
+  if (initialReplay) return { replay: initialReplay };
+  const release = withPrototypeWriteLock(root, action);
+  try {
+    const replay = preflightAction(root, action, input, subject);
+    return replay ? { replay } : { value: apply() };
+  } finally {
+    release();
+  }
+}
+
+function requireHuman(actor) {
+  if (!/^human:[A-Za-z0-9._@/-]+$/.test(String(actor || ""))) {
+    throw new Error("Prototype review write requires actor human:<identity>");
+  }
+}
+
+function requestSnapshot(request) {
+  return {
+    change_request_id: request.change_request_id,
+    revision: request.revision,
+    checksum: request.checksum,
+  };
+}
+
+function requestChecksum(request) {
+  const copy = structuredClone(request);
+  delete copy.checksum;
+  return digest(JSON.stringify(copy));
+}
+
+function formalInspection(root) {
+  return executeDeliveryStateCommand(["inspect", "--project", root], { yaml });
+}
+
+function approvedPrototypeGate(inspection, revisionId, revisionChecksum) {
+  return [...(inspection.workflow_state?.development_state?.gate_decisions || [])].reverse()
+    .find((decision) => decision.gate_id === "UX-UI"
+      && decision.decision === "approved"
+      && decision.prototype_revision_id === revisionId
+      && decision.prototype_revision_checksum === revisionChecksum);
+}
+
+function assertPrototypeRevisionWritable(root, revisionId, revisionChecksum) {
+  if (approvedPrototypeGate(formalInspection(root), revisionId, revisionChecksum)) {
+    throw new Error("Prototype revision is already approved by UX-UI; create a fresh Prototype revision before further review changes");
+  }
+}
+
+function requireTerminalIdentity(value) {
+  if (typeof value !== "string" || !SAFE_ID.test(value)) {
+    throw new PrototypeTerminalScopeError("Logical Terminal identity is required.");
+  }
+  return value;
+}
+
+function resolveTerminalScopedReviewTarget(target, input) {
+  const terminalId = requireTerminalIdentity(input.terminal_id);
+  const terminal = target.terminals.find((item) => item.terminal_id === terminalId);
+  if (!terminal) throw new PrototypeTerminalScopeError(`Logical Terminal is not registered: ${terminalId}`);
+  const page = target.pages.find((item) => item.page_id === input.page_id);
+  if (!page) throw new Error(`Prototype Page does not exist: ${input.page_id}`);
+  if (page.terminal_id !== terminalId) {
+    throw new PrototypeTerminalScopeError(`Prototype Page ${page.page_id} does not belong to Logical Terminal ${terminalId}.`);
+  }
+  const sceneId = input.review_scene_id;
+  if (sceneId === undefined || sceneId === null || sceneId === "") return { terminal, page, scene: null };
+  const scene = target.reviewScenes.find((item) => item.review_scene_id === sceneId);
+  if (!scene) throw new Error(`Review Scene does not exist: ${sceneId}`);
+  if (scene.page_id !== page.page_id || scene.terminal_id !== terminalId) {
+    throw new PrototypeTerminalScopeError(`Review Scene ${scene.review_scene_id} is outside Page ${page.page_id} or Logical Terminal ${terminalId}.`);
+  }
+  return { terminal, page, scene };
+}
+
+function targetForPrototypeRequest(root, input) {
+  const target = buildPrototypeReviewTarget(root, {
+    experience: input.experience || ".workflow/experience",
+    revision: input.revision,
+  });
+  if (target.mode !== "prototype-revision") throw new Error("Prototype Change Request requires an exact Prototype revision");
+  if (target.targetId !== input.prototype_revision_id || target.targetChecksum !== input.prototype_revision_checksum) {
+    throw new Error("Prototype Change Request revision or checksum is stale.");
+  }
+  const resolved = resolveTerminalScopedReviewTarget(target, input);
+  if (resolved.page.page_checksum !== input.page_checksum) {
+    throw new Error("Prototype Change Request Page checksum is stale.");
+  }
+  return { target, ...resolved };
+}
+
+function targetForVisualStandardReview(root, input) {
+  const target = buildPrototypeReviewTarget(root, {
+    experience: input.experience || ".workflow/experience",
+    revision: input.revision,
+  });
+  if (target.mode !== "prototype-revision") throw new Error("Visual Standard review requires an exact Prototype revision");
+  if (target.targetId !== input.prototype_revision_id || target.targetChecksum !== input.prototype_revision_checksum) {
+    throw new Error("Visual Standard review revision or checksum is stale.");
+  }
+  if (target.visualStandard.checksum !== input.visual_standard_checksum) {
+    throw new Error("Visual Standard review checksum is stale.");
+  }
+  const terminalId = input.terminal_id === "all" ? "all" : requireTerminalIdentity(input.terminal_id);
+  if (terminalId !== "all" && !target.terminals.some((terminal) => terminal.terminal_id === terminalId)) {
+    throw new PrototypeTerminalScopeError(`Logical Terminal is not registered: ${terminalId}`);
+  }
+  return { target, terminalId };
+}
+
+const COMPONENT_CANDIDATE_TRANSITION_SCHEMA_VERSION = "workflow-manager.component-candidate-transition.v1";
+
+function readPrototypeRevisionDescriptor(file) {
+  const revision = yaml.parse(fs.readFileSync(file, "utf8"));
+  if (!revision || typeof revision !== "object" || Array.isArray(revision)) {
+    throw new Error("Prototype revision descriptor is invalid.");
+  }
+  return revision;
+}
+
+function bundleFileContents(bundleRoot) {
+  const contents = new Map();
+  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()) {
+        const relative = path.relative(bundleRoot, absolute).replaceAll("\\", "/");
+        contents.set(relative, fs.readFileSync(absolute));
+      } else if (entry.isSymbolicLink()) {
+        throw new Error(`Prototype review bundle must not contain symbolic links: ${absolute}`);
+      } else throw new Error(`Prototype review bundle contains an unsupported filesystem entry: ${absolute}`);
+    }
+  };
+  visit(bundleRoot);
+  return contents;
+}
+
+function bundleDigest(contents) {
+  const hash = crypto.createHash("sha256");
+  for (const relative of [...contents.keys()].sort((left, right) => left.localeCompare(right))) {
+    hash.update(relative);
+    hash.update("\0");
+    hash.update(contents.get(relative));
+    hash.update("\0");
+  }
+  return hash.digest("hex");
+}
+
+function csvCatalog(contents, revision, name) {
+  const entry = revision.catalogs?.[name];
+  if (!entry || entry.algorithm !== "sha256" || typeof entry.ref !== "string") {
+    throw new Error(`Prototype ${name} catalog is invalid.`);
+  }
+  const bytes = contents.get(entry.ref);
+  if (!bytes) throw new Error(`Prototype ${name} catalog is missing from the review bundle.`);
+  const parsed = parsePrototypeCatalogCsv(bytes.toString("utf8"), `Prototype ${name} catalog`);
+  if (parsed.header !== prototypeRevisionCatalogContracts[name]) {
+    throw new Error(`Prototype ${name} catalog header is invalid.`);
+  }
+  return { entry, headers: parsed.header.split(","), rows: parsed.rows };
+}
+
+function transitionCandidateTarget(root, input) {
+  const target = buildPrototypeReviewTarget(root, {
+    experience: input.experience || ".workflow/experience",
+    revision: input.revision,
+  });
+  if (target.mode !== "prototype-revision") {
+    throw new Error("Component Candidate transition requires an exact Prototype revision.");
+  }
+  if (target.targetId !== input.prototype_revision_id || target.targetChecksum !== input.prototype_revision_checksum) {
+    throw new Error("Component Candidate transition revision or checksum is stale.");
+  }
+  assertPrototypeRevisionWritable(root, target.targetId, target.targetChecksum);
+  if (!SAFE_ID.test(String(input.component_id || ""))) {
+    throw new Error("Component Candidate identity is invalid.");
+  }
+  const candidate = target.componentGovernance.component_candidates
+    .find((item) => item.component_id === input.component_id);
+  if (!candidate) throw new Error(`Component Candidate does not exist: ${input.component_id}`);
+  const terminalId = requireTerminalIdentity(input.terminal_id);
+  if (candidate.source_terminal_id !== terminalId) {
+    throw new PrototypeTerminalScopeError(
+      `Component Candidate ${candidate.component_id} does not belong to Logical Terminal ${terminalId}.`,
+    );
+  }
+  if (candidate.lifecycle !== input.expected_lifecycle) {
+    throw new Error(
+      `Component Candidate ${candidate.component_id} lifecycle is ${candidate.lifecycle}; expected ${input.expected_lifecycle}.`,
+    );
+  }
+  const allowed = COMPONENT_CANDIDATE_LIFECYCLE_TRANSITIONS[candidate.lifecycle] || [];
+  if (!allowed.includes(input.target_lifecycle)) {
+    throw new Error(
+      `Component Candidate ${candidate.component_id} cannot transition from ${candidate.lifecycle} to ${input.target_lifecycle}.`,
+    );
+  }
+  const revision = readPrototypeRevisionDescriptor(target.revisionFile);
+  if (revision.status !== "frozen" || revision.artifact_id !== target.targetId || revision.version < 1) {
+    throw new Error("Component Candidate transition input must be a frozen Prototype revision.");
+  }
+  return { target, candidate, terminalId, revision };
+}
+
+function nextPrototypeRevisionIdentity(revision) {
+  const version = Number(revision.version) + 1;
+  if (!Number.isInteger(version) || version < 2) {
+    throw new Error("Prototype revision version is invalid for a successor draft.");
+  }
+  return {
+    artifact_id: `PROTOTYPE-REVISION-${String(version).padStart(4, "0")}`,
+    version,
+  };
+}
+
+function requireTransitionIdempotencyKey(value) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error("Component Candidate transition requires a non-empty idempotency key.");
+  }
+}
+
+function buildComponentCandidateTransition(root, input) {
+  const { target, candidate, terminalId, revision } = transitionCandidateTarget(root, input);
+  const successor = nextPrototypeRevisionIdentity(revision);
+  const successorRoot = path.join(path.dirname(path.dirname(target.revisionFile)), successor.artifact_id);
+  const successorRevisionFile = path.join(successorRoot, "prototype-revision.yaml");
+  if (fs.existsSync(successorRoot)) {
+    throw new Error(`Successor Prototype draft already exists: ${successor.artifact_id}`);
+  }
+
+  const contents = bundleFileContents(target.contentRoot);
+  const componentCatalog = csvCatalog(contents, revision, "components");
+  const candidateCatalog = csvCatalog(contents, revision, "component_candidates");
+  const bindingCatalog = csvCatalog(contents, revision, "component_bindings");
+  const implementationCatalog = csvCatalog(contents, revision, "implementation_bindings");
+  const candidateRow = candidateCatalog.rows.find((item) => item.component_id === candidate.component_id);
+  if (!candidateRow) throw new Error(`Component Candidate catalog entry is missing: ${candidate.component_id}`);
+  candidateRow.lifecycle = input.target_lifecycle;
+  contents.set(
+    candidateCatalog.entry.ref,
+    Buffer.from(serializePrototypeCatalogCsv(candidateCatalog.headers, candidateCatalog.rows)),
+  );
+
+  const requiredBindingStatus = COMPONENT_CANDIDATE_BINDING_STATUS[input.target_lifecycle];
+  const affectedBindings = bindingCatalog.rows.filter((binding) => binding.component_id === candidate.component_id);
+  for (const binding of affectedBindings) binding.status = requiredBindingStatus;
+  if (affectedBindings.length) {
+    contents.set(
+      bindingCatalog.entry.ref,
+      Buffer.from(serializePrototypeCatalogCsv(bindingCatalog.headers, bindingCatalog.rows)),
+    );
+  }
+
+  const retainedComponents = input.target_lifecycle === "registered"
+    ? componentCatalog.rows
+    : componentCatalog.rows.filter((component) => component.component_id !== candidate.component_id);
+  const removedComponentRegistrations = componentCatalog.rows.length - retainedComponents.length;
+  if (removedComponentRegistrations) {
+    contents.set(
+      componentCatalog.entry.ref,
+      Buffer.from(serializePrototypeCatalogCsv(componentCatalog.headers, retainedComponents)),
+    );
+  }
+
+  const retainedImplementationBindings = input.target_lifecycle === "registered"
+    ? implementationCatalog.rows
+    : implementationCatalog.rows.filter((binding) => binding.component_id !== candidate.component_id);
+  const removedImplementationMappings = implementationCatalog.rows.length - retainedImplementationBindings.length;
+  if (removedImplementationMappings) {
+    contents.set(
+      implementationCatalog.entry.ref,
+      Buffer.from(serializePrototypeCatalogCsv(implementationCatalog.headers, retainedImplementationBindings)),
+    );
+  }
+
+  const draftRevision = structuredClone(revision);
+  draftRevision.artifact_id = successor.artifact_id;
+  draftRevision.version = successor.version;
+  draftRevision.status = "draft";
+  draftRevision.frozen_at = null;
+  draftRevision.previous_revision = {
+    ref: path.relative(successorRoot, target.revisionFile).replaceAll("\\", "/"),
+    algorithm: "sha256",
+    checksum: target.targetChecksum,
+  };
+  for (const [name, entry] of Object.entries(draftRevision.catalogs || {})) {
+    const bytes = contents.get(entry.ref);
+    if (!bytes) throw new Error(`Successor Prototype ${name} catalog is missing.`);
+    entry.checksum = digest(bytes);
+  }
+  draftRevision.review_bundle.checksum = bundleDigest(contents);
+  const revisionContent = yaml.stringify(draftRevision);
+  const successorChecksum = digest(revisionContent);
+  const successorRevisionRef = path.relative(target.experienceRoot, successorRevisionFile).replaceAll("\\", "/");
+  const catalogChanges = [
+    {
+      catalog: "component_candidates",
+      operation: "lifecycle-transition",
+      affected_count: 1,
+      from_lifecycle: candidate.lifecycle,
+      to_lifecycle: input.target_lifecycle,
+    },
+    {
+      catalog: "component_bindings",
+      operation: "binding-status-update",
+      affected_count: affectedBindings.length,
+      status: requiredBindingStatus,
+    },
+    {
+      catalog: "components",
+      operation: "remove-superseded-registration",
+      affected_count: removedComponentRegistrations,
+    },
+    {
+      catalog: "implementation_bindings",
+      operation: "remove-ineligible-mappings",
+      affected_count: removedImplementationMappings,
+    },
+  ];
+  const planBase = {
+    schema_version: COMPONENT_CANDIDATE_TRANSITION_SCHEMA_VERSION,
+    action: "prototype-component-candidate-transition-plan",
+    outcome: "planned",
+    prototype_revision: {
+      revision_ref: target.revisionRelative,
+      artifact_id: target.targetId,
+      checksum: target.targetChecksum,
+      version: revision.version,
+    },
+    component_candidate: {
+      component_id: candidate.component_id,
+      terminal_id: terminalId,
+      source_page_id: candidate.source_page_id,
+      source_scene_ids: candidate.source_scene_ids,
+      data_contract_id: candidate.data_contract_id,
+      from_lifecycle: candidate.lifecycle,
+      to_lifecycle: input.target_lifecycle,
+    },
+    successor_revision: {
+      artifact_id: successor.artifact_id,
+      revision_ref: successorRevisionRef,
+      checksum: successorChecksum,
+      version: successor.version,
+      status: "draft",
+      previous_revision: draftRevision.previous_revision,
+    },
+    catalog_changes: catalogChanges,
+    affected_identities: [
+      target.targetId,
+      candidate.component_id,
+      ...affectedBindings.map((binding) => `${binding.page_id}:${binding.scene_ids}`),
+    ],
+  };
+  const plan = { ...planBase, plan_checksum: digest(JSON.stringify(planBase)) };
+  const writes = new Map();
+  const successorBundleRoot = path.join(
+    successorRoot,
+    ...String(draftRevision.review_bundle.ref).split("/"),
+  );
+  for (const [relative, content] of contents) {
+    writes.set(path.join(successorBundleRoot, ...relative.split("/")), content);
+  }
+  writes.set(successorRevisionFile, revisionContent);
+  return {
+    plan,
+    writes: [...writes].map(([file, content]) => ({ file, content })),
+  };
+}
+
+export function planWorkflowManagerComponentCandidateTransition(projectRoot, input = {}) {
+  const root = path.resolve(projectRoot);
+  requireHuman(input.actor);
+  requireTransitionIdempotencyKey(input.idempotency_key);
+  return buildComponentCandidateTransition(root, input).plan;
+}
+
+export function applyWorkflowManagerComponentCandidateTransition(projectRoot, input = {}, options = {}) {
+  const root = path.resolve(projectRoot);
+  requireHuman(input.actor);
+  requireTransitionIdempotencyKey(input.idempotency_key);
+  const guarded = guardedPrototypeWrite(
+    root,
+    "prototype-component-candidate-transition-apply",
+    input,
+    input.component_id,
+    () => {
+      const prepared = buildComponentCandidateTransition(root, input);
+      if (input.expected_plan_checksum !== prepared.plan.plan_checksum) {
+        throw new Error("Component Candidate transition plan checksum is stale.");
+      }
+      const result = {
+        schema_version: COMPONENT_CANDIDATE_TRANSITION_SCHEMA_VERSION,
+        component_id: input.component_id,
+        terminal_id: input.terminal_id,
+        from_lifecycle: input.expected_lifecycle,
+        to_lifecycle: input.target_lifecycle,
+        input_revision: prepared.plan.prototype_revision,
+        successor_revision: prepared.plan.successor_revision,
+        catalog_changes: prepared.plan.catalog_changes,
+        affected_identities: prepared.plan.affected_identities,
+        plan_checksum: prepared.plan.plan_checksum,
+      };
+      const recorded = commitAction(
+        root,
+        "prototype-component-candidate-transition-apply",
+        input,
+        input.component_id,
+        result,
+        prepared.writes,
+        new Date().toISOString(),
+        options,
+      );
+      return { outcome: "applied", ...result, receipt: recorded.receipt, event: recorded.event };
+    },
+  );
+  if (guarded.replay) {
+    return { outcome: "idempotent-replay", ...guarded.replay.result, receipt: guarded.replay };
+  }
+  return guarded.value;
+}
+
+function assertStoredPrototypeRequestTerminal(root, request) {
+  return targetForPrototypeRequest(root, {
+    prototype_revision_id: request.prototype_revision_id,
+    prototype_revision_checksum: request.prototype_revision_checksum,
+    terminal_id: request.terminal_id,
+    page_id: request.page_id,
+    page_checksum: request.page_checksum,
+    review_scene_id: request.review_scene_id,
+  });
+}
+
+function currentRequests(root) {
+  return files(root, REQUEST_ROOT)
+    .map((file) => readJson(file, "Prototype Change Request"))
+    .filter((request) => request.status !== "discarded");
+}
+
+function batches(root) {
+  return files(root, BATCH_ROOT).map((file) => readJson(file, "Prototype Review Batch"));
+}
+
+function tombstones(root) {
+  return files(root, TOMBSTONE_ROOT).map((file) => readJson(file, "Prototype Change Request tombstone"));
+}
+
+function visualStandardReviewFile(root, reviewId) {
+  if (!SAFE_ID.test(String(reviewId || ""))) throw new Error("Visual Standard review identity is invalid");
+  return contained(root, `${VISUAL_STANDARD_REVIEW_ROOT}/${reviewId}.json`, "Visual Standard review path");
+}
+
+function visualStandardReviews(root) {
+  return files(root, VISUAL_STANDARD_REVIEW_ROOT)
+    .map((file) => readJson(file, "Visual Standard review"))
+    .sort((left, right) => String(left.created_at || "").localeCompare(String(right.created_at || "")));
+}
+
+const REVISION_HISTORY_COLLECTIONS = [
+  ["terminals", "terminal_id"],
+  ["pages", "page_id"],
+  ["review_scenes", "review_scene_id"],
+  ["trigger_conditions", "trigger_condition_id"],
+  ["routes", "route_id"],
+  ["ui_mapping", "ui_mapping_id"],
+  ["review_units", "review_unit_id"],
+  ["review_unit_pages", (row) => [row.review_unit_id, row.page_id].join(":")],
+  ["component_bindings", (row) => [
+    row.page_id,
+    row.scene_ids,
+    row.component_id,
+    row.variant,
+    row.data_contract_id,
+  ].join(":")],
+  ["component_candidates", "component_id"],
+  ["components", "component_id"],
+  ["data_contracts", "data_contract_id"],
+  ["implementation_bindings", "component_id"],
+  ["source_inspection_snapshots", "source_snapshot_id"],
+];
+
+function containedFrom(root, relative, label) {
+  if (typeof relative !== "string" || !relative || relative.includes("\0") || relative.includes("\\")
+      || path.posix.isAbsolute(relative) || path.posix.normalize(relative) !== relative) {
+    throw new Error(`${label} must be a normalized relative POSIX path`);
+  }
+  const result = path.resolve(root, ...relative.split("/"));
+  if (!inside(root, result)) throw new Error(`${label} escapes its declared root`);
+  return result;
+}
+
+function containedWithoutSymlinks(root, relative, label) {
+  const result = containedFrom(root, relative, label);
+  const resolvedRoot = path.resolve(root);
+  if (!fs.existsSync(resolvedRoot) || !fs.lstatSync(resolvedRoot).isDirectory()
+      || fs.lstatSync(resolvedRoot).isSymbolicLink()) {
+    throw new Error(`${label} root is missing or unsafe.`);
+  }
+  const segments = path.relative(resolvedRoot, result).split(path.sep).filter(Boolean);
+  let current = resolvedRoot;
+  for (const segment of segments) {
+    current = path.join(current, segment);
+    if (!fs.existsSync(current)) throw new Error(`${label} is missing.`);
+    if (fs.lstatSync(current).isSymbolicLink()) {
+      throw new Error(`${label} must not traverse symbolic links.`);
+    }
+  }
+  const realRoot = fs.realpathSync(resolvedRoot);
+  const realResult = fs.realpathSync(result);
+  if (!inside(realRoot, realResult)) throw new Error(`${label} escapes its declared root through a symbolic link.`);
+  return result;
+}
+
+function canonicalDigest(value) {
+  const normalize = (item) => {
+    if (Array.isArray(item)) return item.map(normalize);
+    if (!item || typeof item !== "object") return item;
+    return Object.fromEntries(Object.keys(item).sort().map((key) => [key, normalize(item[key])]));
+  };
+  return digest(JSON.stringify(normalize(value)));
+}
+
+function historyBundleRoot(revisionFile, revision) {
+  const bundleRoot = containedWithoutSymlinks(
+    path.dirname(revisionFile),
+    revision.review_bundle?.ref,
+    "Prototype revision history bundle",
+  );
+  if (!fs.statSync(bundleRoot).isDirectory()) throw new Error("Prototype revision history bundle is missing or unsafe.");
+  const referencedFiles = [
+    [revision.review_shell?.entrypoint_in_bundle, "Review Shell entrypoint"],
+    [revision.visual_standard?.ref, "Visual Standard evidence"],
+    [revision.review_evidence?.ref, "Prototype review evidence"],
+    ...Object.entries(revision.catalogs || {}).map(([name, entry]) => [
+      entry?.ref,
+      `Prototype revision history ${name} catalog`,
+    ]),
+  ];
+  for (const [relative, label] of referencedFiles) containedWithoutSymlinks(bundleRoot, relative, label);
+  return bundleRoot;
+}
+
+function historyCatalogRows(projectRoot, experience, experienceRoot, revisionFile, revision) {
+  const revisionRelative = path.relative(experienceRoot, revisionFile).replaceAll("\\", "/");
+  historyBundleRoot(revisionFile, revision);
+  validatePrototypeRevision(projectRoot, { experience, revision: revisionRelative });
+  const bundleRoot = historyBundleRoot(revisionFile, revision);
+  const rows = {};
+  for (const [name, expectedHeader] of Object.entries(prototypeRevisionCatalogContracts)) {
+    const entry = revision.catalogs[name];
+    if (entry?.algorithm !== "sha256" || !SHA256.test(String(entry.checksum || ""))) {
+      throw new Error(`Prototype revision history ${name} catalog checksum is invalid.`);
+    }
+    const file = containedWithoutSymlinks(bundleRoot, entry.ref, `Prototype revision history ${name} catalog`);
+    if (!fs.statSync(file).isFile()) {
+      throw new Error(`Prototype revision history ${name} catalog is missing or unsafe.`);
+    }
+    const bytes = fs.readFileSync(file);
+    if (digest(bytes) !== entry.checksum) {
+      throw new Error(`Prototype revision history ${name} catalog checksum mismatch.`);
+    }
+    const parsed = parsePrototypeCatalogCsv(bytes.toString("utf8"), `Prototype revision history ${name} catalog`);
+    if (parsed.header !== expectedHeader) {
+      throw new Error(`Prototype revision history ${name} catalog header is invalid.`);
+    }
+    rows[name] = parsed.rows;
+  }
+  return { revision, rows };
+}
+
+function historyRecordMap(rows, collection, identity) {
+  const mapped = new Map();
+  for (const row of rows) {
+    const key = typeof identity === "function" ? identity(row) : row[identity];
+    if (!String(key || "").trim() || mapped.has(key)) {
+      throw new Error(`Prototype revision history ${collection} identity is invalid.`);
+    }
+    mapped.set(key, canonicalDigest(row));
+  }
+  return mapped;
+}
+
+function terminalHistoryFacts(rows, terminalId) {
+  const terminals = rows.terminals.filter((terminal) => terminal.lifecycle_status === "active"
+    && (terminalId === "all" || terminal.terminal_id === terminalId));
+  if (terminalId !== "all" && !terminals.length) return null;
+  const terminalIds = new Set(terminals.map((terminal) => terminal.terminal_id));
+  const pages = rows.pages.filter((row) => terminalIds.has(row.terminal_id));
+  const pageIds = new Set(pages.map((page) => page.page_id));
+  const reviewScenes = rows.review_scenes.filter((row) => terminalIds.has(row.terminal_id));
+  const reviewSceneIds = new Set(reviewScenes.map((scene) => scene.review_scene_id));
+  const triggerConditionIds = new Set(reviewScenes.map((scene) => scene.trigger_condition_id));
+  const reviewUnitPages = rows.review_unit_pages.filter((row) => pageIds.has(row.page_id));
+  const reviewUnitIds = new Set(reviewUnitPages.map((row) => row.review_unit_id));
+  const reviewUnits = rows.review_units.filter((row) => reviewUnitIds.has(row.review_unit_id)
+    || (row.unit_kind === "page" && pageIds.has(row.target_id))
+    || (row.unit_kind === "review-scene" && reviewSceneIds.has(row.target_id)));
+  for (const row of reviewUnits) reviewUnitIds.add(row.review_unit_id);
+  const pageById = new Map(rows.pages.map((page) => [page.page_id, page]));
+  const componentBindings = rows.component_bindings.filter((row) => terminalIds.has(row.terminal_id));
+  const componentIds = new Set(componentBindings.map((row) => row.component_id));
+  const dataContractIds = new Set(componentBindings.map((row) => row.data_contract_id));
+  const componentCandidates = rows.component_candidates.filter((row) => {
+    const sourcePage = pageById.get(row.source_page_id);
+    if (!sourcePage || !terminalIds.has(sourcePage.terminal_id)) return false;
+    componentIds.add(row.component_id);
+    dataContractIds.add(row.data_contract_id);
+    return true;
+  });
+  const collectionRows = {
+    terminals,
+    pages,
+    review_scenes: reviewScenes,
+    trigger_conditions: rows.trigger_conditions.filter((row) => triggerConditionIds.has(row.trigger_condition_id)),
+    routes: rows.routes.filter((row) => terminalIds.has(row.terminal_id)),
+    ui_mapping: rows.ui_mapping.filter((row) => terminalIds.has(row.terminal_id)),
+    review_units: reviewUnits,
+    review_unit_pages: reviewUnitPages.filter((row) => reviewUnitIds.has(row.review_unit_id)),
+    component_bindings: componentBindings,
+    component_candidates: componentCandidates,
+    components: rows.components.filter((row) => componentIds.has(row.component_id)),
+    data_contracts: rows.data_contracts.filter((row) => dataContractIds.has(row.data_contract_id)),
+    implementation_bindings: rows.implementation_bindings.filter((row) => componentIds.has(row.component_id)),
+    source_inspection_snapshots: rows.source_inspection_snapshots.filter((row) => terminalIds.has(row.terminal_id)),
+  };
+  const collections = Object.fromEntries(REVISION_HISTORY_COLLECTIONS.map(([name, identity]) => [
+    name,
+    historyRecordMap(collectionRows[name], name, identity),
+  ]));
+  return {
+    terminal_ids: [...terminalIds].sort(),
+    collections,
+    catalog_summary: Object.fromEntries(Object.entries(collections).map(([name, value]) => [name, value.size])),
+  };
+}
+
+function unavailableRevisionHistoryEntry(metadata, descriptor, error) {
+  return {
+    ...metadata,
+    history_sort_version: Number.isInteger(descriptor?.version) ? descriptor.version : Number.MAX_SAFE_INTEGER,
+    inspection_status: "unavailable",
+    prototype_revision_id: null,
+    declared_prototype_revision_id: typeof descriptor?.artifact_id === "string" ? descriptor.artifact_id : null,
+    revision_status: "unavailable",
+    version: null,
+    iteration_id: null,
+    frozen_at: null,
+    inspection_error: {
+      code: "prototype-revision-invalid",
+      message: error.message,
+    },
+    terminal_facts: new Map(),
+  };
+}
+
+function readRevisionHistoryEntry(projectRoot, experience, experienceRoot, revisionFile) {
+  let metadata = {
+    path: path.relative(experienceRoot, revisionFile).replaceAll("\\", "/"),
+    checksum: null,
+    modified_at: null,
+  };
+  let descriptor = null;
+  try {
+    const bytes = fs.readFileSync(revisionFile);
+    metadata = {
+      ...metadata,
+      checksum: digest(bytes),
+      modified_at: fs.statSync(revisionFile).mtime.toISOString(),
+    };
+    descriptor = readPrototypeRevisionDescriptor(revisionFile);
+    if (descriptor.status === "draft") return null;
+    if (descriptor.status !== "frozen") throw new Error("Prototype revision history descriptor is not frozen.");
+    const { revision, rows } = historyCatalogRows(projectRoot, experience, experienceRoot, revisionFile, descriptor);
+    return {
+      ...metadata,
+      history_sort_version: revision.version,
+      inspection_status: "available",
+      prototype_revision_id: revision.artifact_id,
+      declared_prototype_revision_id: revision.artifact_id,
+      revision_status: revision.status || "unknown",
+      version: revision.version,
+      iteration_id: revision.iteration_id || null,
+      frozen_at: revision.frozen_at || null,
+      terminal_facts: new Map([
+        ["all", terminalHistoryFacts(rows, "all")],
+        ...rows.terminals.filter((terminal) => terminal.lifecycle_status === "active")
+          .map((terminal) => [terminal.terminal_id, terminalHistoryFacts(rows, terminal.terminal_id)]),
+      ]),
+    };
+  } catch (error) {
+    return unavailableRevisionHistoryEntry(metadata, descriptor, error);
+  }
+}
+
+function revisionHistory(projectRoot, experienceRoot, experience) {
+  const revisionsRoot = path.join(experienceRoot, "prototype", "revisions");
+  if (!fs.existsSync(revisionsRoot)) return [];
+  if (!fs.lstatSync(revisionsRoot).isDirectory() || fs.lstatSync(revisionsRoot).isSymbolicLink()) {
+    throw new Error("Prototype revision history root is missing or unsafe.");
+  }
+  const result = [];
+  const visit = (current) => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const absolute = path.join(current, entry.name);
+      if (entry.isSymbolicLink()) {
+        if (entry.name === "prototype-revision.yaml") {
+          throw new Error("Prototype revision history descriptor must not be a symbolic link");
+        }
+        continue;
+      }
+      if (entry.isDirectory()) visit(absolute);
+      else if (entry.isFile() && entry.name === "prototype-revision.yaml") {
+        const historyEntry = readRevisionHistoryEntry(projectRoot, experience, experienceRoot, absolute);
+        if (historyEntry) result.push(historyEntry);
+      }
+    }
+  };
+  visit(revisionsRoot);
+  return result
+    .sort((left, right) => left.history_sort_version - right.history_sort_version || left.path.localeCompare(right.path))
+    .map(({ history_sort_version, ...entry }) => entry);
+}
+
+function revisionDiff(previous, current) {
+  const collections = Object.fromEntries(REVISION_HISTORY_COLLECTIONS.map(([name]) => {
+    const before = previous?.collections[name] || new Map();
+    const after = current.collections[name];
+    let added = 0;
+    let removed = 0;
+    let changed = 0;
+    for (const [identity, checksum] of after) {
+      if (!before.has(identity)) added += 1;
+      else if (before.get(identity) !== checksum) changed += 1;
+    }
+    for (const identity of before.keys()) {
+      if (!after.has(identity)) removed += 1;
+    }
+    return [name, { added, removed, changed }];
+  }));
+  return {
+    compared_to_revision_id: previous?.prototype_revision_id || null,
+    status: previous ? "compared" : "baseline",
+    changed_facts: Object.values(collections)
+      .reduce((total, collection) => total + collection.added + collection.removed + collection.changed, 0),
+    collections,
+  };
+}
+
+function scopedRevisionHistory(history, terminalId) {
+  const scoped = history.filter((entry) => entry.inspection_status === "unavailable" || entry.terminal_facts.has(terminalId));
+  let previousFacts = null;
+  let previousRevisionId = null;
+  let historyGap = false;
+  return scoped.map((entry) => {
+    if (entry.inspection_status === "unavailable") {
+      previousFacts = null;
+      previousRevisionId = null;
+      historyGap = true;
+      return {
+        path: entry.path,
+        checksum: entry.checksum,
+        modified_at: entry.modified_at,
+        inspection_status: entry.inspection_status,
+        prototype_revision_id: null,
+        declared_prototype_revision_id: entry.declared_prototype_revision_id,
+        revision_status: entry.revision_status,
+        version: null,
+        iteration_id: null,
+        frozen_at: null,
+        terminal_id: terminalId,
+        catalog_summary: null,
+        inspection_error: entry.inspection_error,
+        revision_diff: {
+          compared_to_revision_id: null,
+          status: "unavailable",
+          changed_facts: null,
+          collections: {},
+        },
+      };
+    }
+    const facts = entry.terminal_facts.get(terminalId);
+    const revisionDiffResult = historyGap
+      ? {
+        compared_to_revision_id: null,
+        status: "history-gap",
+        changed_facts: null,
+        collections: {},
+      }
+      : revisionDiff(
+        previousFacts ? { ...previousFacts, prototype_revision_id: previousRevisionId } : null,
+        facts,
+      );
+    const result = {
+      path: entry.path,
+      checksum: entry.checksum,
+      modified_at: entry.modified_at,
+      inspection_status: entry.inspection_status,
+      prototype_revision_id: entry.prototype_revision_id,
+      declared_prototype_revision_id: entry.declared_prototype_revision_id,
+      revision_status: entry.revision_status,
+      version: entry.version,
+      iteration_id: entry.iteration_id,
+      frozen_at: entry.frozen_at,
+      terminal_id: terminalId,
+      catalog_summary: facts.catalog_summary,
+      inspection_error: null,
+      revision_diff: revisionDiffResult,
+    };
+    previousFacts = facts;
+    previousRevisionId = entry.prototype_revision_id;
+    historyGap = false;
+    return result;
+  });
+}
+
+function emptyPrototypeProjection(root, experienceRoot, experience) {
+  return {
+    schema_version: WORKFLOW_MANAGER_PROTOTYPES_SCHEMA_VERSION,
+    registration_status: "not-registered",
+    prototype_revision_id: null,
+    prototype_revision_checksum: null,
+    catalog_schema_version: null,
+    terminals: [],
+    catalog_summary: {},
+    visual_standard: null,
+    component_governance: null,
+    pages: [],
+    review_scenes: [],
+    routes: [],
+    source_inspection_snapshots: [],
+    change_requests: currentRequests(root),
+    review_batches: batches(root),
+    discarded_tombstones: tombstones(root),
+    visual_standard_reviews: visualStandardReviews(root),
+    revision_history: fs.existsSync(experienceRoot) ? revisionHistory(root, experienceRoot, experience) : [],
+    terminal_scope: { terminal_id: "all", mode: "all" },
+  };
+}
+
+function requestedTerminalId(options) {
+  const terminalId = options.terminal_id ?? options.terminalId ?? "all";
+  if (terminalId === "all") return terminalId;
+  if (typeof terminalId !== "string" || !SAFE_ID.test(terminalId)) {
+    throw new PrototypeTerminalScopeError("Logical Terminal identity is invalid.");
+  }
+  return terminalId;
+}
+
+function assertExpectedPrototypeRevisionChecksum(target, options) {
+  const expected = options.expected_checksum ?? options.expectedChecksum;
+  if (expected === undefined || expected === null || expected === "") return;
+  if (!SHA256.test(String(expected))) throw new Error("Prototype revision checksum is invalid.");
+  if (target.targetChecksum !== expected) throw new Error("Prototype revision checksum mismatch.");
+}
+
+function componentGovernanceForTerminal(governance, terminalId) {
+  if (!governance) return null;
+  const componentBindings = governance.component_bindings.filter((binding) =>
+    terminalId === "all" || binding.terminal_id === terminalId);
+  const componentCandidates = (governance.component_candidates || []).filter((candidate) =>
+    terminalId === "all"
+      || candidate.source_terminal_id === terminalId
+      || candidate.terminal_ids?.includes(terminalId));
+  const componentIds = new Set(componentBindings.map((binding) => binding.component_id));
+  const candidateIds = new Set(componentCandidates.map((candidate) => candidate.component_id));
+  const dataContractIds = new Set([
+    ...componentBindings.map((binding) => binding.data_contract_id),
+    ...componentCandidates.map((candidate) => candidate.data_contract_id),
+  ]);
+  const components = governance.components
+    .filter((component) => terminalId === "all" || componentIds.has(component.component_id))
+    .map((component) => {
+      const bindings = componentBindings.filter((binding) => binding.component_id === component.component_id);
+      return {
+        ...component,
+        binding_count: bindings.length,
+        terminal_ids: [...new Set(bindings.map((binding) => binding.terminal_id))].sort(),
+      };
+    });
+  const dataContracts = governance.data_contracts
+    .filter((contract) => terminalId === "all" || dataContractIds.has(contract.data_contract_id))
+    .map((contract) => {
+      const bindings = componentBindings.filter((binding) => binding.data_contract_id === contract.data_contract_id);
+      return {
+        ...contract,
+        binding_count: bindings.length,
+        terminal_ids: [...new Set(bindings.map((binding) => binding.terminal_id))].sort(),
+      };
+    });
+  const implementationBindings = governance.implementation_bindings.filter((binding) =>
+    terminalId === "all" || componentIds.has(binding.component_id) || candidateIds.has(binding.component_id));
+  const counts = {
+    "component-registrations": components.length,
+    "component-candidates": componentCandidates.length,
+    "data-contracts": dataContracts.length,
+    "component-bindings": componentBindings.length,
+    "implementation-mappings": implementationBindings.length,
+  };
+  return {
+    ...governance,
+    terminal_scope: { terminal_id: terminalId },
+    components,
+    component_candidates: componentCandidates,
+    data_contracts: dataContracts,
+    component_bindings: componentBindings,
+    implementation_bindings: implementationBindings,
+    validation: {
+      ...governance.validation,
+      checks: governance.validation.checks.map((check) => ({
+        ...check,
+        count: counts[check.check_id] ?? check.count,
+      })),
+    },
+  };
+}
+
+function visualStandardReviewsForTerminal(reviews, terminalId) {
+  if (terminalId === "all") return reviews;
+  return reviews.filter((review) => review.terminal_id === "all" || review.terminal_id === terminalId);
+}
+
+function withTerminalScope(projection, options) {
+  const terminalId = requestedTerminalId(options);
+  if (terminalId === "all") {
+    return {
+      ...projection,
+      revision_history: scopedRevisionHistory(projection.revision_history || [], terminalId),
+      component_governance: componentGovernanceForTerminal(projection.component_governance, terminalId),
+      visual_standard_reviews: visualStandardReviewsForTerminal(projection.visual_standard_reviews || [], terminalId),
+      terminal_scope: { terminal_id: "all", mode: "all" },
+    };
+  }
+  const terminal = projection.terminals.find((item) => item.terminal_id === terminalId);
+  if (!terminal) {
+    throw new PrototypeTerminalScopeError(`Logical Terminal is not registered: ${terminalId}`);
+  }
+  const pages = projection.pages.filter((page) => page.terminal_id === terminalId);
+  const reviewScenes = projection.review_scenes.filter((scene) => scene.terminal_id === terminalId);
+  const routes = projection.routes.filter((route) => route.terminal_id === terminalId);
+  const sourceInspectionSnapshots = (projection.source_inspection_snapshots || [])
+    .filter((snapshot) => snapshot.terminal_id === terminalId);
+  const changeRequests = projection.change_requests.filter((request) => request.terminal_id === terminalId);
+  const reviewBatches = projection.review_batches.filter((batch) => batch.terminal_id === terminalId);
+  const discardedTombstones = projection.discarded_tombstones.filter((tombstone) => tombstone.terminal_id === terminalId);
+  return {
+    ...projection,
+    pages,
+    review_scenes: reviewScenes,
+    routes,
+    source_inspection_snapshots: sourceInspectionSnapshots,
+    change_requests: changeRequests,
+    review_batches: reviewBatches,
+    discarded_tombstones: discardedTombstones,
+    revision_history: scopedRevisionHistory(projection.revision_history || [], terminalId),
+    component_governance: componentGovernanceForTerminal(projection.component_governance, terminalId),
+    visual_standard_reviews: visualStandardReviewsForTerminal(projection.visual_standard_reviews || [], terminalId),
+    terminal_scope: {
+      terminal_id: terminalId,
+      terminal_name: terminal.terminal_name,
+      mode: "single-terminal",
+    },
+  };
+}
+
+export function inspectWorkflowManagerPrototypes(projectRoot, options = {}) {
+  const root = path.resolve(projectRoot);
+  const experience = String(options.experience || ".workflow/experience");
+  const experienceRoot = contained(root, experience, "Experience directory");
+  if (!fs.existsSync(experienceRoot)) return withTerminalScope(emptyPrototypeProjection(root, experienceRoot, experience), options);
+  const registrationFiles = [
+    "visual-system-confirmation.yaml",
+    "visual-reference-manifest.yaml",
+    "prototype.yaml",
+  ].map((name) => path.join(experienceRoot, name));
+  if (registrationFiles.every((file) => !fs.existsSync(file))) {
+    return withTerminalScope(emptyPrototypeProjection(root, experienceRoot, experience), options);
+  }
+  const target = buildPrototypeReviewTarget(root, { experience, revision: options.revision, now: options.now });
+  if (target.mode !== "prototype-revision") return withTerminalScope({
+    schema_version: WORKFLOW_MANAGER_PROTOTYPES_SCHEMA_VERSION,
+    registration_status: "visual-standard-pending",
+    visual_reference: { target_id: target.targetId, checksum: target.targetChecksum, path: target.visualReferencePath },
+    prototype_revision_id: null, prototype_revision_checksum: null,
+    catalog_schema_version: null, terminals: [], catalog_summary: {},
+    visual_standard: null, component_governance: null,
+    pages: [], review_scenes: [], routes: [], change_requests: currentRequests(root), review_batches: batches(root),
+    source_inspection_snapshots: [],
+    discarded_tombstones: tombstones(root), visual_standard_reviews: visualStandardReviews(root), revision_history: revisionHistory(root, experienceRoot, experience),
+  }, options);
+  assertExpectedPrototypeRevisionChecksum(target, options);
+  return withTerminalScope({
+    schema_version: WORKFLOW_MANAGER_PROTOTYPES_SCHEMA_VERSION,
+    registration_status: "registered",
+    prototype_id: target.prototypeId,
+    prototype_revision_id: target.targetId,
+    prototype_revision_checksum: target.targetChecksum,
+    catalog_schema_version: target.catalogSchemaVersion,
+    iteration_id: target.iterationId,
+    revision_ref: target.revisionRelative,
+    review_entrypoint: target.reviewEntrypoint,
+    terminals: target.terminals,
+    catalog_summary: target.catalogSummary,
+    visual_standard: target.visualStandard,
+    component_governance: target.componentGovernance,
+    pages: target.pages,
+    review_scenes: target.reviewScenes,
+    routes: target.routeGraph,
+    source_inspection_snapshots: target.sourceInspectionSnapshots,
+    change_requests: currentRequests(root).filter((item) => item.prototype_revision_id === target.targetId),
+    review_batches: batches(root).filter((item) => item.prototype_revision_id === target.targetId),
+    discarded_tombstones: tombstones(root).filter((item) => item.prototype_revision_id === target.targetId),
+    visual_standard_reviews: visualStandardReviews(root)
+      .filter((item) => item.prototype_revision_id === target.targetId),
+    revision_history: revisionHistory(root, experienceRoot, experience),
+    mutability: "governed",
+  }, options);
+}
+
+function sourceSnapshotOption(options) {
+  return options.source_snapshot_id ?? options.sourceSnapshotId ?? null;
+}
+
+function sourceSnapshotListContext(target, terminalId) {
+  const terminal = terminalId === "all"
+    ? null
+    : target.terminals.find((item) => item.terminal_id === terminalId);
+  return {
+    terminal_scope: {
+      terminal_id: terminalId,
+      terminal_name: terminal?.terminal_name || undefined,
+      mode: terminalId === "all" ? "all" : "single-terminal",
+    },
+    prototype_revision_id: target.targetId,
+    prototype_revision_checksum: target.targetChecksum,
+    revision_ref: target.revisionRelative,
+    iteration_id: target.iterationId,
+  };
+}
+
+function sourceSnapshotMetadata(snapshot) {
+  return Object.fromEntries([
+    "source_snapshot_id", "asset_kind", "page_id", "review_scene_id", "terminal_id",
+    "source_ref", "checksum", "language", "scene_branch",
+  ].map((key) => [key, snapshot[key] ?? null]));
+}
+
+/**
+ * Read only the source assets explicitly registered by a Prototype Revision.
+ * The source_snapshot_id is the capability boundary; no arbitrary source path
+ * is accepted by this service.
+ */
+export function inspectWorkflowManagerPrototypeSourceSnapshots(projectRoot, options = {}) {
+  const root = path.resolve(projectRoot);
+  if (options.source_ref || options.sourceRef || options.sourcePath || options.relative) {
+    throw new PrototypeSourceSnapshotError(
+      "prototype-source-path-forbidden",
+      "Source Inspection Snapshot reads require a registered source_snapshot_id; arbitrary paths are not allowed.",
+    );
+  }
+  const requestedRevision = String(options.revision || "").trim();
+  const expectedChecksum = options.expected_checksum ?? options.expectedChecksum;
+  if (!requestedRevision || expectedChecksum === undefined || expectedChecksum === null || expectedChecksum === "") {
+    throw new PrototypeSourceSnapshotError(
+      "prototype-source-snapshot-unavailable",
+      "Source Inspection Snapshots require an exact revision and expected checksum.",
+    );
+  }
+  const experience = String(options.experience || ".workflow/experience");
+  const target = buildPrototypeReviewTarget(root, {
+    experience,
+    revision: requestedRevision,
+    now: options.now,
+  });
+  if (target.mode !== "prototype-revision") {
+    throw new PrototypeSourceSnapshotError(
+      "prototype-source-snapshot-unavailable",
+      "Source Inspection Snapshots require an exact Prototype revision.",
+    );
+  }
+  assertExpectedPrototypeRevisionChecksum(target, options);
+  const terminalId = requestedTerminalId(options);
+  if (terminalId !== "all" && !target.terminals.some((terminal) => terminal.terminal_id === terminalId)) {
+    throw new PrototypeTerminalScopeError(`Logical Terminal is not registered: ${terminalId}`);
+  }
+  const sourceSnapshotId = sourceSnapshotOption(options);
+  if (sourceSnapshotId && terminalId !== "all") {
+    const registered = (target.sourceInspectionSnapshots || [])
+      .find((item) => item.source_snapshot_id === sourceSnapshotId);
+    if (registered && registered.terminal_id !== terminalId) {
+      throw new PrototypeTerminalScopeError(
+        `Source Inspection Snapshot ${sourceSnapshotId} does not belong to Logical Terminal ${terminalId}.`,
+      );
+    }
+  }
+  const pages = target.pages.filter((page) => terminalId === "all" || page.terminal_id === terminalId);
+  const scenes = target.reviewScenes.filter((scene) => terminalId === "all" || scene.terminal_id === terminalId);
+  const requestedPage = options.page_id ?? options.pageId;
+  const requestedScene = options.review_scene_id ?? options.reviewSceneId;
+  const page = requestedPage ? pages.find((item) => item.page_id === requestedPage) : null;
+  if (requestedPage && !page) {
+    throw new PrototypeSourceSnapshotError("prototype-source-snapshot-invalid", `Page is not registered in the selected Logical Terminal: ${requestedPage}.`);
+  }
+  const scene = requestedScene ? scenes.find((item) => item.review_scene_id === requestedScene) : null;
+  if (requestedScene && !scene) {
+    throw new PrototypeSourceSnapshotError("prototype-source-snapshot-invalid", `Review Scene is not registered in the selected Logical Terminal: ${requestedScene}.`);
+  }
+  if (scene && page && scene.page_id !== page.page_id) {
+    throw new PrototypeSourceSnapshotError("prototype-source-snapshot-invalid", `Review Scene ${requestedScene} does not belong to Page ${requestedPage}.`);
+  }
+  const scopedPageId = requestedPage || scene?.page_id;
+  const snapshots = (target.sourceInspectionSnapshots || [])
+    .filter((snapshot) => terminalId === "all" || snapshot.terminal_id === terminalId)
+    .map(sourceSnapshotMetadata);
+  const scopedSnapshots = snapshots.filter((snapshot) => (!scopedPageId || snapshot.page_id === scopedPageId)
+    && (!requestedScene || !snapshot.review_scene_id || snapshot.review_scene_id === requestedScene));
+  if (!sourceSnapshotId) {
+    return {
+      schema_version: WORKFLOW_MANAGER_PROTOTYPE_SOURCE_SNAPSHOT_SCHEMA_VERSION,
+      ...sourceSnapshotListContext(target, terminalId),
+      source_inspection_snapshots: scopedSnapshots,
+      mutability: "read-only",
+    };
+  }
+  if (typeof sourceSnapshotId !== "string" || !SAFE_ID.test(sourceSnapshotId)) {
+    throw new PrototypeSourceSnapshotError(
+      "prototype-source-snapshot-invalid",
+      "Source Inspection Snapshot identity is invalid.",
+    );
+  }
+  const snapshot = scopedSnapshots.find((item) => item.source_snapshot_id === sourceSnapshotId);
+  if (!snapshot) {
+    const registered = (target.sourceInspectionSnapshots || [])
+      .find((item) => item.source_snapshot_id === sourceSnapshotId);
+    if (registered && terminalId !== "all" && registered.terminal_id !== terminalId) {
+      throw new PrototypeTerminalScopeError(
+        `Source Inspection Snapshot ${sourceSnapshotId} does not belong to Logical Terminal ${terminalId}.`,
+      );
+    }
+    throw new PrototypeSourceSnapshotError(
+      "prototype-source-snapshot-not-registered",
+      `Source Inspection Snapshot is not registered: ${sourceSnapshotId}`,
+    );
+  }
+  if (requestedPage && requestedPage !== snapshot.page_id) {
+    throw new PrototypeSourceSnapshotError(
+      "prototype-source-snapshot-invalid",
+      `Source Inspection Snapshot ${sourceSnapshotId} does not belong to Page ${requestedPage}.`,
+    );
+  }
+  if (requestedScene && snapshot.review_scene_id && requestedScene !== snapshot.review_scene_id) {
+    throw new PrototypeSourceSnapshotError(
+      "prototype-source-snapshot-invalid",
+      `Source Inspection Snapshot ${sourceSnapshotId} does not belong to Review Scene ${requestedScene}.`,
+    );
+  }
+  const sourceFile = containedWithoutSymlinks(
+    target.sourceRoot,
+    snapshot.source_ref,
+    `Source Inspection Snapshot ${sourceSnapshotId} source`,
+  );
+  if (!fs.statSync(sourceFile).isFile()) {
+    throw new PrototypeSourceSnapshotError(
+      "prototype-source-snapshot-invalid",
+      `Source Inspection Snapshot ${sourceSnapshotId} source is not a file.`,
+    );
+  }
+  const bytes = fs.readFileSync(sourceFile);
+  if (digest(bytes) !== snapshot.checksum) {
+    throw new PrototypeSourceSnapshotError(
+      "prototype-source-snapshot-checksum-mismatch",
+      `Source Inspection Snapshot ${sourceSnapshotId} checksum does not match its registered source.`,
+    );
+  }
+  return {
+    schema_version: WORKFLOW_MANAGER_PROTOTYPE_SOURCE_SNAPSHOT_SCHEMA_VERSION,
+    ...sourceSnapshotListContext(target, terminalId),
+    source_snapshot: {
+      ...snapshot,
+      read_only: true,
+      editable: false,
+      executable: false,
+      content: bytes.toString("utf8"),
+      content_encoding: "utf-8",
+      content_type: "text/plain",
+    },
+    mutability: "read-only",
+  };
+}
+
+export function inspectWorkflowManagerPrototypeSourceSnapshot(projectRoot, options = {}) {
+  const result = inspectWorkflowManagerPrototypeSourceSnapshots(projectRoot, options);
+  if (!result.source_snapshot) {
+    throw new PrototypeSourceSnapshotError(
+      "prototype-source-snapshot-required",
+      "source_snapshot_id is required when reading Source Inspection Snapshot content.",
+    );
+  }
+  return result;
+}
+
+export function resolveWorkflowManagerPrototypeContent(projectRoot, relative, options = {}) {
+  const root = path.resolve(projectRoot);
+  const target = buildPrototypeReviewTarget(root, {
+    experience: options.experience || ".workflow/experience",
+    revision: options.revision,
+  });
+  if (target.mode !== "prototype-revision") throw new Error("Prototype content requires an exact Prototype revision");
+  assertExpectedPrototypeRevisionChecksum(target, options);
+  const file = contained(target.contentRoot, relative, "Prototype content");
+  if (!fs.existsSync(file) || !fs.statSync(file).isFile()) throw new Error("Prototype content was not found");
+  return { file, target_id: target.targetId, target_checksum: target.targetChecksum };
+}
+
+export function applyWorkflowManagerPageReview(projectRoot, input = {}, options = {}) {
+  const root = path.resolve(projectRoot);
+  requireHuman(input.actor);
+  const guarded = guardedPrototypeWrite(
+    root,
+    "prototype-page-review-applied",
+    input,
+    input.page_id,
+    () => {
+      const target = buildPrototypeReviewTarget(root, {
+        experience: input.experience || ".workflow/experience",
+        revision: input.revision,
+      });
+      if (target.mode !== "prototype-revision") throw new Error("Page review requires an exact Prototype revision");
+      const { page } = resolveTerminalScopedReviewTarget(target, input);
+      const inspection = formalInspection(root);
+      if (approvedPrototypeGate(inspection, target.targetId, target.targetChecksum)) {
+        throw new Error("Prototype revision is already approved by UX-UI; create a fresh Prototype revision before further review changes");
+      }
+      const receipt = createPrototypePageReviewReceipt(target, page, input);
+      const write = prototypePageReviewReceiptWrite(root, receipt);
+      const completesRevision = receipt.decision === "approved"
+        && target.pages.every((item) => item.page_id === page.page_id || item.review_status === "approved");
+      const pendingUxUi = (inspection.workflow_state?.development_state?.pending_gates || [])
+        .find((gate) => gate?.gate_id === "UX-UI" && gate.iteration_id === target.iterationId);
+      let formal = null;
+      let recorded;
+      if (completesRevision && pendingUxUi) {
+        if (!Number.isInteger(input.expected_scope_revision) || input.expected_scope_revision < 0) {
+          throw new Error("Final Page approval requires expected_scope_revision for the UX-UI Gate");
+        }
+        const evidence = Array.isArray(input.evidence) && input.evidence.length
+          ? input.evidence
+          : pendingUxUi.evidence || [];
+        const args = [
+          "gate", "decide", "--project", root,
+          "--expected-scope-revision", String(input.expected_scope_revision),
+          "--gate-id", "UX-UI", "--decision", "approved",
+          "--actor", input.actor,
+          "--rationale", String(input.comment || input.rationale || "Prototype Page review completed").trim(),
+        ];
+        for (const item of evidence) args.push("--evidence", item);
+        const formalTransaction = prepareWorkflowManagerFormalTransaction(root, {
+          action: "prototype-page-review-applied",
+          subject: page.page_id,
+          input,
+          resultFactory: () => receipt,
+          detailFactory: () => ({
+            terminal_id: page.terminal_id,
+            result_revision: null,
+            result_receipt_id: receipt.receipt_id,
+            result_decision: receipt.decision,
+            affected_identities: [target.targetId, page.page_id, receipt.receipt_id, "UX-UI"],
+            delegated_writer: "delivery-state.gate-decide",
+          }),
+          receiptPrefix: "WMPR",
+          eventDetail: { terminal_id: page.terminal_id },
+        });
+        formal = executeDeliveryStateCommand(args, {
+          yaml,
+          ...(options.stateOptions || {}),
+          pageReviewReceiptWrite: write,
+          managerTransactionWriteFactory: formalTransaction.factory,
+        });
+        recorded = formalTransaction.result();
+      } else {
+        recorded = commitAction(
+          root,
+          "prototype-page-review-applied",
+          input,
+          page.page_id,
+          receipt,
+          [{ file: write.file, content: write.content }],
+          new Date().toISOString(),
+          options,
+        );
+      }
+      return {
+        outcome: "applied",
+        page_review_receipt: receipt,
+        receipt: recorded.receipt,
+        event: recorded.event,
+        ux_ui_gate: formal?.gate || null,
+        formal,
+      };
+    },
+  );
+  if (guarded.replay) {
+    return { outcome: "idempotent-replay", page_review_receipt: guarded.replay.result, receipt: guarded.replay };
+  }
+  return guarded.value;
+}
+
+export function applyWorkflowManagerVisualStandardReview(projectRoot, input = {}, options = {}) {
+  const root = path.resolve(projectRoot);
+  requireHuman(input.actor);
+  const guarded = guardedPrototypeWrite(
+    root,
+    "prototype-visual-standard-review-applied",
+    input,
+    input.prototype_revision_id,
+    () => {
+      const { target, terminalId } = targetForVisualStandardReview(root, input);
+      assertPrototypeRevisionWritable(root, target.targetId, target.targetChecksum);
+      if (!new Set(["approved", "changes-requested"]).has(input.decision)) {
+        throw new Error("Visual Standard review decision must be approved or changes-requested");
+      }
+      const comment = String(input.comment || "").trim();
+      if (input.decision === "changes-requested" && !comment) {
+        throw new Error("Visual Standard return requires a non-empty comment");
+      }
+      const timestamp = new Date().toISOString();
+      const review = {
+        schema_version: 1,
+        review_id: `VSR-${crypto.randomUUID()}`,
+        prototype_revision_id: target.targetId,
+        prototype_revision_checksum: target.targetChecksum,
+        visual_standard_ref: target.visualStandard.ref,
+        visual_standard_checksum: target.visualStandard.checksum,
+        terminal_id: terminalId,
+        decision: input.decision,
+        comment: comment || null,
+        actor: input.actor,
+        created_at: timestamp,
+      };
+      review.checksum = requestChecksum(review);
+      const recorded = commitAction(
+        root,
+        "prototype-visual-standard-review-applied",
+        input,
+        target.targetId,
+        review,
+        [{ file: visualStandardReviewFile(root, review.review_id), content: `${JSON.stringify(review, null, 2)}\n` }],
+        timestamp,
+        options,
+      );
+      return {
+        outcome: "applied",
+        visual_standard_review: review,
+        receipt: recorded.receipt,
+        event: recorded.event,
+      };
+    },
+  );
+  if (guarded.replay) {
+    return {
+      outcome: "idempotent-replay",
+      visual_standard_review: guarded.replay.result,
+      receipt: guarded.replay,
+    };
+  }
+  return guarded.value;
+}
+
+export function createPrototypeChangeRequest(projectRoot, input = {}, options = {}) {
+  const root = path.resolve(projectRoot);
+  requireHuman(input.actor);
+  const initialReplay = preflightAction(root, "prototype-change-request-created", input);
+  if (initialReplay) return { outcome: "idempotent-replay", change_request: initialReplay.result, receipt: initialReplay };
+  const release = withPrototypeWriteLock(root, "prototype-change-request-created");
+  try {
+    const replay = preflightAction(root, "prototype-change-request-created", input);
+    if (replay) return { outcome: "idempotent-replay", change_request: replay.result, receipt: replay };
+    if (!SAFE_ID.test(String(input.prototype_revision_id || "")) || !SAFE_ID.test(String(input.page_id || ""))) {
+      throw new Error("Prototype revision and Page identities are required");
+    }
+    if (!SHA256.test(String(input.prototype_revision_checksum || "")) || !SHA256.test(String(input.page_checksum || ""))) {
+      throw new Error("Prototype revision and Page checksums are required");
+    }
+    if (!String(input.body || "").trim()) throw new Error("Prototype Change Request body is required");
+    targetForPrototypeRequest(root, input);
+    assertPrototypeRevisionWritable(root, input.prototype_revision_id, input.prototype_revision_checksum);
+    const timestamp = new Date().toISOString();
+    const request = {
+      schema_version: 1,
+      change_request_id: `PCR-${crypto.randomUUID()}`,
+      prototype_revision_id: input.prototype_revision_id,
+      prototype_revision_checksum: input.prototype_revision_checksum,
+      terminal_id: input.terminal_id,
+      page_id: input.page_id,
+      page_checksum: input.page_checksum,
+      review_scene_id: input.review_scene_id || null,
+      revision: 1,
+      status: "draft",
+      body: String(input.body).trim(),
+      attachments: [],
+      actor: input.actor,
+      created_at: timestamp,
+      updated_at: timestamp,
+      review_batch_id: null,
+      execution: { status: "not-started", actor: null, authorization_ref: null, started_at: null },
+    };
+    request.checksum = requestChecksum(request);
+    const recorded = commitAction(
+      root,
+      "prototype-change-request-created",
+      input,
+      null,
+      request,
+      [{ file: requestFile(root, request.change_request_id), content: `${JSON.stringify(request, null, 2)}\n` }],
+      timestamp,
+      options,
+    );
+    return { outcome: "applied", change_request: request, receipt: recorded.receipt, event: recorded.event };
+  } finally {
+    release();
+  }
+}
+
+export function applyPrototypeChangeRequest(projectRoot, changeRequestId, input = {}, options = {}) {
+  const root = path.resolve(projectRoot);
+  requireHuman(input.actor);
+  const guarded = guardedPrototypeWrite(root, "prototype-change-request-edited", input, changeRequestId, () => {
+    const { file, request } = readRequest(root, changeRequestId);
+    assertStoredPrototypeRequestTerminal(root, request);
+    assertPrototypeRevisionWritable(root, request.prototype_revision_id, request.prototype_revision_checksum);
+    if (request.review_batch_id) throw new Error("Prototype Change Request belongs to a finalized review batch");
+    if (request.execution?.status === "started") throw new Error("Prototype Change Request execution has started");
+    if (request.revision !== input.expected_revision) throw new Error("Prototype Change Request revision mismatch");
+    if (!String(input.body || "").trim()) throw new Error("Prototype Change Request body is required");
+    const timestamp = new Date().toISOString();
+    request.body = String(input.body).trim();
+    request.revision += 1;
+    request.updated_at = timestamp;
+    request.checksum = requestChecksum(request);
+    const recorded = commitAction(root, "prototype-change-request-edited", input, changeRequestId, request,
+      [{ file, content: `${JSON.stringify(request, null, 2)}\n` }], timestamp, options);
+    return { outcome: "applied", change_request: request, receipt: recorded.receipt, event: recorded.event };
+  });
+  if (guarded.replay) return { outcome: "idempotent-replay", change_request: guarded.replay.result, receipt: guarded.replay };
+  return guarded.value;
+}
+
+function attachmentBytes(root, input) {
+  if (typeof input.content_base64 === "string") return Buffer.from(input.content_base64, "base64");
+  if (input.source_path) {
+    const source = contained(root, input.source_path, "Prototype attachment source");
+    const importRoot = contained(root, ".workflow/imports", "Prototype import directory");
+    if (!inside(importRoot, source)) throw new Error("Prototype attachment source must remain inside .workflow/imports");
+    if (!fs.existsSync(source) || !fs.statSync(source).isFile()) throw new Error("Prototype attachment source is missing");
+    return fs.readFileSync(source);
+  }
+  throw new Error("Prototype attachment requires source_path or content_base64");
+}
+
+export function appendPrototypeChangeRequestAttachment(projectRoot, changeRequestId, input = {}, options = {}) {
+  const root = path.resolve(projectRoot);
+  requireHuman(input.actor);
+  const guarded = guardedPrototypeWrite(root, "prototype-change-request-attachment-added", input, changeRequestId, () => {
+    const { file, request } = readRequest(root, changeRequestId);
+    assertStoredPrototypeRequestTerminal(root, request);
+    assertPrototypeRevisionWritable(root, request.prototype_revision_id, request.prototype_revision_checksum);
+    if (request.review_batch_id) throw new Error("Prototype Change Request belongs to a finalized review batch");
+    if (request.execution?.status === "started") throw new Error("Prototype Change Request execution has started");
+    if (request.revision !== input.expected_revision) throw new Error("Prototype Change Request revision mismatch");
+    if (!new Set(["image/png", "image/jpeg", "image/webp"]).has(input.media_type)) {
+      throw new Error("Prototype review attachment must be PNG, JPEG, or WebP");
+    }
+    const bytes = attachmentBytes(root, input);
+    if (!bytes.length || bytes.length > 10 * 1024 * 1024) throw new Error("Prototype review attachment must be between 1 byte and 10 MiB");
+    const extension = { "image/png": "png", "image/jpeg": "jpg", "image/webp": "webp" }[input.media_type];
+    const attachmentId = `PCRA-${crypto.randomUUID()}`;
+    const relative = `${ATTACHMENT_ROOT}/${changeRequestId}/${attachmentId}.${extension}`;
+    const target = contained(root, relative, "Prototype review attachment");
+    const timestamp = new Date().toISOString();
+    request.attachments.push({ attachment_id: attachmentId, path: relative, media_type: input.media_type, checksum: digest(bytes), size_bytes: bytes.length, created_at: timestamp });
+    request.revision += 1;
+    request.updated_at = timestamp;
+    request.checksum = requestChecksum(request);
+    const recorded = commitAction(root, "prototype-change-request-attachment-added", input, changeRequestId, request, [
+      { file: target, content: bytes },
+      { file, content: `${JSON.stringify(request, null, 2)}\n` },
+    ], timestamp, options);
+    return { outcome: "applied", change_request: request, receipt: recorded.receipt, event: recorded.event };
+  });
+  if (guarded.replay) return { outcome: "idempotent-replay", change_request: guarded.replay.result, receipt: guarded.replay };
+  return guarded.value;
+}
+
+export function inspectWorkflowManagerPrototypeAttachment(projectRoot, input = {}) {
+  const root = path.resolve(projectRoot);
+  const attachmentId = String(input.attachment_id || "");
+  if (!SAFE_ID.test(attachmentId)) throw new Error("Prototype review attachment identity is invalid");
+  if (!SHA256.test(String(input.expected_checksum || ""))) {
+    throw new Error("Prototype review attachment expected_checksum is required");
+  }
+  let request = null;
+  let metadata = null;
+  for (const candidate of currentRequests(root)) {
+    const match = (candidate.attachments || []).find((item) => item.attachment_id === attachmentId);
+    if (!match) continue;
+    if (metadata) throw new Error(`Prototype review attachment identity is duplicated: ${attachmentId}`);
+    request = candidate;
+    metadata = match;
+  }
+  if (!request || !metadata) throw new Error(`Prototype review attachment does not exist: ${attachmentId}`);
+  const requestAttachmentRoot = contained(
+    root,
+    `${ATTACHMENT_ROOT}/${request.change_request_id}`,
+    "Prototype Change Request attachment directory",
+  );
+  const file = contained(root, metadata.path, "Prototype review attachment");
+  if (!inside(requestAttachmentRoot, file)) throw new Error("Prototype review attachment path does not match its request");
+  if (!fs.existsSync(file) || !fs.statSync(file).isFile()) throw new Error("Prototype review attachment content is missing");
+  const bytes = fs.readFileSync(file);
+  if (!bytes.length || bytes.length > 10 * 1024 * 1024) throw new Error("Prototype review attachment size is invalid");
+  const checksum = digest(bytes);
+  if (checksum !== metadata.checksum || checksum !== input.expected_checksum) {
+    throw new Error("Prototype review attachment checksum mismatch");
+  }
+  return {
+    schema_version: "workflow-manager.attachment.v1",
+    lifecycle_status: request.status,
+    mutability: "immutable-evidence",
+    change_request_id: request.change_request_id,
+    review_batch_id: request.review_batch_id,
+    prototype_revision_id: request.prototype_revision_id,
+    terminal_id: request.terminal_id,
+    page_id: request.page_id,
+    review_scene_id: request.review_scene_id,
+    attachment_id: attachmentId,
+    media_type: metadata.media_type,
+    checksum,
+    size_bytes: bytes.length,
+    content_encoding: "base64",
+    content_base64: bytes.toString("base64"),
+  };
+}
+
+export function finalizePrototypeReviewBatch(projectRoot, input = {}, options = {}) {
+  const root = path.resolve(projectRoot);
+  requireHuman(input.actor);
+  const initialReplay = preflightAction(root, "prototype-review-batch-finalized", input);
+  if (initialReplay) return { outcome: "idempotent-replay", review_batch: initialReplay.result, receipt: initialReplay };
+  const release = withPrototypeWriteLock(root, "prototype-review-batch-finalized");
+  try {
+    const replay = preflightAction(root, "prototype-review-batch-finalized", input);
+    if (replay) return { outcome: "idempotent-replay", review_batch: replay.result, receipt: replay };
+    if (!Array.isArray(input.change_request_ids) || !input.change_request_ids.length) throw new Error("Review Batch requires change_request_ids");
+    requireTerminalIdentity(input.terminal_id);
+    assertPrototypeRevisionWritable(root, input.prototype_revision_id, input.prototype_revision_checksum);
+    const requests = input.change_request_ids.map((id) => readRequest(root, id));
+    for (const { request } of requests) {
+      assertStoredPrototypeRequestTerminal(root, request);
+      if (request.prototype_revision_id !== input.prototype_revision_id || request.prototype_revision_checksum !== input.prototype_revision_checksum
+          || request.terminal_id !== input.terminal_id || request.page_id !== input.page_id) {
+        throw new Error("Review Batch requests must bind the exact Prototype revision, Logical Terminal, and Page");
+      }
+      if (request.review_batch_id) throw new Error("Prototype Change Request already belongs to a finalized review batch");
+      if (request.execution?.status === "started") throw new Error("Prototype Change Request execution has started");
+    }
+    const timestamp = new Date().toISOString();
+    const batch = {
+      schema_version: 1,
+      review_batch_id: `PRB-${crypto.randomUUID()}`,
+      prototype_revision_id: input.prototype_revision_id,
+      prototype_revision_checksum: input.prototype_revision_checksum,
+      terminal_id: input.terminal_id,
+      page_id: input.page_id,
+      status: "finalized",
+      actor: input.actor,
+      finalized_at: timestamp,
+      change_requests: requests.map(({ request }) => requestSnapshot(request)),
+    };
+    batch.checksum = digest(JSON.stringify(batch));
+    const writes = [{
+      file: contained(root, `${BATCH_ROOT}/${batch.review_batch_id}.json`, "Review Batch path"),
+      content: `${JSON.stringify(batch, null, 2)}\n`,
+    }];
+    for (const { file, request } of requests) {
+      request.status = "finalized";
+      request.review_batch_id = batch.review_batch_id;
+      request.updated_at = timestamp;
+      request.checksum = requestChecksum(request);
+      writes.push({ file, content: `${JSON.stringify(request, null, 2)}\n` });
+    }
+    const recorded = commitAction(root, "prototype-review-batch-finalized", input, null, batch, writes, timestamp, options);
+    return { outcome: "applied", review_batch: batch, receipt: recorded.receipt, event: recorded.event };
+  } finally {
+    release();
+  }
+}
+
+export function markPrototypeChangeRequestExecution(projectRoot, changeRequestId, input = {}, options = {}) {
+  const root = path.resolve(projectRoot);
+  if (!/^agent:[A-Za-z0-9._@/-]+$/.test(String(input.actor || ""))) throw new Error("Execution actor must use agent:<identity>");
+  if (!String(input.authorization_ref || "").trim()) throw new Error("Prototype redesign authorization reference is required");
+  const guarded = guardedPrototypeWrite(root, "prototype-change-request-execution-started", input, changeRequestId, () => {
+    const { file, request } = readRequest(root, changeRequestId);
+    assertStoredPrototypeRequestTerminal(root, request);
+    assertPrototypeRevisionWritable(root, request.prototype_revision_id, request.prototype_revision_checksum);
+    if (request.revision !== input.expected_revision) throw new Error("Prototype Change Request revision mismatch");
+    if (request.execution?.status === "started") throw new Error("Prototype Change Request execution already started with another request");
+    const timestamp = new Date().toISOString();
+    request.execution = { status: "started", actor: input.actor, authorization_ref: input.authorization_ref, started_at: timestamp };
+    request.revision += 1;
+    request.status = "in-execution";
+    request.updated_at = timestamp;
+    request.checksum = requestChecksum(request);
+    const recorded = commitAction(root, "prototype-change-request-execution-started", input, changeRequestId, request,
+      [{ file, content: `${JSON.stringify(request, null, 2)}\n` }], timestamp, options);
+    return { outcome: "applied", change_request: request, receipt: recorded.receipt, event: recorded.event };
+  });
+  if (guarded.replay) return { outcome: "idempotent-replay", change_request: guarded.replay.result, receipt: guarded.replay };
+  return guarded.value;
+}
+
+export function discardPrototypeChangeRequest(projectRoot, changeRequestId, input = {}, options = {}) {
+  const root = path.resolve(projectRoot);
+  requireHuman(input.actor);
+  const guarded = guardedPrototypeWrite(root, "prototype-change-request-discarded", input, changeRequestId, () => {
+    const { file, request } = readRequest(root, changeRequestId);
+    assertStoredPrototypeRequestTerminal(root, request);
+    assertPrototypeRevisionWritable(root, request.prototype_revision_id, request.prototype_revision_checksum);
+    if (request.revision !== input.expected_revision) throw new Error("Prototype Change Request revision mismatch");
+    if (request.execution?.status === "started") throw new Error("Prototype Change Request execution has started");
+    if (!String(input.rationale || "").trim()) throw new Error("Discard rationale is required");
+    const timestamp = new Date().toISOString();
+    const tombstone = {
+      schema_version: 1,
+      change_request_id: request.change_request_id,
+      prototype_revision_id: request.prototype_revision_id,
+      terminal_id: request.terminal_id,
+      page_id: request.page_id,
+      review_batch_id: request.review_batch_id,
+      status: "discarded",
+      discarded_by: input.actor,
+      discarded_at: timestamp,
+      rationale: String(input.rationale).trim(),
+    };
+    tombstone.checksum = digest(JSON.stringify(tombstone));
+    const discardedRequest = {
+      schema_version: request.schema_version,
+      change_request_id: request.change_request_id,
+      prototype_revision_id: request.prototype_revision_id,
+      prototype_revision_checksum: request.prototype_revision_checksum,
+      terminal_id: request.terminal_id,
+      page_id: request.page_id,
+      page_checksum: request.page_checksum,
+      review_scene_id: request.review_scene_id,
+      revision: request.revision + 1,
+      status: "discarded",
+      body: null,
+      attachments: [],
+      actor: request.actor,
+      created_at: request.created_at,
+      updated_at: timestamp,
+      review_batch_id: request.review_batch_id,
+      execution: request.execution,
+      discarded_tombstone_checksum: tombstone.checksum,
+    };
+    discardedRequest.checksum = requestChecksum(discardedRequest);
+    const attachmentFiles = (request.attachments || []).map((attachment) =>
+      contained(root, attachment.path, "Prototype review attachment"));
+    const tombstoneFile = contained(root, `${TOMBSTONE_ROOT}/${changeRequestId}.json`, "discard tombstone path");
+    const recorded = commitAction(root, "prototype-change-request-discarded", input, changeRequestId, tombstone, [
+      { file, content: `${JSON.stringify(discardedRequest, null, 2)}\n` },
+      ...attachmentFiles.filter((attachmentFile) => fs.existsSync(attachmentFile))
+        .map((attachmentFile) => ({ file: attachmentFile, content: Buffer.alloc(0) })),
+      { file: tombstoneFile, content: `${JSON.stringify(tombstone, null, 2)}\n` },
+    ], timestamp, options);
+    // Cleanup is intentionally after the atomic scrub: an interrupted cleanup cannot expose discarded content.
+    fs.rmSync(file, { force: true });
+    for (const attachmentFile of attachmentFiles) fs.rmSync(attachmentFile, { force: true });
+    return { outcome: "applied", tombstone, receipt: recorded.receipt, event: recorded.event };
+  });
+  if (guarded.replay) return { outcome: "idempotent-replay", tombstone: guarded.replay.result, receipt: guarded.replay };
+  return guarded.value;
+}