@davmash/bygone 0.8.16 → 0.9.4

package/out/tourCoverage.js

@@ -475,17 +475,29 @@ function runGit(repoRoot, args) {
 var import_child_process3 = require("child_process");
 
 // src/changeTourSource.ts
-var CHANGE_TOUR_SOURCE_VERSION = 2;
+var CHANGE_TOUR_SOURCE_VERSION = 3;
 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) {
+  if (!isRecord(value) || value.version !== 1 && value.version !== 2 && 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");
+  requireOnlyKeys(value, [
+    "version",
+    "title",
+    "windowTitle",
+    "sourceUrl",
+    "range",
+    "anchors",
+    "connections",
+    "chapters",
+    "tours",
+    "coverage",
+    "review"
+  ], "source");
   optionalString(value.title, "title");
   optionalString(value.windowTitle, "windowTitle");
   optionalString(value.sourceUrl, "sourceUrl");
@@ -549,30 +561,81 @@ function parseChangeTourSource(value) {
     }
     connectionIds.add(id);
   }
+  const authoredWalkthroughSteps = validateSourceChapters(
+    value.chapters,
+    "chapters",
+    value.version,
+    value.anchors,
+    connectionIds,
+    "root"
+  );
+  if (value.tours !== void 0) {
+    if (value.version !== 3) throw new Error("Independent tours require version 3.");
+    if (!isRecord(value.tours)) throw new Error("tours must be an object.");
+    requireOnlyKeys(value.tours, ["historical", "deconstructed"], "tours");
+    if (value.tours.historical === void 0 && value.tours.deconstructed === void 0) {
+      throw new Error("tours must contain a historical or deconstructed tour.");
+    }
+    for (const mode of ["historical", "deconstructed"]) {
+      const tour = value.tours[mode];
+      if (tour === void 0) continue;
+      const path = `tours.${mode}`;
+      if (!isRecord(tour)) throw new Error(`${path} must be an object.`);
+      requireOnlyKeys(tour, ["chapters"], path);
+      validateSourceChapters(tour.chapters, `${path}.chapters`, value.version, value.anchors, connectionIds, mode);
+    }
+  }
+  if (value.review !== void 0) {
+    if (value.version !== 3) throw new Error("Review notes require version 3.");
+    validateChangeTourReview(value.review, { authoredWalkthroughSteps });
+  }
+  return { ...value, connections: rawConnections };
+}
+function validateSourceChapters(chaptersValue, chaptersPath, version, anchors, connectionIds, mode) {
+  if (!Array.isArray(chaptersValue) || chaptersValue.length === 0) {
+    throw new Error(`${chaptersPath} must be a non-empty array.`);
+  }
   const chapterIds = /* @__PURE__ */ new Set();
   const sceneIds = /* @__PURE__ */ new Set();
-  for (const [chapterIndex, chapter] of value.chapters.entries()) {
+  const authoredWalkthroughSteps = /* @__PURE__ */ new Map();
+  for (const [chapterIndex, chapter] of chaptersValue.entries()) {
+    const chapterPath = `${chaptersPath}[${chapterIndex}]`;
     if (!isRecord(chapter) || !Array.isArray(chapter.scenes) || chapter.scenes.length === 0) {
-      throw new Error(`chapters[${chapterIndex}] must contain a non-empty scenes array.`);
+      throw new Error(`${chapterPath} 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}]`);
+    requireString(chapter.id, `${chapterPath}.id`);
+    requireString(chapter.title, `${chapterPath}.title`);
+    requireOnlyKeys(chapter, ["id", "title", "scenes"], chapterPath);
     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}]`;
+      const path = `${chapterPath}.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);
+      if (scene.overview !== void 0 && version !== 3) {
+        throw new Error(`${path}.overview requires version 3.`);
+      }
       validateNarrative(scene, path);
       if (scene.kind === "deconstructed-diff") {
+        if (mode === "historical") {
+          throw new Error(`${path} cannot contain a deconstructed-diff scene in the historical tour.`);
+        }
         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);
+        validateSceneOverview(scene.overview, `${path}.overview`, {
+          endpointIds: deconstructedOverviewEndpointIds(scene, path)
+        });
+        const requireRealEvidence = mode === "root" && version >= 2;
+        if (requireRealEvidence || scene.stack !== void 0) {
+          validateRealStack(scene.stack, `${path}.stack`, 2);
+        }
+        if (requireRealEvidence || scene.steps !== void 0) {
+          validateWalkthroughSteps(scene, path, anchors, connectionIds);
+          if (scene.steps !== void 0) {
+            authoredWalkthroughSteps.set(scene.id, collectStepIds(scene.steps));
+          }
         }
         continue;
       }
