@davmash/bygone 0.8.13 → 0.8.16

package/out/tourCoverage.js

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var tourCoverage_exports = {};
 __export(tourCoverage_exports, {
   TOUR_COVERAGE_REPORT_VERSION: () => TOUR_COVERAGE_REPORT_VERSION,
+  buildTourAuthoringCoverage: () => buildTourAuthoringCoverage,
   buildTourCoverageReport: () => buildTourCoverageReport
 });
 module.exports = __toCommonJS(tourCoverage_exports);
@@ -473,33 +474,330 @@ function runGit(repoRoot, args) {
 // src/changeTour.ts
 var import_child_process3 = require("child_process");
 
+// src/changeTourSource.ts
+var CHANGE_TOUR_SOURCE_VERSION = 2;
+function parseChangeTourSource(value) {
+  if (isRecord(value) && Number.isInteger(value.version) && Number(value.version) > CHANGE_TOUR_SOURCE_VERSION) {
+    throw new Error(
+      `This tour uses source format version ${value.version}, but this version of Bygone supports up to version ${CHANGE_TOUR_SOURCE_VERSION}. Upgrade Bygone to open it.`
+    );
+  }
+  if (!isRecord(value) || value.version !== 1 && value.version !== CHANGE_TOUR_SOURCE_VERSION) {
+    throw new Error("Unsupported or missing change-tour source version.");
+  }
+  requireOnlyKeys(value, ["version", "title", "windowTitle", "sourceUrl", "range", "anchors", "connections", "chapters", "coverage"], "source");
+  optionalString(value.title, "title");
+  optionalString(value.windowTitle, "windowTitle");
+  optionalString(value.sourceUrl, "sourceUrl");
+  if (value.range !== void 0) {
+    if (!isRecord(value.range)) throw new Error("range must be an object.");
+    requireOnlyKeys(value.range, ["base", "head"], "range");
+    requireString(value.range.base, "range.base");
+    requireString(value.range.head, "range.head");
+  }
+  if (value.coverage !== void 0) {
+    if (!isRecord(value.coverage) || !Array.isArray(value.coverage.exclusions)) {
+      throw new Error("coverage must contain an exclusions array.");
+    }
+    requireOnlyKeys(value.coverage, ["exclusions"], "coverage");
+    for (const [index, exclusion] of value.coverage.exclusions.entries()) {
+      const exclusionPath = `coverage.exclusions[${index}]`;
+      if (!isRecord(exclusion)) throw new Error(`${exclusionPath} must be an object.`);
+      requireOnlyKeys(exclusion, ["path", "hunks", "reason"], exclusionPath);
+      requireString(exclusion.path, `${exclusionPath}.path`);
+      requireString(exclusion.reason, `${exclusionPath}.reason`);
+      if (exclusion.hunks !== void 0) requireStringArray(exclusion.hunks, `${exclusionPath}.hunks`);
+    }
+  }
+  if (!isRecord(value.anchors)) {
+    throw new Error("anchors must be an object.");
+  }
+  for (const [id, anchor] of Object.entries(value.anchors)) {
+    if (!isRecord(anchor)) {
+      throw new Error(`anchors.${id} must be an object.`);
+    }
+    requireOnlyKeys(anchor, ["file", "revision", "contains", "occurrence"], `anchors.${id}`);
+    requireString(anchor.file, `anchors.${id}.file`);
+    if (anchor.revision !== "base" && anchor.revision !== "head") {
+      throw new Error(`anchors.${id}.revision must be base or head.`);
+    }
+    requireString(anchor.contains, `anchors.${id}.contains`);
+    if (anchor.occurrence !== void 0 && (!Number.isInteger(anchor.occurrence) || Number(anchor.occurrence) < 1)) {
+      throw new Error(`anchors.${id}.occurrence must be a positive integer.`);
+    }
+  }
+  const rawConnections = Array.isArray(value.connections) ? value.connections : isRecord(value.connections) ? Object.entries(value.connections).map(([id, connection]) => isRecord(connection) ? { id, ...connection } : connection) : null;
+  if (!rawConnections || !Array.isArray(value.chapters) || value.chapters.length === 0) {
+    throw new Error("connections must be an array or object, and chapters must be a non-empty array.");
+  }
+  const connectionIds = /* @__PURE__ */ new Set();
+  for (const [index, connection] of rawConnections.entries()) {
+    if (!isRecord(connection)) {
+      throw new Error(`connections[${index}] must be an object.`);
+    }
+    requireOnlyKeys(connection, ["id", "from", "to", "label"], `connections[${index}]`);
+    requireString(connection.id, `connections[${index}].id`);
+    requireString(connection.from, `connections[${index}].from`);
+    requireString(connection.to, `connections[${index}].to`);
+    requireString(connection.label, `connections[${index}].label`);
+    const { id, from, to } = connection;
+    if (!value.anchors[from] || !value.anchors[to]) {
+      throw new Error(`Connection ${id} references an unknown anchor.`);
+    }
+    if (connectionIds.has(id)) {
+      throw new Error(`Duplicate connection id: ${id}`);
+    }
+    connectionIds.add(id);
+  }
+  const chapterIds = /* @__PURE__ */ new Set();
+  const sceneIds = /* @__PURE__ */ new Set();
+  for (const [chapterIndex, chapter] of value.chapters.entries()) {
+    if (!isRecord(chapter) || !Array.isArray(chapter.scenes) || chapter.scenes.length === 0) {
+      throw new Error(`chapters[${chapterIndex}] must contain a non-empty scenes array.`);
+    }
+    requireString(chapter.id, `chapters[${chapterIndex}].id`);
+    requireString(chapter.title, `chapters[${chapterIndex}].title`);
+    requireOnlyKeys(chapter, ["id", "title", "scenes"], `chapters[${chapterIndex}]`);
+    if (chapterIds.has(chapter.id)) throw new Error(`Duplicate chapter id: ${chapter.id}`);
+    chapterIds.add(chapter.id);
+    for (const [sceneIndex, scene] of chapter.scenes.entries()) {
+      const path = `chapters[${chapterIndex}].scenes[${sceneIndex}]`;
+      if (!isRecord(scene)) throw new Error(`${path} must be an object.`);
+      requireString(scene.id, `${path}.id`);
+      requireString(scene.title, `${path}.title`);
+      if (sceneIds.has(scene.id)) throw new Error(`Duplicate scene id: ${scene.id}`);
+      sceneIds.add(scene.id);
+      validateNarrative(scene, path);
+      if (scene.kind === "deconstructed-diff") {
+        validateDeconstructedScene(scene, path);
+        if (value.version === 2 || scene.stack !== void 0) validateRealStack(scene.stack, `${path}.stack`, 2);
+        if (value.version === 2 || scene.steps !== void 0) {
+          validateWalkthroughSteps(scene, path, value.anchors, connectionIds);
+        }
+        continue;
+      }
+      if (!Array.isArray(scene.steps) || scene.steps.length === 0) {
+        throw new Error(`${path} must contain a non-empty steps array.`);
+      }
+      if (scene.kind === "stacked-diff") {
+        validateStackedScene(scene, path, value.version === 2 ? 2 : 3);
+        continue;
+      }
+      if (scene.kind !== void 0 && scene.kind !== "walkthrough") {
+        throw new Error(`${path}.kind must be walkthrough, stacked-diff, or deconstructed-diff.`);
+      }
+      requireOnlyKeys(scene, ["id", "kind", "title", "summary", "bullets", "tags", "takeaway", "steps"], path);
+      validateWalkthroughSteps(scene, path, value.anchors, connectionIds);
+    }
+  }
+  return { ...value, connections: rawConnections };
+}
+function validateDeconstructedScene(scene, path) {
+  requireOnlyKeys(scene, ["id", "kind", "title", "summary", "bullets", "tags", "takeaway", "base", "target", "stack", "steps", "stages", "exclusions"], path);
+  optionalString(scene.base, `${path}.base`);
+  optionalString(scene.target, `${path}.target`);
+  if (!Array.isArray(scene.stages) || scene.stages.length === 0 || scene.stages.length > 12) {
+    throw new Error(`${path}.stages must contain between 1 and 12 stages.`);
+  }
+  const stageIds = /* @__PURE__ */ new Set();
+  for (const [stageIndex, stage] of scene.stages.entries()) {
+    const stagePath = `${path}.stages[${stageIndex}]`;
+    if (!isRecord(stage)) throw new Error(`${stagePath} must be an object.`);
+    requireOnlyKeys(stage, ["id", "title", "narration", "changes"], stagePath);
+    requireString(stage.id, `${stagePath}.id`);
+    requireString(stage.title, `${stagePath}.title`);
+    requireString(stage.narration, `${stagePath}.narration`);
+    if (!Array.isArray(stage.changes) || stage.changes.length === 0) {
+      throw new Error(`${stagePath}.changes must be a non-empty array.`);
+    }
+    if (stageIds.has(stage.id)) throw new Error(`Duplicate deconstructed stage id: ${stage.id}`);
+    stageIds.add(stage.id);
+    stage.changes.forEach((change, changeIndex) => validateDeconstructedSelection(
+      change,
+      `${stagePath}.changes[${changeIndex}]`,
+      false
+    ));
+  }
+  if (scene.exclusions !== void 0) {
+    if (!Array.isArray(scene.exclusions)) throw new Error(`${path}.exclusions must be an array.`);
+    scene.exclusions.forEach((exclusion, exclusionIndex) => validateDeconstructedSelection(
+      exclusion,
+      `${path}.exclusions[${exclusionIndex}]`,
+      true
+    ));
+  }
+}
+function validateWalkthroughSteps(scene, path, anchors, connectionIds) {
+  if (!Array.isArray(scene.steps) || scene.steps.length === 0) {
+    throw new Error(`${path} must contain a non-empty steps array.`);
+  }
+  const stepIds = /* @__PURE__ */ new Set();
+  for (const [stepIndex, step] of scene.steps.entries()) {
+    const stepPath = `${path}.steps[${stepIndex}]`;
+    if (!isRecord(step)) throw new Error(`${stepPath} must be an object.`);
+    requireString(step.id, `${stepPath}.id`);
+    requireString(step.title, `${stepPath}.title`);
+    requireString(step.body, `${stepPath}.body`);
+    requireString(step.focus, `${stepPath}.focus`);
+    requireOnlyKeys(step, ["id", "title", "body", "focus", "connection", "depth", "requirement"], stepPath);
+    if (step.depth !== void 0 && !["mentioned", "explained", "contextualized"].includes(String(step.depth))) {
+      throw new Error(`${stepPath}.depth must be mentioned, explained, or contextualized.`);
+    }
+    validateStepRequirement(step.requirement, `${stepPath}.requirement`);
+    if (stepIds.has(step.id)) throw new Error(`Duplicate step id in scene ${scene.id}: ${step.id}`);
+    stepIds.add(step.id);
+    if (!anchors[step.focus]) throw new Error(`${stepPath} references unknown anchor ${step.focus}.`);
+    optionalString(step.connection, `${stepPath}.connection`);
+    if (typeof step.connection === "string" && !connectionIds.has(step.connection)) {
+      throw new Error(`${stepPath} references unknown connection ${step.connection}.`);
+    }
+  }
+}
+function validateDeconstructedSelection(value, path, requiresReason) {
+  if (!isRecord(value)) throw new Error(`${path} must be an object.`);
+  requireOnlyKeys(value, requiresReason ? ["file", "hunks", "reason"] : ["file", "hunks"], path);
+  requireString(value.file, `${path}.file`);
+  if (!requiresReason || value.hunks !== void 0) {
+    requireStringArray(value.hunks, `${path}.hunks`);
+    if (value.hunks.length === 0) throw new Error(`${path}.hunks must not be empty.`);
+  }
+  if (requiresReason) requireString(value.reason, `${path}.reason`);
+}
+function validateRealStack(stack, path, minimum) {
+  if (!Array.isArray(stack) || stack.length < minimum || stack.length > 6) {
+    throw new Error(`${path} must contain between ${minimum} and 6 explicit real revisions.`);
+  }
+  const ids = /* @__PURE__ */ new Set();
+  for (const [index, entry] of stack.entries()) {
+    if (!isRecord(entry)) throw new Error(`${path}[${index}] must be an object.`);
+    requireOnlyKeys(entry, ["id", "ref", "label"], `${path}[${index}]`);
+    requireString(entry.id, `${path}[${index}].id`);
+    requireString(entry.ref, `${path}[${index}].ref`);
+    optionalString(entry.label, `${path}[${index}].label`);
+    if (ids.has(entry.id)) throw new Error(`Duplicate stack entry id: ${entry.id}`);
+    ids.add(entry.id);
+  }
+}
+function validateStackedScene(scene, path, minimum = 3) {
+  requireOnlyKeys(scene, ["id", "kind", "title", "summary", "bullets", "tags", "takeaway", "stack", "files", "steps"], path);
+  if (!Array.isArray(scene.stack) || scene.stack.length < minimum || scene.stack.length > 6) {
+    throw new Error(`${path}.stack must contain between ${minimum} and 6 revisions.`);
+  }
+  const stackIds = /* @__PURE__ */ new Set();
+  for (const [index, entry] of scene.stack.entries()) {
+    const entryPath = `${path}.stack[${index}]`;
+    if (!isRecord(entry)) throw new Error(`${entryPath} must be an object.`);
+    requireOnlyKeys(entry, ["id", "ref", "label"], entryPath);
+    requireString(entry.id, `${entryPath}.id`);
+    requireString(entry.ref, `${entryPath}.ref`);
+    optionalString(entry.label, `${entryPath}.label`);
+    if (stackIds.has(entry.id)) throw new Error(`Duplicate stack entry id: ${entry.id}`);
+    stackIds.add(entry.id);
+  }
+  if (scene.files !== void 0) requireStringArray(scene.files, `${path}.files`);
+  if (!Array.isArray(scene.steps) || scene.steps.length === 0) throw new Error(`${path}.steps must be a non-empty array.`);
+  const stepIds = /* @__PURE__ */ new Set();
+  for (const [index, step] of scene.steps.entries()) {
+    const stepPath = `${path}.steps[${index}]`;
+    if (!isRecord(step)) throw new Error(`${stepPath} must be an object.`);
+    requireOnlyKeys(step, ["id", "title", "body", "file", "pair", "side", "lines"], stepPath);
+    requireString(step.id, `${stepPath}.id`);
+    requireString(step.title, `${stepPath}.title`);
+    requireString(step.body, `${stepPath}.body`);
+    requireString(step.file, `${stepPath}.file`);
+    const stepId = step.id;
+    if (stepIds.has(stepId)) throw new Error(`Duplicate step id in scene ${scene.id}: ${stepId}`);
+    stepIds.add(stepId);
+    if (!Array.isArray(step.pair) || step.pair.length !== 2 || step.pair.some((id) => typeof id !== "string")) {
+      throw new Error(`${stepPath}.pair must contain two stack entry ids.`);
+    }
+    const pair = step.pair;
+    const leftIndex = scene.stack.findIndex((entry) => isRecord(entry) && entry.id === pair[0]);
+    const rightIndex = scene.stack.findIndex((entry) => isRecord(entry) && entry.id === pair[1]);
+    if (leftIndex < 0 || rightIndex !== leftIndex + 1) throw new Error(`${stepPath}.pair must reference adjacent stack entries in order.`);
+    if (step.side !== void 0 && step.side !== "left" && step.side !== "right") throw new Error(`${stepPath}.side must be left or right.`);
+    if (step.lines !== void 0 && (!Array.isArray(step.lines) || step.lines.length !== 2 || step.lines.some((line) => !Number.isInteger(line) || Number(line) < 1) || Number(step.lines[1]) < Number(step.lines[0]))) {
+      throw new Error(`${stepPath}.lines must contain an ordered positive line range.`);
+    }
+  }
+}
+function validateStepRequirement(value, path) {
+  if (value === void 0) return;
+  if (!isRecord(value)) throw new Error(`${path} must be an object.`);
+  requireOnlyKeys(value, ["id", "text", "status", "source", "confidence"], path);
+  requireString(value.id, `${path}.id`);
+  requireString(value.text, `${path}.text`);
+  if (value.status !== void 0 && !["fulfilled", "gap"].includes(String(value.status))) {
+    throw new Error(`${path}.status must be fulfilled or gap.`);
+  }
+  optionalString(value.source, `${path}.source`);
+  if (value.confidence !== void 0 && !["high", "medium", "low"].includes(String(value.confidence))) {
+    throw new Error(`${path}.confidence must be high, medium, or low.`);
+  }
+}
+function validateNarrative(value, path) {
+  requireString(value.summary, `${path}.summary`);
+  requireStringArray(value.bullets, `${path}.bullets`);
+  requireStringArray(value.tags, `${path}.tags`);
+  requireString(value.takeaway, `${path}.takeaway`);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireString(value, path) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`${path} must be a non-empty string.`);
+  }
+}
+function optionalString(value, path) {
+  if (value !== void 0) {
+    requireString(value, path);
+  }
+}
+function requireStringArray(value, path) {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+    throw new Error(`${path} must be an array of strings.`);
+  }
+}
+function requireOnlyKeys(value, allowed, path) {
+  const unexpected = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unexpected.length > 0) {
+    throw new Error(`${path} contains unknown field${unexpected.length === 1 ? "" : "s"}: ${unexpected.join(", ")}`);
+  }
+}
+
 // src/changeTourManifest.ts
