ai-delivery-workflow 0.2.2 → 0.4.0

package/lib/prototype-migration.mjs

@@ -0,0 +1,713 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { resolveContainedPath as containedRef } from "./artifact-files.mjs";
+import { atomicWrite, filesUnder } from "./fs-utils.mjs";
+import { parsePrototypeCatalogCsv } from "./prototype-revision.mjs";
+import { stableValue } from "./stable-value.mjs";
+
+const TARGET_PROTOTYPE_ID = "PROTOTYPE";
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+function toPosix(value) {
+  return value.replaceAll("\\", "/");
+}
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function stableJson(value) {
+  return JSON.stringify(stableValue(value));
+}
+
+function readYaml(file, label) {
+  try {
+    const document = parseYaml(fs.readFileSync(file, "utf8"));
+    if (!document || typeof document !== "object" || Array.isArray(document)) {
+      throw new Error("expected a mapping");
+    }
+    return document;
+  } catch (error) {
+    throw new Error(`Cannot read ${label} (${toPosix(file)}): ${error.message}`);
+  }
+}
+
+function currentIterationId(root) {
+  for (const deliveryRoot of [".workflow/delivery", "delivery"]) {
+    const stateFile = path.join(root, ...deliveryRoot.split("/"), "workflow-state.yaml");
+    if (fs.existsSync(stateFile)) {
+      const state = readYaml(stateFile, "workflow state");
+      const active = String(state.development_state?.scope_id || "").trim();
+      if (active) {
+        if (!SAFE_ID.test(active)) throw new Error(`Active iteration ID is unsafe: ${active}.`);
+        return active;
+      }
+    }
+    const projectFile = path.join(root, ...deliveryRoot.split("/"), "project.yaml");
+    if (fs.existsSync(projectFile)) {
+      const project = readYaml(projectFile, "project descriptor");
+      const active = String(project.current_iteration_id || "").trim();
+      if (active) {
+        if (!SAFE_ID.test(active)) throw new Error(`Active iteration ID is unsafe: ${active}.`);
+        return active;
+      }
+    }
+  }
+  return null;
+}
+
+function discoverLegacySets(root, activeIterationId) {
+  const iterationPrefixes = [".workflow/iterations", "iterations"];
+  const experiencePrefixes = [".workflow/experience", "experience"];
+  const archivePrefixes = [".workflow/control/archives/versions", "control/archives/versions"];
+  const designNodes = ["02-solution-design", "04-experience-design"];
+  const sets = [];
+  const addIterationSets = (prefix, scopeForIteration) => {
+    const iterationsRoot = path.join(root, ...prefix.split("/"));
+    if (!fs.existsSync(iterationsRoot)) return;
+    for (const entry of fs.readdirSync(iterationsRoot, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const iterationId = entry.name;
+      for (const node of designNodes) {
+        const file = path.join(iterationsRoot, iterationId, node, "prototype-set.yaml");
+        if (!fs.existsSync(file) || !fs.statSync(file).isFile()) continue;
+        sets.push({ file, iteration_id: iterationId, scope: scopeForIteration(iterationId) });
+      }
+    }
+  };
+  for (const prefix of iterationPrefixes) {
+    addIterationSets(prefix, (iterationId) =>
+      iterationId === activeIterationId ? "open" : "closed");
+  }
+  for (const prefix of experiencePrefixes) {
+    const experienceRoot = path.join(root, ...prefix.split("/"));
+    if (fs.existsSync(experienceRoot)) {
+      for (const entry of fs.readdirSync(experienceRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        const file = path.join(experienceRoot, entry.name, "prototype-set.yaml");
+        if (!fs.existsSync(file) || !fs.statSync(file).isFile()) continue;
+        sets.push({
+          file,
+          iteration_id: entry.name,
+          scope: entry.name === activeIterationId ? "open" : "closed",
+        });
+      }
+    }
+    const directFile = path.join(experienceRoot, "prototype-set.yaml");
+    if (fs.existsSync(directFile) && fs.statSync(directFile).isFile()) {
+      sets.push({
+        file: directFile,
+        iteration_id: activeIterationId,
+        scope: activeIterationId ? "open" : "closed",
+      });
+    }
+  }
+  for (const prefix of archivePrefixes) {
+    addIterationSets(prefix, () => "archived");
+  }
+  return sets.sort((left, right) => left.file.localeCompare(right.file));
+}
+
+function setMembers(document) {
+  if (Array.isArray(document.members)) return document.members;
+  if (Array.isArray(document.ordered_members)) return document.ordered_members;
+  return [];
+}
+
+function memberIdentity(value) {
+  return String(value?.prototype_member_id || value?.prototype_artifact_id || value?.artifact_id || "").trim();
+}
+
+function manifestRef(setDirectory, member, memberId) {
+  const explicit = String(member.manifest_ref || "").trim();
+  if (explicit) return explicit;
+  for (const candidate of [`prototype-manifest-${memberId}.yaml`, "prototype-manifest.yaml"]) {
+    if (fs.existsSync(path.join(setDirectory, candidate))) return candidate;
+  }
+  return "";
+}
+
+function catalogBinding(manifest, kind) {
+  const keys = kind === "routes"
+    ? ["prototype_routes", "routes"]
+    : kind === "pages" ? ["page_catalog"] : ["prototype_files"];
+  for (const key of keys) {
+    const ref = manifest[`${key}_ref`];
+    if (!ref) continue;
+    return {
+      ref: String(ref),
+      algorithm: String(manifest[`${key}_algorithm`] || "sha256"),
+      checksum: String(manifest[`${key}_checksum`] || ""),
+    };
+  }
+  return null;
+}
+
+function sourceBinding(manifest) {
+  const ref = manifest.source_path || manifest.prototype?.source_ref;
+  const checksum = manifest.source_checksum || manifest.prototype?.source_checksum;
+  return {
+    ref: String(ref || ""),
+    algorithm: String(manifest.source_algorithm || manifest.prototype?.source_algorithm || "sha256"),
+    checksum: String(checksum || ""),
+  };
+}
+
+function exactSourceFiles(source) {
+  if (!fs.existsSync(source)) return [];
+  if (fs.statSync(source).isFile()) return [source];
+  if (fs.statSync(source).isDirectory()) return filesUnder(source);
+  return [];
+}
+
+function sourceDigest(source) {
+  if (fs.statSync(source).isFile()) return sha256(fs.readFileSync(source));
+  const hash = crypto.createHash("sha256");
+  for (const file of filesUnder(source)) {
+    hash.update(toPosix(path.relative(source, file)));
+    hash.update("\0");
+    hash.update(fs.readFileSync(file));
+    hash.update("\0");
+  }
+  return hash.digest("hex");
+}
+
+function conflict(kind, id, records, reason = "member-definitions-differ") {
+  const memberIds = [...new Set(records.map((record) => record.member_id))].sort();
+  const recordChecksums = records.map((record) => record.record_checksum).sort();
+  const conflictId = `PROTO-CONFLICT-${sha256(stableJson({ kind, id, memberIds, recordChecksums, reason })).slice(0, 16).toUpperCase()}`;
+  return {
+    conflict_id: conflictId,
+    target_kind: kind,
+    target_id: id,
+    member_ids: memberIds,
+    reason,
+    decision_required: reason === "member-definitions-differ",
+  };
+}
+
+function mergeRecords(kind, identityField, records) {
+  const grouped = new Map();
+  const conflicts = [];
+  for (const [index, record] of records.entries()) {
+    const id = String(record[identityField] || "").trim();
+    if (!id) {
+      conflicts.push(conflict(
+        kind,
+        `${record.member_id}:${identityField}:row-${index + 1}`,
+        [record],
+        "missing-stable-identity",
+      ));
+      continue;
+    }
+    if (!grouped.has(id)) grouped.set(id, []);
+    grouped.get(id).push(record);
+  }
+  const merged = [];
+  for (const [id, candidates] of grouped) {
+    const unique = new Set(candidates.map((record) => record.record_checksum));
+    const duplicateMembers = new Set(candidates
+      .map((record) => record.member_id)
+      .filter((memberId, index, memberIds) => memberIds.indexOf(memberId) !== index));
+    if (duplicateMembers.size) {
+      conflicts.push(conflict(
+        kind,
+        id,
+        candidates.filter((record) => duplicateMembers.has(record.member_id)),
+        "duplicate-member-record-id",
+      ));
+    } else if (unique.size > 1) conflicts.push(conflict(kind, id, candidates));
+    const canonical = [...candidates].sort((left, right) =>
+      left.member_id.localeCompare(right.member_id))[0];
+    merged.push({
+      [`${kind === "file" ? "file" : kind}_id`]: id,
+      member_ids: [...new Set(candidates.map((record) => record.member_id))].sort(),
+      record_checksum: canonical.record_checksum,
+      conflict: unique.size > 1,
+    });
+  }
+  return {
+    records: merged.sort((left, right) => String(left[`${kind === "file" ? "file" : kind}_id`])
+      .localeCompare(String(right[`${kind === "file" ? "file" : kind}_id`]))),
+    conflicts,
+  };
+}
+
+function readCatalog(member, kind, conflicts, sourceFiles, required) {
+  const binding = catalogBinding(member.manifest, kind);
+  if (!binding) {
+    if (required) conflicts.push(conflict("catalog", `${member.member_id}:${kind}`, [{
+      member_id: member.member_id,
+      record_checksum: sha256("missing"),
+    }], "catalog-binding-missing"));
+    return [];
+  }
+  let file;
+  try {
+    file = containedRef(member.directory, binding.ref, `Legacy Prototype ${kind} catalog`);
+  } catch (error) {
+    conflicts.push(conflict("catalog", `${member.member_id}:${kind}`, [{
+      member_id: member.member_id,
+      record_checksum: sha256(error.message),
+    }], "invalid-catalog-ref"));
+    return [];
+  }
+  if (binding.algorithm !== "sha256" || !/^[a-f0-9]{64}$/.test(binding.checksum)
+      || !fs.existsSync(file) || sha256(fs.readFileSync(file)) !== binding.checksum) {
+    conflicts.push(conflict("catalog", `${member.member_id}:${kind}`, [{
+      member_id: member.member_id,
+      record_checksum: fs.existsSync(file) ? sha256(fs.readFileSync(file)) : sha256("missing"),
+    }], "catalog-checksum-mismatch"));
+    return [];
+  }
+  sourceFiles.add(file);
+  return parsePrototypeCatalogCsv(
+    fs.readFileSync(file, "utf8"),
+    `Legacy Prototype ${kind} catalog`,
+  ).rows
+    .map((row) => ({
+      ...row,
+      member_id: member.member_id,
+      record_checksum: sha256(stableJson(row)),
+    }));
+}
+
+function loadOpenMembers(root, openSets) {
+  const members = [];
+  const conflicts = [];
+  const sourceFiles = new Set();
+  let declaredMemberCount = 0;
+  for (const set of openSets) {
+    sourceFiles.add(set.file);
+    const document = readYaml(set.file, "legacy Prototype set");
+    const directory = path.dirname(set.file);
+    for (const item of setMembers(document)) {
+      declaredMemberCount += 1;
+      const expectedId = memberIdentity(item);
+      if (!SAFE_ID.test(expectedId)) {
+        conflicts.push(conflict("member", expectedId || "missing", [{
+          member_id: expectedId || "missing",
+          record_checksum: sha256(stableJson(item)),
+        }], "invalid-member-id"));
+        continue;
+      }
+      const ref = manifestRef(directory, item, expectedId);
+      let manifestFile;
+      try {
+        manifestFile = containedRef(directory, ref, "Legacy Prototype member manifest");
+      } catch (error) {
+        conflicts.push(conflict("member", expectedId || "missing", [{
+          member_id: expectedId || "missing",
+          record_checksum: sha256(error.message),
+        }], "invalid-manifest-ref"));
+        continue;
+      }
+      const expectedChecksum = String(item.manifest_checksum || "");
+      if (!expectedId || !fs.existsSync(manifestFile) || !/^[a-f0-9]{64}$/.test(expectedChecksum)
+          || sha256(fs.readFileSync(manifestFile)) !== expectedChecksum) {
+        conflicts.push(conflict("member", expectedId || "missing", [{
+          member_id: expectedId || "missing",
+          record_checksum: fs.existsSync(manifestFile)
+            ? sha256(fs.readFileSync(manifestFile)) : sha256("missing"),
+        }], "manifest-checksum-mismatch"));
+        continue;
+      }
+      sourceFiles.add(manifestFile);
+      const manifest = readYaml(manifestFile, "legacy Prototype member manifest");
+      const actualId = memberIdentity(manifest);
+      if (actualId !== expectedId) {
+        conflicts.push(conflict("member", expectedId, [{
+          member_id: expectedId,
+          record_checksum: sha256(stableJson({ expectedId, actualId })),
+        }], "member-identity-mismatch"));
+        continue;
+      }
+      const binding = sourceBinding(manifest);
+      let source;
+      try {
+        source = containedRef(directory, binding.ref, "Legacy Prototype source");
+      } catch (error) {
+        conflicts.push(conflict("source", expectedId, [{
+          member_id: expectedId,
+          record_checksum: sha256(error.message),
+        }], "invalid-source-ref"));
+        continue;
+      }
+      if (!fs.existsSync(source) || !new Set(["sha256", "sha256-tree-v1"]).has(binding.algorithm)
+          || !/^[a-f0-9]{64}$/.test(binding.checksum)
+          || sourceDigest(source) !== binding.checksum) {
+        conflicts.push(conflict("source", expectedId, [{
+          member_id: expectedId,
+          record_checksum: fs.existsSync(source) ? sourceDigest(source) : sha256("missing"),
+        }], "source-checksum-mismatch"));
+        continue;
+      }
+      for (const file of exactSourceFiles(source)) sourceFiles.add(file);
+      members.push({
+        member_id: expectedId,
+        manifest_ref: toPosix(path.relative(root, manifestFile)),
+        manifest_checksum: expectedChecksum,
+        directory,
+        manifest,
+        source,
+        source_ref: toPosix(path.relative(root, source)),
+        source_checksum: binding.checksum,
+        terminal_ids: [...new Set([
+          ...(Array.isArray(item.terminal_ids) ? item.terminal_ids : []),
+          ...(Array.isArray(manifest.terminal_ids) ? manifest.terminal_ids : []),
+          ...(Array.isArray(manifest.coverage?.terminal_ids) ? manifest.coverage.terminal_ids : []),
+        ].map(String))].sort(),
+      });
+    }
+  }
+  members.sort((left, right) => left.member_id.localeCompare(right.member_id));
+  const duplicateIds = [...new Set(members.map((member) => member.member_id))]
+    .filter((id) => members.filter((member) => member.member_id === id).length > 1);
+  for (const id of duplicateIds) {
+    conflicts.push(conflict("member", id, members.filter((member) => member.member_id === id)
+      .map((member) => ({ member_id: id, record_checksum: member.manifest_checksum })), "duplicate-member-id"));
+  }
+  return { members, conflicts, sourceFiles, declaredMemberCount };
+}
+
+function mergeReport(loaded) {
+  const conflicts = [...loaded.conflicts];
+  const sourceFiles = loaded.sourceFiles;
+  const terminals = loaded.members.flatMap((member) => member.terminal_ids.map((terminalId) => ({
+    terminal_id: terminalId,
+    member_id: member.member_id,
+    record_checksum: sha256(stableJson({ terminal_id: terminalId })),
+  })));
+  const requireCatalogs = loaded.members.length > 0;
+  const pages = loaded.members.flatMap((member) =>
+    readCatalog(member, "pages", conflicts, sourceFiles, requireCatalogs));
+  const routes = loaded.members.flatMap((member) =>
+    readCatalog(member, "routes", conflicts, sourceFiles, requireCatalogs));
+  const files = loaded.members.flatMap((member) =>
+    readCatalog(member, "files", conflicts, sourceFiles, requireCatalogs));
+  const terminalMerge = mergeRecords("terminal", "terminal_id", terminals);
+  const pageMerge = mergeRecords("page", "page_id", pages);
+  const routeMerge = mergeRecords("route", "route_id", routes);
+  const fileMerge = mergeRecords("file", "file_ref", files);
+  conflicts.push(...terminalMerge.conflicts, ...pageMerge.conflicts, ...routeMerge.conflicts, ...fileMerge.conflicts);
+  return {
+    terminals: terminalMerge.records,
+    pages: pageMerge.records,
+    routes: routeMerge.records,
+    files: fileMerge.records,
+    conflicts: conflicts.sort((left, right) => left.conflict_id.localeCompare(right.conflict_id)),
+  };
+}
+
+function applyDecisions(report, decisionsFile, sourceChecksum) {
+  report.decisions = [];
+  report.unresolved_conflicts = report.merge_report.conflicts.map((item) => ({ ...item }));
+  report.decision_template = {
+    schema_version: 1,
+    source_checksum: sourceChecksum || "REPLACE_WITH_MIGRATION_SOURCE_CHECKSUM",
+    actor: "human:<identity>",
+    decisions: [],
+    prototype_decisions: report.merge_report.conflicts.filter((item) => item.decision_required).map((item) => ({
+      conflict_id: item.conflict_id,
+      action: "choose-member",
+      member_id: item.member_ids[0] || "<member-id>",
+      rationale: "<why this member is canonical for the merged identity>",
+    })),
+  };
+  if (!decisionsFile) return;
+  if (!sourceChecksum) throw new Error("Prototype migration decisions require the migration source checksum.");
+  const document = readYaml(path.resolve(decisionsFile), "migration decisions");
+  if (document.schema_version !== 1 || document.source_checksum !== sourceChecksum) {
+    throw new Error("Prototype migration decisions do not match the current source checksum.");
+  }
+  const actor = String(document.actor || "").trim();
+  if (!actor.startsWith("human:")) {
+    throw new Error("Prototype migration decisions require actor human:<identity>.");
+  }
+  if (!Array.isArray(document.prototype_decisions)) {
+    throw new Error("Prototype migration decisions must contain a prototype_decisions list.");
+  }
+  const byId = new Map();
+  for (const decision of document.prototype_decisions) {
+    const id = String(decision?.conflict_id || "");
+    if (!id || byId.has(id)) throw new Error(`Prototype migration conflict decision is missing or duplicated: ${id || "missing"}.`);
+    byId.set(id, decision);
+  }
+  const unresolved = [];
+  for (const item of report.merge_report.conflicts) {
+    const decision = byId.get(item.conflict_id);
+    if (!decision) {
+      unresolved.push(item);
+      continue;
+    }
+    if (!item.decision_required) {
+      throw new Error(
+        `Prototype migration conflict ${item.conflict_id} (${item.reason}) is not human-resolvable; decisions cannot override integrity or structural evidence.`,
+      );
+    }
+    const memberId = String(decision.member_id || "");
+    const rationale = String(decision.rationale || "").trim();
+    if (decision.action !== "choose-member" || !item.member_ids.includes(memberId) || !rationale) {
+      throw new Error(`Prototype migration decision is invalid for ${item.conflict_id}.`);
+    }
+    const normalized = {
+      conflict_id: item.conflict_id,
+      action: "choose-member",
+      member_id: memberId,
+      actor,
+      rationale,
+    };
+    report.decisions.push(normalized);
+    item.decision_required = false;
+    item.resolution = normalized;
+  }
+  for (const id of byId.keys()) {
+    if (!report.merge_report.conflicts.some((item) => item.conflict_id === id)) {
+      throw new Error(`Prototype migration decision does not match a conflict: ${id}.`);
+    }
+  }
+  report.decisions.sort((left, right) => left.conflict_id.localeCompare(right.conflict_id));
+  report.unresolved_conflicts = unresolved;
+}
+
+function generatedContent(report) {
+  const migrationId = `PROTOTYPE-MIGRATION-${report.source_checksum.slice(0, 16).toUpperCase()}`;
+  const migrationRecord = stableValue({
+    schema_version: 1,
+    artifact_id: migrationId,
+    artifact_type: "legacy-prototype-migration",
+    iteration_id: report.iteration_id,
+    status: "applied-pending-ux-ui",
+    source_checksum: report.source_checksum,
+    target_prototype_id: TARGET_PROTOTYPE_ID,
+    legacy_sets: report.legacy_sets,
+    members: report.members,
+    merge_report: report.merge_report,
+    decisions: report.decisions,
+    preserved_history: report.preserved_history,
+    approval: report.approval,
+  });
+  const descriptor = stableValue({
+    schema_version: 1,
+    artifact_type: "prototype-current",
+    prototype_id: TARGET_PROTOTYPE_ID,
+    iteration_id: report.iteration_id,
+    status: "migration-pending-ux-ui",
+    current_source_ref: "prototype/source",
+    current_review_shell_ref: "prototype/review-shell",
+    current_revision_ref: null,
+    migration: {
+      artifact_id: migrationId,
+      ref: "prototype-migration.yaml",
+      algorithm: "sha256",
+      checksum: sha256(stringifyYaml(migrationRecord, { lineWidth: 0 })),
+    },
+  });
+  const links = report.members.map((member) =>
+    `<li><a href="../source/${encodeURIComponent(member.member_id)}/">${member.member_id}</a></li>`).join("");
+  const shell = `<!doctype html>\n<html lang="en"><head><meta charset="utf-8"><title>Legacy Prototype migration</title></head><body><main><h1>Prototype migration pending UX-UI</h1><ul>${links}</ul></main></body></html>\n`;
+  return {
+    descriptor: stringifyYaml(descriptor, { lineWidth: 0 }),
+    migration: stringifyYaml(migrationRecord, { lineWidth: 0 }),
+    shell,
+  };
+}
+
+function buildOperations(root, report) {
+  const generated = generatedContent(report);
+  const writes = [
+    { path: ".workflow/experience/" + report.iteration_id + "/prototype.yaml", kind: "prototype-current", content: Buffer.from(generated.descriptor) },
+    { path: ".workflow/experience/" + report.iteration_id + "/prototype-migration.yaml", kind: "prototype-migration-record", content: Buffer.from(generated.migration) },
+    { path: ".workflow/experience/" + report.iteration_id + "/prototype/review-shell/index.html", kind: "prototype-review-shell", content: Buffer.from(generated.shell) },
+  ];
+  const copies = [];
+  for (const member of report.members) {
+    const source = path.join(root, ...member.source_ref.split("/"));
+    const sourceRoot = fs.statSync(source).isDirectory() ? source : path.dirname(source);
+    for (const file of exactSourceFiles(source)) {
+      const sourceTail = fs.statSync(source).isDirectory()
+        ? toPosix(path.relative(sourceRoot, file)) : path.basename(file);
+      copies.push({
+        source_path: toPosix(path.relative(root, file)),
+        target_path: `.workflow/experience/${report.iteration_id}/prototype/source/${member.member_id}/${sourceTail}`,
+        source_sha256: sha256(fs.readFileSync(file)),
+        target_sha256: sha256(fs.readFileSync(file)),
+        transformation: "byte-for-byte",
+      });
+    }
+  }
+  const targetConflicts = [];
+  for (const operation of [...writes.map((item) => ({ ...item, target_path: item.path, target_sha256: sha256(item.content) })), ...copies]) {
+    const target = path.join(root, ...operation.target_path.split("/"));
+    if (fs.existsSync(target)) {
+      const actual = sha256(fs.readFileSync(target));
+      const reason = actual === operation.target_sha256
+        ? "migration-target-already-exists" : "migration-target-conflict";
+      targetConflicts.push(conflict("target", operation.target_path, [{
+        member_id: "existing-project",
+        record_checksum: actual,
+      }], reason));
+    }
+  }
+  Object.defineProperty(report, "_operations", {
+    enumerable: false,
+    value: { writes, copies },
+  });
+  report.file_changes = {
+    additions: writes.map((item) => ({ path: item.path, kind: item.kind, sha256: sha256(item.content) })),
+    copies,
+  };
+  report.merge_report.conflicts.push(...targetConflicts);
+  report.merge_report.conflicts.sort((left, right) => left.conflict_id.localeCompare(right.conflict_id));
+  report.unresolved_conflicts.push(...targetConflicts);
+}
+
+export function planPrototypeMigration(project, options = {}) {
+  const root = path.resolve(project);
+  const iterationId = currentIterationId(root);
+  const sets = discoverLegacySets(root, iterationId);
+  const openSets = sets.filter((item) => item.scope === "open");
+  const preservedHistory = sets.filter((item) => item.scope !== "open").map((item) => ({
+    iteration_id: item.iteration_id,
+    scope: item.scope,
+    set_ref: toPosix(path.relative(root, item.file)),
+    set_checksum: sha256(fs.readFileSync(item.file)),
+    policy: "byte-for-byte-preserved",
+  }));
+  const targetRelative = iterationId ? `.workflow/experience/${iterationId}/prototype.yaml` : null;
+  const targetFile = targetRelative ? path.join(root, ...targetRelative.split("/")) : null;
+  const existingCurrent = targetFile && fs.existsSync(targetFile) ? readYaml(targetFile, "current Prototype") : null;
+  const loaded = loadOpenMembers(root, openSets);
+  const merged = mergeReport(loaded);
+  const sourceFiles = [...loaded.sourceFiles].sort((left, right) => left.localeCompare(right));
+  const legacySourceChecksum = sha256(stableJson(sourceFiles.map((file) => ({
+    path: toPosix(path.relative(root, file)),
+    sha256: sha256(fs.readFileSync(file)),
+  }))));
+  const report = {
+    schema_version: 1,
+    status: "not-required",
+    applied: false,
+    iteration_id: iterationId,
+    source_checksum: legacySourceChecksum,
+    member_count: loaded.declaredMemberCount,
+    valid_member_count: loaded.members.length,
+    invalid_member_count: loaded.declaredMemberCount - loaded.members.length,
+    legacy_sets: openSets.map((item) => ({
+      iteration_id: item.iteration_id,
+      ref: toPosix(path.relative(root, item.file)),
+      checksum: sha256(fs.readFileSync(item.file)),
+    })),
+    members: loaded.members.map((member) => ({
+      member_id: member.member_id,
+      manifest_ref: member.manifest_ref,
+      manifest_checksum: member.manifest_checksum,
+      source_ref: member.source_ref,
+      source_checksum: member.source_checksum,
+      terminal_ids: member.terminal_ids,
+    })),
+    target: {
+      prototype_id: TARGET_PROTOTYPE_ID,
+      descriptor_ref: targetRelative,
+      experience_ref: iterationId ? `.workflow/experience/${iterationId}` : null,
+    },
+    merge_report: merged,
+    preserved_history: preservedHistory,
+    preserved_sources: sourceFiles.map((file) => ({
+      path: toPosix(path.relative(root, file)),
+      sha256: sha256(fs.readFileSync(file)),
+    })),
+    approval: {
+      required_gate: loaded.declaredMemberCount ? "UX-UI" : null,
+      existing_approval_reused: false,
+      policy: loaded.declaredMemberCount ? "fresh-approval-required" : "not-applicable",
+    },
+    required_follow_up: {
+      command: "ai-delivery migrate",
+      write_planned: false,
+    },
+  };
+  applyDecisions(report, options.decisionsFile, options.sourceChecksum);
+  report.can_apply = report.unresolved_conflicts.length === 0;
+  if (!iterationId || !openSets.length || !loaded.members.length) {
+    report.status = report.unresolved_conflicts.length ? "blocked" : "not-required";
+    report.file_changes = { additions: [], copies: [] };
+    report.can_apply = report.unresolved_conflicts.length === 0;
+    return report;
+  }
+  if (existingCurrent) {
+    if (existingCurrent.artifact_type !== "prototype-current"
+        || existingCurrent.prototype_id !== TARGET_PROTOTYPE_ID) {
+      report.unresolved_conflicts.push(conflict("target", targetRelative, [{
+        member_id: "existing-project",
+        record_checksum: sha256(stableJson(existingCurrent)),
+      }], "incompatible-current-prototype"));
+      report.can_apply = false;
+      report.status = "blocked";
+    } else {
+      report.status = "already-current";
+      report.can_apply = true;
+    }
+    report.file_changes = { additions: [], copies: [] };
+    return report;
+  }
+  if (report.can_apply) buildOperations(root, report);
+  report.can_apply = report.unresolved_conflicts.length === 0;
+  report.status = report.can_apply ? "ready" : "blocked";
+  return report;
+}
+
+export function applyPrototypeMigration(project, report) {
+  const root = path.resolve(project);
+  if (report.status === "not-required" || report.status === "already-current") return report;
+  if (!report.can_apply || !report._operations) {
+    throw new Error("Prototype migration requires checksum-bound human decisions before apply.");
+  }
+  for (const source of report.preserved_sources) {
+    const file = path.join(root, ...source.path.split("/"));
+    if (!fs.existsSync(file) || sha256(fs.readFileSync(file)) !== source.sha256) {
+      throw new Error(`Legacy Prototype source changed during apply: ${source.path}.`);
+    }
+  }
+  const created = [];
+  try {
+    for (const write of report._operations.writes) {
+      const target = path.join(root, ...write.path.split("/"));
+      if (fs.existsSync(target)) throw new Error(`Prototype migration target already exists: ${write.path}.`);
+      atomicWrite(target, write.content);
+      created.push(target);
+    }
+    for (const copy of report._operations.copies) {
+      const source = path.join(root, ...copy.source_path.split("/"));
+      const target = path.join(root, ...copy.target_path.split("/"));
+      if (fs.existsSync(target) || sha256(fs.readFileSync(source)) !== copy.source_sha256) {
+        throw new Error(`Prototype migration copy changed during apply: ${copy.source_path}.`);
+      }
+      atomicWrite(target, fs.readFileSync(source));
+      created.push(target);
+    }
+  } catch (error) {
+    for (const file of created.reverse()) fs.rmSync(file, { force: true });
+    throw error;
+  }
+  report.applied = true;
+  return report;
+}
+
+export function rollbackPrototypeMigration(project, report) {
+  if (!report?.file_changes) return;
+  const root = path.resolve(project);
+  const files = [
+    ...(report.file_changes.copies || []).map((item) => ({ path: item.target_path, sha256: item.target_sha256 })),
+    ...(report.file_changes.additions || []).map((item) => ({ path: item.path, sha256: item.sha256 })),
+  ].reverse();
+  for (const item of files) {
+    const file = path.join(root, ...item.path.split("/"));
+    if (!fs.existsSync(file) || sha256(fs.readFileSync(file)) !== item.sha256) {
+      throw new Error(`Migrated Prototype bytes changed; rollback is blocked: ${item.path}.`);
+    }
+  }
+  for (const item of files) fs.rmSync(path.join(root, ...item.path.split("/")), { force: true });
+}