@@ -580,20 +643,110 @@ function parseChangeTourSource(value) {
         throw new Error(`${path} must contain a non-empty steps array.`);
       }
       if (scene.kind === "stacked-diff") {
-        validateStackedScene(scene, path, value.version === 2 ? 2 : 3);
+        validateStackedScene(scene, path, mode === "root" ? version >= 2 ? 2 : 3 : 2);
+        validateSceneOverview(scene.overview, `${path}.overview`, {
+          endpointIds: stackedOverviewEndpointIds(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);
-      validateWalkthroughSteps(scene, path, value.anchors, connectionIds);
+      requireOnlyKeys(scene, ["id", "kind", "title", "summary", "bullets", "tags", "takeaway", "overview", "steps"], path);
+      validateSceneOverview(scene.overview, `${path}.overview`, { allowComparison: false });
+      validateWalkthroughSteps(scene, path, anchors, connectionIds);
+      authoredWalkthroughSteps.set(scene.id, collectStepIds(scene.steps));
+    }
+  }
+  if (mode === "deconstructed" && !chaptersValue.some((chapter) => isRecord(chapter) && Array.isArray(chapter.scenes) && chapter.scenes.some((scene) => isRecord(scene) && scene.kind === "deconstructed-diff"))) {
+    throw new Error(`${chaptersPath} must contain at least one deconstructed-diff scene.`);
+  }
+  return authoredWalkthroughSteps;
+}
+function stackedOverviewEndpointIds(scene, path) {
+  if (!Array.isArray(scene.stack)) {
+    throw new Error(`${path}.stack must be an array.`);
+  }
+  return scene.stack.filter(isRecord).map((entry) => typeof entry.id === "string" ? entry.id : "").filter((id) => id.length > 0);
+}
+function deconstructedOverviewEndpointIds(scene, path) {
+  if (!Array.isArray(scene.stages)) {
+    throw new Error(`${path}.stages must be an array.`);
+  }
+  return [
+    "explanation-baseline",
+    ...scene.stages.filter(isRecord).map((stage) => typeof stage.id === "string" ? `explanation-stage-${stage.id}` : "").filter((id) => id.length > 0)
+  ];
+}
+function validateChangeTourReview(value, context = {}) {
+  if (!isRecord(value)) {
+    throw new Error("review must be an object.");
+  }
+  requireOnlyKeys(value, ["baseOid", "headOid", "items"], "review");
+  requireFullGitOid(value.baseOid, "review.baseOid");
+  requireFullGitOid(value.headOid, "review.headOid");
+  if (!Array.isArray(value.items) || value.items.length === 0) {
+    throw new Error("review.items must be a non-empty array.");
+  }
+  if (context.expectedRange) {
+    if (normalizeGitOid(value.baseOid) !== normalizeGitOid(context.expectedRange.baseOid)) {
+      throw new Error(
+        `Stale review: review.baseOid ${value.baseOid} does not match the resolved range.mergeBaseOid ${context.expectedRange.baseOid}.`
+      );
+    }
+    if (normalizeGitOid(value.headOid) !== normalizeGitOid(context.expectedRange.headOid)) {
+      throw new Error(
+        `Stale review: review.headOid ${value.headOid} does not match the resolved range.headOid ${context.expectedRange.headOid}.`
+      );
+    }
+  }
+  const itemIds = /* @__PURE__ */ new Set();
+  for (const [index, item] of value.items.entries()) {
+    const itemPath = `review.items[${index}]`;
+    if (!isRecord(item)) throw new Error(`${itemPath} must be an object.`);
+    requireOnlyKeys(item, ["id", "kind", "title", "body", "evidence", "nextCheck"], itemPath);
+    requireReviewString(item.id, `${itemPath}.id`);
+    if (itemIds.has(item.id)) throw new Error(`Duplicate review item id: ${item.id}`);
+    itemIds.add(item.id);
+    if (typeof item.kind !== "string" || !["concept", "boundary", "tradeoff", "question"].includes(item.kind)) {
+      throw new Error(`${itemPath}.kind must be concept, boundary, tradeoff, or question.`);
+    }
+    requireReviewString(item.title, `${itemPath}.title`);
+    requireReviewString(item.body, `${itemPath}.body`);
+    if (!Array.isArray(item.evidence)) {
+      throw new Error(`${itemPath}.evidence must be an array.`);
+    }
+    if (item.kind !== "question" && item.evidence.length === 0) {
+      throw new Error(`${itemPath}.evidence must contain at least one reference for claims.`);
+    }
+    if (item.kind === "question" && item.nextCheck === void 0) {
+      throw new Error(`${itemPath}.nextCheck must be a non-empty string for question items.`);
+    }
+    if (item.nextCheck !== void 0) requireReviewString(item.nextCheck, `${itemPath}.nextCheck`);
+    for (const [evidenceIndex, evidence] of item.evidence.entries()) {
+      const evidencePath = `${itemPath}.evidence[${evidenceIndex}]`;
+      if (!isRecord(evidence)) throw new Error(`${evidencePath} must be an object.`);
+      requireOnlyKeys(evidence, ["sceneId", "stepId"], evidencePath);
+      requireReviewString(evidence.sceneId, `${evidencePath}.sceneId`);
+      requireReviewString(evidence.stepId, `${evidencePath}.stepId`);
+      if (context.authoredWalkthroughSteps) {
+        const stepIds = context.authoredWalkthroughSteps.get(evidence.sceneId);
+        if (!stepIds) {
+          throw new Error(
+            `${evidencePath} references unknown authored walkthrough scene ${evidence.sceneId}.`
+          );
+        }
+        if (!stepIds.has(evidence.stepId)) {
+          throw new Error(
+            `${evidencePath} references unknown authored walkthrough step ${evidence.sceneId}/${evidence.stepId}.`
+          );
+        }
+      }
     }
   }
-  return { ...value, connections: rawConnections };
 }
 function validateDeconstructedScene(scene, path) {
-  requireOnlyKeys(scene, ["id", "kind", "title", "summary", "bullets", "tags", "takeaway", "base", "target", "stack", "steps", "stages", "exclusions"], path);
+  requireOnlyKeys(scene, ["id", "kind", "title", "summary", "bullets", "tags", "takeaway", "overview", "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) {
@@ -679,7 +832,7 @@ function validateRealStack(stack, path, minimum) {
   }
 }
 function validateStackedScene(scene, path, minimum = 3) {
-  requireOnlyKeys(scene, ["id", "kind", "title", "summary", "bullets", "tags", "takeaway", "stack", "files", "steps"], path);
+  requireOnlyKeys(scene, ["id", "kind", "title", "summary", "bullets", "tags", "takeaway", "overview", "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.`);
   }
@@ -735,6 +888,53 @@ function validateStepRequirement(value, path) {
     throw new Error(`${path}.confidence must be high, medium, or low.`);
   }
 }
+function validateSceneOverview(value, path, options = {}) {
+  if (value === void 0) return;
+  if (!isRecord(value)) throw new Error(`${path} must be an object.`);
+  requireOnlyKeys(value, ["kind", "path", "comparison"], path);
+  if (value.kind !== "directory-diff") {
+    throw new Error(`${path}.kind must be directory-diff.`);
+  }
+  if (value.path !== void 0) validateDirectoryOverviewPath(value.path, `${path}.path`);
+  if (value.comparison === void 0) return;
+  if (options.allowComparison === false) {
+    throw new Error(`${path}.comparison is not supported for walkthrough scenes; use the fixed base-to-head comparison.`);
+  }
+  if (!isRecord(value.comparison)) throw new Error(`${path}.comparison must be an object.`);
+  requireOnlyKeys(value.comparison, ["from", "to"], `${path}.comparison`);
+  requireString(value.comparison.from, `${path}.comparison.from`);
+  requireString(value.comparison.to, `${path}.comparison.to`);
+  if (value.comparison.from === value.comparison.to) {
+    throw new Error(`${path}.comparison.from and to must identify distinct endpoints.`);
+  }
+  if (options.endpointIds !== void 0) {
+    for (const endpoint of [value.comparison.from, value.comparison.to]) {
+      if (!options.endpointIds.includes(endpoint)) {
+        throw new Error(`${path}.comparison endpoint ${endpoint} is not defined by this scene.`);
+      }
+    }
+  }
+}
+function validateDirectoryOverviewPath(value, path) {
+  requireString(value, path);
+  if (value.includes("\\")) {
+    throw new Error(`${path} must use a relative POSIX directory path without backslashes.`);
+  }
+  if (value.startsWith("/") || /^[A-Za-z]:/.test(value)) {
+    throw new Error(`${path} must be relative to the repository root.`);
+  }
+  if (value.split("/").some((segment) => segment === "..")) {
+    throw new Error(`${path} must not contain parent-directory traversal.`);
+  }
+}
+function collectStepIds(value) {
+  const ids = /* @__PURE__ */ new Set();
+  if (!Array.isArray(value)) return ids;
+  for (const step of value) {
+    if (isRecord(step) && typeof step.id === "string") ids.add(step.id);
+  }
+  return ids;
+}
 function validateNarrative(value, path) {
   requireString(value.summary, `${path}.summary`);
   requireStringArray(value.bullets, `${path}.bullets`);
@@ -749,6 +949,20 @@ function requireString(value, path) {
     throw new Error(`${path} must be a non-empty string.`);
   }
 }
+function requireFullGitOid(value, path) {
+  requireString(value, path);
+  if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i.test(value)) {
+    throw new Error(`${path} must be a full 40- or 64-character hexadecimal Git OID.`);
+  }
+}
+function requireReviewString(value, path) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${path} must be a non-empty string.`);
+  }
+}
+function normalizeGitOid(value) {
+  return value.toLowerCase();
+}
 function optionalString(value, path) {
   if (value !== void 0) {
     requireString(value, path);
@@ -767,14 +981,14 @@ function requireOnlyKeys(value, allowed, path) {
 }
 
 // src/changeTourManifest.ts
-var CHANGE_TOUR_MANIFEST_VERSION = 2;
+var CHANGE_TOUR_MANIFEST_VERSION = 3;
 function parseChangeTourManifest(value) {
   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) {
+  if (!isRecord2(value) || value.version !== 1 && value.version !== 2 && value.version !== CHANGE_TOUR_MANIFEST_VERSION) {
     throw new Error(`Unsupported or missing change-tour manifest version.`);
   }
   requireString2(value.title, "title");
@@ -806,7 +1020,7 @@ function parseChangeTourManifest(value) {
   }
   const sceneIds = /* @__PURE__ */ new Set();
   for (const [index, candidate] of value.scenes.entries()) {
-    validateScene(candidate, index);
+    validateScene(candidate, index, value.version);
     if (sceneIds.has(candidate.id)) {
       throw new Error(`Duplicate change-tour scene id: ${candidate.id}`);
     }
@@ -838,14 +1052,44 @@ function parseChangeTourManifest(value) {
   if (value.authoringCoverage !== void 0) {
     validateAuthoringCoverage(value.authoringCoverage, value.version);
   }
-  if (value.version === 2) validateZoom(value);
+  if (value.tours !== void 0) {
+    if (value.version !== 3) throw new Error("Independent tours require manifest version 3.");
+    validateModeTours(value.tours, value.version);
+  }
+  if (value.version !== 1) validateZoom(value, value.version);
+  if (value.review !== void 0) {
+    if (value.version !== 3) throw new Error("Review notes require manifest version 3.");
+    const evidenceScenes = value.version >= 2 && isRecord2(value.zoom) && isRecord2(value.zoom.final) ? value.zoom.final.scenes : value.scenes;
+    validateChangeTourReview(value.review, {
+      expectedRange: {
+        baseOid: String(value.range.mergeBaseOid),
+        headOid: String(value.range.headOid)
+      },
+      authoredWalkthroughSteps: collectAuthoredWalkthroughStepIds(evidenceScenes)
+    });
+  }
   return { ...value, files };
 }
+function collectAuthoredWalkthroughStepIds(value) {
+  const scenes = /* @__PURE__ */ new Map();
+  if (!Array.isArray(value)) return scenes;
+  for (const scene of value) {
+    if (!isRecord2(scene) || scene.kind !== "walkthrough" || !Array.isArray(scene.steps) || typeof scene.id !== "string") {
+      continue;
+    }
+    const stepIds = /* @__PURE__ */ new Set();
+    for (const step of scene.steps) {
+      if (isRecord2(step) && typeof step.id === "string") stepIds.add(step.id);
+    }
+    scenes.set(scene.id, stepIds);
+  }
+  return scenes;
+}
 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";
+  const expectedScope = version >= 2 ? "final" : "tour";
   if (value.walkthrough.scope !== expectedScope) {
     throw new Error(`authoringCoverage.walkthrough.scope must be ${expectedScope}.`);
   }
@@ -869,7 +1113,49 @@ function validateAuthoringCoverage(value, version) {
     }
   }
 }
-function validateZoom(value) {
+function validateModeTours(value, version) {
+  if (!isRecord2(value)) throw new Error("Change-tour manifest tours must be an object.");
+  if (value.historical === void 0 && value.deconstructed === void 0) {
+    throw new Error("Change-tour manifest tours must contain a historical or deconstructed tour.");
+  }
+  for (const mode of ["historical", "deconstructed"]) {
+    const tour = value[mode];
+    if (tour === void 0) continue;
+    if (!isRecord2(tour) || !Array.isArray(tour.chapters) || !Array.isArray(tour.scenes) || tour.chapters.length === 0 || tour.scenes.length === 0) {
+      throw new Error(`Change-tour manifest tours.${mode} must contain non-empty chapters and scenes arrays.`);
+    }
+    const sceneIds = /* @__PURE__ */ new Set();
+    let hasDeconstructed = false;
+    for (const [index, scene] of tour.scenes.entries()) {
+      validateScene(scene, index, version);
+      if (sceneIds.has(scene.id)) {
+        throw new Error(`Duplicate ${mode} tour scene id: ${scene.id}`);
+      }
+      sceneIds.add(scene.id);
+      if (scene.kind === "deconstructed-diff") hasDeconstructed = true;
+      if (mode === "historical" && scene.kind === "deconstructed-diff") {
+        throw new Error("Historical tours cannot contain synthetic deconstructed scenes.");
+      }
+    }
+    if (mode === "deconstructed" && !hasDeconstructed) {
+      throw new Error("Deconstructed tours must contain a constructed deconstructed-diff scene.");
+    }
+    for (const [index, chapter] of tour.chapters.entries()) {
+      if (!isRecord2(chapter)) {
+        throw new Error(`tours.${mode}.chapters[${index}] must be an object.`);
+      }
+      requireString2(chapter.id, `tours.${mode}.chapters[${index}].id`);
+      requireString2(chapter.title, `tours.${mode}.chapters[${index}].title`);
+      requireStringArray2(chapter.sceneIds, `tours.${mode}.chapters[${index}].sceneIds`);
+      for (const sceneId of chapter.sceneIds) {
+        if (!sceneIds.has(sceneId)) {
+          throw new Error(`tours.${mode} chapter references unknown scene id: ${sceneId}`);
+        }
+      }
+    }
+  }
+}
+function validateZoom(value, version) {
   if (!isRecord2(value.repository) || typeof value.repository.root !== "string" || !value.repository.root) {
     throw new Error("A v2 tour requires its originating repository.root.");
   }
@@ -880,7 +1166,7 @@ function validateZoom(value) {
   const revisions = value.zoom.revisions;
   const ids = /* @__PURE__ */ new Set();
   for (const [index, scene] of revisions.entries()) {
-    validateScene(scene, index);
+    validateScene(scene, index, version);
     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);
@@ -910,7 +1196,7 @@ function validateZoom(value) {
   }
   const finalSceneIds = /* @__PURE__ */ new Set();
   for (const [index, scene] of value.zoom.final.scenes.entries()) {
-    validateScene(scene, index);
+    validateScene(scene, index, version);
     if (scene.kind === "stacked-diff" || scene.kind === "deconstructed-diff") {
       throw new Error("zoom.final must contain only non-stacked scenes.");
     }
@@ -929,18 +1215,23 @@ function validateZoom(value) {
     }
   }
 }
-function validateScene(value, index) {
+function validateScene(value, index, version) {
   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"]) {
     requireString2(value[key], `scenes[${index}].${key}`);
   }
+  if (value.overview !== void 0 && version !== 3) {
+    throw new Error(`scenes[${index}].overview requires manifest version 3.`);
+  }
   validateNarrative2(value, `scenes[${index}]`);
   if (value.kind === "discussion") {
+    validateSceneOverview(value.overview, `scenes[${index}].overview`, { allowComparison: false });
     return;
   }
   if (value.kind === "walkthrough") {
+    validateSceneOverview(value.overview, `scenes[${index}].overview`, { allowComparison: false });
     if (!Array.isArray(value.steps) || value.steps.length === 0) {
       throw new Error(`scenes[${index}].steps must be a non-empty array.`);
     }
@@ -955,7 +1246,7 @@ function validateScene(value, index) {
       }
       validateStepRequirement(step.requirement, `${path}.requirement`);
       validateResolvedAnchor(step.focus, `${path}.focus`);
-      validateScene(step.diff, index);
+      validateScene(step.diff, index, version);
       if (step.diff.kind !== "text-diff") throw new Error(`${path}.diff must be a text-diff scene.`);
       if (step.connection !== void 0) {
         if (!isRecord2(step.connection)) throw new Error(`${path}.connection must be an object.`);
@@ -969,12 +1260,19 @@ function validateScene(value, index) {
   }
   if (value.kind === "stacked-diff") {
     validateStackedScene2(value, index);
+    validateSceneOverview(value.overview, `scenes[${index}].overview`, {
+      endpointIds: value.stack.map((panel) => panel.id)
+    });
     return;
   }
   if (value.kind === "deconstructed-diff") {
     validateDeconstructedScene2(value, index);
+    validateSceneOverview(value.overview, `scenes[${index}].overview`, {
+      endpointIds: value.panels.map((panel) => panel.id)
+    });
     return;
   }
+  validateSceneOverview(value.overview, `scenes[${index}].overview`, { allowComparison: false });
   for (const key of ["path", "leftLabel", "rightLabel", "leftContent", "rightContent"]) {
     requireString2(value[key], `scenes[${index}].${key}`);
   }
@@ -1092,7 +1390,7 @@ function validateMultiPanelSteps(value, panelCount, index, deconstructed) {
 function validateTourFile(value, index) {
   if (!isRecord2(value)) throw new Error(`files[${index}] must be an object.`);
   if (value.kind === "text-diff") {
-    validateScene(value, index);
+    validateScene(value, index, 1);
     return;
   }
   if (value.kind !== "omitted") {
@@ -2794,12 +3092,21 @@ var CHAPTERS = {
   packaging: { id: "packaging", title: "Packaging and dependencies", priority: 4 }
 };
 function buildChangeTourManifest(startPath, options = {}) {
-  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k;
+  var _a, _b, _c, _d;
+  const source = options.source ? parseChangeTourSource(options.source) : void 0;
   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)
+    options.headRef ?? ((_a = source == null ? void 0 : source.range) == null ? void 0 : _a.head),
+    options.baseRef ?? ((_b = source == null ? void 0 : source.range) == null ? void 0 : _b.base)
   );
+  if (source == null ? void 0 : source.review) {
+    validateChangeTourReview(source.review, {
+      expectedRange: {
+        baseOid: range.mergeBaseOid,
+        headOid: range.headOid
+      }
+    });
+  }
   const maxFileBytes = options.maxFileBytes ?? DEFAULT_MAX_TOUR_FILE_BYTES;
   const maxLineBytes = options.maxLineBytes ?? DEFAULT_MAX_TOUR_LINE_BYTES;
   const omittedFiles = [];
@@ -2860,7 +3167,7 @@ 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));
   let defaultScenes = sceneRecords.map(({ scene }, index) => ({ ...scene, id: `file-${index + 1}` }));
-  if (options.story && options.source) {
+  if (options.story && source) {
     throw new Error("A change tour can use either a legacy story or a source file, not both.");
   }
   const attention = buildChangeAttention(files.map((file) => ({
@@ -2880,7 +3187,7 @@ function buildChangeTourManifest(startPath, options = {}) {
     };
     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(
+  const authored = source ? applySource(source, defaultScenes, range.repoRoot) : options.story ? applyStory(options.story, defaultScenes) : buildGeneratedTourLanding(
     defaultScenes,
     buildChapters(sceneRecords, new Map(defaultScenes.map((scene) => [scene.path, scene.id]))),
     attention,
@@ -2897,12 +3204,12 @@ function buildChangeTourManifest(startPath, options = {}) {
   const finalScenes = "finalScenes" in authored ? authored.finalScenes : scenes;
   const finalChapters = "finalChapters" in authored ? authored.finalChapters : chapters;
   const manifest = {
-    // Only authored v2 files opt into repository-bound zoom modes. Generated
+    // 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,
+    version: (source == null ? void 0 : source.version) ?? 1,
+    title: (source == null ? void 0 : source.title) || ((_c = options.story) == null ? void 0 : _c.title) || options.title || `${range.headRef} against ${range.baseRef}`,
+    windowTitle: source == null ? void 0 : source.windowTitle,
+    sourceUrl: (source == null ? void 0 : source.sourceUrl) || ((_d = options.story) == null ? void 0 : _d.sourceUrl) || options.sourceUrl,
     generatedAt: options.generatedAt || (/* @__PURE__ */ new Date()).toISOString(),
     range: {
       baseRef: range.baseRef,
@@ -2921,22 +3228,33 @@ function buildChangeTourManifest(startPath, options = {}) {
     commits: range.commits,
     files,
     chapters,
-    scenes
+    scenes,
+    ...(source == null ? void 0 : source.review) ? { review: source.review } : {}
   };
-  if (manifest.version === 2) {
+  const authoredModeTours = (source == null ? void 0 : source.version) === 3 ? buildAuthoredModeTours(
+    source,
+    authored,
+    defaultScenes,
+    range.repoRoot,
+    range.mergeBaseOid,
+    range.headOid
+  ) : void 0;
+  if (authoredModeTours) manifest.tours = authoredModeTours;
+  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);
+        const authoredScene = source == null ? void 0 : source.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.`);
+          throw new Error(`Deconstructed scene ${scene.id} requires an explicit real revision stack in v2+.`);
         }
         realStack = buildStackedScene(range.repoRoot, {
           ...authoredScene,
           kind: "stacked-diff",
+          overview: compileSceneOverview(authoredScene.overview, false),
           stack: authoredScene.stack,
           files: scene.files.map((file) => file.path),
           steps: []
@@ -2969,6 +3287,9 @@ function buildChangeTourManifest(startPath, options = {}) {
   return parseChangeTourManifest(manifest);
 }
 function applySource(source, defaultScenes, repoRoot) {
+  return applySourceChapters(source, source.chapters, defaultScenes, repoRoot);
+}
+function applySourceChapters(source, chaptersToCompile, defaultScenes, repoRoot) {
   var _a, _b;
   const available = new Map(defaultScenes.map((scene) => [scene.path, scene]));
   const resolvedAnchors = /* @__PURE__ */ new Map();
@@ -2990,7 +3311,7 @@ function applySource(source, defaultScenes, repoRoot) {
   const chapters = [];
   const finalScenes = [];
   const finalChapters = [];
-  for (const chapter of source.chapters) {
+  for (const chapter of chaptersToCompile) {
     const sceneIds = [];
     const finalSceneIds = [];
     for (const authoredScene of chapter.scenes) {
@@ -3044,7 +3365,60 @@ function applySource(source, defaultScenes, repoRoot) {
   }
   return { scenes, chapters, finalScenes, finalChapters };
 }
+function buildAuthoredModeTours(source, root, defaultScenes, repoRoot, mergeBaseOid, headOid) {
+  var _a, _b;
+  const tours = {};
+  if ((_a = source.tours) == null ? void 0 : _a.historical) {
+    const compiled = applySourceChapters(source, source.tours.historical.chapters, defaultScenes, repoRoot);
+    validateHistoricalStackEndpoints(compiled.scenes, mergeBaseOid, headOid);
+    tours.historical = { chapters: compiled.chapters, scenes: compiled.scenes };
+  } else if (source.version === 3) {
+    const fallback = buildHistoricalFallback(source.chapters, root);
+    if (fallback) tours.historical = fallback;
+  }
+  if ((_b = source.tours) == null ? void 0 : _b.deconstructed) {
+    const compiled = applySourceChapters(source, source.tours.deconstructed.chapters, defaultScenes, repoRoot);
+    tours.deconstructed = { chapters: compiled.chapters, scenes: compiled.scenes };
+  } else if (source.version === 3 && source.chapters.some((chapter) => chapter.scenes.some((scene) => scene.kind === "deconstructed-diff"))) {
+    tours.deconstructed = { chapters: root.chapters, scenes: root.scenes };
+  }
+  return tours.historical || tours.deconstructed ? tours : void 0;
+}
+function validateHistoricalStackEndpoints(scenes, mergeBaseOid, headOid) {
+  for (const scene of scenes) {
+    if (scene.kind !== "stacked-diff") continue;
+    if (scene.stack[0].oid !== mergeBaseOid || scene.stack[scene.stack.length - 1].oid !== headOid) {
+      throw new Error(`Historical scene ${scene.id} real stack endpoints must match the tour's final diff range.`);
+    }
+  }
+}
+function buildHistoricalFallback(sourceChapters, root) {
+  const regularScenes = new Map(root.scenes.map((scene) => [scene.id, scene]));
+  const finalScenes = new Map(root.finalScenes.map((scene) => [scene.id, scene]));
+  const scenes = [];
+  const chapters = [];
+  for (const chapter of sourceChapters) {
+    const sceneIds = [];
+    for (const authoredScene of chapter.scenes) {
+      const scene = authoredScene.kind === "deconstructed-diff" ? authoredScene.steps ? finalScenes.get(authoredScene.id) : void 0 : regularScenes.get(authoredScene.id);
+      if (!scene) continue;
+      scenes.push(scene);
+      sceneIds.push(scene.id);
+    }
+    if (sceneIds.length > 0) chapters.push({ id: chapter.id, title: chapter.title, sceneIds });
+  }
+  return scenes.length > 0 ? { chapters, scenes } : void 0;
+}
+function compileSceneOverview(overview, includeComparison = true) {
+  if (!overview) return void 0;
+  return {
+    kind: overview.kind,
+    ...overview.path === void 0 ? {} : { path: overview.path },
+    ...includeComparison && overview.comparison ? { comparison: { ...overview.comparison } } : {}
+  };
+}
 function buildWalkthroughManifestScene(authoredScene, available, resolvedAnchors, connections) {
+  const overview = compileSceneOverview(authoredScene.overview, false);
   return {
     id: authoredScene.id,
     kind: "walkthrough",
@@ -3053,6 +3427,7 @@ function buildWalkthroughManifestScene(authoredScene, available, resolvedAnchors
     bullets: authoredScene.bullets,
     tags: authoredScene.tags,
     takeaway: authoredScene.takeaway,
+    ...overview ? { overview } : {},
     steps: authoredScene.steps.map((step) => {
       const focus = requireResolvedAnchor(resolvedAnchors, step.focus);
       const diff2 = available.get(focus.path);
@@ -3127,6 +3502,7 @@ function buildDeconstructedManifestScene(repoRoot, source, baseRef, targetRef, a
   });
   if (files.length === 0) throw new Error(`Deconstructed scene ${source.id} has no staged files.`);
   const steps = buildDeconstructedFocusSteps(source.id, compiled.stages, files);
+  const overview = compileSceneOverview(source.overview);
   return {
     id: source.id,
     kind: "deconstructed-diff",
@@ -3135,6 +3511,7 @@ function buildDeconstructedManifestScene(repoRoot, source, baseRef, targetRef, a
     bullets: source.bullets,
     tags: source.tags,
     takeaway: source.takeaway,
+    ...overview ? { overview } : {},
     stageLabel: "Explanation stages",
     realRange: {
       baseRef: baseRef || compiled.baseOid,
@@ -3276,6 +3653,7 @@ function buildStackedScene(repoRoot, source, availableFilePaths) {
   });
   if (files.length === 0) throw new Error(`Stacked scene ${source.id} has no materializable text files.`);
   const stackIds = stack.map((entry) => entry.id);
+  const overview = compileSceneOverview(source.overview);
   return {
     id: source.id,
     kind: "stacked-diff",
@@ -3284,6 +3662,7 @@ function buildStackedScene(repoRoot, source, availableFilePaths) {
     bullets: source.bullets,
     tags: source.tags,
     takeaway: source.takeaway,
+    ...overview ? { overview } : {},
     stack,
     files,
     steps: source.steps.length === 0 ? stack.slice(0, -1).map((_, pairIndex) => ({
@@ -3536,7 +3915,7 @@ var DEPTH_ORDER = {
   contextualized: 2
 };
 function buildTourCoverageReport(startPath, sourceValue) {
-  var _a, _b, _c, _d, _e, _f;
+  var _a, _b, _c, _d, _e, _f, _g, _h;
   const source = parseChangeTourSource(sourceValue);
   const inventory = buildChangeInventory(startPath, {
     headRef: (_a = source.range) == null ? void 0 : _a.head,
@@ -3552,8 +3931,10 @@ function buildTourCoverageReport(startPath, sourceValue) {
   const includedUnits = textualUnits.filter((unit) => !excludedIds.has(unit.id));
   const coverage = /* @__PURE__ */ new Map();
   const contextualOnlyEvidence = [];
-  const percentageDecimalPlaces = manifest.version === 2 ? 2 : 0;
-  const walkthroughScenes = manifest.version === 2 ? requireFinalScenes((_e = manifest.zoom) == null ? void 0 : _e.final.scenes) : manifest.scenes;
+  const percentageDecimalPlaces = manifest.version >= 2 ? 2 : 0;
+  const authoredHistoricalScenes = (_f = (_e = manifest.tours) == null ? void 0 : _e.historical) == null ? void 0 : _f.scenes;
+  const historicalHasWalkthrough = (authoredHistoricalScenes == null ? void 0 : authoredHistoricalScenes.some((scene) => scene.kind === "walkthrough")) === true;
+  const walkthroughScenes = manifest.version >= 2 ? requireFinalScenes(historicalHasWalkthrough ? authoredHistoricalScenes : (_g = manifest.zoom) == null ? void 0 : _g.final.scenes) : historicalHasWalkthrough ? authoredHistoricalScenes : manifest.scenes;
   for (const scene of walkthroughScenes) {
     if (scene.kind !== "walkthrough") continue;
     for (const step of scene.steps) {
@@ -3597,7 +3978,7 @@ function buildTourCoverageReport(startPath, sourceValue) {
     },
     depth,
     files,
-    exclusions: (((_f = source.coverage) == null ? void 0 : _f.exclusions) || []).map((exclusion) => {
+    exclusions: (((_h = source.coverage) == null ? void 0 : _h.exclusions) || []).map((exclusion) => {
       var _a2;
       return {
         path: exclusion.path,
@@ -3621,9 +4002,11 @@ function requireFinalScenes(scenes) {
   return scenes;
 }
 function buildExplanationAssignments(source, files) {
+  var _a, _b;
   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 deconstructedChapters = ((_b = (_a = source.tours) == null ? void 0 : _a.deconstructed) == null ? void 0 : _b.chapters) || source.chapters;
+  return deconstructedChapters.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;