-var CHANGE_TOUR_MANIFEST_VERSION = 1;
+var CHANGE_TOUR_MANIFEST_VERSION = 2;
 function parseChangeTourManifest(value) {
-  if (!isRecord(value) || value.version !== CHANGE_TOUR_MANIFEST_VERSION) {
+  if (isRecord2(value) && Number.isInteger(value.version) && Number(value.version) > CHANGE_TOUR_MANIFEST_VERSION) {
+    throw new Error(
+      `This tour uses manifest format version ${value.version}, but this version of Bygone supports up to version ${CHANGE_TOUR_MANIFEST_VERSION}. Upgrade Bygone to open it.`
+    );
+  }
+  if (!isRecord2(value) || value.version !== 1 && value.version !== CHANGE_TOUR_MANIFEST_VERSION) {
     throw new Error(`Unsupported or missing change-tour manifest version.`);
   }
-  requireString(value.title, "title");
-  requireString(value.generatedAt, "generatedAt");
+  requireString2(value.title, "title");
+  requireString2(value.generatedAt, "generatedAt");
   if (value.windowTitle !== void 0) {
-    requireString(value.windowTitle, "windowTitle");
+    requireString2(value.windowTitle, "windowTitle");
   }
   if (value.sourceUrl !== void 0) {
-    requireString(value.sourceUrl, "sourceUrl");
+    requireString2(value.sourceUrl, "sourceUrl");
   }
-  if (!isRecord(value.range)) {
+  if (!isRecord2(value.range)) {
     throw new Error("Change-tour manifest range must be an object.");
   }
   for (const key of ["baseRef", "headRef", "mergeBaseOid", "headOid"]) {
-    requireString(value.range[key], `range.${key}`);
+    requireString2(value.range[key], `range.${key}`);
   }
-  if (!isRecord(value.summary)) {
+  if (!isRecord2(value.summary)) {
     throw new Error("Change-tour manifest summary must be an object.");
   }
   for (const key of ["changedFiles", "includedScenes", "additions", "deletions", "commitCount"]) {
     requireNonNegativeInteger(value.summary[key], `summary.${key}`);
   }
-  requireStringArray(value.summary.omittedFiles, "summary.omittedFiles");
+  requireStringArray2(value.summary.omittedFiles, "summary.omittedFiles");
   if (!Array.isArray(value.commits) || !Array.isArray(value.chapters) || !Array.isArray(value.scenes)) {
     throw new Error("Change-tour manifest commits, chapters, and scenes must be arrays.");
   }
@@ -515,12 +813,12 @@ function parseChangeTourManifest(value) {
     sceneIds.add(candidate.id);
   }
   for (const [index, candidate] of value.chapters.entries()) {
-    if (!isRecord(candidate)) {
+    if (!isRecord2(candidate)) {
       throw new Error(`chapters[${index}] must be an object.`);
     }
-    requireString(candidate.id, `chapters[${index}].id`);
-    requireString(candidate.title, `chapters[${index}].title`);
-    requireStringArray(candidate.sceneIds, `chapters[${index}].sceneIds`);
+    requireString2(candidate.id, `chapters[${index}].id`);
+    requireString2(candidate.title, `chapters[${index}].title`);
+    requireStringArray2(candidate.sceneIds, `chapters[${index}].sceneIds`);
     for (const sceneId of candidate.sceneIds) {
       if (!sceneIds.has(sceneId)) {
         throw new Error(`Chapter references unknown scene id: ${sceneId}`);
@@ -537,16 +835,108 @@ function parseChangeTourManifest(value) {
   if (value.files !== void 0 && value.summary.changedFiles !== files.length) {
     throw new Error("summary.changedFiles must match the number of files.");
   }
+  if (value.authoringCoverage !== void 0) {
+    validateAuthoringCoverage(value.authoringCoverage, value.version);
+  }
+  if (value.version === 2) validateZoom(value);
   return { ...value, files };
 }
+function validateAuthoringCoverage(value, version) {
+  if (!isRecord2(value) || !isRecord2(value.walkthrough) || !Array.isArray(value.explanationAssignments)) {
+    throw new Error("authoringCoverage must contain walkthrough and explanationAssignments.");
+  }
+  const expectedScope = version === 2 ? "final" : "tour";
+  if (value.walkthrough.scope !== expectedScope) {
+    throw new Error(`authoringCoverage.walkthrough.scope must be ${expectedScope}.`);
+  }
+  requireNonNegativeInteger(value.walkthrough.coveredUnits, "authoringCoverage.walkthrough.coveredUnits");
+  requireNonNegativeInteger(value.walkthrough.includedUnits, "authoringCoverage.walkthrough.includedUnits");
+  requirePercentage(value.walkthrough.coveragePercent, "authoringCoverage.walkthrough.coveragePercent");
+  if (value.walkthrough.coveredUnits > value.walkthrough.includedUnits) {
+    throw new Error("authoringCoverage.walkthrough.coveredUnits must not exceed includedUnits.");
+  }
+  for (const [index, assignment] of value.explanationAssignments.entries()) {
+    const path = `authoringCoverage.explanationAssignments[${index}]`;
+    if (!isRecord2(assignment)) throw new Error(`${path} must be an object.`);
+    requireString2(assignment.sceneId, `${path}.sceneId`);
+    requireNonNegativeInteger(assignment.assignedUnits, `${path}.assignedUnits`);
+    requireNonNegativeInteger(assignment.excludedUnits, `${path}.excludedUnits`);
+    requireNonNegativeInteger(assignment.completeUnits, `${path}.completeUnits`);
+    requireNonNegativeInteger(assignment.totalUnits, `${path}.totalUnits`);
+    requirePercentage(assignment.assignmentPercent, `${path}.assignmentPercent`);
+    if (assignment.assignedUnits + assignment.excludedUnits !== assignment.completeUnits || assignment.completeUnits > assignment.totalUnits) {
+      throw new Error(`${path} contains inconsistent unit counts.`);
+    }
+  }
+}
+function validateZoom(value) {
+  if (!isRecord2(value.repository) || typeof value.repository.root !== "string" || !value.repository.root) {
+    throw new Error("A v2 tour requires its originating repository.root.");
+  }
+  if (!isRecord2(value.zoom) || !Array.isArray(value.zoom.revisions) || !isRecord2(value.zoom.final)) {
+    throw new Error("A v2 tour requires zoom metadata and real revision evidence.");
+  }
+  const scenes = value.scenes;
+  const revisions = value.zoom.revisions;
+  const ids = /* @__PURE__ */ new Set();
+  for (const [index, scene] of revisions.entries()) {
+    validateScene(scene, index);
+    if (scene.kind !== "stacked-diff") throw new Error("zoom.revisions must contain real stacked-diff scenes.");
+    if (ids.has(scene.id)) throw new Error(`Duplicate zoom revision scene: ${scene.id}`);
+    ids.add(scene.id);
+    const range = value.range;
+    if (scene.stack[0].oid !== range.mergeBaseOid || scene.stack[scene.stack.length - 1].oid !== range.headOid) {
+      throw new Error(`Revision scene ${scene.id} endpoints must match the final diff range.`);
+    }
+  }
+  for (const scene of scenes) {
+    if (scene.kind !== "deconstructed-diff" && scene.kind !== "stacked-diff") continue;
+    const real = revisions.find((candidate) => candidate.id === scene.id);
+    if (!real) throw new Error(`Scene ${scene.id} is missing its real revision evidence.`);
+    if (scene.kind === "deconstructed-diff" && (real.stack[0].oid !== scene.realRange.baseOid || real.stack[real.stack.length - 1].oid !== scene.realRange.targetOid)) {
+      throw new Error(`Deconstructed scene ${scene.id} real stack endpoints must match its explanation range.`);
+    }
+  }
+  const explanation = scenes.some((scene) => scene.kind === "deconstructed-diff");
+  const distinct = revisions.some((scene) => scene.stack.length > 2);
+  const depth = explanation ? "explanation" : distinct ? "revisions" : "final";
+  const modes = [...explanation ? ["explanation"] : [], ...distinct ? ["revisions"] : [], "final", "history"];
+  if (value.zoom.authoredDepth !== depth || JSON.stringify(value.zoom.modes) !== JSON.stringify(modes)) {
+    throw new Error("zoom depth and modes must match the maximum authored depth.");
+  }
+  if (!Array.isArray(value.files)) throw new Error("A v2 tour requires final endpoint file evidence.");
+  if (!Array.isArray(value.zoom.final.scenes) || !Array.isArray(value.zoom.final.chapters)) {
+    throw new Error("A v2 tour requires a non-stacked final tour.");
+  }
+  const finalSceneIds = /* @__PURE__ */ new Set();
+  for (const [index, scene] of value.zoom.final.scenes.entries()) {
+    validateScene(scene, index);
+    if (scene.kind === "stacked-diff" || scene.kind === "deconstructed-diff") {
+      throw new Error("zoom.final must contain only non-stacked scenes.");
+    }
+    if (finalSceneIds.has(scene.id)) throw new Error(`Duplicate final tour scene: ${scene.id}`);
+    finalSceneIds.add(scene.id);
+  }
+  for (const [index, chapter] of value.zoom.final.chapters.entries()) {
+    if (!isRecord2(chapter) || !Array.isArray(chapter.sceneIds)) {
+      throw new Error(`zoom.final.chapters[${index}] must contain sceneIds.`);
+    }
+    requireString2(chapter.id, `zoom.final.chapters[${index}].id`);
+    requireString2(chapter.title, `zoom.final.chapters[${index}].title`);
+    for (const sceneId of chapter.sceneIds) {
+      requireString2(sceneId, `zoom.final.chapters[${index}].sceneIds`);
+      if (!finalSceneIds.has(sceneId)) throw new Error(`Final tour chapter references unknown scene: ${sceneId}`);
+    }
+  }
+}
 function validateScene(value, index) {
-  if (!isRecord(value) || !["text-diff", "discussion", "walkthrough", "stacked-diff", "deconstructed-diff"].includes(String(value.kind))) {
+  if (!isRecord2(value) || !["text-diff", "discussion", "walkthrough", "stacked-diff", "deconstructed-diff"].includes(String(value.kind))) {
     throw new Error(`scenes[${index}] must be a text-diff, discussion, walkthrough, stacked-diff, or deconstructed-diff scene.`);
   }
   for (const key of ["id", "title"]) {
-    requireString(value[key], `scenes[${index}].${key}`);
+    requireString2(value[key], `scenes[${index}].${key}`);
   }
-  validateNarrative(value, `scenes[${index}]`);
+  validateNarrative2(value, `scenes[${index}]`);
   if (value.kind === "discussion") {
     return;
   }
@@ -556,20 +946,21 @@ function validateScene(value, index) {
     }
     for (const [stepIndex, step] of value.steps.entries()) {
       const path = `scenes[${index}].steps[${stepIndex}]`;
-      if (!isRecord(step) || !isRecord(step.focus) || !isRecord(step.diff)) {
+      if (!isRecord2(step) || !isRecord2(step.focus) || !isRecord2(step.diff)) {
         throw new Error(`${path} must contain focus and diff objects.`);
       }
-      for (const key of ["id", "title", "body"]) requireString(step[key], `${path}.${key}`);
+      for (const key of ["id", "title", "body"]) requireString2(step[key], `${path}.${key}`);
       if (step.depth !== void 0 && !["mentioned", "explained", "contextualized"].includes(String(step.depth))) {
         throw new Error(`${path}.depth must be mentioned, explained, or contextualized.`);
       }
+      validateStepRequirement(step.requirement, `${path}.requirement`);
       validateResolvedAnchor(step.focus, `${path}.focus`);
       validateScene(step.diff, index);
       if (step.diff.kind !== "text-diff") throw new Error(`${path}.diff must be a text-diff scene.`);
       if (step.connection !== void 0) {
-        if (!isRecord(step.connection)) throw new Error(`${path}.connection must be an object.`);
-        requireString(step.connection.id, `${path}.connection.id`);
-        requireString(step.connection.label, `${path}.connection.label`);
+        if (!isRecord2(step.connection)) throw new Error(`${path}.connection must be an object.`);
+        requireString2(step.connection.id, `${path}.connection.id`);
+        requireString2(step.connection.label, `${path}.connection.label`);
         validateResolvedAnchor(step.connection.from, `${path}.connection.from`);
         validateResolvedAnchor(step.connection.to, `${path}.connection.to`);
       }
@@ -577,68 +968,68 @@ function validateScene(value, index) {
     return;
   }
   if (value.kind === "stacked-diff") {
-    validateStackedScene(value, index);
+    validateStackedScene2(value, index);
     return;
   }
   if (value.kind === "deconstructed-diff") {
-    validateDeconstructedScene(value, index);
+    validateDeconstructedScene2(value, index);
     return;
   }
   for (const key of ["path", "leftLabel", "rightLabel", "leftContent", "rightContent"]) {
-    requireString(value[key], `scenes[${index}].${key}`);
+    requireString2(value[key], `scenes[${index}].${key}`);
   }
   if (value.previousPath !== void 0) {
-    requireString(value.previousPath, `scenes[${index}].previousPath`);
+    requireString2(value.previousPath, `scenes[${index}].previousPath`);
   }
-  requireString(value.changeKind, `scenes[${index}].changeKind`);
+  requireString2(value.changeKind, `scenes[${index}].changeKind`);
   requireNonNegativeInteger(value.additions, `scenes[${index}].additions`);
   requireNonNegativeInteger(value.deletions, `scenes[${index}].deletions`);
   if (value.focusChangeIndex !== void 0) {
     requireNonNegativeInteger(value.focusChangeIndex, `scenes[${index}].focusChangeIndex`);
   }
 }
-function validateStackedScene(value, index) {
-  if (!Array.isArray(value.stack) || value.stack.length < 3 || value.stack.length > 6) {
-    throw new Error(`scenes[${index}].stack must contain between 3 and 6 revisions.`);
+function validateStackedScene2(value, index) {
+  if (!Array.isArray(value.stack) || value.stack.length < 2 || value.stack.length > 6) {
+    throw new Error(`scenes[${index}].stack must contain between 2 and 6 revisions.`);
   }
   for (const [panelIndex, panel] of value.stack.entries()) {
-    if (!isRecord(panel)) throw new Error(`scenes[${index}].stack[${panelIndex}] must be an object.`);
-    for (const key of ["id", "ref", "oid", "label"]) requireString(panel[key], `scenes[${index}].stack[${panelIndex}].${key}`);
+    if (!isRecord2(panel)) throw new Error(`scenes[${index}].stack[${panelIndex}] must be an object.`);
+    for (const key of ["id", "ref", "oid", "label"]) requireString2(panel[key], `scenes[${index}].stack[${panelIndex}].${key}`);
   }
   validateMultiPanelFiles(value.files, value.stack.length, index);
   validateMultiPanelSteps(value.steps, value.stack.length, index, false);
 }
-function validateDeconstructedScene(value, index) {
+function validateDeconstructedScene2(value, index) {
   if (value.stageLabel !== "Explanation stages") {
     throw new Error(`scenes[${index}].stageLabel must be Explanation stages.`);
   }
-  if (!isRecord(value.realRange)) throw new Error(`scenes[${index}].realRange must be an object.`);
+  if (!isRecord2(value.realRange)) throw new Error(`scenes[${index}].realRange must be an object.`);
   for (const key of ["baseRef", "targetRef", "baseOid", "targetOid"]) {
-    requireString(value.realRange[key], `scenes[${index}].realRange.${key}`);
+    requireString2(value.realRange[key], `scenes[${index}].realRange.${key}`);
   }
   if (!Array.isArray(value.panels) || value.panels.length < 2 || value.panels.length > 13) {
     throw new Error(`scenes[${index}].panels must contain a baseline and between 1 and 12 stages.`);
   }
   const panels = value.panels;
   for (const [panelIndex, panel] of panels.entries()) {
-    if (!isRecord(panel)) throw new Error(`scenes[${index}].panels[${panelIndex}] must be an object.`);
-    for (const key of ["id", "label", "role"]) requireString(panel[key], `scenes[${index}].panels[${panelIndex}].${key}`);
+    if (!isRecord2(panel)) throw new Error(`scenes[${index}].panels[${panelIndex}] must be an object.`);
+    for (const key of ["id", "label", "role"]) requireString2(panel[key], `scenes[${index}].panels[${panelIndex}].${key}`);
     const expectedRole = panelIndex === 0 ? "baseline" : "stage";
     if (panel.role !== expectedRole) throw new Error(`scenes[${index}].panels[${panelIndex}].role must be ${expectedRole}.`);
-    if (panelIndex > 0) requireString(panel.stageId, `scenes[${index}].panels[${panelIndex}].stageId`);
+    if (panelIndex > 0) requireString2(panel.stageId, `scenes[${index}].panels[${panelIndex}].stageId`);
   }
   validateMultiPanelFiles(value.files, panels.length, index);
   validateMultiPanelSteps(value.steps, panels.length, index, true);
   if (Array.isArray(value.steps)) {
     let previousPairIndex = -1;
     value.steps.forEach((step, stepIndex) => {
-      if (!isRecord(step)) return;
+      if (!isRecord2(step)) return;
       const pairIndex = Number(step.pairIndex);
       if (pairIndex < previousPairIndex) {
         throw new Error(`scenes[${index}].steps must remain grouped in explanation stage order.`);
       }
       previousPairIndex = pairIndex;
-      if (step.stageId !== void 0) requireString(step.stageId, `scenes[${index}].steps[${stepIndex}].stageId`);
+      if (step.stageId !== void 0) requireString2(step.stageId, `scenes[${index}].steps[${stepIndex}].stageId`);
       if (step.stageIndex !== void 0) requireNonNegativeInteger(step.stageIndex, `scenes[${index}].steps[${stepIndex}].stageIndex`);
       if (step.focusIndex !== void 0) requireNonNegativeInteger(step.focusIndex, `scenes[${index}].steps[${stepIndex}].focusIndex`);
       if (step.focusCount !== void 0) requirePositiveInteger(step.focusCount, `scenes[${index}].steps[${stepIndex}].focusCount`);
@@ -651,14 +1042,14 @@ function validateDeconstructedScene(value, index) {
     });
     for (let stageIndex = 0; stageIndex < panels.length - 1; stageIndex += 1) {
       const panel = panels[stageIndex + 1];
-      const stageSteps = value.steps.filter((step) => isRecord(step) && Number(step.pairIndex) === stageIndex);
-      if (!isRecord(panel) || stageSteps.length === 0) {
+      const stageSteps = value.steps.filter((step) => isRecord2(step) && Number(step.pairIndex) === stageIndex);
+      if (!isRecord2(panel) || stageSteps.length === 0) {
         throw new Error(`scenes[${index}].steps must cover every explanation stage.`);
       }
       const firstStep = stageSteps[0];
-      const fallbackStageId = isRecord(firstStep) ? firstStep.id : void 0;
+      const fallbackStageId = isRecord2(firstStep) ? firstStep.id : void 0;
       if (stageSteps.some((step) => {
-        if (!isRecord(step)) return true;
+        if (!isRecord2(step)) return true;
         return (step.stageId ?? fallbackStageId) !== panel.stageId;
       })) {
         throw new Error(`scenes[${index}].panels must align with explanation stage ids.`);
@@ -669,15 +1060,15 @@ function validateDeconstructedScene(value, index) {
 function validateMultiPanelFiles(value, panelCount, index) {
   if (!Array.isArray(value) || value.length === 0) throw new Error(`scenes[${index}].files must be non-empty.`);
   for (const [fileIndex, file] of value.entries()) {
-    if (!isRecord(file)) throw new Error(`scenes[${index}].files[${fileIndex}] must be an object.`);
-    requireString(file.path, `scenes[${index}].files[${fileIndex}].path`);
+    if (!isRecord2(file)) throw new Error(`scenes[${index}].files[${fileIndex}] must be an object.`);
+    requireString2(file.path, `scenes[${index}].files[${fileIndex}].path`);
     if (!Array.isArray(file.panels) || file.panels.length !== panelCount) {
       throw new Error(`scenes[${index}].files[${fileIndex}].panels must match panel count.`);
     }
     for (const [panelIndex, panel] of file.panels.entries()) {
-      if (!isRecord(panel)) throw new Error(`scenes[${index}].files[${fileIndex}].panels[${panelIndex}] must be an object.`);
-      for (const key of ["id", "label", "content"]) requireString(panel[key], `scenes[${index}].files[${fileIndex}].panels[${panelIndex}].${key}`);
-      if (panel.path !== void 0) requireString(panel.path, `scenes[${index}].files[${fileIndex}].panels[${panelIndex}].path`);
+      if (!isRecord2(panel)) throw new Error(`scenes[${index}].files[${fileIndex}].panels[${panelIndex}] must be an object.`);
+      for (const key of ["id", "label", "content"]) requireString2(panel[key], `scenes[${index}].files[${fileIndex}].panels[${panelIndex}].${key}`);
+      if (panel.path !== void 0) requireString2(panel.path, `scenes[${index}].files[${fileIndex}].panels[${panelIndex}].path`);
       if (typeof panel.exists !== "boolean") throw new Error(`scenes[${index}].files[${fileIndex}].panels[${panelIndex}].exists must be boolean.`);
     }
   }
@@ -685,12 +1076,12 @@ function validateMultiPanelFiles(value, panelCount, index) {
 function validateMultiPanelSteps(value, panelCount, index, deconstructed) {
   if (!Array.isArray(value) || value.length === 0) throw new Error(`scenes[${index}].steps must be non-empty.`);
   for (const [stepIndex, step] of value.entries()) {
-    if (!isRecord(step)) throw new Error(`scenes[${index}].steps[${stepIndex}] must be an object.`);
-    for (const key of ["id", "title", "body", "file", "side"]) requireString(step[key], `scenes[${index}].steps[${stepIndex}].${key}`);
+    if (!isRecord2(step)) throw new Error(`scenes[${index}].steps[${stepIndex}] must be an object.`);
+    for (const key of ["id", "title", "body", "file", "side"]) requireString2(step[key], `scenes[${index}].steps[${stepIndex}].${key}`);
     requireNonNegativeInteger(step.pairIndex, `scenes[${index}].steps[${stepIndex}].pairIndex`);
     if (Number(step.pairIndex) >= panelCount - 1) throw new Error(`scenes[${index}].steps[${stepIndex}].pairIndex is outside the panels.`);
     if (deconstructed) {
-      requireStringArray(step.introducedHunks, `scenes[${index}].steps[${stepIndex}].introducedHunks`);
+      requireStringArray2(step.introducedHunks, `scenes[${index}].steps[${stepIndex}].introducedHunks`);
       if (step.introducedHunks.length === 0) throw new Error(`scenes[${index}].steps[${stepIndex}].introducedHunks must be non-empty.`);
     }
     if (step.side !== "left" && step.side !== "right") throw new Error(`scenes[${index}].steps[${stepIndex}].side must be left or right.`);
@@ -699,7 +1090,7 @@ function validateMultiPanelSteps(value, panelCount, index, deconstructed) {
   }
 }
 function validateTourFile(value, index) {
-  if (!isRecord(value)) throw new Error(`files[${index}] must be an object.`);
+  if (!isRecord2(value)) throw new Error(`files[${index}] must be an object.`);
   if (value.kind === "text-diff") {
     validateScene(value, index);
     return;
@@ -708,9 +1099,9 @@ function validateTourFile(value, index) {
     throw new Error(`files[${index}].kind must be text-diff or omitted.`);
   }
   for (const key of ["id", "title", "path", "changeKind", "reason"]) {
-    requireString(value[key], `files[${index}].${key}`);
+    requireString2(value[key], `files[${index}].${key}`);
   }
-  if (value.previousPath !== void 0) requireString(value.previousPath, `files[${index}].previousPath`);
+  if (value.previousPath !== void 0) requireString2(value.previousPath, `files[${index}].previousPath`);
   requireNonNegativeInteger(value.additions, `files[${index}].additions`);
   requireNonNegativeInteger(value.deletions, `files[${index}].deletions`);
 }
@@ -730,263 +1121,13 @@ function collectLegacyTourFiles(scenes) {
   return [...files.values()].sort((left, right) => left.path.localeCompare(right.path));
 }
 function validateResolvedAnchor(value, path) {
-  if (!isRecord(value)) throw new Error(`${path} must be an object.`);
-  for (const key of ["id", "path", "revision", "excerpt"]) requireString(value[key], `${path}.${key}`);
+  if (!isRecord2(value)) throw new Error(`${path} must be an object.`);
+  for (const key of ["id", "path", "revision", "excerpt"]) requireString2(value[key], `${path}.${key}`);
   if (value.revision !== "base" && value.revision !== "head") throw new Error(`${path}.revision must be base or head.`);
   requirePositiveInteger(value.startLine, `${path}.startLine`);
   requirePositiveInteger(value.endLine, `${path}.endLine`);
   if (Number(value.endLine) < Number(value.startLine)) throw new Error(`${path}.endLine must not precede startLine.`);
 }
-function validateNarrative(value, path) {
-  requireString(value.summary, `${path}.summary`);
-  requireStringArray(value.bullets, `${path}.bullets`);
-  requireStringArray(value.tags, `${path}.tags`);
-  requireString(value.takeaway, `${path}.takeaway`);
-}
-function isRecord(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function requireString(value, path) {
-  if (typeof value !== "string") {
-    throw new Error(`${path} must be a string.`);
-  }
-}
-function requireStringArray(value, path) {
-  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
-    throw new Error(`${path} must be an array of strings.`);
-  }
-}
-function requireNonNegativeInteger(value, path) {
-  if (!Number.isInteger(value) || Number(value) < 0) {
-    throw new Error(`${path} must be a non-negative integer.`);
-  }
-}
-function requirePositiveInteger(value, path) {
-  if (!Number.isInteger(value) || Number(value) < 1) throw new Error(`${path} must be a positive integer.`);
-}
-
-// src/changeTourSource.ts
-var CHANGE_TOUR_SOURCE_VERSION = 1;
-function parseChangeTourSource(value) {
-  if (!isRecord2(value) || value.version !== CHANGE_TOUR_SOURCE_VERSION) {
-    throw new Error("Unsupported or missing change-tour source version.");
-  }
-  requireOnlyKeys(value, ["version", "title", "windowTitle", "sourceUrl", "range", "anchors", "connections", "chapters", "coverage"], "source");
-  optionalString(value.title, "title");
-  optionalString(value.windowTitle, "windowTitle");
-  optionalString(value.sourceUrl, "sourceUrl");
-  if (value.range !== void 0) {
-    if (!isRecord2(value.range)) throw new Error("range must be an object.");
-    requireOnlyKeys(value.range, ["base", "head"], "range");
-    requireString2(value.range.base, "range.base");
-    requireString2(value.range.head, "range.head");
-  }
-  if (value.coverage !== void 0) {
-    if (!isRecord2(value.coverage) || !Array.isArray(value.coverage.exclusions)) {
-      throw new Error("coverage must contain an exclusions array.");
-    }
-    requireOnlyKeys(value.coverage, ["exclusions"], "coverage");
-    for (const [index, exclusion] of value.coverage.exclusions.entries()) {
-      const exclusionPath = `coverage.exclusions[${index}]`;
-      if (!isRecord2(exclusion)) throw new Error(`${exclusionPath} must be an object.`);
-      requireOnlyKeys(exclusion, ["path", "hunks", "reason"], exclusionPath);
-      requireString2(exclusion.path, `${exclusionPath}.path`);
-      requireString2(exclusion.reason, `${exclusionPath}.reason`);
-      if (exclusion.hunks !== void 0) requireStringArray2(exclusion.hunks, `${exclusionPath}.hunks`);
-    }
-  }
-  if (!isRecord2(value.anchors)) {
-    throw new Error("anchors must be an object.");
-  }
-  for (const [id, anchor] of Object.entries(value.anchors)) {
-    if (!isRecord2(anchor)) {
-      throw new Error(`anchors.${id} must be an object.`);
-    }
-    requireOnlyKeys(anchor, ["file", "revision", "contains", "occurrence"], `anchors.${id}`);
-    requireString2(anchor.file, `anchors.${id}.file`);
-    if (anchor.revision !== "base" && anchor.revision !== "head") {
-      throw new Error(`anchors.${id}.revision must be base or head.`);
-    }
-    requireString2(anchor.contains, `anchors.${id}.contains`);
-    if (anchor.occurrence !== void 0 && (!Number.isInteger(anchor.occurrence) || Number(anchor.occurrence) < 1)) {
-      throw new Error(`anchors.${id}.occurrence must be a positive integer.`);
-    }
-  }
-  const rawConnections = Array.isArray(value.connections) ? value.connections : isRecord2(value.connections) ? Object.entries(value.connections).map(([id, connection]) => isRecord2(connection) ? { id, ...connection } : connection) : null;
-  if (!rawConnections || !Array.isArray(value.chapters) || value.chapters.length === 0) {
-    throw new Error("connections must be an array or object, and chapters must be a non-empty array.");
-  }
-  const connectionIds = /* @__PURE__ */ new Set();
-  for (const [index, connection] of rawConnections.entries()) {
-    if (!isRecord2(connection)) {
-      throw new Error(`connections[${index}] must be an object.`);
-    }
-    requireOnlyKeys(connection, ["id", "from", "to", "label"], `connections[${index}]`);
-    requireString2(connection.id, `connections[${index}].id`);
-    requireString2(connection.from, `connections[${index}].from`);
-    requireString2(connection.to, `connections[${index}].to`);
-    requireString2(connection.label, `connections[${index}].label`);
-    const { id, from, to } = connection;
-    if (!value.anchors[from] || !value.anchors[to]) {
-      throw new Error(`Connection ${id} references an unknown anchor.`);
-    }
-    if (connectionIds.has(id)) {
-      throw new Error(`Duplicate connection id: ${id}`);
-    }
-    connectionIds.add(id);
-  }
-  const chapterIds = /* @__PURE__ */ new Set();
-  const sceneIds = /* @__PURE__ */ new Set();
-  for (const [chapterIndex, chapter] of value.chapters.entries()) {
-    if (!isRecord2(chapter) || !Array.isArray(chapter.scenes) || chapter.scenes.length === 0) {
-      throw new Error(`chapters[${chapterIndex}] must contain a non-empty scenes array.`);
-    }
-    requireString2(chapter.id, `chapters[${chapterIndex}].id`);
-    requireString2(chapter.title, `chapters[${chapterIndex}].title`);
-    requireOnlyKeys(chapter, ["id", "title", "scenes"], `chapters[${chapterIndex}]`);
-    if (chapterIds.has(chapter.id)) throw new Error(`Duplicate chapter id: ${chapter.id}`);
-    chapterIds.add(chapter.id);
-    for (const [sceneIndex, scene] of chapter.scenes.entries()) {
-      const path = `chapters[${chapterIndex}].scenes[${sceneIndex}]`;
-      if (!isRecord2(scene)) throw new Error(`${path} must be an object.`);
-      requireString2(scene.id, `${path}.id`);
-      requireString2(scene.title, `${path}.title`);
-      if (sceneIds.has(scene.id)) throw new Error(`Duplicate scene id: ${scene.id}`);
-      sceneIds.add(scene.id);
-      validateNarrative2(scene, path);
-      if (scene.kind === "deconstructed-diff") {
-        validateDeconstructedScene2(scene, path);
-        continue;
-      }
-      if (!Array.isArray(scene.steps) || scene.steps.length === 0) {
-        throw new Error(`${path} must contain a non-empty steps array.`);
-      }
-      if (scene.kind === "stacked-diff") {
-        validateStackedScene2(scene, path);
-        continue;
-      }
-      if (scene.kind !== void 0 && scene.kind !== "walkthrough") {
-        throw new Error(`${path}.kind must be walkthrough, stacked-diff, or deconstructed-diff.`);
-      }
-      requireOnlyKeys(scene, ["id", "kind", "title", "summary", "bullets", "tags", "takeaway", "steps"], path);
-      const stepIds = /* @__PURE__ */ new Set();
-      for (const [stepIndex, step] of scene.steps.entries()) {
-        const stepPath = `${path}.steps[${stepIndex}]`;
-        if (!isRecord2(step)) {
-          throw new Error(`${stepPath} must be an object.`);
-        }
-        requireString2(step.id, `${stepPath}.id`);
-        requireString2(step.title, `${stepPath}.title`);
-        requireString2(step.body, `${stepPath}.body`);
-        requireString2(step.focus, `${stepPath}.focus`);
-        requireOnlyKeys(step, ["id", "title", "body", "focus", "connection", "depth"], stepPath);
-        if (step.depth !== void 0 && !["mentioned", "explained", "contextualized"].includes(String(step.depth))) {
-          throw new Error(`${stepPath}.depth must be mentioned, explained, or contextualized.`);
-        }
-        if (stepIds.has(step.id)) throw new Error(`Duplicate step id in scene ${scene.id}: ${step.id}`);
-        stepIds.add(step.id);
-        const focus = step.focus;
-        if (!value.anchors[focus]) {
-          throw new Error(`${stepPath} references unknown anchor ${focus}.`);
-        }
-        optionalString(step.connection, `${stepPath}.connection`);
-        const connection = step.connection;
-        if (typeof connection === "string" && !connectionIds.has(connection)) {
-          throw new Error(`${stepPath} references unknown connection ${connection}.`);
-        }
-      }
-    }
-  }
-  return { ...value, connections: rawConnections };
-}
-function validateDeconstructedScene2(scene, path) {
-  requireOnlyKeys(scene, ["id", "kind", "title", "summary", "bullets", "tags", "takeaway", "base", "target", "stages", "exclusions"], path);
-  optionalString(scene.base, `${path}.base`);
-  optionalString(scene.target, `${path}.target`);
-  if (!Array.isArray(scene.stages) || scene.stages.length === 0 || scene.stages.length > 12) {
-    throw new Error(`${path}.stages must contain between 1 and 12 stages.`);
-  }
-  const stageIds = /* @__PURE__ */ new Set();
-  for (const [stageIndex, stage] of scene.stages.entries()) {
-    const stagePath = `${path}.stages[${stageIndex}]`;
-    if (!isRecord2(stage)) throw new Error(`${stagePath} must be an object.`);
-    requireOnlyKeys(stage, ["id", "title", "narration", "changes"], stagePath);
-    requireString2(stage.id, `${stagePath}.id`);
-    requireString2(stage.title, `${stagePath}.title`);
-    requireString2(stage.narration, `${stagePath}.narration`);
-    if (!Array.isArray(stage.changes) || stage.changes.length === 0) {
-      throw new Error(`${stagePath}.changes must be a non-empty array.`);
-    }
-    if (stageIds.has(stage.id)) throw new Error(`Duplicate deconstructed stage id: ${stage.id}`);
-    stageIds.add(stage.id);
-    stage.changes.forEach((change, changeIndex) => validateDeconstructedSelection(
-      change,
-      `${stagePath}.changes[${changeIndex}]`,
-      false
-    ));
-  }
-  if (scene.exclusions !== void 0) {
-    if (!Array.isArray(scene.exclusions)) throw new Error(`${path}.exclusions must be an array.`);
-    scene.exclusions.forEach((exclusion, exclusionIndex) => validateDeconstructedSelection(
-      exclusion,
-      `${path}.exclusions[${exclusionIndex}]`,
-      true
-    ));
-  }
-}
-function validateDeconstructedSelection(value, path, requiresReason) {
-  if (!isRecord2(value)) throw new Error(`${path} must be an object.`);
-  requireOnlyKeys(value, requiresReason ? ["file", "hunks", "reason"] : ["file", "hunks"], path);
-  requireString2(value.file, `${path}.file`);
-  if (!requiresReason || value.hunks !== void 0) {
-    requireStringArray2(value.hunks, `${path}.hunks`);
-    if (value.hunks.length === 0) throw new Error(`${path}.hunks must not be empty.`);
-  }
-  if (requiresReason) requireString2(value.reason, `${path}.reason`);
-}
-function validateStackedScene2(scene, path) {
-  requireOnlyKeys(scene, ["id", "kind", "title", "summary", "bullets", "tags", "takeaway", "stack", "files", "steps"], path);
-  if (!Array.isArray(scene.stack) || scene.stack.length < 3 || scene.stack.length > 6) {
-    throw new Error(`${path}.stack must contain between 3 and 6 revisions.`);
-  }
-  const stackIds = /* @__PURE__ */ new Set();
-  for (const [index, entry] of scene.stack.entries()) {
-    const entryPath = `${path}.stack[${index}]`;
-    if (!isRecord2(entry)) throw new Error(`${entryPath} must be an object.`);
-    requireOnlyKeys(entry, ["id", "ref", "label"], entryPath);
-    requireString2(entry.id, `${entryPath}.id`);
-    requireString2(entry.ref, `${entryPath}.ref`);
-    optionalString(entry.label, `${entryPath}.label`);
-    if (stackIds.has(entry.id)) throw new Error(`Duplicate stack entry id: ${entry.id}`);
-    stackIds.add(entry.id);
-  }
-  if (scene.files !== void 0) requireStringArray2(scene.files, `${path}.files`);
-  if (!Array.isArray(scene.steps) || scene.steps.length === 0) throw new Error(`${path}.steps must be a non-empty array.`);
-  const stepIds = /* @__PURE__ */ new Set();
-  for (const [index, step] of scene.steps.entries()) {
-    const stepPath = `${path}.steps[${index}]`;
-    if (!isRecord2(step)) throw new Error(`${stepPath} must be an object.`);
-    requireOnlyKeys(step, ["id", "title", "body", "file", "pair", "side", "lines"], stepPath);
-    requireString2(step.id, `${stepPath}.id`);
-    requireString2(step.title, `${stepPath}.title`);
-    requireString2(step.body, `${stepPath}.body`);
-    requireString2(step.file, `${stepPath}.file`);
-    const stepId = step.id;
-    if (stepIds.has(stepId)) throw new Error(`Duplicate step id in scene ${scene.id}: ${stepId}`);
-    stepIds.add(stepId);
-    if (!Array.isArray(step.pair) || step.pair.length !== 2 || step.pair.some((id) => typeof id !== "string")) {
-      throw new Error(`${stepPath}.pair must contain two stack entry ids.`);
-    }
-    const pair = step.pair;
-    const leftIndex = scene.stack.findIndex((entry) => isRecord2(entry) && entry.id === pair[0]);
-    const rightIndex = scene.stack.findIndex((entry) => isRecord2(entry) && entry.id === pair[1]);
-    if (leftIndex < 0 || rightIndex !== leftIndex + 1) throw new Error(`${stepPath}.pair must reference adjacent stack entries in order.`);
-    if (step.side !== void 0 && step.side !== "left" && step.side !== "right") throw new Error(`${stepPath}.side must be left or right.`);
-    if (step.lines !== void 0 && (!Array.isArray(step.lines) || step.lines.length !== 2 || step.lines.some((line) => !Number.isInteger(line) || Number(line) < 1) || Number(step.lines[1]) < Number(step.lines[0]))) {
-      throw new Error(`${stepPath}.lines must contain an ordered positive line range.`);
-    }
-  }
-}
 function validateNarrative2(value, path) {
   requireString2(value.summary, `${path}.summary`);
   requireStringArray2(value.bullets, `${path}.bullets`);
@@ -997,13 +1138,8 @@ function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function requireString2(value, path) {
-  if (typeof value !== "string" || value.length === 0) {
-    throw new Error(`${path} must be a non-empty string.`);
-  }
-}
-function optionalString(value, path) {
-  if (value !== void 0) {
-    requireString2(value, path);
+  if (typeof value !== "string") {
+    throw new Error(`${path} must be a string.`);
   }
 }
 function requireStringArray2(value, path) {
@@ -1011,12 +1147,19 @@ function requireStringArray2(value, path) {
     throw new Error(`${path} must be an array of strings.`);
   }
 }
-function requireOnlyKeys(value, allowed, path) {
-  const unexpected = Object.keys(value).filter((key) => !allowed.includes(key));
-  if (unexpected.length > 0) {
-    throw new Error(`${path} contains unknown field${unexpected.length === 1 ? "" : "s"}: ${unexpected.join(", ")}`);
+function requireNonNegativeInteger(value, path) {
+  if (!Number.isInteger(value) || Number(value) < 0) {
+    throw new Error(`${path} must be a non-negative integer.`);
+  }
+}
+function requirePercentage(value, path) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 100) {
+    throw new Error(`${path} must be a number from 0 to 100.`);
   }
 }
+function requirePositiveInteger(value, path) {
+  if (!Number.isInteger(value) || Number(value) < 1) throw new Error(`${path} must be a positive integer.`);
+}
 
 // src/deconstructedChange.ts
 function buildDeconstructedScene(startPath, scene, options = {}) {
@@ -1551,12 +1694,20 @@ var DIFF_TIMEOUT_MS = readPositiveIntegerEnv("BYGONE_DIFF_TIMEOUT_MS", DEFAULT_D
 function buildTwoWayDiffModel(leftContent, rightContent, options = {}) {
   const leftLines = normalizeLines(leftContent);
   const rightLines = normalizeLines(rightContent);
-  const changes = diffArrays(leftLines, rightLines, {
+  if (leftContent === rightContent) {
+    return buildIdenticalTwoWayDiffModel(leftLines);
+  }
+  const interned = internDiffLines(leftLines, rightLines);
+  const internedChanges = diffArrays(interned.left, interned.right, {
     timeout: options.timeoutMs ?? DIFF_TIMEOUT_MS
   });
-  if (!changes) {
+  if (!internedChanges) {
     return buildConservativeTwoWayDiffModel(leftLines, rightLines);
   }
+  const changes = internedChanges.map((change) => ({
+    ...change,
+    value: change.value.map((lineId) => interned.lines[lineId])
+  }));
   const rows = [];
   const renderedLeftLines = [];
   const renderedRightLines = [];
@@ -1580,29 +1731,18 @@ function buildTwoWayDiffModel(leftContent, rightContent, options = {}) {
     }
     if (change.removed && index + 1 < changes.length && changes[index + 1].added) {
       const nextChange = changes[index + 1];
-      const leftStart = renderedLeftLines.length;
-      const rightStart = renderedRightLines.length;
-      const alignedLines = alignReplacementLines(removedLines, nextChange.value);
-      for (const { left: removedLine, right: addedLine } of alignedLines) {
-        let renderedLeftLine;
-        let renderedRightLine;
-        if (removedLine !== void 0) {
-          renderedLeftLine = makeDiffLine("removed", removedLine, leftLineNumber);
-          renderedLeftLines.push(renderedLeftLine);
-        }
-        if (addedLine !== void 0) {
-          renderedRightLine = makeDiffLine("added", addedLine, rightLineNumber);
-          renderedRightLines.push(renderedRightLine);
-        }
-        if (renderedLeftLine && renderedRightLine) {
-          applyInlineHighlightPair(renderedLeftLine, renderedRightLine);
-        }
-        rows.push(makeDiffRow(
-          removedLine === void 0 ? makePlaceholder() : makeDiffCell("removed", removedLine, leftLineNumber++),
-          addedLine === void 0 ? makePlaceholder() : makeDiffCell("added", addedLine, rightLineNumber++)
-        ));
-      }
-      blocks.push(makeDiffBlock("replace", leftStart, renderedLeftLines.length, rightStart, renderedRightLines.length));
+      const nextLineNumbers = appendReplacementCandidate(
+        removedLines,
+        nextChange.value,
+        leftLineNumber,
+        rightLineNumber,
+        rows,
+        renderedLeftLines,
+        renderedRightLines,
+        blocks
+      );
+      leftLineNumber = nextLineNumbers.left;
+      rightLineNumber = nextLineNumbers.right;
       index++;
       continue;
     }
@@ -1638,7 +1778,40 @@ function buildTwoWayDiffModel(leftContent, rightContent, options = {}) {
     leftLines: renderedLeftLines,
     rightLines: renderedRightLines,
     blocks,
-    hasChanges
+    hasChanges,
+    quality: "exact"
+  };
+}
+function internDiffLines(leftLines, rightLines) {
+  const lineIds = /* @__PURE__ */ new Map();
+  const lines = [];
+  const intern = (line) => {
+    const existingId = lineIds.get(line);
+    if (existingId !== void 0) {
+      return existingId;
+    }
+    const lineId = lines.length;
+    lineIds.set(line, lineId);
+    lines.push(line);
+    return lineId;
+  };
+  return {
+    left: leftLines.map(intern),
+    right: rightLines.map(intern),
+    lines
+  };
+}
+function buildIdenticalTwoWayDiffModel(lines) {
+  return {
+    rows: lines.map((line, index) => makeDiffRow(
+      makeDiffCell("context", line, index + 1),
+      makeDiffCell("context", line, index + 1)
+    )),
+    leftLines: lines.map((line, index) => makeDiffLine("context", line, index + 1)),
+    rightLines: lines.map((line, index) => makeDiffLine("context", line, index + 1)),
+    blocks: [],
+    hasChanges: false,
+    quality: "exact"
   };
 }
 function buildConservativeTwoWayDiffModel(leftLines, rightLines) {
@@ -1665,7 +1838,8 @@ function buildConservativeTwoWayDiffModel(leftLines, rightLines) {
     leftLines: renderedLeftLines,
     rightLines: renderedRightLines,
     blocks: rows.length === 0 ? [] : [makeDiffBlock(blockKind, 0, leftLines.length, 0, rightLines.length)],
-    hasChanges: rows.length > 0
+    hasChanges: rows.length > 0,
+    quality: "fallback"
   };
 }
 function normalizeLines(content) {
@@ -1678,6 +1852,100 @@ function normalizeLines(content) {
   }
   return lines;
 }
+function appendReplacementCandidate(leftLines, rightLines, initialLeftLineNumber, initialRightLineNumber, rows, renderedLeftLines, renderedRightLines, blocks) {
+  const aligned = alignReplacementLines(leftLines, rightLines);
+  const crediblePairs = aligned.filter((row) => row.left !== void 0 && row.right !== void 0 && hasCredibleLineCorrespondence(row.left, row.right)).length;
+  const coherentBlock = hasCoherentBlockCorrespondence(leftLines, rightLines, crediblePairs);
+  const normalized = aligned.flatMap((row) => {
+    if (row.left === void 0 || row.right === void 0 || hasCredibleLineCorrespondence(row.left, row.right)) {
+      return [row];
+    }
+    return [{ left: row.left }, { right: row.right }];
+  });
+  let leftLineNumber = initialLeftLineNumber;
+  let rightLineNumber = initialRightLineNumber;
+  let blockKind;
+  let blockLeftStart = renderedLeftLines.length;
+  let blockRightStart = renderedRightLines.length;
+  const flushBlock = () => {
+    if (!blockKind) return;
+    blocks.push(makeDiffBlock(
+      blockKind,
+      blockLeftStart,
+      renderedLeftLines.length,
+      blockRightStart,
+      renderedRightLines.length
+    ));
+  };
+  for (const { left, right } of normalized) {
+    const nextKind = coherentBlock ? "replace" : left !== void 0 && right !== void 0 ? "replace" : left !== void 0 ? "delete" : "insert";
+    if (blockKind !== nextKind) {
+      flushBlock();
+      blockKind = nextKind;
+      blockLeftStart = renderedLeftLines.length;
+      blockRightStart = renderedRightLines.length;
+    }
+    let renderedLeftLine;
+    let renderedRightLine;
+    if (left !== void 0) {
+      renderedLeftLine = makeDiffLine("removed", left, leftLineNumber);
+      renderedLeftLines.push(renderedLeftLine);
+    }
+    if (right !== void 0) {
+      renderedRightLine = makeDiffLine("added", right, rightLineNumber);
+      renderedRightLines.push(renderedRightLine);
+    }
+    if (renderedLeftLine && renderedRightLine) {
+      applyInlineHighlightPair(renderedLeftLine, renderedRightLine);
+    } else if (coherentBlock) {
+      if (renderedLeftLine) applyFullLineHighlight(renderedLeftLine);
+      if (renderedRightLine) applyFullLineHighlight(renderedRightLine);
+    }
+    rows.push(makeDiffRow(
+      left === void 0 ? makePlaceholder() : makeDiffCell("removed", left, leftLineNumber++),
+      right === void 0 ? makePlaceholder() : makeDiffCell("added", right, rightLineNumber++)
+    ));
+  }
+  flushBlock();
+  return { left: leftLineNumber, right: rightLineNumber };
+}
+function hasCredibleLineCorrespondence(left, right) {
+  const score = scoreReplacementLinePair(left, right);
+  if (score.eligible) return true;
+  const leftAnchor = declarationAnchorKey(left);
+  if (leftAnchor && leftAnchor === declarationAnchorKey(right)) return true;
+  const leftTokens = new Set(tokenizeMatchingContent(normalizeMatchingContent(left)).filter(isSharedContentToken));
+  return tokenizeMatchingContent(normalizeMatchingContent(right)).some((token) => leftTokens.has(token) && isSharedContentToken(token));
+}
+var NON_SUBSTANTIVE_SHARED_TOKENS = /* @__PURE__ */ new Set([
+  "and",
+  "are",
+  "for",
+  "from",
+  "into",
+  "that",
+  "the",
+  "this",
+  "to",
+  "with"
+]);
+function isSharedContentToken(token) {
+  return token.length >= 3 && /^[\p{L}\p{N}_$]+$/u.test(token) && !NON_SUBSTANTIVE_SHARED_TOKENS.has(token);
+}
+function hasCoherentBlockCorrespondence(leftLines, rightLines, crediblePairs) {
+  if (crediblePairs === 0) return false;
+  const longestSide = Math.max(leftLines.length, rightLines.length);
+  if (longestSide <= 2 || crediblePairs * 2 >= longestSide) return true;
+  const roles = [...leftLines, ...rightLines].map(collectionLineRole);
+  return roles[0] !== null && roles.every((role) => role === roles[0]);
+}
+function collectionLineRole(line) {
+  const normalized = line.trimStart();
+  if (/^[-*+]\s+/.test(normalized)) return "bullet";
+  if (/^\d+[.)]\s+/.test(normalized)) return "ordered";
+  if (/^>\s+/.test(normalized)) return "quote";
+  return null;
+}
 var MAX_ALIGNMENT_CELLS = 1e4;
 var MAX_SCORING_LINE_LENGTH = 2e3;
 var MINIMUM_MATCH_SCORE = 0.52;
@@ -1690,6 +1958,7 @@ var CONTEXTUAL_AMBIGUITY_MARGIN = 0.05;
 var GAP_PENALTY = -0.12;
 var MAX_BOUNDED_CANDIDATES = 5e3;
 var MAX_LARGE_HUNK_ANCHORS = 2e3;
+var MAX_ALIGNMENT_CHARACTER_CELLS = 5e7;
 var MAX_RARE_TOKEN_OCCURRENCES = 4;
 var MAX_CONTEXTUAL_HUNK_LINES = 8;
 var MAX_CONTEXTUAL_LENGTH_DELTA = 4;
@@ -1700,9 +1969,17 @@ function alignReplacementLines(leftLines, rightLines) {
   if (rightLines.length === 0) {
     return leftLines.map((left) => ({ left }));
   }
+  const leftCharacterCount = leftLines.reduce((total, line) => total + line.length, 0);
+  const rightCharacterCount = rightLines.reduce((total, line) => total + line.length, 0);
+  if (leftCharacterCount * rightCharacterCount > MAX_ALIGNMENT_CHARACTER_CELLS) {
+    return [
+      ...leftLines.map((left) => ({ left })),
+      ...rightLines.map((right) => ({ right }))
+    ];
+  }
   if (leftLines.length === 1 && rightLines.length === 1) {
     const singletonScore = scoreReplacementLinePair(leftLines[0], rightLines[0]);
-    if ((singletonScore.eligible || singletonScore.score >= MINIMUM_SINGLE_PAIR_SCORE) && haveCompatibleLineRoles(leftLines[0], rightLines[0]) && isInformativeLine(normalizeMatchingContent(leftLines[0])) && isInformativeLine(normalizeMatchingContent(rightLines[0]))) {
+    if ((singletonScore.eligible || singletonScore.score >= MINIMUM_SINGLE_PAIR_SCORE) && hasCredibleLineCorrespondence(leftLines[0], rightLines[0]) && haveCompatibleLineRoles(leftLines[0], rightLines[0]) && isInformativeLine(normalizeMatchingContent(leftLines[0])) && isInformativeLine(normalizeMatchingContent(rightLines[0]))) {
       return [{ left: leftLines[0], right: rightLines[0] }];
     }
     return [{ left: leftLines[0] }, { right: rightLines[0] }];
@@ -2224,6 +2501,11 @@ function applyInlineHighlightPair(leftLine, rightLine) {
     rightLine.segments = rightSegments;
   }
 }
+function applyFullLineHighlight(line) {
+  if (/[^\s]/.test(line.content)) {
+    line.segments = [{ kind: line.kind, text: line.content, emphasis: true }];
+  }
+}
 function buildInlineSegments(leftContent, rightContent) {
   const changes = diffWordsWithSpace(leftContent, rightContent);
   const leftSegments = [];
@@ -2375,6 +2657,125 @@ function findBlankLineBoundary(lines, target, minimum, maximum) {
   return Math.min(Math.max(target, minimum), maximum - 1);
 }
 
+// src/changeAttention.ts
+var CHANGE_ATTENTION_VERSION = 1;
+var LOCKFILES = /* @__PURE__ */ new Set([
+  "cargo.lock",
+  "package-lock.json",
+  "pnpm-lock.yaml",
+  "yarn.lock",
+  "poetry.lock",
+  "gemfile.lock",
+  "composer.lock"
+]);
+var MAX_FAN_IN_FILES = 250;
+var MAX_FAN_IN_TEXT_BYTES = 64 * 1024;
+function classifyChangeFileRole(filePath) {
+  const lower = filePath.toLowerCase();
+  const fileName = lower.split("/").pop() || lower;
+  if (/(^|\/)(dist|build|generated|vendor)(\/|$)/.test(lower) || /(?:\.min\.js|\.map)$/.test(lower)) return "generated";
+  if (/(^|\/)(tests?|__tests__)(\/|$)/.test(lower) || /(^|\/)test_[^/]+$/.test(lower) || /\.(test|spec)\.[^/]+$/.test(lower)) return "test";
+  if (lower.startsWith("docs/") || fileName === "readme.md" || /\.(md|mdx|rst)$/.test(lower)) return "documentation";
+  if (LOCKFILES.has(fileName) || /(^|\/)(pyproject\.toml|package\.json|go\.mod|go\.sum|cargo\.toml)$/.test(lower)) return "dependency";
+  return "production";
+}
+function buildChangeAttention(inputs) {
+  const prepared = inputs.map((input) => prepareFile(input, inputs));
+  const production = prepared.filter((file) => file.role === "production" && !file.mechanical);
+  const documentation = prepared.filter((file) => file.role === "documentation" && !file.mechanical);
+  const eligible = production.length > 0 ? production : documentation;
+  const entry = [...eligible].sort(compareRanked)[0];
+  const fallback = [...prepared].filter((file) => !file.binary).sort((left, right) => right.changedLines - left.changedLines || left.path.localeCompare(right.path))[0];
+  const focusCandidates = prepared.filter((file) => file.path !== (entry == null ? void 0 : entry.path) && file.role === "production" && !file.mechanical).sort(compareRanked).slice(0, Math.max(0, 7 - (entry ? 1 : 0)));
+  const pairedTest = entry || focusCandidates.length > 0 ? prepared.filter((file) => file.role === "test" && !file.mechanical && file.changedLines >= 5 && isTestForFocus(file.path, [entry, ...focusCandidates].filter(Boolean).map((candidate) => candidate.path))).sort(compareRanked)[0] : void 0;
+  if (pairedTest && focusCandidates.length < Math.max(0, 7 - (entry ? 1 : 0))) focusCandidates.push(pairedTest);
+  const focusPaths = focusCandidates.map((file) => file.path);
+  const files = prepared.map((file) => {
+    const attention = file.path === (entry == null ? void 0 : entry.path) ? "entry" : focusPaths.includes(file.path) ? "focus" : file.mechanical ? "mechanical" : "background";
+    return {
+      path: file.path,
+      previousPath: file.previousPath,
+      changeKind: file.changeKind,
+      role: file.role,
+      attention,
+      additions: file.additions,
+      deletions: file.deletions,
+      reason: attention === "entry" ? entryReason(file, production.length) : attentionReason(file),
+      score: file.score
+    };
+  }).sort((left, right) => left.path.localeCompare(right.path));
+  return {
+    version: CHANGE_ATTENTION_VERSION,
+    entryPath: (entry == null ? void 0 : entry.path) || null,
+    entryReason: entry ? entryReason(entry, production.length) : noEntryReason(prepared),
+    fallbackPath: (fallback == null ? void 0 : fallback.path) || null,
+    focusPaths,
+    backgroundPaths: files.filter((file) => file.attention === "background").map((file) => file.path),
+    mechanicalPaths: files.filter((file) => file.attention === "mechanical").map((file) => file.path),
+    files
+  };
+}
+function prepareFile(input, all) {
+  const role = classifyChangeFileRole(input.path);
+  const fileName = input.path.toLowerCase().split("/").pop() || input.path.toLowerCase();
+  const mechanical = Boolean(input.binary) || role === "generated" || LOCKFILES.has(fileName);
+  const changedLines = (input.additions ?? 0) + (input.deletions ?? 0);
+  const contract = /(^|[\/._-])(types?|schema|models?|contracts?|interfaces?)([\/._-]|$)/i.test(input.path);
+  const referenceHints = new Set([
+    fileName.replace(/\.[^.]+$/, ""),
+    ...(input.symbolHints || []).map((hint) => hint.toLowerCase())
+  ].filter((hint) => hint.length >= 4));
+  const fanIn = [...all].filter((candidate) => candidate.path !== input.path).sort((left, right) => left.path.localeCompare(right.path)).slice(0, MAX_FAN_IN_FILES).filter((candidate) => {
+    var _a;
+    const boundedText = (_a = candidate.headText) == null ? void 0 : _a.slice(0, MAX_FAN_IN_TEXT_BYTES).toLowerCase();
+    return Boolean(boundedText && [...referenceHints].some((hint) => boundedText.includes(hint)));
+  }).length;
+  const roleScore = role === "production" ? 300 : role === "documentation" ? 150 : role === "dependency" ? 80 : role === "test" ? 50 : 0;
+  const sizePenalty = changedLines > 2e3 ? 80 : changedLines > 500 ? 30 : 0;
+  const readmePenalty = fileName === "readme.md" && all.filter((candidate) => !candidate.binary).length > 1 ? 100 : 0;
+  return {
+    ...input,
+    role,
+    mechanical,
+    changedLines,
+    contract,
+    fanIn,
+    binary: Boolean(input.binary),
+    score: mechanical ? -1e3 : roleScore + (contract ? 100 : 0) + fanIn * 40 + (input.commitCount || 0) * 5 - sizePenalty - readmePenalty
+  };
+}
+function compareRanked(left, right) {
+  return right.score - left.score || right.fanIn - left.fanIn || left.changedLines - right.changedLines || left.path.localeCompare(right.path);
+}
+function entryReason(file, productionCount) {
+  if (file.fanIn > 0) return `Referenced by ${file.fanIn} other changed file${file.fanIn === 1 ? "" : "s"}.`;
+  if (file.contract) return "Contract-shaped path central to the change.";
+  if (productionCount === 1) return "Only production file in this range.";
+  return "Highest-ranked production file for a first pass.";
+}
+function attentionReason(file) {
+  if (file.binary) return "Binary file.";
+  if (file.mechanical) return file.role === "generated" ? "Generated artifact." : "Dependency lockfile.";
+  if (file.role === "test") return "Test or proof file.";
+  if (file.role === "documentation") return "Documentation change.";
+  if (file.role === "dependency") return "Dependency or packaging manifest.";
+  return "Additional production file.";
+}
+function noEntryReason(files) {
+  if (files.every((file) => file.mechanical)) return "This change is entirely mechanical or generated.";
+  if (files.every((file) => file.mechanical || file.role === "test")) return "This change contains only tests and mechanical files.";
+  return "No single entry-point is reliable for this change.";
+}
+function isTestForFocus(testPath, focusPaths) {
+  const normalizedTest = testPath.toLowerCase().replace(/\.(test|spec)(?=\.)/, "").replace(/^test_/, "");
+  return focusPaths.some((candidate) => {
+    var _a;
+    const normalizedCandidate = candidate.toLowerCase();
+    const stem = ((_a = normalizedCandidate.split("/").pop()) == null ? void 0 : _a.replace(/\.[^.]+$/, "")) || normalizedCandidate;
+    return stem.length >= 3 && normalizedTest.includes(stem);
+  });
+}
+
 // src/changeTourContext.ts
 var DEFAULT_MAX_PATCH_BYTES = 128 * 1024;
 var DEFAULT_MAX_TOTAL_PATCH_BYTES = 2 * 1024 * 1024;
@@ -2393,8 +2794,12 @@ var CHAPTERS = {
   packaging: { id: "packaging", title: "Packaging and dependencies", priority: 4 }
 };
 function buildChangeTourManifest(startPath, options = {}) {
-  var _a, _b, _c, _d, _e;
-  const range = resolveBranchReviewRange(startPath, options.headRef, options.baseRef);
+  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k;
+  const range = resolveBranchReviewRange(
+    startPath,
+    options.headRef ?? ((_b = (_a = options.source) == null ? void 0 : _a.range) == null ? void 0 : _b.head),
+    options.baseRef ?? ((_d = (_c = options.source) == null ? void 0 : _c.range) == null ? void 0 : _d.base)
+  );
   const maxFileBytes = options.maxFileBytes ?? DEFAULT_MAX_TOUR_FILE_BYTES;
   const maxLineBytes = options.maxLineBytes ?? DEFAULT_MAX_TOUR_LINE_BYTES;
   const omittedFiles = [];
@@ -2402,8 +2807,9 @@ function buildChangeTourManifest(startPath, options = {}) {
   const sceneRecords = [];
   let totalAdditions = 0;
   let totalDeletions = 0;
+  let totalBinaryFiles = 0;
   for (const changedPath of range.changedPaths) {
-    const { additions, deletions } = readGitLineStats(
+    const { additions, deletions, binary } = readGitLineStats(
       range.repoRoot,
       range.mergeBaseOid,
       range.headOid,
@@ -2412,6 +2818,7 @@ function buildChangeTourManifest(startPath, options = {}) {
     );
     totalAdditions += additions;
     totalDeletions += deletions;
+    if (binary) totalBinaryFiles += 1;
     const pair = resolveReviewPathPair(range.changedPaths, changedPath.path);
     if (!pair) {
       omittedFiles.push(changedPath.path);
@@ -2452,21 +2859,50 @@ function buildChangeTourManifest(startPath, options = {}) {
   }
   files.sort((left, right) => left.path.localeCompare(right.path));
   sceneRecords.sort((left, right) => left.chapter.priority - right.chapter.priority || left.scene.path.localeCompare(right.scene.path));
-  const defaultScenes = sceneRecords.map(({ scene }, index) => ({ ...scene, id: `file-${index + 1}` }));
+  let defaultScenes = sceneRecords.map(({ scene }, index) => ({ ...scene, id: `file-${index + 1}` }));
   if (options.story && options.source) {
     throw new Error("A change tour can use either a legacy story or a source file, not both.");
   }
-  const authored = options.source ? applySource(parseChangeTourSource(options.source), defaultScenes, range.repoRoot) : options.story ? applyStory(options.story, defaultScenes) : {
-    scenes: defaultScenes,
-    chapters: buildChapters(sceneRecords, new Map(defaultScenes.map((scene) => [scene.path, scene.id])))
-  };
+  const attention = buildChangeAttention(files.map((file) => ({
+    path: file.path,
+    previousPath: file.previousPath,
+    changeKind: file.changeKind,
+    additions: file.additions,
+    deletions: file.deletions,
+    binary: file.kind === "omitted",
+    headText: file.kind === "text-diff" ? file.rightContent : void 0,
+    symbolHints: file.kind === "text-diff" ? findDeclarationNames(file.rightContent) : []
+  })));
+  if (!options.story && !options.source && attention.entryPath) {
+    const focusRank = (scenePath) => {
+      const index = attention.focusPaths.indexOf(scenePath);
+      return index === -1 ? Number.MAX_SAFE_INTEGER : index;
+    };
+    defaultScenes = [...defaultScenes].sort((left, right) => Number(right.path === attention.entryPath) - Number(left.path === attention.entryPath) || focusRank(left.path) - focusRank(right.path) || left.id.localeCompare(right.id));
+  }
+  const authored = options.source ? applySource(parseChangeTourSource(options.source), defaultScenes, range.repoRoot) : options.story ? applyStory(options.story, defaultScenes) : buildGeneratedTourLanding(
+    defaultScenes,
+    buildChapters(sceneRecords, new Map(defaultScenes.map((scene) => [scene.path, scene.id]))),
+    attention,
+    {
+      changedFiles: range.changedPaths.length,
+      binaryFiles: totalBinaryFiles,
+      additions: totalAdditions,
+      deletions: totalDeletions,
+      commitCount: range.commits.length
+    }
+  );
   const scenes = authored.scenes;
   const chapters = authored.chapters;
+  const finalScenes = "finalScenes" in authored ? authored.finalScenes : scenes;
+  const finalChapters = "finalChapters" in authored ? authored.finalChapters : chapters;
   const manifest = {
-    version: CHANGE_TOUR_MANIFEST_VERSION,
-    title: ((_a = options.source) == null ? void 0 : _a.title) || ((_b = options.story) == null ? void 0 : _b.title) || options.title || `${range.headRef} against ${range.baseRef}`,
-    windowTitle: (_c = options.source) == null ? void 0 : _c.windowTitle,
-    sourceUrl: ((_d = options.source) == null ? void 0 : _d.sourceUrl) || ((_e = options.story) == null ? void 0 : _e.sourceUrl) || options.sourceUrl,
+    // Only authored v2 files opt into repository-bound zoom modes. Generated
+    // and legacy/story tours retain the portable v1 manifest contract.
+    version: ((_e = options.source) == null ? void 0 : _e.version) ?? 1,
+    title: ((_f = options.source) == null ? void 0 : _f.title) || ((_g = options.story) == null ? void 0 : _g.title) || options.title || `${range.headRef} against ${range.baseRef}`,
+    windowTitle: (_h = options.source) == null ? void 0 : _h.windowTitle,
+    sourceUrl: ((_i = options.source) == null ? void 0 : _i.sourceUrl) || ((_j = options.story) == null ? void 0 : _j.sourceUrl) || options.sourceUrl,
     generatedAt: options.generatedAt || (/* @__PURE__ */ new Date()).toISOString(),
     range: {
       baseRef: range.baseRef,
@@ -2487,6 +2923,49 @@ function buildChangeTourManifest(startPath, options = {}) {
     chapters,
     scenes
   };
+  if (manifest.version === 2) {
+    manifest.repository = { root: range.repoRoot };
+    const revisions = [];
+    for (const scene of scenes) {
+      let realStack;
+      if (scene.kind === "stacked-diff") realStack = scene;
+      if (scene.kind === "deconstructed-diff") {
+        const authoredScene = (_k = options.source) == null ? void 0 : _k.chapters.flatMap((chapter) => chapter.scenes).find((candidate) => candidate.id === scene.id);
+        if ((authoredScene == null ? void 0 : authoredScene.kind) !== "deconstructed-diff" || !authoredScene.stack) {
+          throw new Error(`Deconstructed scene ${scene.id} requires an explicit real revision stack in v2.`);
+        }
+        realStack = buildStackedScene(range.repoRoot, {
+          ...authoredScene,
+          kind: "stacked-diff",
+          stack: authoredScene.stack,
+          files: scene.files.map((file) => file.path),
+          steps: []
+        }, files.map((file) => file.path));
+        if (realStack.stack[0].oid !== scene.realRange.baseOid || realStack.stack[realStack.stack.length - 1].oid !== scene.realRange.targetOid) {
+          throw new Error(`Deconstructed scene ${scene.id} real stack endpoints must match its explanation range.`);
+        }
+      }
+      if (realStack) {
+        if (realStack.stack[0].oid !== range.mergeBaseOid || realStack.stack[realStack.stack.length - 1].oid !== range.headOid) {
+          throw new Error(`Scene ${scene.id} real stack endpoints must match the tour's final diff range.`);
+        }
+        revisions.push(realStack);
+      }
+    }
+    const explanation = scenes.some((scene) => scene.kind === "deconstructed-diff");
+    const distinctRevisions = revisions.some((scene) => scene.stack.length > 2);
+    manifest.zoom = {
+      authoredDepth: explanation ? "explanation" : distinctRevisions ? "revisions" : "final",
+      modes: [
+        ...explanation ? ["explanation"] : [],
+        ...distinctRevisions ? ["revisions"] : [],
+        "final",
+        "history"
+      ],
+      revisions,
+      final: { scenes: finalScenes, chapters: finalChapters }
+    };
+  }
   return parseChangeTourManifest(manifest);
 }
 function applySource(source, defaultScenes, repoRoot) {
@@ -2509,8 +2988,11 @@ function applySource(source, defaultScenes, repoRoot) {
   }]));
   const scenes = [];
   const chapters = [];
+  const finalScenes = [];
+  const finalChapters = [];
   for (const chapter of source.chapters) {
     const sceneIds = [];
+    const finalSceneIds = [];
     for (const authoredScene of chapter.scenes) {
       if (authoredScene.kind === "deconstructed-diff") {
         const deconstructedScene = buildDeconstructedManifestScene(
@@ -2522,6 +3004,16 @@ function applySource(source, defaultScenes, repoRoot) {
         );
         scenes.push(deconstructedScene);
         sceneIds.push(deconstructedScene.id);
+        if (authoredScene.steps) {
+          const finalScene = buildWalkthroughManifestScene(
+            { ...authoredScene, steps: authoredScene.steps },
+            available,
+            resolvedAnchors,
+            connections
+          );
+          finalScenes.push(finalScene);
+          finalSceneIds.push(finalScene.id);
+        }
         continue;
       }
       if (authoredScene.kind === "stacked-diff") {
@@ -2532,37 +3024,51 @@ function applySource(source, defaultScenes, repoRoot) {
         );
         scenes.push(stackedScene);
         sceneIds.push(stackedScene.id);
+        for (const [index, file] of stackedScene.files.entries()) {
+          const endpoint = available.get(file.path);
+          if (!endpoint) continue;
+          const finalScene = { ...endpoint, id: `${stackedScene.id}-final-${index + 1}`, title: file.path };
+          finalScenes.push(finalScene);
+          finalSceneIds.push(finalScene.id);
+        }
         continue;
       }
-      const scene = {
-        id: authoredScene.id,
-        kind: "walkthrough",
-        title: authoredScene.title,
-        summary: authoredScene.summary,
-        bullets: authoredScene.bullets,
-        tags: authoredScene.tags,
-        takeaway: authoredScene.takeaway,
-        steps: authoredScene.steps.map((step) => {
-          const focus = requireResolvedAnchor(resolvedAnchors, step.focus);
-          const diff2 = available.get(focus.path);
-          if (!diff2) throw new Error(`Step ${step.id} has no text diff for ${focus.path}.`);
-          return {
-            id: step.id,
-            title: step.title,
-            body: step.body,
-            depth: step.depth,
-            focus,
-            connection: step.connection ? connections.get(step.connection) : void 0,
-            diff: { ...diff2, id: `${authoredScene.id}-${step.id}` }
-          };
-        })
-      };
+      const scene = buildWalkthroughManifestScene(authoredScene, available, resolvedAnchors, connections);
       scenes.push(scene);
       sceneIds.push(scene.id);
+      finalScenes.push(scene);
+      finalSceneIds.push(scene.id);
     }
     chapters.push({ id: chapter.id, title: chapter.title, sceneIds });
+    finalChapters.push({ id: chapter.id, title: chapter.title, sceneIds: finalSceneIds });
   }
-  return { scenes, chapters };
+  return { scenes, chapters, finalScenes, finalChapters };
+}
+function buildWalkthroughManifestScene(authoredScene, available, resolvedAnchors, connections) {
+  return {
+    id: authoredScene.id,
+    kind: "walkthrough",
+    title: authoredScene.title,
+    summary: authoredScene.summary,
+    bullets: authoredScene.bullets,
+    tags: authoredScene.tags,
+    takeaway: authoredScene.takeaway,
+    steps: authoredScene.steps.map((step) => {
+      const focus = requireResolvedAnchor(resolvedAnchors, step.focus);
+      const diff2 = available.get(focus.path);
+      if (!diff2) throw new Error(`Step ${step.id} has no text diff for ${focus.path}.`);
+      return {
+        id: step.id,
+        title: step.title,
+        body: step.body,
+        depth: step.depth,
+        requirement: step.requirement,
+        focus,
+        connection: step.connection ? connections.get(step.connection) : void 0,
+        diff: { ...diff2, id: `${authoredScene.id}-${step.id}` }
+      };
+    })
+  };
 }
 function buildDeconstructedManifestScene(repoRoot, source, baseRef, targetRef, availableFilePaths = []) {
   const compiled = buildDeconstructedScene(repoRoot, source, { baseRef, headRef: targetRef });
@@ -2728,7 +3234,7 @@ function buildStackedScene(repoRoot, source, availableFilePaths) {
   let totalContentBytes = 0;
   const files = filePaths.flatMap((filePath) => {
     const aliases = /* @__PURE__ */ new Set([filePath]);
-    for (const changes of adjacentChanges) {
+    for (const changes of [...adjacentChanges].reverse()) {
       for (const change of changes) {
         if (aliases.has(change.path) || change.previousPath && aliases.has(change.previousPath)) {
           aliases.add(change.path);
@@ -2739,7 +3245,9 @@ function buildStackedScene(repoRoot, source, availableFilePaths) {
     let fileContentBytes = 0;
     const panels = [];
     for (const entry of stack) {
-      const resolvedPath = [...aliases].find((candidate) => gitBlobExists(repoRoot, entry.oid, candidate));
+      const candidates = [...aliases].filter((candidate) => gitBlobExists(repoRoot, entry.oid, candidate));
+      if (candidates.length > 1) throw new Error(`Ambiguous revision paths for ${filePath} at ${entry.ref}: ${candidates.join(", ")}`);
+      const resolvedPath = candidates[0];
       if (!resolvedPath) {
         panels.push({ id: entry.id, label: `${entry.label} / ${filePath} (missing)`, content: "", exists: false });
         continue;
@@ -2766,6 +3274,7 @@ function buildStackedScene(repoRoot, source, availableFilePaths) {
     }
     return [{ path: filePath, panels }];
   });
+  if (files.length === 0) throw new Error(`Stacked scene ${source.id} has no materializable text files.`);
   const stackIds = stack.map((entry) => entry.id);
   return {
     id: source.id,
@@ -2777,7 +3286,14 @@ function buildStackedScene(repoRoot, source, availableFilePaths) {
     takeaway: source.takeaway,
     stack,
     files,
-    steps: source.steps.map((step) => {
+    steps: source.steps.length === 0 ? stack.slice(0, -1).map((_, pairIndex) => ({
+      id: `${source.id}-revision-${pairIndex}`,
+      title: "",
+      body: "",
+      file: files[0].path,
+      pairIndex,
+      side: "right"
+    })) : source.steps.map((step) => {
       var _a, _b;
       return {
         id: step.id,
@@ -2889,21 +3405,51 @@ function buildChapters(records, sceneIdByPath) {
 }
 function chapterForPath(filePath) {
   const lower = filePath.toLowerCase();
-  const fileName = lower.split("/").pop() || lower;
-  if (lower.startsWith("docs/") || fileName === "readme.md" || fileName.includes("architecture")) {
+  const role = classifyChangeFileRole(filePath);
+  if (role === "documentation" || lower.includes("architecture")) {
     return CHAPTERS.context;
   }
-  if (/(^|\/)(tests?|__tests__)(\/|$)/.test(lower) || /(^|\/)test_[^/]+$/.test(lower)) {
+  if (role === "test") {
     return CHAPTERS.proof;
   }
   if (/(^|\/)(models?|schema|types?|contracts?)\.[^/]+$/.test(lower)) {
     return CHAPTERS.contracts;
   }
-  if (/(^|\/)(package-lock\.json|.*\.lock|pyproject\.toml|package\.json)$/.test(lower)) {
+  if (role === "dependency" || role === "generated") {
     return CHAPTERS.packaging;
   }
   return CHAPTERS.behavior;
 }
+function buildGeneratedTourLanding(scenes, chapters, attention, summary) {
+  const entry = attention.entryPath ? `Start here: ${attention.entryPath} \u2014 ${attention.entryReason}` : `No single entry-point \u2014 ${attention.entryReason}`;
+  const focus = attention.focusPaths.length > 0 ? `Pay attention: ${attention.focusPaths.join(", ")}` : "Pay attention: no additional production files were identified.";
+  const skipped = attention.backgroundPaths.length + attention.mechanicalPaths.length;
+  const overview = {
+    id: "change-overview",
+    kind: "discussion",
+    title: "Change overview",
+    summary: `${summary.changedFiles} files (${summary.changedFiles - summary.binaryFiles} text, ${summary.binaryFiles} binary) \xB7 +${summary.additions} \u2212${summary.deletions} \xB7 ${summary.commitCount} commits`,
+    bullets: [entry, focus, `Usually skip on a first pass: ${skipped} file${skipped === 1 ? "" : "s"}. All files remain available.`],
+    tags: ["start here", "first pass"],
+    takeaway: attention.entryPath ? `Next: open ${attention.entryPath}.` : "Next: open the first available textual change."
+  };
+  return {
+    scenes: [overview, ...scenes],
+    chapters: [
+      { id: "start-here", title: "Start here", sceneIds: [overview.id] },
+      ...chapters
+    ]
+  };
+}
+function findDeclarationNames(content) {
+  const names = /* @__PURE__ */ new Set();
+  for (const line of content.split("\n")) {
+    const match = line.match(/^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:function|class|interface|type|enum|const|let|var)\s+([A-Za-z_$][\w$]*)/) || line.match(/^\s*(?:async\s+)?(?:class|def)\s+([A-Za-z_]\w*)/);
+    if (match) names.add(match[1]);
+    if (names.size >= 25) break;
+  }
+  return [...names];
+}
 function buildSceneNote(kind, additions, deletions, previousPath) {
   const label = formatChangeKind(kind);
   const rename = previousPath ? ` from ${previousPath}` : "";
@@ -2966,19 +3512,31 @@ function readGitLineStats(repoRoot, baseOid, headOid, filePath, previousPath) {
   const [additionsText = "0", deletionsText = "0"] = output.trim().split(/\s+/, 3);
   return {
     additions: Number.parseInt(additionsText, 10) || 0,
-    deletions: Number.parseInt(deletionsText, 10) || 0
+    deletions: Number.parseInt(deletionsText, 10) || 0,
+    binary: additionsText === "-" || deletionsText === "-"
   };
 }
 
 // src/tourCoverage.ts
-var TOUR_COVERAGE_REPORT_VERSION = 1;
+var TOUR_COVERAGE_REPORT_VERSION = 2;
+function buildTourAuthoringCoverage(report) {
+  return {
+    walkthrough: {
+      scope: report.version === 2 ? "final" : "tour",
+      coveredUnits: report.totals.coveredUnits,
+      includedUnits: report.totals.includedUnits,
+      coveragePercent: report.totals.coveragePercent
+    },
+    explanationAssignments: report.version === 2 ? report.explanationAssignments : []
+  };
+}
 var DEPTH_ORDER = {
   mentioned: 0,
   explained: 1,
   contextualized: 2
 };
 function buildTourCoverageReport(startPath, sourceValue) {
-  var _a, _b, _c, _d, _e;
+  var _a, _b, _c, _d, _e, _f;
   const source = parseChangeTourSource(sourceValue);
   const inventory = buildChangeInventory(startPath, {
     headRef: (_a = source.range) == null ? void 0 : _a.head,
@@ -2994,7 +3552,9 @@ function buildTourCoverageReport(startPath, sourceValue) {
   const includedUnits = textualUnits.filter((unit) => !excludedIds.has(unit.id));
   const coverage = /* @__PURE__ */ new Map();
   const contextualOnlyEvidence = [];
-  for (const scene of manifest.scenes) {
+  const percentageDecimalPlaces = manifest.version === 2 ? 2 : 0;
+  const walkthroughScenes = manifest.version === 2 ? requireFinalScenes((_e = manifest.zoom) == null ? void 0 : _e.final.scenes) : manifest.scenes;
+  for (const scene of walkthroughScenes) {
     if (scene.kind !== "walkthrough") continue;
     for (const step of scene.steps) {
       const matches = includedUnits.filter((unit) => evidenceIntersectsUnit(step.focus, unit));
@@ -3015,11 +3575,10 @@ function buildTourCoverageReport(startPath, sourceValue) {
     const highest = covered.depths.reduce((left, right) => DEPTH_ORDER[right] > DEPTH_ORDER[left] ? right : left);
     depth[highest] += 1;
   }
-  const files = inventory.files.filter((file) => file.material === "text").map((file) => buildFileResult(file, excludedIds, coverage));
+  const files = inventory.files.filter((file) => file.material === "text").map((file) => buildFileResult(file, excludedIds, coverage, percentageDecimalPlaces));
   const includedChangedLines = includedUnits.reduce((total, unit) => total + unit.additions + unit.deletions, 0);
   const coveredChangedLines = [...coverage.values()].reduce((total, entry) => total + entry.unit.additions + entry.unit.deletions, 0);
-  return {
-    version: TOUR_COVERAGE_REPORT_VERSION,
+  const report = {
     range: {
       baseRef: inventory.range.baseRef,
       headRef: inventory.range.headRef,
@@ -3032,13 +3591,13 @@ function buildTourCoverageReport(startPath, sourceValue) {
       includedUnits: includedUnits.length,
       coveredUnits: coverage.size,
       uncoveredUnits: includedUnits.length - coverage.size,
-      coveragePercent: percentage(coverage.size, includedUnits.length),
+      coveragePercent: percentage(coverage.size, includedUnits.length, percentageDecimalPlaces),
       coveredChangedLines,
       includedChangedLines
     },
     depth,
     files,
-    exclusions: (((_e = source.coverage) == null ? void 0 : _e.exclusions) || []).map((exclusion) => {
+    exclusions: (((_f = source.coverage) == null ? void 0 : _f.exclusions) || []).map((exclusion) => {
       var _a2;
       return {
         path: exclusion.path,
@@ -3049,6 +3608,34 @@ function buildTourCoverageReport(startPath, sourceValue) {
     unsupported: inventory.files.filter((file) => file.material !== "text").map((file) => ({ path: file.path, material: file.material })),
     contextualOnlyEvidence
   };
+  if (manifest.version === 1) return { version: 1, ...report };
+  return {
+    version: TOUR_COVERAGE_REPORT_VERSION,
+    ...report,
+    walkthroughScope: "final",
+    explanationAssignments: buildExplanationAssignments(source, inventory.files)
+  };
+}
+function requireFinalScenes(scenes) {
+  if (!scenes) throw new Error("A v2 tour requires Final-mode scenes for coverage reporting.");
+  return scenes;
+}
+function buildExplanationAssignments(source, files) {
+  const materializableFiles = files.filter((file) => file.material === "text" && file.changeKind !== "renamed" && file.baseContent !== void 0 && file.headContent !== void 0);
+  const totalUnits = materializableFiles.reduce((total, file) => total + file.units.length, 0);
+  return source.chapters.flatMap((chapter) => chapter.scenes).filter((scene) => scene.kind === "deconstructed-diff").map((scene) => {
+    const assignedUnits = scene.stages.reduce((stageTotal, stage) => stageTotal + stage.changes.reduce((changeTotal, change) => changeTotal + change.hunks.length, 0), 0);
+    const excludedUnits = totalUnits - assignedUnits;
+    const completeUnits = assignedUnits + excludedUnits;
+    return {
+      sceneId: scene.id,
+      assignedUnits,
+      excludedUnits,
+      completeUnits,
+      totalUnits,
+      assignmentPercent: percentage(completeUnits, totalUnits)
+    };
+  });
 }
 function resolveExclusions(source, files) {
   var _a, _b, _c;
@@ -3075,7 +3662,7 @@ function evidenceIntersectsUnit(focus, unit) {
   const end = start + count - 1;
   return focus.startLine <= end && focus.endLine >= start;
 }
-function buildFileResult(file, excludedIds, coverage) {
+function buildFileResult(file, excludedIds, coverage, percentageDecimalPlaces) {
   const included = file.units.filter((unit) => !excludedIds.has(unit.id));
   const covered = included.filter((unit) => coverage.has(unit.id));
   return {
@@ -3083,16 +3670,19 @@ function buildFileResult(file, excludedIds, coverage) {
     originalUnits: file.units.length,
     includedUnits: included.length,
     coveredUnits: covered.length,
-    coveragePercent: percentage(covered.length, included.length),
+    coveragePercent: percentage(covered.length, included.length, percentageDecimalPlaces),
     uncoveredHunks: included.filter((unit) => !coverage.has(unit.id)).map((unit) => unit.id)
   };
 }
-function percentage(numerator, denominator) {
-  return denominator === 0 ? 100 : Math.round(numerator / denominator * 100);
+function percentage(numerator, denominator, decimalPlaces = 0) {
+  if (denominator === 0) return 100;
+  const precision = 10 ** decimalPlaces;
+  return Math.round(numerator / denominator * 100 * precision) / precision;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   TOUR_COVERAGE_REPORT_VERSION,
+  buildTourAuthoringCoverage,
   buildTourCoverageReport
 });
 //# sourceMappingURL=tourCoverage.js.map