@davmash/bygone 0.10.0 → 0.11.0

package/out/tourCoverage.js

@@ -44,11 +44,13 @@ var import_child_process2 = require("child_process");
 var import_child_process = require("child_process");
 var fs = __toESM(require("fs"));
 var DEFAULT_GIT_MAX_BUFFER_BYTES = 64 * 1024 * 1024;
+var DEFAULT_GIT_TIMEOUT_MS = 3e4;
 function createGitRunner(maxBuffer = readGitMaxBuffer()) {
   return (args, cwd) => (0, import_child_process.execFileSync)("git", [...args], {
     cwd,
     encoding: "utf8",
     maxBuffer,
+    timeout: DEFAULT_GIT_TIMEOUT_MS,
     stdio: ["ignore", "pipe", "pipe"]
   }).trimEnd();
 }
@@ -115,12 +117,12 @@ function parseNameStatusZ(output) {
   }
   const changedPaths = [];
   for (let index = 0; index < fields.length; ) {
-    const status = fields[index++];
-    if (!status) {
+    const status2 = fields[index++];
+    if (!status2) {
       continue;
     }
-    const code = status[0];
-    const similarityText = status.slice(1);
+    const code = status2[0];
+    const similarityText = status2.slice(1);
     const similarity = similarityText ? Number.parseInt(similarityText, 10) : void 0;
     if (code === "R" || code === "C") {
       const previousPath = fields[index++];
@@ -471,1568 +473,1878 @@ function runGit(repoRoot, args) {
   });
 }
 
-// src/tourImage.ts
-var MAX_TOUR_IMAGE_BYTES = 8 * 1024 * 1024;
-function record(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-function validPath(value) {
-  return typeof value === "string" && value.length > 0 && !/[\\\x00-\x1f:]/.test(value) && value.split("/").every((part) => part !== "" && part !== "." && part !== "..");
-}
-function validateTourImageSource(value, label) {
-  if (value === void 0) return;
-  if (!record(value) || Object.keys(value).some((key) => !["file", "revision", "alt"].includes(key)) || !validPath(value.file) || !["base", "head"].includes(String(value.revision)) || typeof value.alt !== "string" || !value.alt.trim()) {
-    throw new Error(`${label} must contain a repository-relative file, base/head revision, and non-empty alt text.`);
-  }
-}
-function validateTourImage(value, label) {
-  if (value === void 0) return;
-  if (!record(value) || !validPath(value.path) || typeof value.alt !== "string" || !value.alt.trim() || typeof value.revision !== "string" || !/^[a-f0-9]{40,64}$/.test(value.revision) || typeof value.dataUrl !== "string" || !value.dataUrl.startsWith("data:image/png;base64,")) {
-    throw new Error(`${label} must contain pinned, embedded PNG evidence and alt text.`);
-  }
-  const base64 = value.dataUrl.slice(22);
-  const decodedBytes = base64.length / 4 * 3 - (base64.endsWith("==") ? 2 : base64.endsWith("=") ? 1 : 0);
-  if (decodedBytes > MAX_TOUR_IMAGE_BYTES || base64.length % 4 !== 0 || !/^[A-Za-z0-9+/]+={0,2}$/.test(base64)) throw new Error(`${label} must be a PNG of at most 8 MiB.`);
-  const header = Uint8Array.from(atob(base64.slice(0, 44)), (character) => character.charCodeAt(0));
-  validatePngHeader(header, label);
-}
-function validatePngHeader(bytes, label) {
-  const signature = [137, 80, 78, 71, 13, 10, 26, 10, 0, 0, 0, 13, 73, 72, 68, 82];
-  if (bytes.length < 33 || signature.some((byte, index) => bytes[index] !== byte)) {
-    throw new Error(`${label} must be a PNG with an IHDR header.`);
-  }
-  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-  const width = view.getUint32(16), height = view.getUint32(20);
-  if (!width || !height || width > 16384 || height > 16384 || width * height > 64 * 1024 * 1024) {
-    throw new Error(`${label} exceeds the PNG dimension limit.`);
-  }
-}
-
 // src/changeTour.ts
-var import_child_process3 = require("child_process");
+var import_fs2 = require("fs");
+var import_path = require("path");
 
-// src/tourFraming.ts
-function validateTourFraming(value, version, path) {
-  for (const key of ["opening", "conclusion"]) {
-    const passage = value[key];
-    if (passage === void 0) continue;
-    if (Number(version) < 5) throw new Error(`${path}.${key} requires version 5.`);
-    if (!passage || typeof passage !== "object" || Array.isArray(passage)) {
-      throw new Error(`${path}.${key} must be an object.`);
-    }
-    const fields = passage;
-    for (const field of Object.keys(fields)) {
-      if (!["title", "summary", "bullets"].includes(field)) throw new Error(`${path}.${key}.${field} is unsupported.`);
-    }
-    for (const field of ["title", "summary"]) requireProse(fields[field], `${path}.${key}.${field}`);
-    if (fields.bullets !== void 0) {
-      if (!Array.isArray(fields.bullets)) throw new Error(`${path}.${key}.bullets must be an array.`);
-      fields.bullets.forEach((bullet, index) => requireProse(bullet, `${path}.${key}.bullets[${index}]`));
-    }
-  }
-}
-function validateOverviewPurpose(value, version, path) {
-  if (value === void 0) return;
-  if (version < 5) {
-    if (value && typeof value === "object" && "purpose" in value) throw new Error(`${path}.purpose requires version 5.`);
-    return;
-  }
-  requireProse(value == null ? void 0 : value.purpose, `${path}.purpose`);
-}
-function requireProse(value, path) {
-  if (typeof value !== "string" || !value.trim()) throw new Error(`${path} must be a non-empty string.`);
-}
+// src/changeCorrespondence.ts
+var import_crypto2 = require("crypto");
+var import_child_process3 = require("child_process");
+var import_fs = require("fs");
 
-// src/tourDetails.ts
-function validateChangeTourDetails(value, path) {
-  if (value === void 0) return;
-  if (!isRecord(value)) throw new Error(`${path} must be an object.`);
-  requireOnlyKeys(value, ["audience"], path);
-  validateAudience(value.audience, `${path}.audience`);
-}
-function validateAudience(value, path) {
-  if (value === void 0) return;
-  if (!isRecord(value)) throw new Error(`${path} must be an object.`);
-  requireOnlyKeys(value, [
-    "codebase",
-    "language",
-    "domain",
-    "readingDemand",
-    "purpose",
-    "scope",
-    "estimatedMinutes"
-  ], path);
-  if (typeof value.codebase !== "string" || !["none", "some", "maintainer"].includes(value.codebase)) {
-    throw new Error(`${path}.codebase must be none, some, or maintainer.`);
-  }
-  if (typeof value.language !== "string" || !["none", "basic", "fluent", "advanced"].includes(value.language)) {
-    throw new Error(`${path}.language must be none, basic, fluent, or advanced.`);
-  }
-  if (value.domain !== void 0) requireStringArray(value.domain, `${path}.domain`);
-  if (typeof value.readingDemand !== "string" || !["general", "technical", "specialist"].includes(value.readingDemand)) {
-    throw new Error(`${path}.readingDemand must be general, technical, or specialist.`);
-  }
-  if (typeof value.purpose !== "string" || !["overview", "explanation", "review"].includes(value.purpose)) {
-    throw new Error(`${path}.purpose must be overview, explanation, or review.`);
-  }
-  requireString(value.scope, `${path}.scope`);
-  if (value.estimatedMinutes !== void 0 && (typeof value.estimatedMinutes !== "number" || !Number.isFinite(value.estimatedMinutes) || value.estimatedMinutes <= 0)) {
-    throw new Error(`${path}.estimatedMinutes must be a finite positive number.`);
-  }
-}
-function isRecord(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function requireString(value, path) {
-  if (typeof value !== "string" || value.trim().length === 0) {
-    throw new Error(`${path} must be a non-empty string.`);
-  }
-}
-function requireStringArray(value, path) {
-  if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || item.trim().length === 0)) {
-    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(", ")}`);
-  }
+// node_modules/diff/lib/index.mjs
+function Diff() {
 }
-
-// src/changeTourSource.ts
-var CHANGE_TOUR_SOURCE_VERSION = 5;
-function parseChangeTourSource(value) {
-  if (isRecord2(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 (isRecord2(value) && value.version === 3) {
-    throw new Error("Tour source format version 3 is retired. Remove the review block, set source version to 4, and recompile the tour.");
-  }
-  if (!isRecord2(value) || value.version !== 1 && value.version !== 2 && value.version !== 4 && value.version !== CHANGE_TOUR_SOURCE_VERSION) {
-    throw new Error("Unsupported or missing change-tour source version.");
-  }
-  requireOnlyKeys2(value, [
-    "version",
-    "title",
-    "windowTitle",
-    "sourceUrl",
-    "range",
-    "anchors",
-    "connections",
-    "chapters",
-    "tours",
-    "coverage",
-    "opening",
-    "conclusion",
-    "details"
-  ], "source");
-  validateTourFraming(value, value.version, "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.");
-    requireOnlyKeys2(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.");
-    }
-    requireOnlyKeys2(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.`);
-      requireOnlyKeys2(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.`);
-    }
-    requireOnlyKeys2(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.`);
-    }
-    requireOnlyKeys2(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);
-  }
-  validateSourceChapters(
-    value.chapters,
-    "chapters",
-    value.version,
-    value.anchors,
-    connectionIds,
-    "root"
-  );
-  if (value.details !== void 0) {
-    if (value.version < 5) throw new Error("source.details requires version 5.");
-    validateChangeTourDetails(value.details, "details");
-  }
-  if (value.tours !== void 0) {
-    if (value.version < 4) throw new Error("Independent tours require version 4.");
-    if (!isRecord2(value.tours)) throw new Error("tours must be an object.");
-    requireOnlyKeys2(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.");
+Diff.prototype = {
+  diff: function diff(oldString, newString) {
+    var _options$timeout;
+    var options = arguments.length > 2 && arguments[2] !== void 0 ? arguments[2] : {};
+    var callback = options.callback;
+    if (typeof options === "function") {
+      callback = options;
+      options = {};
     }
-    for (const mode of ["historical", "deconstructed"]) {
-      const tour = value.tours[mode];
-      if (tour === void 0) continue;
-      const path = `tours.${mode}`;
-      if (!isRecord2(tour)) throw new Error(`${path} must be an object.`);
-      requireOnlyKeys2(tour, ["chapters", "opening", "conclusion", "details"], path);
-      validateTourFraming(tour, value.version, path);
-      validateSourceChapters(tour.chapters, `${path}.chapters`, value.version, value.anchors, connectionIds, mode);
-      if (tour.details !== void 0) {
-        if (value.version < 5) throw new Error(`${path}.details requires source version 5.`);
-        validateChangeTourDetails(tour.details, `${path}.details`);
+    this.options = options;
+    var self = this;
+    function done(value) {
+      if (callback) {
+        setTimeout(function() {
+          callback(void 0, value);
+        }, 0);
+        return true;
+      } else {
+        return value;
       }
     }
-  }
-  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 chaptersValue.entries()) {
-    const chapterPath = `${chaptersPath}[${chapterIndex}]`;
-    if (!isRecord2(chapter) || !Array.isArray(chapter.scenes) || chapter.scenes.length === 0) {
-      throw new Error(`${chapterPath} must contain a non-empty scenes array.`);
+    oldString = this.castInput(oldString);
+    newString = this.castInput(newString);
+    oldString = this.removeEmpty(this.tokenize(oldString));
+    newString = this.removeEmpty(this.tokenize(newString));
+    var newLen = newString.length, oldLen = oldString.length;
+    var editLength = 1;
+    var maxEditLength = newLen + oldLen;
+    if (options.maxEditLength) {
+      maxEditLength = Math.min(maxEditLength, options.maxEditLength);
     }
-    requireString2(chapter.id, `${chapterPath}.id`);
-    requireString2(chapter.title, `${chapterPath}.title`);
-    if (chapter.summary !== void 0) {
-      if (version < 5) throw new Error(`${chapterPath}.summary requires source version 5.`);
-      requireProse2(chapter.summary, `${chapterPath}.summary`);
+    var maxExecutionTime = (_options$timeout = options.timeout) !== null && _options$timeout !== void 0 ? _options$timeout : Infinity;
+    var abortAfterTimestamp = Date.now() + maxExecutionTime;
+    var bestPath = [{
+      oldPos: -1,
+      lastComponent: void 0
+    }];
+    var newPos = this.extractCommon(bestPath[0], newString, oldString, 0);
+    if (bestPath[0].oldPos + 1 >= oldLen && newPos + 1 >= newLen) {
+      return done([{
+        value: this.join(newString),
+        count: newString.length
+      }]);
     }
-    requireOnlyKeys2(chapter, ["id", "title", "summary", "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 = `${chapterPath}.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);
-      if (scene.overview !== void 0 && version < 4) {
-        throw new Error(`${path}.overview requires version 4.`);
-      }
-      validateOverviewPurpose(scene.overview, version, `${path}.overview`);
-      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.`);
+    var minDiagonalToConsider = -Infinity, maxDiagonalToConsider = Infinity;
+    function execEditLength() {
+      for (var diagonalPath = Math.max(minDiagonalToConsider, -editLength); diagonalPath <= Math.min(maxDiagonalToConsider, editLength); diagonalPath += 2) {
+        var basePath = void 0;
+        var removePath = bestPath[diagonalPath - 1], addPath = bestPath[diagonalPath + 1];
+        if (removePath) {
+          bestPath[diagonalPath - 1] = void 0;
         }
-        validateDeconstructedScene(scene, path);
-        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);
+        var canAdd = false;
+        if (addPath) {
+          var addPathNewPos = addPath.oldPos - diagonalPath;
+          canAdd = addPath && 0 <= addPathNewPos && addPathNewPos < newLen;
         }
-        if (requireRealEvidence || scene.steps !== void 0) {
-          validateWalkthroughSteps(scene, path, anchors, connectionIds);
+        var canRemove = removePath && removePath.oldPos + 1 < oldLen;
+        if (!canAdd && !canRemove) {
+          bestPath[diagonalPath] = void 0;
+          continue;
+        }
+        if (!canRemove || canAdd && removePath.oldPos + 1 < addPath.oldPos) {
+          basePath = self.addToPath(addPath, true, void 0, 0);
+        } else {
+          basePath = self.addToPath(removePath, void 0, true, 1);
+        }
+        newPos = self.extractCommon(basePath, newString, oldString, diagonalPath);
+        if (basePath.oldPos + 1 >= oldLen && newPos + 1 >= newLen) {
+          return done(buildValues(self, basePath.lastComponent, newString, oldString, self.useLongestToken));
+        } else {
+          bestPath[diagonalPath] = basePath;
+          if (basePath.oldPos + 1 >= oldLen) {
+            maxDiagonalToConsider = Math.min(maxDiagonalToConsider, diagonalPath - 1);
+          }
+          if (newPos + 1 >= newLen) {
+            minDiagonalToConsider = Math.max(minDiagonalToConsider, diagonalPath + 1);
+          }
         }
-        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, 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.`);
+      editLength++;
+    }
+    if (callback) {
+      (function exec() {
+        setTimeout(function() {
+          if (editLength > maxEditLength || Date.now() > abortAfterTimestamp) {
+            return callback();
+          }
+          if (!execEditLength()) {
+            exec();
+          }
+        }, 0);
+      })();
+    } else {
+      while (editLength <= maxEditLength && Date.now() <= abortAfterTimestamp) {
+        var ret = execEditLength();
+        if (ret) {
+          return ret;
+        }
       }
-      requireOnlyKeys2(scene, ["id", "kind", "title", "summary", "bullets", "tags", "takeaway", "overview", "steps"], path);
-      validateSceneOverview(scene.overview, `${path}.overview`, { allowComparison: false });
-      validateWalkthroughSteps(scene, path, anchors, connectionIds);
     }
-  }
-  if (mode === "deconstructed" && !chaptersValue.some((chapter) => isRecord2(chapter) && Array.isArray(chapter.scenes) && chapter.scenes.some((scene) => isRecord2(scene) && scene.kind === "deconstructed-diff"))) {
-    throw new Error(`${chaptersPath} must contain at least one deconstructed-diff scene.`);
-  }
-}
-function stackedOverviewEndpointIds(scene, path) {
-  if (!Array.isArray(scene.stack)) {
-    throw new Error(`${path}.stack must be an array.`);
-  }
-  return scene.stack.filter(isRecord2).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(isRecord2).map((stage) => typeof stage.id === "string" ? `explanation-stage-${stage.id}` : "").filter((id) => id.length > 0)
-  ];
-}
-function validateDeconstructedScene(scene, path) {
-  requireOnlyKeys2(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) {
-    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.`);
-    requireOnlyKeys2(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.`);
+  },
+  addToPath: function addToPath(path, added, removed, oldPosInc) {
+    var last = path.lastComponent;
+    if (last && last.added === added && last.removed === removed) {
+      return {
+        oldPos: path.oldPos + oldPosInc,
+        lastComponent: {
+          count: last.count + 1,
+          added,
+          removed,
+          previousComponent: last.previousComponent
+        }
+      };
+    } else {
+      return {
+        oldPos: path.oldPos + oldPosInc,
+        lastComponent: {
+          count: 1,
+          added,
+          removed,
+          previousComponent: last
+        }
+      };
     }
-    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 (!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`);
-    requireOnlyKeys2(step, ["id", "title", "body", "focus", "connection", "depth", "requirement", "image"], stepPath);
-    if (step.depth !== void 0 && !["mentioned", "explained", "contextualized"].includes(String(step.depth))) {
-      throw new Error(`${stepPath}.depth must be mentioned, explained, or contextualized.`);
+  },
+  extractCommon: function extractCommon(basePath, newString, oldString, diagonalPath) {
+    var newLen = newString.length, oldLen = oldString.length, oldPos = basePath.oldPos, newPos = oldPos - diagonalPath, commonCount = 0;
+    while (newPos + 1 < newLen && oldPos + 1 < oldLen && this.equals(newString[newPos + 1], oldString[oldPos + 1])) {
+      newPos++;
+      oldPos++;
+      commonCount++;
     }
-    validateStepRequirement(step.requirement, `${stepPath}.requirement`);
-    validateTourImageSource(step.image, `${stepPath}.image`);
-    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}.`);
+    if (commonCount) {
+      basePath.lastComponent = {
+        count: commonCount,
+        previousComponent: basePath.lastComponent
+      };
+    }
+    basePath.oldPos = oldPos;
+    return newPos;
+  },
+  equals: function equals(left, right) {
+    if (this.options.comparator) {
+      return this.options.comparator(left, right);
+    } else {
+      return left === right || this.options.ignoreCase && left.toLowerCase() === right.toLowerCase();
+    }
+  },
+  removeEmpty: function removeEmpty(array) {
+    var ret = [];
+    for (var i = 0; i < array.length; i++) {
+      if (array[i]) {
+        ret.push(array[i]);
+      }
+    }
+    return ret;
+  },
+  castInput: function castInput(value) {
+    return value;
+  },
+  tokenize: function tokenize(value) {
+    return value.split("");
+  },
+  join: function join(chars) {
+    return chars.join("");
+  }
+};
+function buildValues(diff2, lastComponent, newString, oldString, useLongestToken) {
+  var components = [];
+  var nextComponent;
+  while (lastComponent) {
+    components.push(lastComponent);
+    nextComponent = lastComponent.previousComponent;
+    delete lastComponent.previousComponent;
+    lastComponent = nextComponent;
+  }
+  components.reverse();
+  var componentPos = 0, componentLen = components.length, newPos = 0, oldPos = 0;
+  for (; componentPos < componentLen; componentPos++) {
+    var component = components[componentPos];
+    if (!component.removed) {
+      if (!component.added && useLongestToken) {
+        var value = newString.slice(newPos, newPos + component.count);
+        value = value.map(function(value2, i) {
+          var oldValue = oldString[oldPos + i];
+          return oldValue.length > value2.length ? oldValue : value2;
+        });
+        component.value = diff2.join(value);
+      } else {
+        component.value = diff2.join(newString.slice(newPos, newPos + component.count));
+      }
+      newPos += component.count;
+      if (!component.added) {
+        oldPos += component.count;
+      }
+    } else {
+      component.value = diff2.join(oldString.slice(oldPos, oldPos + component.count));
+      oldPos += component.count;
+      if (componentPos && components[componentPos - 1].added) {
+        var tmp = components[componentPos - 1];
+        components[componentPos - 1] = components[componentPos];
+        components[componentPos] = tmp;
+      }
     }
   }
-}
-function validateDeconstructedSelection(value, path, requiresReason) {
-  if (!isRecord2(value)) throw new Error(`${path} must be an object.`);
-  requireOnlyKeys2(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.`);
+  var finalComponent = components[componentLen - 1];
+  if (componentLen > 1 && typeof finalComponent.value === "string" && (finalComponent.added || finalComponent.removed) && diff2.equals("", finalComponent.value)) {
+    components[componentLen - 2].value += finalComponent.value;
+    components.pop();
   }
-  if (requiresReason) requireString2(value.reason, `${path}.reason`);
+  return components;
 }
-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.`);
+var characterDiff = new Diff();
+function diffChars(oldStr, newStr, options) {
+  return characterDiff.diff(oldStr, newStr, options);
+}
+var extendedWordChars = /^[A-Za-z\xC0-\u02C6\u02C8-\u02D7\u02DE-\u02FF\u1E00-\u1EFF]+$/;
+var reWhitespace = /\S/;
+var wordDiff = new Diff();
+wordDiff.equals = function(left, right) {
+  if (this.options.ignoreCase) {
+    left = left.toLowerCase();
+    right = right.toLowerCase();
   }
-  const ids = /* @__PURE__ */ new Set();
-  for (const [index, entry] of stack.entries()) {
-    if (!isRecord2(entry)) throw new Error(`${path}[${index}] must be an object.`);
-    requireOnlyKeys2(entry, ["id", "ref", "label"], `${path}[${index}]`);
-    requireString2(entry.id, `${path}[${index}].id`);
-    requireString2(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);
+  return left === right || this.options.ignoreWhitespace && !reWhitespace.test(left) && !reWhitespace.test(right);
+};
+wordDiff.tokenize = function(value) {
+  var tokens = value.split(/([^\S\r\n]+|[()[\]{}'"\r\n]|\b)/);
+  for (var i = 0; i < tokens.length - 1; i++) {
+    if (!tokens[i + 1] && tokens[i + 2] && extendedWordChars.test(tokens[i]) && extendedWordChars.test(tokens[i + 2])) {
+      tokens[i] += tokens[i + 2];
+      tokens.splice(i + 1, 2);
+      i--;
+    }
   }
+  return tokens;
+};
+function diffWordsWithSpace(oldStr, newStr, options) {
+  return wordDiff.diff(oldStr, newStr, options);
 }
-function validateStackedScene(scene, path, minimum = 3) {
-  requireOnlyKeys2(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.`);
+var lineDiff = new Diff();
+lineDiff.tokenize = function(value) {
+  if (this.options.stripTrailingCr) {
+    value = value.replace(/\r\n/g, "\n");
   }
-  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.`);
-    requireOnlyKeys2(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);
+  var retLines = [], linesAndNewlines = value.split(/(\n|\r\n)/);
+  if (!linesAndNewlines[linesAndNewlines.length - 1]) {
+    linesAndNewlines.pop();
   }
-  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.`);
-    requireOnlyKeys2(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.`);
+  for (var i = 0; i < linesAndNewlines.length; i++) {
+    var line = linesAndNewlines[i];
+    if (i % 2 && !this.options.newlineIsToken) {
+      retLines[retLines.length - 1] += line;
+    } else {
+      if (this.options.ignoreWhitespace) {
+        line = line.trim();
+      }
+      retLines.push(line);
     }
   }
+  return retLines;
+};
+function diffLines(oldStr, newStr, callback) {
+  return lineDiff.diff(oldStr, newStr, callback);
 }
-function validateStepRequirement(value, path) {
-  if (value === void 0) return;
-  if (!isRecord2(value)) throw new Error(`${path} must be an object.`);
-  requireOnlyKeys2(value, ["id", "text", "status", "source", "confidence"], path);
-  requireString2(value.id, `${path}.id`);
-  requireString2(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.`);
+var sentenceDiff = new Diff();
+sentenceDiff.tokenize = function(value) {
+  return value.split(/(\S.+?[.!?])(?=\s+|$)/);
+};
+var cssDiff = new Diff();
+cssDiff.tokenize = function(value) {
+  return value.split(/([{}:;,]|\s+)/);
+};
+function _typeof(obj) {
+  "@babel/helpers - typeof";
+  if (typeof Symbol === "function" && typeof Symbol.iterator === "symbol") {
+    _typeof = function(obj2) {
+      return typeof obj2;
+    };
+  } else {
+    _typeof = function(obj2) {
+      return obj2 && typeof Symbol === "function" && obj2.constructor === Symbol && obj2 !== Symbol.prototype ? "symbol" : typeof obj2;
+    };
   }
+  return _typeof(obj);
 }
-function validateSceneOverview(value, path, options = {}) {
-  if (value === void 0) return;
-  if (!isRecord2(value)) throw new Error(`${path} must be an object.`);
-  requireOnlyKeys2(value, ["kind", "path", "comparison", "purpose"], path);
-  if (value.kind !== "directory-diff") {
-    throw new Error(`${path}.kind must be directory-diff.`);
-  }
-  if (value.purpose !== void 0) requireString2(value.purpose, `${path}.purpose`);
-  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 (!isRecord2(value.comparison)) throw new Error(`${path}.comparison must be an object.`);
-  requireOnlyKeys2(value.comparison, ["from", "to"], `${path}.comparison`);
-  requireString2(value.comparison.from, `${path}.comparison.from`);
-  requireString2(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.`);
+var objectPrototypeToString = Object.prototype.toString;
+var jsonDiff = new Diff();
+jsonDiff.useLongestToken = true;
+jsonDiff.tokenize = lineDiff.tokenize;
+jsonDiff.castInput = function(value) {
+  var _this$options = this.options, undefinedReplacement = _this$options.undefinedReplacement, _this$options$stringi = _this$options.stringifyReplacer, stringifyReplacer = _this$options$stringi === void 0 ? function(k, v) {
+    return typeof v === "undefined" ? undefinedReplacement : v;
+  } : _this$options$stringi;
+  return typeof value === "string" ? value : JSON.stringify(canonicalize(value, null, null, stringifyReplacer), stringifyReplacer, "  ");
+};
+jsonDiff.equals = function(left, right) {
+  return Diff.prototype.equals.call(jsonDiff, left.replace(/,([\r\n])/g, "$1"), right.replace(/,([\r\n])/g, "$1"));
+};
+function canonicalize(obj, stack, replacementStack, replacer, key) {
+  stack = stack || [];
+  replacementStack = replacementStack || [];
+  if (replacer) {
+    obj = replacer(key, obj);
   }
-  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.`);
-      }
+  var i;
+  for (i = 0; i < stack.length; i += 1) {
+    if (stack[i] === obj) {
+      return replacementStack[i];
     }
   }
-}
-function validateDirectoryOverviewPath(value, path) {
-  requireString2(value, path);
-  if (value.includes("\\")) {
-    throw new Error(`${path} must use a relative POSIX directory path without backslashes.`);
+  var canonicalizedObj;
+  if ("[object Array]" === objectPrototypeToString.call(obj)) {
+    stack.push(obj);
+    canonicalizedObj = new Array(obj.length);
+    replacementStack.push(canonicalizedObj);
+    for (i = 0; i < obj.length; i += 1) {
+      canonicalizedObj[i] = canonicalize(obj[i], stack, replacementStack, replacer, key);
+    }
+    stack.pop();
+    replacementStack.pop();
+    return canonicalizedObj;
   }
-  if (value.startsWith("/") || /^[A-Za-z]:/.test(value)) {
-    throw new Error(`${path} must be relative to the repository root.`);
+  if (obj && obj.toJSON) {
+    obj = obj.toJSON();
   }
-  if (value.split("/").some((segment) => segment === "..")) {
-    throw new Error(`${path} must not contain parent-directory traversal.`);
+  if (_typeof(obj) === "object" && obj !== null) {
+    stack.push(obj);
+    canonicalizedObj = {};
+    replacementStack.push(canonicalizedObj);
+    var sortedKeys = [], _key;
+    for (_key in obj) {
+      if (obj.hasOwnProperty(_key)) {
+        sortedKeys.push(_key);
+      }
+    }
+    sortedKeys.sort();
+    for (i = 0; i < sortedKeys.length; i += 1) {
+      _key = sortedKeys[i];
+      canonicalizedObj[_key] = canonicalize(obj[_key], stack, replacementStack, replacer, _key);
+    }
+    stack.pop();
+    replacementStack.pop();
+  } else {
+    canonicalizedObj = obj;
   }
+  return canonicalizedObj;
 }
-function validateNarrative(value, path) {
-  requireString2(value.summary, `${path}.summary`);
-  requireStringArray2(value.bullets, `${path}.bullets`);
-  requireStringArray2(value.tags, `${path}.tags`);
-  requireString2(value.takeaway, `${path}.takeaway`);
+var arrayDiff = new Diff();
+arrayDiff.tokenize = function(value) {
+  return value.slice();
+};
+arrayDiff.join = arrayDiff.removeEmpty = function(value) {
+  return value;
+};
+function diffArrays(oldArr, newArr, callback) {
+  return arrayDiff.diff(oldArr, newArr, callback);
 }
-function isRecord2(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
+
+// src/changeCorrespondence.ts
+var MAX_BYTES = 16 * 1024 * 1024;
+var MAX_SOURCE_BYTES = 8 * 1024 * 1024;
+var digest = (text) => (0, import_crypto2.createHash)("sha256").update(text, "utf8").digest("hex");
+function object(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Invalid correspondence object.");
+  return value;
 }
-function requireString2(value, path) {
-  if (typeof value !== "string" || value.length === 0) {
-    throw new Error(`${path} must be a non-empty string.`);
-  }
+function list(value, max = 2e4) {
+  if (!Array.isArray(value) || value.length > max) throw new Error("Invalid or over-budget correspondence array.");
+  return value;
 }
-function optionalString(value, path) {
-  if (value !== void 0) {
-    requireString2(value, path);
-  }
+function string(value) {
+  if (typeof value !== "string" || !value || value.length > 4096) throw new Error("Invalid correspondence string.");
+  return value;
 }
-function requireProse2(value, path) {
-  if (typeof value !== "string" || !value.trim()) {
-    throw new Error(`${path} must be a non-empty string.`);
-  }
+function integer(value) {
+  if (!Number.isSafeInteger(value) || value < 0) throw new Error("Invalid correspondence offset.");
+  return value;
 }
-function requireStringArray2(value, path) {
-  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
-    throw new Error(`${path} must be an array of strings.`);
+function filePath(value) {
+  const name = string(value);
+  if (name.startsWith("/") || name.includes("\\") || name.includes("\0") || name.split("/").some((p) => !p || p === "." || p === "..")) {
+    throw new Error("Invalid correspondence repository path.");
   }
+  return name;
 }
-function requireOnlyKeys2(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 hash(value) {
+  const result = string(value);
+  if (!/^[0-9a-f]{64}$/.test(result)) throw new Error("Invalid correspondence digest.");
+  return result;
 }
-
-// src/changeTourManifest.ts
-var CHANGE_TOUR_MANIFEST_VERSION = 5;
-function parseChangeTourManifest(value, options = {}) {
-  if (isRecord3(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 (isRecord3(value) && value.version === 3) {
-    throw new Error("Tour manifest format version 3 is retired. Remove the review block, set source version to 4, and recompile the tour.");
-  }
-  if (!isRecord3(value) || value.version !== 1 && value.version !== 2 && value.version !== 4 && value.version !== CHANGE_TOUR_MANIFEST_VERSION) {
-    throw new Error(`Unsupported or missing change-tour manifest version.`);
-  }
-  if ("review" in value) throw new Error("Change-tour manifests do not support the review field. Put observations in scene and step narrative.");
-  validateTourFraming(value, value.version, "manifest");
-  requireString3(value.title, "title");
-  requireString3(value.generatedAt, "generatedAt");
-  if (value.windowTitle !== void 0) {
-    requireString3(value.windowTitle, "windowTitle");
-  }
-  if (value.sourceUrl !== void 0) {
-    requireString3(value.sourceUrl, "sourceUrl");
-  }
-  if (!isRecord3(value.range)) {
-    throw new Error("Change-tour manifest range must be an object.");
-  }
-  for (const key of ["baseRef", "headRef", "mergeBaseOid", "headOid"]) {
-    requireString3(value.range[key], `range.${key}`);
-  }
-  if (!isRecord3(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}`);
-  }
-  requireStringArray3(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.");
-  }
-  if (value.files !== void 0 && !Array.isArray(value.files)) {
-    throw new Error("Change-tour manifest files must be an array.");
-  }
-  const sceneIds = /* @__PURE__ */ new Set();
-  for (const [index, candidate] of value.scenes.entries()) {
-    validateScene(candidate, index, value.version);
-    if (sceneIds.has(candidate.id)) {
-      throw new Error(`Duplicate change-tour scene id: ${candidate.id}`);
-    }
-    sceneIds.add(candidate.id);
-  }
-  for (const [index, candidate] of value.chapters.entries()) {
-    if (!isRecord3(candidate)) {
-      throw new Error(`chapters[${index}] must be an object.`);
-    }
-    requireString3(candidate.id, `chapters[${index}].id`);
-    requireString3(candidate.title, `chapters[${index}].title`);
-    validateChapterSummary(candidate.summary, value.version, `chapters[${index}].summary`);
-    requireStringArray3(candidate.sceneIds, `chapters[${index}].sceneIds`);
-    for (const sceneId of candidate.sceneIds) {
-      if (!sceneIds.has(sceneId)) {
-        throw new Error(`Chapter references unknown scene id: ${sceneId}`);
+function status(value) {
+  if (value !== "complete" && value !== "partial" && value !== "unavailable") throw new Error("Invalid correspondence analysis status.");
+  return value;
+}
+function readCorrespondenceJson(file) {
+  if ((0, import_fs.statSync)(file).size > MAX_BYTES) throw new Error("Correspondence file exceeds 16 MiB.");
+  return JSON.parse((0, import_fs.readFileSync)(file, "utf8"));
+}
+function validateRange(value, expected) {
+  const input = object(value);
+  for (const key of ["baseOid", "headOid"]) {
+    if (input[key] !== expected[key] || !/^[0-9a-f]{40,64}$/.test(expected[key])) {
+      throw new Error("Correspondence revisions do not match the selected merge-base/head comparison.");
+    }
+  }
+  return { ...expected };
+}
+function validateChangeCorrespondence(repoRoot, input, expected) {
+  const data = object(input);
+  if (data.version !== 1) throw new Error("Unsupported correspondence version.");
+  const range = validateRange(data.range, expected);
+  const documents = object(data.documents), symbols = object(data.symbols);
+  const result = {
+    version: 1,
+    range,
+    producer: string(data.producer),
+    status: status(data.status),
+    documents: { before: [], after: [] },
+    symbols: { before: [], after: [] },
+    relations: [],
+    unresolved: [],
+    limitations: list(data.limitations, 100).map(string)
+  };
+  const entries = /* @__PURE__ */ new Map();
+  const documentsBySide = { before: /* @__PURE__ */ new Map(), after: /* @__PURE__ */ new Map() };
+  const lineIndexes = /* @__PURE__ */ new Map();
+  const lineAt = (side, path, start) => {
+    const key = `${side}:${path}`;
+    let lines = lineIndexes.get(key);
+    if (!lines) {
+      const text = documentsBySide[side].get(path);
+      lines = [0];
+      for (let at = text.indexOf("\n"); at !== -1; at = text.indexOf("\n", at + 1)) lines.push(at + 1);
+      lineIndexes.set(key, lines);
+    }
+    let low = 0, high = lines.length;
+    while (low < high) {
+      const mid = Math.floor((low + high) / 2);
+      if (lines[mid] <= start) low = mid + 1;
+      else high = mid;
+    }
+    return low;
+  };
+  let sourceBytes = 0, symbolBytes = 0;
+  for (const side of ["before", "after"]) {
+    const texts = /* @__PURE__ */ new Map();
+    const oid = side === "before" ? range.baseOid : range.headOid;
+    for (const value of list(documents[side], 128)) {
+      const doc = object(value), name = filePath(doc.path), expectedDigest = hash(doc.digest);
+      const documentStatus = string(doc.status);
+      if (!["complete", "invalid", "unsupported"].includes(documentStatus) || texts.has(name)) throw new Error("Invalid or duplicate correspondence document.");
+      const bytes = (0, import_child_process3.execFileSync)("git", ["show", `${oid}:${name}`], { cwd: repoRoot, timeout: 1e4, maxBuffer: 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] });
+      const text = bytes.toString("utf8");
+      sourceBytes += bytes.length;
+      if (sourceBytes > MAX_SOURCE_BYTES || !Buffer.from(text, "utf8").equals(bytes) || digest(text) !== expectedDigest) {
+        throw new Error(`Correspondence source digest mismatch or source budget exceeded: ${side}/${name}`);
       }
-    }
-  }
-  if (value.summary.includedScenes !== value.scenes.length) {
-    throw new Error("summary.includedScenes must match the number of scenes.");
-  }
-  if (value.details !== void 0) {
-    if (value.version !== 5) throw new Error("details requires manifest version 5.");
-    validateChangeTourDetails(value.details, "details");
-  }
-  const files = value.files === void 0 ? collectLegacyTourFiles(value.scenes) : value.files.map((candidate, index) => {
-    validateTourFile(candidate, index);
-    return candidate;
-  });
-  if (value.files !== void 0 && value.summary.changedFiles !== files.length) {
-    throw new Error("summary.changedFiles must match the number of files.");
+      texts.set(name, { text, status: documentStatus });
+      documentsBySide[side].set(name, text);
+      result.documents[side].push({ path: name, digest: expectedDigest, status: documentStatus, text });
+    }
+    for (const value of list(symbols[side])) {
+      const entry = object(value), name = filePath(entry.path), doc = texts.get(name);
+      const id = string(entry.id), start = integer(entry.start), end = integer(entry.end);
+      if (!doc || start >= end || end > doc.text.length || entries.has(id)) throw new Error("Invalid correspondence symbol ownership/range/ID.");
+      const text = doc.text.slice(start, end);
+      symbolBytes += Buffer.byteLength(text);
+      if (symbolBytes > MAX_SOURCE_BYTES || digest(text) !== hash(entry.digest)) throw new Error(`Correspondence symbol digest mismatch or budget exceeded: ${name}`);
+      const symbol = {
+        id,
+        path: name,
+        name: string(entry.name),
+        kind: string(entry.kind),
+        start,
+        end,
+        digest: digest(text),
+        text,
+        startLine: lineAt(side, name, start),
+        endLine: lineAt(side, name, end - 1)
+      };
+      entries.set(id, { side, symbol, documentStatus: doc.status });
+      result.symbols[side].push(symbol);
+    }
+  }
+  const ids = /* @__PURE__ */ new Set(), sources = /* @__PURE__ */ new Set(), destinations = /* @__PURE__ */ new Set();
+  for (const value of list(data.relations)) {
+    const relation = object(value), id = string(relation.id), sourceId = string(relation.sourceId), destinationId = string(relation.destinationId);
+    const source = entries.get(sourceId), destination = entries.get(destinationId);
+    if (ids.has(id) || sources.has(sourceId) || destinations.has(destinationId)) throw new Error("Conflicting correspondence continuations; preserve them as unresolved candidates.");
+    if ((source == null ? void 0 : source.side) !== "before" || (destination == null ? void 0 : destination.side) !== "after" || source.documentStatus !== "complete" || destination.documentStatus !== "complete") {
+      throw new Error("Correspondence endpoints must resolve to valid, parsed before/after documents.");
+    }
+    ids.add(id);
+    sources.add(sourceId);
+    destinations.add(destinationId);
+    const producers = list(relation.producers, 10).map(string);
+    if (relation.coverage !== void 0 && relation.coverage !== "complete") throw new Error("Invalid correspondence relation coverage.");
+    const covered = result.status === "partial" && relation.coverage === "complete" && producers.some((producer) => ["refactoring-miner", "bygone-strand"].includes(producer));
+    if (result.status !== "complete" && !covered && !(producers.includes("exact-declaration") && source.symbol.text === destination.symbol.text)) continue;
+    const a = source.symbol, b = destination.symbol;
+    result.relations.push({
+      id,
+      sourceId,
+      destinationId,
+      producers,
+      pathChanged: a.path !== b.path,
+      nameChanged: a.name !== b.name,
+      ...relation.coverage === "complete" ? { coverage: "complete" } : {},
+      rawEqual: a.text === b.text,
+      behavior: "unassessed",
+      localDiff: (diffLines(a.text, b.text, { timeout: 100, maxEditLength: 2e3 }) || [{ value: a.text, removed: true }, { value: b.text, added: true }]).map((part) => ({
+        value: part.value,
+        ...part.added ? { added: true } : {},
+        ...part.removed ? { removed: true } : {}
+      }))
+    });
   }
-  if (value.authoringCoverage !== void 0) {
-    validateAuthoringCoverage(value.authoringCoverage, value.version);
+  for (const value of list(data.unresolved)) {
+    const candidate = object(value);
+    const sourceIds = list(candidate.sourceIds).map(string), destinationIds = list(candidate.destinationIds).map(string);
+    if (!sourceIds.length && !destinationIds.length) throw new Error("Unresolved correspondence needs candidate endpoints.");
+    if (sourceIds.some((id) => {
+      var _a;
+      return ((_a = entries.get(id)) == null ? void 0 : _a.side) !== "before";
+    }) || destinationIds.some((id) => {
+      var _a;
+      return ((_a = entries.get(id)) == null ? void 0 : _a.side) !== "after";
+    })) {
+      throw new Error("Unresolved correspondence references unknown endpoints.");
+    }
+    if (sourceIds.some((id) => sources.has(id)) || destinationIds.some((id) => destinations.has(id))) throw new Error("Ambiguous endpoints cannot also be accepted continuations.");
+    result.unresolved.push({ reason: string(candidate.reason), sourceIds, destinationIds });
+  }
+  if (data.diagnostics !== void 0) {
+    const diagnostics = object(data.diagnostics);
+    if (diagnostics.version !== 1) throw new Error("Unsupported correspondence diagnostics version.");
+    let locationCount = 0;
+    result.diagnostics = { version: 1, scope: list(diagnostics.scope, 20).map(string), records: list(diagnostics.records).map((value) => {
+      const record2 = object(value), category = string(record2.category);
+      if (!["outside", "syntax", "rejected", "unmatched", "relationship", "problem"].includes(category)) throw new Error("Invalid correspondence diagnostic category.");
+      return {
+        category,
+        reason: string(record2.reason),
+        ...record2.message !== void 0 ? { message: string(record2.message) } : {},
+        ...record2.producerId !== void 0 ? { producerId: string(record2.producerId) } : {},
+        locations: list(record2.locations, 100).map((value2) => {
+          var _a, _b;
+          if (++locationCount > 4e4) throw new Error("Correspondence diagnostic location budget exceeded.");
+          const location = object(value2), path = filePath(location.path);
+          const side = location.side;
+          if (side !== void 0 && side !== "before" && side !== "after") throw new Error("Invalid diagnostic revision side.");
+          const symbolId = location.symbolId === void 0 ? void 0 : string(location.symbolId);
+          if (symbolId && (((_a = entries.get(symbolId)) == null ? void 0 : _a.side) !== side || ((_b = entries.get(symbolId)) == null ? void 0 : _b.symbol.path) !== path)) throw new Error("Invalid diagnostic symbol reference.");
+          const start = location.start === void 0 ? symbolId ? entries.get(symbolId).symbol.start : void 0 : integer(location.start);
+          const text = side ? documentsBySide[side].get(path) : void 0;
+          if (start !== void 0 && (text === void 0 || start > text.length)) throw new Error("Invalid diagnostic source location.");
+          return {
+            path,
+            ...side ? { side } : {},
+            ...symbolId ? { symbolId } : {},
+            ...start !== void 0 ? { start, line: lineAt(side, path, start) } : {},
+            ...location.reason !== void 0 ? { reason: string(location.reason) } : {}
+          };
+        })
+      };
+    }) };
   }
-  if (value.tours !== void 0) {
-    if (value.version !== 4 && value.version !== 5) throw new Error("Independent tours require manifest version 4.");
-    validateModeTours(value.tours, value.version);
+  return result;
+}
+function loadChangeCorrespondence(repoRoot, file, range) {
+  return validateChangeCorrespondence(repoRoot, readCorrespondenceJson(file), range);
+}
+
+// src/tourSymbol.ts
+function compileTourSymbol(evidence, selector, focus) {
+  let before, after;
+  let status2 = "inferred";
+  if (selector.relation) {
+    const relation = evidence.relations.find((item) => item.id === selector.relation);
+    if (!relation) throw new Error(`No accepted correspondence: ${selector.relation}`);
+    before = evidence.symbols.before.find((item) => item.id === relation.sourceId);
+    after = evidence.symbols.after.find((item) => item.id === relation.destinationId);
+  } else {
+    const id = selector.symbol;
+    if (evidence.relations.some((item) => item.sourceId === id || item.destinationId === id)) throw new Error("Matched symbols must use their accepted relation ID.");
+    before = evidence.symbols.before.find((item) => item.id === id);
+    after = evidence.symbols.after.find((item) => item.id === id);
+    if (!before && !after) throw new Error(`Unknown correspondence symbol: ${id}`);
+    status2 = evidence.unresolved.some((group) => [...group.sourceIds, ...group.destinationIds].includes(id)) ? "ambiguous" : "unmatched";
+  }
+  const endpoint = focus.revision === "base" ? before : after;
+  if (!endpoint || endpoint.path !== focus.path || focus.startLine < endpoint.startLine || focus.endLine > endpoint.endLine) throw new Error("Symbol stop focus must lie within the selected declaration on its revision side.");
+  const text = (side, entry) => entry ? evidence.documents[side].find((doc) => doc.path === entry.path).text : "";
+  const result = {
+    id: selector.relation || selector.symbol,
+    range: evidence.range,
+    status: status2,
+    before,
+    after,
+    context: { leftContent: text("before", before), rightContent: text("after", after) },
+    behavior: "unassessed"
+  };
+  validateTourSymbol(result);
+  return result;
+}
+function validateTourSymbol(value) {
+  const fail = () => {
+    throw new Error("Invalid pinned symbol tour evidence.");
+  };
+  if (!value || typeof value !== "object") fail();
+  const data = value;
+  if (typeof data.id !== "string" || !data.id.trim() || !data.range || ![data.range.baseOid, data.range.headOid].every((oid) => typeof oid === "string" && /^[0-9a-f]{40,64}$/.test(oid)) || !["inferred", "unmatched", "ambiguous"].includes(data.status) || data.behavior !== "unassessed" || !data.context) fail();
+  const count = Number(!!data.before) + Number(!!data.after);
+  if (count !== (data.status === "inferred" ? 2 : 1)) fail();
+  for (const [entry, content] of [[data.before, data.context.leftContent], [data.after, data.context.rightContent]]) {
+    if (typeof content !== "string") fail();
+    if (!entry) {
+      if (content !== "") fail();
+      continue;
+    }
+    if (typeof entry.id !== "string" || !entry.id || typeof entry.name !== "string" || !entry.name || typeof entry.kind !== "string" || !entry.kind || typeof entry.path !== "string" || entry.path.includes("\0") || entry.path.startsWith("/") || entry.path.includes("\\") || entry.path.split("/").some((part) => !part || part === "." || part === "..") || typeof entry.digest !== "string" || !/^[0-9a-f]{64}$/.test(entry.digest) || !Number.isSafeInteger(entry.start) || !Number.isSafeInteger(entry.end) || entry.start < 0 || entry.end <= entry.start || entry.end > content.length || content.slice(entry.start, entry.end) !== entry.text || entry.startLine !== content.slice(0, entry.start).split("\n").length || entry.endLine !== content.slice(0, entry.end - 1).split("\n").length) fail();
   }
-  if (value.version !== 1) validateZoom(value, value.version, Boolean(options.exported));
-  return { ...value, files };
 }
-function validateAuthoringCoverage(value, version) {
-  if (!isRecord3(value) || !isRecord3(value.walkthrough) || !Array.isArray(value.explanationAssignments)) {
-    throw new Error("authoringCoverage must contain walkthrough and explanationAssignments.");
+
+// src/tourImage.ts
+var MAX_TOUR_IMAGE_BYTES = 8 * 1024 * 1024;
+function record(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function validPath(value) {
+  return typeof value === "string" && value.length > 0 && !/[\\\x00-\x1f:]/.test(value) && value.split("/").every((part) => part !== "" && part !== "." && part !== "..");
+}
+function validateTourImageSource(value, label) {
+  if (value === void 0) return;
+  if (!record(value) || Object.keys(value).some((key) => !["file", "revision", "alt"].includes(key)) || !validPath(value.file) || !["base", "head"].includes(String(value.revision)) || typeof value.alt !== "string" || !value.alt.trim()) {
+    throw new Error(`${label} must contain a repository-relative file, base/head revision, and non-empty alt text.`);
   }
-  const expectedScope = version >= 2 ? "final" : "tour";
-  if (value.walkthrough.scope !== expectedScope) {
-    throw new Error(`authoringCoverage.walkthrough.scope must be ${expectedScope}.`);
+}
+function validateTourImage(value, label) {
+  if (value === void 0) return;
+  if (!record(value) || !validPath(value.path) || typeof value.alt !== "string" || !value.alt.trim() || typeof value.revision !== "string" || !/^[a-f0-9]{40,64}$/.test(value.revision) || typeof value.dataUrl !== "string" || !value.dataUrl.startsWith("data:image/png;base64,")) {
+    throw new Error(`${label} must contain pinned, embedded PNG evidence and alt text.`);
   }
-  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.");
+  const base64 = value.dataUrl.slice(22);
+  const decodedBytes = base64.length / 4 * 3 - (base64.endsWith("==") ? 2 : base64.endsWith("=") ? 1 : 0);
+  if (decodedBytes > MAX_TOUR_IMAGE_BYTES || base64.length % 4 !== 0 || !/^[A-Za-z0-9+/]+={0,2}$/.test(base64)) throw new Error(`${label} must be a PNG of at most 8 MiB.`);
+  const header = Uint8Array.from(atob(base64.slice(0, 44)), (character) => character.charCodeAt(0));
+  validatePngHeader(header, label);
+}
+function validatePngHeader(bytes, label) {
+  const signature = [137, 80, 78, 71, 13, 10, 26, 10, 0, 0, 0, 13, 73, 72, 68, 82];
+  if (bytes.length < 33 || signature.some((byte, index) => bytes[index] !== byte)) {
+    throw new Error(`${label} must be a PNG with an IHDR header.`);
   }
-  for (const [index, assignment] of value.explanationAssignments.entries()) {
-    const path = `authoringCoverage.explanationAssignments[${index}]`;
-    if (!isRecord3(assignment)) throw new Error(`${path} must be an object.`);
-    requireString3(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.`);
-    }
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const width = view.getUint32(16), height = view.getUint32(20);
+  if (!width || !height || width > 16384 || height > 16384 || width * height > 64 * 1024 * 1024) {
+    throw new Error(`${label} exceeds the PNG dimension limit.`);
   }
 }
-function validateModeTours(value, version) {
-  if (!isRecord3(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 (!isRecord3(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.`);
-    }
-    validateTourFraming(tour, version, `tours.${mode}`);
-    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 (tour.details !== void 0) {
-      if (version !== 5) throw new Error(`tours.${mode}.details requires manifest version 5.`);
-      validateChangeTourDetails(tour.details, `tours.${mode}.details`);
-    }
-    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 (!isRecord3(chapter)) {
-        throw new Error(`tours.${mode}.chapters[${index}] must be an object.`);
-      }
-      requireString3(chapter.id, `tours.${mode}.chapters[${index}].id`);
-      requireString3(chapter.title, `tours.${mode}.chapters[${index}].title`);
-      validateChapterSummary(chapter.summary, version, `tours.${mode}.chapters[${index}].summary`);
-      requireStringArray3(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}`);
-        }
-      }
+
+// src/changeTour.ts
+var import_child_process4 = require("child_process");
+
+// src/tourFraming.ts
+function validateTourFraming(value, version, path) {
+  for (const key of ["opening", "conclusion"]) {
+    const passage = value[key];
+    if (passage === void 0) continue;
+    if (Number(version) < 5) throw new Error(`${path}.${key} requires version 5.`);
+    if (!passage || typeof passage !== "object" || Array.isArray(passage)) {
+      throw new Error(`${path}.${key} must be an object.`);
+    }
+    const fields = passage;
+    for (const field of Object.keys(fields)) {
+      if (!["title", "summary", "bullets"].includes(field)) throw new Error(`${path}.${key}.${field} is unsupported.`);
+    }
+    for (const field of ["title", "summary"]) requireProse(fields[field], `${path}.${key}.${field}`);
+    if (fields.bullets !== void 0) {
+      if (!Array.isArray(fields.bullets)) throw new Error(`${path}.${key}.bullets must be an array.`);
+      fields.bullets.forEach((bullet, index) => requireProse(bullet, `${path}.${key}.bullets[${index}]`));
     }
   }
 }
-function validateZoom(value, version, exported) {
-  if (!exported && (!isRecord3(value.repository) || typeof value.repository.root !== "string" || !value.repository.root)) {
-    throw new Error("A v2 tour requires its originating repository.root.");
+function validateOverviewPurpose(value, version, path) {
+  if (value === void 0) return;
+  if (version < 5) {
+    if (value && typeof value === "object" && "purpose" in value) throw new Error(`${path}.purpose requires version 5.`);
+    return;
   }
-  if (!isRecord3(value.zoom) || !Array.isArray(value.zoom.revisions) || !isRecord3(value.zoom.final)) {
-    throw new Error("A v2 tour requires zoom metadata and real revision evidence.");
+  requireProse(value == null ? void 0 : value.purpose, `${path}.purpose`);
+}
+function requireProse(value, path) {
+  if (typeof value !== "string" || !value.trim()) throw new Error(`${path} must be a non-empty string.`);
+}
+
+// src/tourDetails.ts
+function validateChangeTourDetails(value, path) {
+  if (value === void 0) return;
+  if (!isRecord(value)) throw new Error(`${path} must be an object.`);
+  requireOnlyKeys(value, ["audience"], path);
+  validateAudience(value.audience, `${path}.audience`);
+}
+function validateAudience(value, path) {
+  if (value === void 0) return;
+  if (!isRecord(value)) throw new Error(`${path} must be an object.`);
+  requireOnlyKeys(value, [
+    "codebase",
+    "language",
+    "domain",
+    "readingDemand",
+    "purpose",
+    "scope",
+    "estimatedMinutes"
+  ], path);
+  if (typeof value.codebase !== "string" || !["none", "some", "maintainer"].includes(value.codebase)) {
+    throw new Error(`${path}.codebase must be none, some, or maintainer.`);
   }
-  const scenes = value.scenes;
-  const revisions = value.zoom.revisions;
-  const ids = /* @__PURE__ */ new Set();
-  for (const [index, scene] of revisions.entries()) {
-    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);
-    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.`);
-    }
+  if (typeof value.language !== "string" || !["none", "basic", "fluent", "advanced"].includes(value.language)) {
+    throw new Error(`${path}.language must be none, basic, fluent, or advanced.`);
   }
-  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.`);
-    }
+  if (value.domain !== void 0) requireStringArray(value.domain, `${path}.domain`);
+  if (typeof value.readingDemand !== "string" || !["general", "technical", "specialist"].includes(value.readingDemand)) {
+    throw new Error(`${path}.readingDemand must be general, technical, or specialist.`);
   }
-  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 (typeof value.purpose !== "string" || !["overview", "explanation", "review"].includes(value.purpose)) {
+    throw new Error(`${path}.purpose must be overview, explanation, or review.`);
   }
-  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.");
+  requireString(value.scope, `${path}.scope`);
+  if (value.estimatedMinutes !== void 0 && (typeof value.estimatedMinutes !== "number" || !Number.isFinite(value.estimatedMinutes) || value.estimatedMinutes <= 0)) {
+    throw new Error(`${path}.estimatedMinutes must be a finite positive number.`);
   }
-  const finalSceneIds = /* @__PURE__ */ new Set();
-  for (const [index, scene] of value.zoom.final.scenes.entries()) {
-    validateScene(scene, index, version);
-    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);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireString(value, path) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${path} must be a non-empty string.`);
   }
-  for (const [index, chapter] of value.zoom.final.chapters.entries()) {
-    if (!isRecord3(chapter) || !Array.isArray(chapter.sceneIds)) {
-      throw new Error(`zoom.final.chapters[${index}] must contain sceneIds.`);
-    }
-    requireString3(chapter.id, `zoom.final.chapters[${index}].id`);
-    requireString3(chapter.title, `zoom.final.chapters[${index}].title`);
-    validateChapterSummary(chapter.summary, version, `zoom.final.chapters[${index}].summary`);
-    for (const sceneId of chapter.sceneIds) {
-      requireString3(sceneId, `zoom.final.chapters[${index}].sceneIds`);
-      if (!finalSceneIds.has(sceneId)) throw new Error(`Final tour chapter references unknown scene: ${sceneId}`);
-    }
+}
+function requireStringArray(value, path) {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || item.trim().length === 0)) {
+    throw new Error(`${path} must be an array of strings.`);
   }
 }
-function validateScene(value, index, version) {
-  if (!isRecord3(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.`);
+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(", ")}`);
   }
-  for (const key of ["id", "title"]) {
-    requireString3(value[key], `scenes[${index}].${key}`);
+}
+
+// src/changeTourSource.ts
+var CHANGE_TOUR_SOURCE_VERSION = 6;
+function parseChangeTourSource(value) {
+  if (isRecord2(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 (value.overview !== void 0 && version < 4) {
-    throw new Error(`scenes[${index}].overview requires manifest version 4.`);
+  if (isRecord2(value) && value.version === 3) {
+    throw new Error("Tour source format version 3 is retired. Remove the review block, set source version to 4, and recompile the tour.");
   }
-  validateOverviewPurpose(value.overview, version, `scenes[${index}].overview`);
-  validateNarrative2(value, `scenes[${index}]`);
-  if (value.kind === "discussion") {
-    validateSceneOverview(value.overview, `scenes[${index}].overview`, { allowComparison: false });
-    return;
+  if (!isRecord2(value) || value.version !== 1 && value.version !== 2 && value.version !== 4 && value.version !== 5 && value.version !== CHANGE_TOUR_SOURCE_VERSION) {
+    throw new Error("Unsupported or missing change-tour source version.");
   }
-  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.`);
+  requireOnlyKeys2(value, [
+    "version",
+    "title",
+    "windowTitle",
+    "sourceUrl",
+    "correspondence",
+    "range",
+    "anchors",
+    "connections",
+    "chapters",
+    "tours",
+    "coverage",
+    "opening",
+    "conclusion",
+    "details"
+  ], "source");
+  validateTourFraming(value, value.version, "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.");
+    requireOnlyKeys2(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.");
     }
-    for (const [stepIndex, step] of value.steps.entries()) {
-      const path = `scenes[${index}].steps[${stepIndex}]`;
-      if (!isRecord3(step) || !isRecord3(step.focus) || !isRecord3(step.diff)) {
-        throw new Error(`${path} must contain focus and diff objects.`);
-      }
-      for (const key of ["id", "title", "body"]) requireString3(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`);
-      validateTourImage(step.image, `${path}.image`);
-      validateResolvedAnchor(step.focus, `${path}.focus`);
-      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 (!isRecord3(step.connection)) throw new Error(`${path}.connection must be an object.`);
-        requireString3(step.connection.id, `${path}.connection.id`);
-        requireString3(step.connection.label, `${path}.connection.label`);
-        validateResolvedAnchor(step.connection.from, `${path}.connection.from`);
-        validateResolvedAnchor(step.connection.to, `${path}.connection.to`);
-      }
+    requireOnlyKeys2(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.`);
+      requireOnlyKeys2(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`);
     }
-    return;
-  }
-  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"]) {
-    requireString3(value[key], `scenes[${index}].${key}`);
-  }
-  if (value.previousPath !== void 0) {
-    requireString3(value.previousPath, `scenes[${index}].previousPath`);
   }
-  requireString3(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`);
+  if (!isRecord2(value.anchors)) {
+    throw new Error("anchors must be an object.");
   }
-}
-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 [id, anchor] of Object.entries(value.anchors)) {
+    if (!isRecord2(anchor)) {
+      throw new Error(`anchors.${id} must be an object.`);
+    }
+    requireOnlyKeys2(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.`);
+    }
   }
-  for (const [panelIndex, panel] of value.stack.entries()) {
-    if (!isRecord3(panel)) throw new Error(`scenes[${index}].stack[${panelIndex}] must be an object.`);
-    for (const key of ["id", "ref", "oid", "label"]) requireString3(panel[key], `scenes[${index}].stack[${panelIndex}].${key}`);
+  if (value.correspondence !== void 0) {
+    if (value.version < 6) throw new Error("correspondence requires source version 6.");
+    requireString2(value.correspondence, "correspondence");
+    if (value.correspondence.startsWith("/") || value.correspondence.includes("\\") || value.correspondence.includes("\0") || value.correspondence.split("/").some((part) => !part || part === "." || part === "..")) throw new Error("correspondence must be a repository-relative file path.");
   }
-  validateMultiPanelFiles(value.files, value.stack.length, index);
-  validateMultiPanelSteps(value.steps, value.stack.length, index, false);
-}
-function validateDeconstructedScene2(value, index) {
-  if (value.stageLabel !== "Explanation stages") {
-    throw new Error(`scenes[${index}].stageLabel must be Explanation stages.`);
+  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.");
   }
-  if (!isRecord3(value.realRange)) throw new Error(`scenes[${index}].realRange must be an object.`);
-  for (const key of ["baseRef", "targetRef", "baseOid", "targetOid"]) {
-    requireString3(value.realRange[key], `scenes[${index}].realRange.${key}`);
+  const connectionIds = /* @__PURE__ */ new Set();
+  for (const [index, connection] of rawConnections.entries()) {
+    if (!isRecord2(connection)) {
+      throw new Error(`connections[${index}] must be an object.`);
+    }
+    requireOnlyKeys2(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);
   }
-  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.`);
+  validateSourceChapters(
+    value.chapters,
+    "chapters",
+    value.version,
+    value.anchors,
+    connectionIds,
+    "root"
+  );
+  if (value.details !== void 0) {
+    if (value.version < 5) throw new Error("source.details requires version 5.");
+    validateChangeTourDetails(value.details, "details");
   }
-  const panels = value.panels;
-  for (const [panelIndex, panel] of panels.entries()) {
-    if (!isRecord3(panel)) throw new Error(`scenes[${index}].panels[${panelIndex}] must be an object.`);
-    for (const key of ["id", "label", "role"]) requireString3(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) requireString3(panel.stageId, `scenes[${index}].panels[${panelIndex}].stageId`);
+  if (value.tours !== void 0) {
+    if (value.version < 4) throw new Error("Independent tours require version 4.");
+    if (!isRecord2(value.tours)) throw new Error("tours must be an object.");
+    requireOnlyKeys2(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 (!isRecord2(tour)) throw new Error(`${path} must be an object.`);
+      requireOnlyKeys2(tour, ["chapters", "opening", "conclusion", "details"], path);
+      validateTourFraming(tour, value.version, path);
+      validateSourceChapters(tour.chapters, `${path}.chapters`, value.version, value.anchors, connectionIds, mode);
+      if (tour.details !== void 0) {
+        if (value.version < 5) throw new Error(`${path}.details requires source version 5.`);
+        validateChangeTourDetails(tour.details, `${path}.details`);
+      }
+    }
   }
-  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 (!isRecord3(step)) return;
-      const pairIndex = Number(step.pairIndex);
-      if (pairIndex < previousPairIndex) {
-        throw new Error(`scenes[${index}].steps must remain grouped in explanation stage order.`);
+  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 chaptersValue.entries()) {
+    const chapterPath = `${chaptersPath}[${chapterIndex}]`;
+    if (!isRecord2(chapter) || !Array.isArray(chapter.scenes) || chapter.scenes.length === 0) {
+      throw new Error(`${chapterPath} must contain a non-empty scenes array.`);
+    }
+    requireString2(chapter.id, `${chapterPath}.id`);
+    requireString2(chapter.title, `${chapterPath}.title`);
+    if (chapter.summary !== void 0) {
+      if (version < 5) throw new Error(`${chapterPath}.summary requires source version 5.`);
+      requireProse2(chapter.summary, `${chapterPath}.summary`);
+    }
+    requireOnlyKeys2(chapter, ["id", "title", "summary", "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 = `${chapterPath}.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);
+      if (scene.overview !== void 0 && version < 4) {
+        throw new Error(`${path}.overview requires version 4.`);
       }
-      previousPairIndex = pairIndex;
-      if (step.stageId !== void 0) requireString3(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`);
-      if (step.stageIndex !== void 0 && Number(step.stageIndex) !== pairIndex) {
-        throw new Error(`scenes[${index}].steps[${stepIndex}].stageIndex must match pairIndex.`);
+      validateOverviewPurpose(scene.overview, version, `${path}.overview`);
+      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);
+        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, version);
+        }
+        continue;
       }
-      if (step.focusIndex !== void 0 && step.focusCount !== void 0 && Number(step.focusIndex) >= Number(step.focusCount)) {
-        throw new Error(`scenes[${index}].steps[${stepIndex}].focusIndex must be less than focusCount.`);
+      if (!Array.isArray(scene.steps) || scene.steps.length === 0) {
+        throw new Error(`${path} must contain a non-empty steps array.`);
       }
-    });
-    for (let stageIndex = 0; stageIndex < panels.length - 1; stageIndex += 1) {
-      const panel = panels[stageIndex + 1];
-      const stageSteps = value.steps.filter((step) => isRecord3(step) && Number(step.pairIndex) === stageIndex);
-      if (!isRecord3(panel) || stageSteps.length === 0) {
-        throw new Error(`scenes[${index}].steps must cover every explanation stage.`);
+      if (scene.kind === "stacked-diff") {
+        validateStackedScene(scene, path, mode === "root" ? version >= 2 ? 2 : 3 : 2);
+        validateSceneOverview(scene.overview, `${path}.overview`, {
+          endpointIds: stackedOverviewEndpointIds(scene, path)
+        });
+        continue;
       }
-      const firstStep = stageSteps[0];
-      const fallbackStageId = isRecord3(firstStep) ? firstStep.id : void 0;
-      if (stageSteps.some((step) => {
-        if (!isRecord3(step)) return true;
-        return (step.stageId ?? fallbackStageId) !== panel.stageId;
-      })) {
-        throw new Error(`scenes[${index}].panels must align with explanation stage ids.`);
+      if (scene.kind !== void 0 && scene.kind !== "walkthrough") {
+        throw new Error(`${path}.kind must be walkthrough, stacked-diff, or deconstructed-diff.`);
       }
+      requireOnlyKeys2(scene, ["id", "kind", "title", "summary", "bullets", "tags", "takeaway", "overview", "steps"], path);
+      validateSceneOverview(scene.overview, `${path}.overview`, { allowComparison: false });
+      validateWalkthroughSteps(scene, path, anchors, connectionIds, version);
     }
   }
+  if (mode === "deconstructed" && !chaptersValue.some((chapter) => isRecord2(chapter) && Array.isArray(chapter.scenes) && chapter.scenes.some((scene) => isRecord2(scene) && scene.kind === "deconstructed-diff"))) {
+    throw new Error(`${chaptersPath} must contain at least one deconstructed-diff scene.`);
+  }
 }
-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 (!isRecord3(file)) throw new Error(`scenes[${index}].files[${fileIndex}] must be an object.`);
-    requireString3(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 (!isRecord3(panel)) throw new Error(`scenes[${index}].files[${fileIndex}].panels[${panelIndex}] must be an object.`);
-      for (const key of ["id", "label", "content"]) requireString3(panel[key], `scenes[${index}].files[${fileIndex}].panels[${panelIndex}].${key}`);
-      if (panel.path !== void 0) requireString3(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.`);
-    }
+function stackedOverviewEndpointIds(scene, path) {
+  if (!Array.isArray(scene.stack)) {
+    throw new Error(`${path}.stack must be an array.`);
   }
+  return scene.stack.filter(isRecord2).map((entry) => typeof entry.id === "string" ? entry.id : "").filter((id) => id.length > 0);
 }
-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 (!isRecord3(step)) throw new Error(`scenes[${index}].steps[${stepIndex}] must be an object.`);
-    for (const key of ["id", "title", "body", "file", "side"]) requireString3(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) {
-      requireStringArray3(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.`);
-    if (step.startLine !== void 0) requirePositiveInteger(step.startLine, `scenes[${index}].steps[${stepIndex}].startLine`);
-    if (step.endLine !== void 0) requirePositiveInteger(step.endLine, `scenes[${index}].steps[${stepIndex}].endLine`);
+function deconstructedOverviewEndpointIds(scene, path) {
+  if (!Array.isArray(scene.stages)) {
+    throw new Error(`${path}.stages must be an array.`);
   }
+  return [
+    "explanation-baseline",
+    ...scene.stages.filter(isRecord2).map((stage) => typeof stage.id === "string" ? `explanation-stage-${stage.id}` : "").filter((id) => id.length > 0)
+  ];
 }
-function validateTourFile(value, index) {
-  if (!isRecord3(value)) throw new Error(`files[${index}] must be an object.`);
-  if (value.kind === "text-diff") {
-    validateScene(value, index, 1);
-    return;
+function validateDeconstructedScene(scene, path) {
+  requireOnlyKeys2(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) {
+    throw new Error(`${path}.stages must contain between 1 and 12 stages.`);
   }
-  if (value.kind !== "omitted") {
-    throw new Error(`files[${index}].kind must be text-diff or omitted.`);
+  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.`);
+    requireOnlyKeys2(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
+    ));
   }
-  for (const key of ["id", "title", "path", "changeKind", "reason"]) {
-    requireString3(value[key], `files[${index}].${key}`);
+  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
+    ));
   }
-  if (value.previousPath !== void 0) requireString3(value.previousPath, `files[${index}].previousPath`);
-  requireNonNegativeInteger(value.additions, `files[${index}].additions`);
-  requireNonNegativeInteger(value.deletions, `files[${index}].deletions`);
 }
-function collectLegacyTourFiles(scenes) {
-  const files = /* @__PURE__ */ new Map();
-  for (const scene of scenes) {
-    if (scene.kind === "text-diff") {
-      if (!files.has(scene.path)) files.set(scene.path, scene);
-      continue;
+function validateWalkthroughSteps(scene, path, anchors, connectionIds, version) {
+  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 (!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`);
+    requireOnlyKeys2(step, ["id", "title", "body", "focus", "connection", "depth", "requirement", "image", "symbol"], 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 (scene.kind === "walkthrough") {
-      for (const step of scene.steps) {
-        if (!files.has(step.diff.path)) files.set(step.diff.path, step.diff);
-      }
+    if (step.symbol !== void 0) {
+      if (version < 6 || !isRecord2(step.symbol)) throw new Error(`${stepPath}.symbol requires an object and source version 6.`);
+      requireOnlyKeys2(step.symbol, ["relation", "symbol"], `${stepPath}.symbol`);
+      if (step.symbol.relation === void 0 === (step.symbol.symbol === void 0)) throw new Error(`${stepPath}.symbol requires exactly one relation or symbol ID.`);
+      requireString2(step.symbol.relation ?? step.symbol.symbol, `${stepPath}.symbol ID`);
+      if (step.image || step.connection) throw new Error(`${stepPath}.symbol cannot combine with image or connection.`);
+    }
+    validateStepRequirement(step.requirement, `${stepPath}.requirement`);
+    validateTourImageSource(step.image, `${stepPath}.image`);
+    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}.`);
     }
   }
-  return [...files.values()].sort((left, right) => left.path.localeCompare(right.path));
-}
-function validateResolvedAnchor(value, path) {
-  if (!isRecord3(value)) throw new Error(`${path} must be an object.`);
-  for (const key of ["id", "path", "revision", "excerpt"]) requireString3(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 validateNarrative2(value, path) {
-  requireString3(value.summary, `${path}.summary`);
-  requireStringArray3(value.bullets, `${path}.bullets`);
-  requireStringArray3(value.tags, `${path}.tags`);
-  requireString3(value.takeaway, `${path}.takeaway`);
 }
-function validateChapterSummary(value, version, path) {
-  if (value === void 0) return;
-  if (version < 5) throw new Error(`${path} requires manifest version 5.`);
-  if (typeof value !== "string" || !value.trim()) {
-    throw new Error(`${path} must be a non-empty string.`);
+function validateDeconstructedSelection(value, path, requiresReason) {
+  if (!isRecord2(value)) throw new Error(`${path} must be an object.`);
+  requireOnlyKeys2(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 isRecord3(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function requireString3(value, path) {
-  if (typeof value !== "string") {
-    throw new Error(`${path} must be a string.`);
+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.`);
   }
-}
-function requireStringArray3(value, path) {
-  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
-    throw new Error(`${path} must be an array of strings.`);
+  const ids = /* @__PURE__ */ new Set();
+  for (const [index, entry] of stack.entries()) {
+    if (!isRecord2(entry)) throw new Error(`${path}[${index}] must be an object.`);
+    requireOnlyKeys2(entry, ["id", "ref", "label"], `${path}[${index}]`);
+    requireString2(entry.id, `${path}[${index}].id`);
+    requireString2(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 requireNonNegativeInteger(value, path) {
-  if (!Number.isInteger(value) || Number(value) < 0) {
-    throw new Error(`${path} must be a non-negative integer.`);
+function validateStackedScene(scene, path, minimum = 3) {
+  requireOnlyKeys2(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.`);
   }
-}
-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.`);
+  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.`);
+    requireOnlyKeys2(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);
   }
-}
-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 = {}) {
-  return compileDeconstructedScene(buildChangeInventory(startPath, {
-    headRef: options.headRef || scene.target,
-    baseRef: options.baseRef || scene.base
-  }), scene);
-}
-function compileDeconstructedScene(inventory, scene) {
-  const ownership = /* @__PURE__ */ new Map();
-  const excludedByFile = /* @__PURE__ */ new Map();
-  const cumulativeByFile = /* @__PURE__ */ new Map();
-  const wholeFileExclusions = /* @__PURE__ */ new Map();
-  const excludedFiles = [];
-  for (const exclusion of scene.exclusions || []) {
-    const file = requireInventoryFile(inventory, exclusion.file, "Exclusion");
-    if (!exclusion.hunks) {
-      if (wholeFileExclusions.has(file)) {
-        throw new Error(`File is excluded more than once: ${exclusion.file}`);
-      }
-      wholeFileExclusions.set(file, exclusion.reason);
-      excludedFiles.push({ path: file.path, reason: exclusion.reason });
+  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.`);
+    requireOnlyKeys2(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 ids = exclusion.hunks || file.units.map((unit) => unit.id);
-    if (file.material !== "text" && exclusion.hunks) {
-      throw new Error(`Unsupported file ${exclusion.file} must be excluded as a whole file.`);
+    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.`);
     }
-    claimHunks(file, ids, `exclusion for ${exclusion.file}`, ownership);
-    const excluded = excludedByFile.get(file) || /* @__PURE__ */ new Set();
-    ids.forEach((id) => excluded.add(id));
-    excludedByFile.set(file, excluded);
   }
-  const stageClaims = scene.stages.map((stage) => {
-    const claims = [];
-    for (const change of stage.changes) {
-      const file = requireInventoryFile(inventory, change.file, `Stage ${stage.id}`);
-      if (file.material !== "text") {
-        throw new Error(`Stage ${stage.id} cannot assign unsupported file: ${change.file}`);
-      }
-      if (file.changeKind === "renamed") {
-        throw new Error(`Stage ${stage.id} cannot assign renamed file ${change.file} until path-transition units are supported.`);
-      }
-      claimHunks(file, change.hunks, `stage ${stage.id}`, ownership);
-      claims.push({ file, ids: [...change.hunks] });
-    }
-    return { stage, claims };
-  });
-  for (const file of inventory.files) {
-    const wholeFileExcluded = wholeFileExclusions.has(file);
-    if (file.material !== "text" || file.changeKind === "renamed" || file.units.length === 0) {
-      if (!wholeFileExcluded) {
-        const reason = file.changeKind === "renamed" ? "rename path transitions are not supported yet" : file.material !== "text" ? `${file.material} content cannot be materialized` : "the change has no textual hunks";
-        throw new Error(`Deconstructed scene ${scene.id} must exclude ${file.path} as a whole file because ${reason}.`);
-      }
-      continue;
-    }
-    for (const unit of file.units) {
-      if (!ownership.has(unitKey(file, unit.id))) {
-        throw new Error(`Unassigned change unit in ${file.path}: ${unit.id}`);
-      }
-    }
+}
+function validateStepRequirement(value, path) {
+  if (value === void 0) return;
+  if (!isRecord2(value)) throw new Error(`${path} must be an object.`);
+  requireOnlyKeys2(value, ["id", "text", "status", "source", "confidence"], path);
+  requireString2(value.id, `${path}.id`);
+  requireString2(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.`);
   }
-  for (const file of inventory.files) {
-    cumulativeByFile.set(file, new Set(excludedByFile.get(file) || []));
+  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.`);
   }
-  const materializableFiles = inventory.files.filter((file) => file.material === "text" && file.changeKind !== "renamed" && file.baseContent !== void 0 && file.headContent !== void 0);
-  const baselineFiles = materializableFiles.map((file) => buildFileState(
-    file,
-    cumulativeByFile.get(file) || /* @__PURE__ */ new Set(),
-    wholeFileExclusions.has(file)
-  ));
-  const stages = [];
-  for (const { stage, claims } of stageClaims) {
-    const introducedHunks = [];
-    const introducedFiles = [];
-    const introducedChanges = [];
-    for (const claim of claims) {
-      const cumulative = cumulativeByFile.get(claim.file) || /* @__PURE__ */ new Set();
-      claim.ids.forEach((id) => {
-        cumulative.add(id);
-        introducedHunks.push(id);
-      });
-      cumulativeByFile.set(claim.file, cumulative);
-      if (!introducedFiles.includes(claim.file.path)) introducedFiles.push(claim.file.path);
-      const introducedChange = introducedChanges.find((change) => change.file === claim.file.path);
-      if (introducedChange) {
-        introducedChange.hunks.push(...claim.ids);
-      } else {
-        introducedChanges.push({ file: claim.file.path, hunks: [...claim.ids] });
-      }
-    }
-    stages.push({
-      id: stage.id,
-      title: stage.title,
-      narration: stage.narration,
-      introducedHunks,
-      introducedFiles,
-      introducedChanges,
-      cumulativeHunks: [...cumulativeByFile.values()].flatMap((ids) => [...ids]),
-      files: materializableFiles.map((file) => buildFileState(
-        file,
-        cumulativeByFile.get(file) || /* @__PURE__ */ new Set(),
-        wholeFileExclusions.has(file)
-      ))
-    });
+}
+function validateSceneOverview(value, path, options = {}) {
+  if (value === void 0) return;
+  if (!isRecord2(value)) throw new Error(`${path} must be an object.`);
+  requireOnlyKeys2(value, ["kind", "path", "comparison", "purpose"], path);
+  if (value.kind !== "directory-diff") {
+    throw new Error(`${path}.kind must be directory-diff.`);
   }
-  for (const file of materializableFiles) {
-    const finalState = buildFileState(
-      file,
-      cumulativeByFile.get(file) || /* @__PURE__ */ new Set(),
-      wholeFileExclusions.has(file)
-    );
-    const expectedExists = file.changeKind !== "deleted";
-    if (finalState.exists !== expectedExists || finalState.content !== file.headContent) {
-      throw new Error(`Final deconstructed state does not match the target for ${file.path}.`);
+  if (value.purpose !== void 0) requireString2(value.purpose, `${path}.purpose`);
+  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 (!isRecord2(value.comparison)) throw new Error(`${path}.comparison must be an object.`);
+  requireOnlyKeys2(value.comparison, ["from", "to"], `${path}.comparison`);
+  requireString2(value.comparison.from, `${path}.comparison.from`);
+  requireString2(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.`);
+      }
     }
   }
-  return {
-    id: scene.id,
-    title: scene.title,
-    baseOid: inventory.range.baseOid,
-    targetOid: inventory.range.headOid,
-    baselineFiles,
-    excludedHunks: [...excludedByFile.values()].flatMap((ids) => [...ids]),
-    excludedFiles,
-    stages
-  };
 }
-function requireInventoryFile(inventory, path, owner) {
-  const matches = inventory.files.filter((file) => file.path === path || file.previousPath === path);
-  if (matches.length === 0) throw new Error(`${owner} references a file outside the change inventory: ${path}`);
-  if (matches.length > 1) throw new Error(`${owner} references an ambiguous changed path: ${path}`);
-  return matches[0];
+function validateDirectoryOverviewPath(value, path) {
+  requireString2(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 claimHunks(file, ids, owner, ownership) {
-  const known = new Set(file.units.map((unit) => unit.id));
-  for (const id of ids) {
-    if (!known.has(id)) throw new Error(`${owner} references an unknown hunk in ${file.path}: ${id}`);
-    const key = unitKey(file, id);
-    const previousOwner = ownership.get(key);
-    if (previousOwner) throw new Error(`Change unit ${id} in ${file.path} is assigned to both ${previousOwner} and ${owner}.`);
-    ownership.set(key, owner);
+function validateNarrative(value, path) {
+  requireString2(value.summary, `${path}.summary`);
+  requireStringArray2(value.bullets, `${path}.bullets`);
+  requireStringArray2(value.tags, `${path}.tags`);
+  requireString2(value.takeaway, `${path}.takeaway`);
+}
+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 unitKey(file, id) {
-  return `${file.previousPath || ""}\0${file.path}\0${id}`;
+function optionalString(value, path) {
+  if (value !== void 0) {
+    requireString2(value, path);
+  }
 }
-function buildFileState(file, selected, wholeFileExcluded) {
-  if (file.baseContent === void 0) throw new Error(`Missing base content for ${file.path}.`);
-  const content = materializeChangeUnits(file.baseContent, file.units, selected);
-  let exists = true;
-  if (file.changeKind === "added") exists = wholeFileExcluded || selected.size > 0;
-  if (file.changeKind === "deleted") exists = !(wholeFileExcluded || selected.size === file.units.length);
-  return {
-    path: file.path,
-    previousPath: file.previousPath,
-    changeKind: file.changeKind,
-    exists,
-    content: exists ? content : "",
-    appliedHunks: [...selected]
-  };
+function requireProse2(value, path) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`${path} must be a non-empty string.`);
+  }
 }
-
-// node_modules/diff/lib/index.mjs
-function Diff() {
+function requireStringArray2(value, path) {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+    throw new Error(`${path} must be an array of strings.`);
+  }
 }
-Diff.prototype = {
-  diff: function diff(oldString, newString) {
-    var _options$timeout;
-    var options = arguments.length > 2 && arguments[2] !== void 0 ? arguments[2] : {};
-    var callback = options.callback;
-    if (typeof options === "function") {
-      callback = options;
-      options = {};
+function requireOnlyKeys2(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 = 6;
+function parseChangeTourManifest(value, options = {}) {
+  if (isRecord3(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 (isRecord3(value) && value.version === 3) {
+    throw new Error("Tour manifest format version 3 is retired. Remove the review block, set source version to 4, and recompile the tour.");
+  }
+  if (!isRecord3(value) || value.version !== 1 && value.version !== 2 && value.version !== 4 && value.version !== 5 && value.version !== CHANGE_TOUR_MANIFEST_VERSION) {
+    throw new Error(`Unsupported or missing change-tour manifest version.`);
+  }
+  if ("review" in value) throw new Error("Change-tour manifests do not support the review field. Put observations in scene and step narrative.");
+  validateTourFraming(value, value.version, "manifest");
+  requireString3(value.title, "title");
+  requireString3(value.generatedAt, "generatedAt");
+  if (value.windowTitle !== void 0) {
+    requireString3(value.windowTitle, "windowTitle");
+  }
+  if (value.sourceUrl !== void 0) {
+    requireString3(value.sourceUrl, "sourceUrl");
+  }
+  if (!isRecord3(value.range)) {
+    throw new Error("Change-tour manifest range must be an object.");
+  }
+  for (const key of ["baseRef", "headRef", "mergeBaseOid", "headOid"]) {
+    requireString3(value.range[key], `range.${key}`);
+  }
+  if (!isRecord3(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}`);
+  }
+  requireStringArray3(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.");
+  }
+  if (value.files !== void 0 && !Array.isArray(value.files)) {
+    throw new Error("Change-tour manifest files must be an array.");
+  }
+  const sceneIds = /* @__PURE__ */ new Set();
+  for (const [index, candidate] of value.scenes.entries()) {
+    validateScene(candidate, index, value.version);
+    if (sceneIds.has(candidate.id)) {
+      throw new Error(`Duplicate change-tour scene id: ${candidate.id}`);
     }
-    this.options = options;
-    var self = this;
-    function done(value) {
-      if (callback) {
-        setTimeout(function() {
-          callback(void 0, value);
-        }, 0);
-        return true;
-      } else {
-        return value;
+    sceneIds.add(candidate.id);
+  }
+  for (const [index, candidate] of value.chapters.entries()) {
+    if (!isRecord3(candidate)) {
+      throw new Error(`chapters[${index}] must be an object.`);
+    }
+    requireString3(candidate.id, `chapters[${index}].id`);
+    requireString3(candidate.title, `chapters[${index}].title`);
+    validateChapterSummary(candidate.summary, value.version, `chapters[${index}].summary`);
+    requireStringArray3(candidate.sceneIds, `chapters[${index}].sceneIds`);
+    for (const sceneId of candidate.sceneIds) {
+      if (!sceneIds.has(sceneId)) {
+        throw new Error(`Chapter references unknown scene id: ${sceneId}`);
       }
     }
-    oldString = this.castInput(oldString);
-    newString = this.castInput(newString);
-    oldString = this.removeEmpty(this.tokenize(oldString));
-    newString = this.removeEmpty(this.tokenize(newString));
-    var newLen = newString.length, oldLen = oldString.length;
-    var editLength = 1;
-    var maxEditLength = newLen + oldLen;
-    if (options.maxEditLength) {
-      maxEditLength = Math.min(maxEditLength, options.maxEditLength);
+  }
+  if (value.summary.includedScenes !== value.scenes.length) {
+    throw new Error("summary.includedScenes must match the number of scenes.");
+  }
+  if (value.details !== void 0) {
+    if (value.version < 5) throw new Error("details requires manifest version 5.");
+    validateChangeTourDetails(value.details, "details");
+  }
+  const files = value.files === void 0 ? collectLegacyTourFiles(value.scenes) : value.files.map((candidate, index) => {
+    validateTourFile(candidate, index);
+    return candidate;
+  });
+  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.tours !== void 0) {
+    if (value.version !== 4 && value.version !== 5 && value.version !== 6) throw new Error("Independent tours require manifest version 4.");
+    validateModeTours(value.tours, value.version);
+  }
+  if (value.version !== 1) validateZoom(value, value.version, Boolean(options.exported));
+  const symbolScenes = [
+    value.scenes,
+    ...isRecord3(value.zoom) && isRecord3(value.zoom.final) ? [value.zoom.final.scenes] : [],
+    ...isRecord3(value.tours) ? Object.values(value.tours).flatMap((tour) => isRecord3(tour) ? [tour.scenes] : []) : []
+  ];
+  for (const scenes of symbolScenes) for (const scene of scenes) {
+    if (scene.kind !== "walkthrough") continue;
+    for (const step of scene.steps) if (step.symbol) {
+      const symbol = step.symbol;
+      if (symbol.range.baseOid !== value.range.mergeBaseOid || symbol.range.headOid !== value.range.headOid) throw new Error("Symbol tour evidence revisions do not match the tour.");
+      const endpoint = step.focus.revision === "base" ? symbol.before : symbol.after;
+      if (!endpoint || endpoint.path !== step.focus.path || step.focus.startLine < endpoint.startLine || step.focus.endLine > endpoint.endLine) throw new Error("Symbol stop focus must lie within its selected declaration.");
     }
-    var maxExecutionTime = (_options$timeout = options.timeout) !== null && _options$timeout !== void 0 ? _options$timeout : Infinity;
-    var abortAfterTimestamp = Date.now() + maxExecutionTime;
-    var bestPath = [{
-      oldPos: -1,
-      lastComponent: void 0
-    }];
-    var newPos = this.extractCommon(bestPath[0], newString, oldString, 0);
-    if (bestPath[0].oldPos + 1 >= oldLen && newPos + 1 >= newLen) {
-      return done([{
-        value: this.join(newString),
-        count: newString.length
-      }]);
+  }
+  return { ...value, files };
+}
+function validateAuthoringCoverage(value, version) {
+  if (!isRecord3(value) || !isRecord3(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 (!isRecord3(assignment)) throw new Error(`${path} must be an object.`);
+    requireString3(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 validateModeTours(value, version) {
+  if (!isRecord3(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 (!isRecord3(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.`);
     }
-    var minDiagonalToConsider = -Infinity, maxDiagonalToConsider = Infinity;
-    function execEditLength() {
-      for (var diagonalPath = Math.max(minDiagonalToConsider, -editLength); diagonalPath <= Math.min(maxDiagonalToConsider, editLength); diagonalPath += 2) {
-        var basePath = void 0;
-        var removePath = bestPath[diagonalPath - 1], addPath = bestPath[diagonalPath + 1];
-        if (removePath) {
-          bestPath[diagonalPath - 1] = void 0;
-        }
-        var canAdd = false;
-        if (addPath) {
-          var addPathNewPos = addPath.oldPos - diagonalPath;
-          canAdd = addPath && 0 <= addPathNewPos && addPathNewPos < newLen;
-        }
-        var canRemove = removePath && removePath.oldPos + 1 < oldLen;
-        if (!canAdd && !canRemove) {
-          bestPath[diagonalPath] = void 0;
-          continue;
-        }
-        if (!canRemove || canAdd && removePath.oldPos + 1 < addPath.oldPos) {
-          basePath = self.addToPath(addPath, true, void 0, 0);
-        } else {
-          basePath = self.addToPath(removePath, void 0, true, 1);
-        }
-        newPos = self.extractCommon(basePath, newString, oldString, diagonalPath);
-        if (basePath.oldPos + 1 >= oldLen && newPos + 1 >= newLen) {
-          return done(buildValues(self, basePath.lastComponent, newString, oldString, self.useLongestToken));
-        } else {
-          bestPath[diagonalPath] = basePath;
-          if (basePath.oldPos + 1 >= oldLen) {
-            maxDiagonalToConsider = Math.min(maxDiagonalToConsider, diagonalPath - 1);
-          }
-          if (newPos + 1 >= newLen) {
-            minDiagonalToConsider = Math.max(minDiagonalToConsider, diagonalPath + 1);
-          }
-        }
+    validateTourFraming(tour, version, `tours.${mode}`);
+    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.");
       }
-      editLength++;
     }
-    if (callback) {
-      (function exec() {
-        setTimeout(function() {
-          if (editLength > maxEditLength || Date.now() > abortAfterTimestamp) {
-            return callback();
-          }
-          if (!execEditLength()) {
-            exec();
-          }
-        }, 0);
-      })();
-    } else {
-      while (editLength <= maxEditLength && Date.now() <= abortAfterTimestamp) {
-        var ret = execEditLength();
-        if (ret) {
-          return ret;
+    if (tour.details !== void 0) {
+      if (version < 5) throw new Error(`tours.${mode}.details requires manifest version 5.`);
+      validateChangeTourDetails(tour.details, `tours.${mode}.details`);
+    }
+    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 (!isRecord3(chapter)) {
+        throw new Error(`tours.${mode}.chapters[${index}] must be an object.`);
+      }
+      requireString3(chapter.id, `tours.${mode}.chapters[${index}].id`);
+      requireString3(chapter.title, `tours.${mode}.chapters[${index}].title`);
+      validateChapterSummary(chapter.summary, version, `tours.${mode}.chapters[${index}].summary`);
+      requireStringArray3(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}`);
         }
       }
     }
-  },
-  addToPath: function addToPath(path, added, removed, oldPosInc) {
-    var last = path.lastComponent;
-    if (last && last.added === added && last.removed === removed) {
-      return {
-        oldPos: path.oldPos + oldPosInc,
-        lastComponent: {
-          count: last.count + 1,
-          added,
-          removed,
-          previousComponent: last.previousComponent
-        }
-      };
-    } else {
-      return {
-        oldPos: path.oldPos + oldPosInc,
-        lastComponent: {
-          count: 1,
-          added,
-          removed,
-          previousComponent: last
-        }
-      };
+  }
+}
+function validateZoom(value, version, exported) {
+  if (!exported && (!isRecord3(value.repository) || typeof value.repository.root !== "string" || !value.repository.root)) {
+    throw new Error("A v2 tour requires its originating repository.root.");
+  }
+  if (!isRecord3(value.zoom) || !Array.isArray(value.zoom.revisions) || !isRecord3(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, 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);
+    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.`);
     }
-  },
-  extractCommon: function extractCommon(basePath, newString, oldString, diagonalPath) {
-    var newLen = newString.length, oldLen = oldString.length, oldPos = basePath.oldPos, newPos = oldPos - diagonalPath, commonCount = 0;
-    while (newPos + 1 < newLen && oldPos + 1 < oldLen && this.equals(newString[newPos + 1], oldString[oldPos + 1])) {
-      newPos++;
-      oldPos++;
-      commonCount++;
+  }
+  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.`);
     }
-    if (commonCount) {
-      basePath.lastComponent = {
-        count: commonCount,
-        previousComponent: basePath.lastComponent
-      };
+  }
+  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, version);
+    if (scene.kind === "stacked-diff" || scene.kind === "deconstructed-diff") {
+      throw new Error("zoom.final must contain only non-stacked scenes.");
     }
-    basePath.oldPos = oldPos;
-    return newPos;
-  },
-  equals: function equals(left, right) {
-    if (this.options.comparator) {
-      return this.options.comparator(left, right);
-    } else {
-      return left === right || this.options.ignoreCase && left.toLowerCase() === right.toLowerCase();
+    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 (!isRecord3(chapter) || !Array.isArray(chapter.sceneIds)) {
+      throw new Error(`zoom.final.chapters[${index}] must contain sceneIds.`);
     }
-  },
-  removeEmpty: function removeEmpty(array) {
-    var ret = [];
-    for (var i = 0; i < array.length; i++) {
-      if (array[i]) {
-        ret.push(array[i]);
+    requireString3(chapter.id, `zoom.final.chapters[${index}].id`);
+    requireString3(chapter.title, `zoom.final.chapters[${index}].title`);
+    validateChapterSummary(chapter.summary, version, `zoom.final.chapters[${index}].summary`);
+    for (const sceneId of chapter.sceneIds) {
+      requireString3(sceneId, `zoom.final.chapters[${index}].sceneIds`);
+      if (!finalSceneIds.has(sceneId)) throw new Error(`Final tour chapter references unknown scene: ${sceneId}`);
+    }
+  }
+}
+function validateScene(value, index, version) {
+  if (!isRecord3(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"]) {
+    requireString3(value[key], `scenes[${index}].${key}`);
+  }
+  if (value.overview !== void 0 && version < 4) {
+    throw new Error(`scenes[${index}].overview requires manifest version 4.`);
+  }
+  validateOverviewPurpose(value.overview, version, `scenes[${index}].overview`);
+  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.`);
+    }
+    for (const [stepIndex, step] of value.steps.entries()) {
+      const path = `scenes[${index}].steps[${stepIndex}]`;
+      if (!isRecord3(step) || !isRecord3(step.focus) || !isRecord3(step.diff)) {
+        throw new Error(`${path} must contain focus and diff objects.`);
+      }
+      for (const key of ["id", "title", "body"]) requireString3(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`);
+      validateTourImage(step.image, `${path}.image`);
+      if (step.symbol !== void 0) {
+        if (version < 6) throw new Error(`${path}.symbol requires manifest version 6.`);
+        if (step.image || step.connection) throw new Error(`${path}.symbol cannot combine with image or connection.`);
+        validateTourSymbol(step.symbol);
+      }
+      validateResolvedAnchor(step.focus, `${path}.focus`);
+      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 (!isRecord3(step.connection)) throw new Error(`${path}.connection must be an object.`);
+        requireString3(step.connection.id, `${path}.connection.id`);
+        requireString3(step.connection.label, `${path}.connection.label`);
+        validateResolvedAnchor(step.connection.from, `${path}.connection.from`);
+        validateResolvedAnchor(step.connection.to, `${path}.connection.to`);
       }
     }
-    return ret;
-  },
-  castInput: function castInput(value) {
-    return value;
-  },
-  tokenize: function tokenize(value) {
-    return value.split("");
-  },
-  join: function join(chars) {
-    return chars.join("");
+    return;
+  }
+  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;
   }
-};
-function buildValues(diff2, lastComponent, newString, oldString, useLongestToken) {
-  var components = [];
-  var nextComponent;
-  while (lastComponent) {
-    components.push(lastComponent);
-    nextComponent = lastComponent.previousComponent;
-    delete lastComponent.previousComponent;
-    lastComponent = nextComponent;
+  validateSceneOverview(value.overview, `scenes[${index}].overview`, { allowComparison: false });
+  for (const key of ["path", "leftLabel", "rightLabel", "leftContent", "rightContent"]) {
+    requireString3(value[key], `scenes[${index}].${key}`);
   }
-  components.reverse();
-  var componentPos = 0, componentLen = components.length, newPos = 0, oldPos = 0;
-  for (; componentPos < componentLen; componentPos++) {
-    var component = components[componentPos];
-    if (!component.removed) {
-      if (!component.added && useLongestToken) {
-        var value = newString.slice(newPos, newPos + component.count);
-        value = value.map(function(value2, i) {
-          var oldValue = oldString[oldPos + i];
-          return oldValue.length > value2.length ? oldValue : value2;
-        });
-        component.value = diff2.join(value);
-      } else {
-        component.value = diff2.join(newString.slice(newPos, newPos + component.count));
+  if (value.previousPath !== void 0) {
+    requireString3(value.previousPath, `scenes[${index}].previousPath`);
+  }
+  requireString3(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 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 (!isRecord3(panel)) throw new Error(`scenes[${index}].stack[${panelIndex}] must be an object.`);
+    for (const key of ["id", "ref", "oid", "label"]) requireString3(panel[key], `scenes[${index}].stack[${panelIndex}].${key}`);
+  }
+  validateMultiPanelFiles(value.files, value.stack.length, index);
+  validateMultiPanelSteps(value.steps, value.stack.length, index, false);
+}
+function validateDeconstructedScene2(value, index) {
+  if (value.stageLabel !== "Explanation stages") {
+    throw new Error(`scenes[${index}].stageLabel must be Explanation stages.`);
+  }
+  if (!isRecord3(value.realRange)) throw new Error(`scenes[${index}].realRange must be an object.`);
+  for (const key of ["baseRef", "targetRef", "baseOid", "targetOid"]) {
+    requireString3(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 (!isRecord3(panel)) throw new Error(`scenes[${index}].panels[${panelIndex}] must be an object.`);
+    for (const key of ["id", "label", "role"]) requireString3(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) requireString3(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 (!isRecord3(step)) return;
+      const pairIndex = Number(step.pairIndex);
+      if (pairIndex < previousPairIndex) {
+        throw new Error(`scenes[${index}].steps must remain grouped in explanation stage order.`);
       }
-      newPos += component.count;
-      if (!component.added) {
-        oldPos += component.count;
+      previousPairIndex = pairIndex;
+      if (step.stageId !== void 0) requireString3(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`);
+      if (step.stageIndex !== void 0 && Number(step.stageIndex) !== pairIndex) {
+        throw new Error(`scenes[${index}].steps[${stepIndex}].stageIndex must match pairIndex.`);
       }
-    } else {
-      component.value = diff2.join(oldString.slice(oldPos, oldPos + component.count));
-      oldPos += component.count;
-      if (componentPos && components[componentPos - 1].added) {
-        var tmp = components[componentPos - 1];
-        components[componentPos - 1] = components[componentPos];
-        components[componentPos] = tmp;
+      if (step.focusIndex !== void 0 && step.focusCount !== void 0 && Number(step.focusIndex) >= Number(step.focusCount)) {
+        throw new Error(`scenes[${index}].steps[${stepIndex}].focusIndex must be less than focusCount.`);
+      }
+    });
+    for (let stageIndex = 0; stageIndex < panels.length - 1; stageIndex += 1) {
+      const panel = panels[stageIndex + 1];
+      const stageSteps = value.steps.filter((step) => isRecord3(step) && Number(step.pairIndex) === stageIndex);
+      if (!isRecord3(panel) || stageSteps.length === 0) {
+        throw new Error(`scenes[${index}].steps must cover every explanation stage.`);
+      }
+      const firstStep = stageSteps[0];
+      const fallbackStageId = isRecord3(firstStep) ? firstStep.id : void 0;
+      if (stageSteps.some((step) => {
+        if (!isRecord3(step)) return true;
+        return (step.stageId ?? fallbackStageId) !== panel.stageId;
+      })) {
+        throw new Error(`scenes[${index}].panels must align with explanation stage ids.`);
       }
     }
   }
-  var finalComponent = components[componentLen - 1];
-  if (componentLen > 1 && typeof finalComponent.value === "string" && (finalComponent.added || finalComponent.removed) && diff2.equals("", finalComponent.value)) {
-    components[componentLen - 2].value += finalComponent.value;
-    components.pop();
-  }
-  return components;
-}
-var characterDiff = new Diff();
-function diffChars(oldStr, newStr, options) {
-  return characterDiff.diff(oldStr, newStr, options);
 }
-var extendedWordChars = /^[A-Za-z\xC0-\u02C6\u02C8-\u02D7\u02DE-\u02FF\u1E00-\u1EFF]+$/;
-var reWhitespace = /\S/;
-var wordDiff = new Diff();
-wordDiff.equals = function(left, right) {
-  if (this.options.ignoreCase) {
-    left = left.toLowerCase();
-    right = right.toLowerCase();
+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 (!isRecord3(file)) throw new Error(`scenes[${index}].files[${fileIndex}] must be an object.`);
+    requireString3(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 (!isRecord3(panel)) throw new Error(`scenes[${index}].files[${fileIndex}].panels[${panelIndex}] must be an object.`);
+      for (const key of ["id", "label", "content"]) requireString3(panel[key], `scenes[${index}].files[${fileIndex}].panels[${panelIndex}].${key}`);
+      if (panel.path !== void 0) requireString3(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.`);
+    }
   }
-  return left === right || this.options.ignoreWhitespace && !reWhitespace.test(left) && !reWhitespace.test(right);
-};
-wordDiff.tokenize = function(value) {
-  var tokens = value.split(/([^\S\r\n]+|[()[\]{}'"\r\n]|\b)/);
-  for (var i = 0; i < tokens.length - 1; i++) {
-    if (!tokens[i + 1] && tokens[i + 2] && extendedWordChars.test(tokens[i]) && extendedWordChars.test(tokens[i + 2])) {
-      tokens[i] += tokens[i + 2];
-      tokens.splice(i + 1, 2);
-      i--;
+}
+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 (!isRecord3(step)) throw new Error(`scenes[${index}].steps[${stepIndex}] must be an object.`);
+    for (const key of ["id", "title", "body", "file", "side"]) requireString3(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) {
+      requireStringArray3(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.`);
+    if (step.startLine !== void 0) requirePositiveInteger(step.startLine, `scenes[${index}].steps[${stepIndex}].startLine`);
+    if (step.endLine !== void 0) requirePositiveInteger(step.endLine, `scenes[${index}].steps[${stepIndex}].endLine`);
   }
-  return tokens;
-};
-function diffWordsWithSpace(oldStr, newStr, options) {
-  return wordDiff.diff(oldStr, newStr, options);
 }
-var lineDiff = new Diff();
-lineDiff.tokenize = function(value) {
-  if (this.options.stripTrailingCr) {
-    value = value.replace(/\r\n/g, "\n");
+function validateTourFile(value, index) {
+  if (!isRecord3(value)) throw new Error(`files[${index}] must be an object.`);
+  if (value.kind === "text-diff") {
+    validateScene(value, index, 1);
+    return;
   }
-  var retLines = [], linesAndNewlines = value.split(/(\n|\r\n)/);
-  if (!linesAndNewlines[linesAndNewlines.length - 1]) {
-    linesAndNewlines.pop();
+  if (value.kind !== "omitted") {
+    throw new Error(`files[${index}].kind must be text-diff or omitted.`);
   }
-  for (var i = 0; i < linesAndNewlines.length; i++) {
-    var line = linesAndNewlines[i];
-    if (i % 2 && !this.options.newlineIsToken) {
-      retLines[retLines.length - 1] += line;
-    } else {
-      if (this.options.ignoreWhitespace) {
-        line = line.trim();
+  for (const key of ["id", "title", "path", "changeKind", "reason"]) {
+    requireString3(value[key], `files[${index}].${key}`);
+  }
+  if (value.previousPath !== void 0) requireString3(value.previousPath, `files[${index}].previousPath`);
+  requireNonNegativeInteger(value.additions, `files[${index}].additions`);
+  requireNonNegativeInteger(value.deletions, `files[${index}].deletions`);
+}
+function collectLegacyTourFiles(scenes) {
+  const files = /* @__PURE__ */ new Map();
+  for (const scene of scenes) {
+    if (scene.kind === "text-diff") {
+      if (!files.has(scene.path)) files.set(scene.path, scene);
+      continue;
+    }
+    if (scene.kind === "walkthrough") {
+      for (const step of scene.steps) {
+        if (!files.has(step.diff.path)) files.set(step.diff.path, step.diff);
       }
-      retLines.push(line);
     }
   }
-  return retLines;
-};
-var sentenceDiff = new Diff();
-sentenceDiff.tokenize = function(value) {
-  return value.split(/(\S.+?[.!?])(?=\s+|$)/);
-};
-var cssDiff = new Diff();
-cssDiff.tokenize = function(value) {
-  return value.split(/([{}:;,]|\s+)/);
-};
-function _typeof(obj) {
-  "@babel/helpers - typeof";
-  if (typeof Symbol === "function" && typeof Symbol.iterator === "symbol") {
-    _typeof = function(obj2) {
-      return typeof obj2;
-    };
-  } else {
-    _typeof = function(obj2) {
-      return obj2 && typeof Symbol === "function" && obj2.constructor === Symbol && obj2 !== Symbol.prototype ? "symbol" : typeof obj2;
-    };
+  return [...files.values()].sort((left, right) => left.path.localeCompare(right.path));
+}
+function validateResolvedAnchor(value, path) {
+  if (!isRecord3(value)) throw new Error(`${path} must be an object.`);
+  for (const key of ["id", "path", "revision", "excerpt"]) requireString3(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 validateNarrative2(value, path) {
+  requireString3(value.summary, `${path}.summary`);
+  requireStringArray3(value.bullets, `${path}.bullets`);
+  requireStringArray3(value.tags, `${path}.tags`);
+  requireString3(value.takeaway, `${path}.takeaway`);
+}
+function validateChapterSummary(value, version, path) {
+  if (value === void 0) return;
+  if (version < 5) throw new Error(`${path} requires manifest version 5.`);
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`${path} must be a non-empty string.`);
+  }
+}
+function isRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireString3(value, path) {
+  if (typeof value !== "string") {
+    throw new Error(`${path} must be a string.`);
+  }
+}
+function requireStringArray3(value, path) {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+    throw new Error(`${path} must be an array of strings.`);
   }
-  return _typeof(obj);
 }
-var objectPrototypeToString = Object.prototype.toString;
-var jsonDiff = new Diff();
-jsonDiff.useLongestToken = true;
-jsonDiff.tokenize = lineDiff.tokenize;
-jsonDiff.castInput = function(value) {
-  var _this$options = this.options, undefinedReplacement = _this$options.undefinedReplacement, _this$options$stringi = _this$options.stringifyReplacer, stringifyReplacer = _this$options$stringi === void 0 ? function(k, v) {
-    return typeof v === "undefined" ? undefinedReplacement : v;
-  } : _this$options$stringi;
-  return typeof value === "string" ? value : JSON.stringify(canonicalize(value, null, null, stringifyReplacer), stringifyReplacer, "  ");
-};
-jsonDiff.equals = function(left, right) {
-  return Diff.prototype.equals.call(jsonDiff, left.replace(/,([\r\n])/g, "$1"), right.replace(/,([\r\n])/g, "$1"));
-};
-function canonicalize(obj, stack, replacementStack, replacer, key) {
-  stack = stack || [];
-  replacementStack = replacementStack || [];
-  if (replacer) {
-    obj = replacer(key, obj);
+function requireNonNegativeInteger(value, path) {
+  if (!Number.isInteger(value) || Number(value) < 0) {
+    throw new Error(`${path} must be a non-negative integer.`);
   }
-  var i;
-  for (i = 0; i < stack.length; i += 1) {
-    if (stack[i] === obj) {
-      return replacementStack[i];
+}
+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 = {}) {
+  return compileDeconstructedScene(buildChangeInventory(startPath, {
+    headRef: options.headRef || scene.target,
+    baseRef: options.baseRef || scene.base
+  }), scene);
+}
+function compileDeconstructedScene(inventory, scene) {
+  const ownership = /* @__PURE__ */ new Map();
+  const excludedByFile = /* @__PURE__ */ new Map();
+  const cumulativeByFile = /* @__PURE__ */ new Map();
+  const wholeFileExclusions = /* @__PURE__ */ new Map();
+  const excludedFiles = [];
+  for (const exclusion of scene.exclusions || []) {
+    const file = requireInventoryFile(inventory, exclusion.file, "Exclusion");
+    if (!exclusion.hunks) {
+      if (wholeFileExclusions.has(file)) {
+        throw new Error(`File is excluded more than once: ${exclusion.file}`);
+      }
+      wholeFileExclusions.set(file, exclusion.reason);
+      excludedFiles.push({ path: file.path, reason: exclusion.reason });
+    }
+    const ids = exclusion.hunks || file.units.map((unit) => unit.id);
+    if (file.material !== "text" && exclusion.hunks) {
+      throw new Error(`Unsupported file ${exclusion.file} must be excluded as a whole file.`);
     }
+    claimHunks(file, ids, `exclusion for ${exclusion.file}`, ownership);
+    const excluded = excludedByFile.get(file) || /* @__PURE__ */ new Set();
+    ids.forEach((id) => excluded.add(id));
+    excludedByFile.set(file, excluded);
   }
-  var canonicalizedObj;
-  if ("[object Array]" === objectPrototypeToString.call(obj)) {
-    stack.push(obj);
-    canonicalizedObj = new Array(obj.length);
-    replacementStack.push(canonicalizedObj);
-    for (i = 0; i < obj.length; i += 1) {
-      canonicalizedObj[i] = canonicalize(obj[i], stack, replacementStack, replacer, key);
+  const stageClaims = scene.stages.map((stage) => {
+    const claims = [];
+    for (const change of stage.changes) {
+      const file = requireInventoryFile(inventory, change.file, `Stage ${stage.id}`);
+      if (file.material !== "text") {
+        throw new Error(`Stage ${stage.id} cannot assign unsupported file: ${change.file}`);
+      }
+      if (file.changeKind === "renamed") {
+        throw new Error(`Stage ${stage.id} cannot assign renamed file ${change.file} until path-transition units are supported.`);
+      }
+      claimHunks(file, change.hunks, `stage ${stage.id}`, ownership);
+      claims.push({ file, ids: [...change.hunks] });
+    }
+    return { stage, claims };
+  });
+  for (const file of inventory.files) {
+    const wholeFileExcluded = wholeFileExclusions.has(file);
+    if (file.material !== "text" || file.changeKind === "renamed" || file.units.length === 0) {
+      if (!wholeFileExcluded) {
+        const reason = file.changeKind === "renamed" ? "rename path transitions are not supported yet" : file.material !== "text" ? `${file.material} content cannot be materialized` : "the change has no textual hunks";
+        throw new Error(`Deconstructed scene ${scene.id} must exclude ${file.path} as a whole file because ${reason}.`);
+      }
+      continue;
+    }
+    for (const unit of file.units) {
+      if (!ownership.has(unitKey(file, unit.id))) {
+        throw new Error(`Unassigned change unit in ${file.path}: ${unit.id}`);
+      }
     }
-    stack.pop();
-    replacementStack.pop();
-    return canonicalizedObj;
   }
-  if (obj && obj.toJSON) {
-    obj = obj.toJSON();
+  for (const file of inventory.files) {
+    cumulativeByFile.set(file, new Set(excludedByFile.get(file) || []));
   }
-  if (_typeof(obj) === "object" && obj !== null) {
-    stack.push(obj);
-    canonicalizedObj = {};
-    replacementStack.push(canonicalizedObj);
-    var sortedKeys = [], _key;
-    for (_key in obj) {
-      if (obj.hasOwnProperty(_key)) {
-        sortedKeys.push(_key);
+  const materializableFiles = inventory.files.filter((file) => file.material === "text" && file.changeKind !== "renamed" && file.baseContent !== void 0 && file.headContent !== void 0);
+  const baselineFiles = materializableFiles.map((file) => buildFileState(
+    file,
+    cumulativeByFile.get(file) || /* @__PURE__ */ new Set(),
+    wholeFileExclusions.has(file)
+  ));
+  const stages = [];
+  for (const { stage, claims } of stageClaims) {
+    const introducedHunks = [];
+    const introducedFiles = [];
+    const introducedChanges = [];
+    for (const claim of claims) {
+      const cumulative = cumulativeByFile.get(claim.file) || /* @__PURE__ */ new Set();
+      claim.ids.forEach((id) => {
+        cumulative.add(id);
+        introducedHunks.push(id);
+      });
+      cumulativeByFile.set(claim.file, cumulative);
+      if (!introducedFiles.includes(claim.file.path)) introducedFiles.push(claim.file.path);
+      const introducedChange = introducedChanges.find((change) => change.file === claim.file.path);
+      if (introducedChange) {
+        introducedChange.hunks.push(...claim.ids);
+      } else {
+        introducedChanges.push({ file: claim.file.path, hunks: [...claim.ids] });
       }
     }
-    sortedKeys.sort();
-    for (i = 0; i < sortedKeys.length; i += 1) {
-      _key = sortedKeys[i];
-      canonicalizedObj[_key] = canonicalize(obj[_key], stack, replacementStack, replacer, _key);
+    stages.push({
+      id: stage.id,
+      title: stage.title,
+      narration: stage.narration,
+      introducedHunks,
+      introducedFiles,
+      introducedChanges,
+      cumulativeHunks: [...cumulativeByFile.values()].flatMap((ids) => [...ids]),
+      files: materializableFiles.map((file) => buildFileState(
+        file,
+        cumulativeByFile.get(file) || /* @__PURE__ */ new Set(),
+        wholeFileExclusions.has(file)
+      ))
+    });
+  }
+  for (const file of materializableFiles) {
+    const finalState = buildFileState(
+      file,
+      cumulativeByFile.get(file) || /* @__PURE__ */ new Set(),
+      wholeFileExclusions.has(file)
+    );
+    const expectedExists = file.changeKind !== "deleted";
+    if (finalState.exists !== expectedExists || finalState.content !== file.headContent) {
+      throw new Error(`Final deconstructed state does not match the target for ${file.path}.`);
     }
-    stack.pop();
-    replacementStack.pop();
-  } else {
-    canonicalizedObj = obj;
   }
-  return canonicalizedObj;
+  return {
+    id: scene.id,
+    title: scene.title,
+    baseOid: inventory.range.baseOid,
+    targetOid: inventory.range.headOid,
+    baselineFiles,
+    excludedHunks: [...excludedByFile.values()].flatMap((ids) => [...ids]),
+    excludedFiles,
+    stages
+  };
 }
-var arrayDiff = new Diff();
-arrayDiff.tokenize = function(value) {
-  return value.slice();
-};
-arrayDiff.join = arrayDiff.removeEmpty = function(value) {
-  return value;
-};
-function diffArrays(oldArr, newArr, callback) {
-  return arrayDiff.diff(oldArr, newArr, callback);
+function requireInventoryFile(inventory, path, owner) {
+  const matches = inventory.files.filter((file) => file.path === path || file.previousPath === path);
+  if (matches.length === 0) throw new Error(`${owner} references a file outside the change inventory: ${path}`);
+  if (matches.length > 1) throw new Error(`${owner} references an ambiguous changed path: ${path}`);
+  return matches[0];
+}
+function claimHunks(file, ids, owner, ownership) {
+  const known = new Set(file.units.map((unit) => unit.id));
+  for (const id of ids) {
+    if (!known.has(id)) throw new Error(`${owner} references an unknown hunk in ${file.path}: ${id}`);
+    const key = unitKey(file, id);
+    const previousOwner = ownership.get(key);
+    if (previousOwner) throw new Error(`Change unit ${id} in ${file.path} is assigned to both ${previousOwner} and ${owner}.`);
+    ownership.set(key, owner);
+  }
+}
+function unitKey(file, id) {
+  return `${file.previousPath || ""}\0${file.path}\0${id}`;
+}
+function buildFileState(file, selected, wholeFileExcluded) {
+  if (file.baseContent === void 0) throw new Error(`Missing base content for ${file.path}.`);
+  const content = materializeChangeUnits(file.baseContent, file.units, selected);
+  let exists = true;
+  if (file.changeKind === "added") exists = wholeFileExcluded || selected.size > 0;
+  if (file.changeKind === "deleted") exists = !(wholeFileExcluded || selected.size === file.units.length);
+  return {
+    path: file.path,
+    previousPath: file.previousPath,
+    changeKind: file.changeKind,
+    exists,
+    content: exists ? content : "",
+    appliedHunks: [...selected]
+  };
 }
 
 // src/diffEngine.ts
@@ -2065,17 +2377,10 @@ function buildTwoWayDiffModel(leftContent, rightContent, options = {}) {
     model.formattingOnly = true;
     return model;
   }
-  const interned = internDiffLines(leftLines, rightLines);
-  const internedChanges = diffArrays(interned.left, interned.right, {
-    timeout: options.timeoutMs ?? DIFF_TIMEOUT_MS
-  });
-  if (!internedChanges) {
+  const changes = diffAnchoredLines(leftLines, rightLines, options.timeoutMs ?? DIFF_TIMEOUT_MS);
+  if (!changes) {
     return buildConservativeTwoWayDiffModel(leftLines, rightLines);
   }
-  const changes = internedChanges.map((change) => ({
-    ...change,
-    value: change.value.map((lineId) => interned.lines[lineId])
-  }));
   const rows = [];
   const renderedLeftLines = [];
   const renderedRightLines = [];
@@ -2190,6 +2495,54 @@ function mergeTouchingBlocks(blocks) {
   }
   return merged;
 }
+function diffAnchoredLines(leftLines, rightLines, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  const namedLines = (lines) => lines.flatMap((line, index) => {
+    const key = normalizeMatchingContent(line);
+    return isInformativeLine(key) ? [{ key, index }] : [];
+  });
+  const leftNames = namedLines(leftLines);
+  const rightNames = namedLines(rightLines);
+  const namedChanges = diffArrays(leftNames.map((line) => line.key), rightNames.map((line) => line.key), {
+    timeout: deadline - Date.now()
+  });
+  if (!namedChanges) return void 0;
+  const changes = [];
+  let leftStart = 0;
+  let rightStart = 0;
+  const appendGap = (leftEnd, rightEnd) => {
+    if (leftStart === leftEnd && rightStart === rightEnd) return true;
+    const interned = internDiffLines(leftLines.slice(leftStart, leftEnd), rightLines.slice(rightStart, rightEnd));
+    const gap = diffArrays(interned.left, interned.right, { timeout: deadline - Date.now() });
+    if (!gap) return false;
+    changes.push(...gap.map((change) => ({ ...change, value: change.value.map((id) => interned.lines[id]) })));
+    return true;
+  };
+  let leftName = 0;
+  let rightName = 0;
+  for (const change of namedChanges) {
+    if (change.removed) {
+      leftName += change.value.length;
+      continue;
+    }
+    if (change.added) {
+      rightName += change.value.length;
+      continue;
+    }
+    for (let index = 0; index < change.value.length; index++) {
+      const leftIndex = leftNames[leftName++].index;
+      const rightIndex = rightNames[rightName++].index;
+      if (!appendGap(leftIndex, rightIndex)) return void 0;
+      const left = leftLines[leftIndex];
+      const right = rightLines[rightIndex];
+      if (left === right) changes.push({ value: [left] });
+      else changes.push({ removed: true, value: [left] }, { added: true, value: [right] });
+      leftStart = leftIndex + 1;
+      rightStart = rightIndex + 1;
+    }
+  }
+  return appendGap(leftLines.length, rightLines.length) ? changes : void 0;
+}
 function internDiffLines(leftLines, rightLines) {
   const lineIds = /* @__PURE__ */ new Map();
   const lines = [];
@@ -3170,8 +3523,8 @@ function buildInlineSegments(leftContent, rightContent) {
     }
   }
   return {
-    leftSegments,
-    rightSegments,
+    leftSegments: normalizeIndentationHighlights(leftSegments),
+    rightSegments: normalizeIndentationHighlights(rightSegments),
     hasInlineChanges
   };
 }
@@ -3205,7 +3558,40 @@ function buildWhitespaceOnlySegments(left, right) {
     append(leftSegments, "context", part.slice(part.length - suffix));
     append(rightSegments, "context", other.slice(other.length - suffix));
   });
-  return { leftSegments, rightSegments };
+  return {
+    leftSegments: normalizeIndentationHighlights(leftSegments),
+    rightSegments: normalizeIndentationHighlights(rightSegments)
+  };
+}
+function normalizeIndentationHighlights(segments) {
+  const result = [];
+  splitSegmentsIntoLines(segments).forEach((line, index) => {
+    if (index > 0) result.push({ kind: "context", text: "\n", emphasis: false });
+    const content = line.map((segment) => segment.text).join("");
+    const indentLength = content.match(/^[\t ]*/u)[0].length;
+    let offset = 0;
+    let emphasized = 0;
+    let kind = "context";
+    for (const segment of line) {
+      if (offset >= indentLength) break;
+      if (segment.emphasis) {
+        emphasized += Math.min(segment.text.length, indentLength - offset);
+        kind = segment.kind;
+      }
+      offset += segment.text.length;
+    }
+    if (emphasized) result.push({ kind, text: content.slice(0, emphasized), emphasis: true });
+    if (indentLength > emphasized) {
+      result.push({ kind: "context", text: content.slice(emphasized, indentLength), emphasis: false });
+    }
+    offset = 0;
+    for (const segment of line) {
+      const start = Math.max(0, indentLength - offset);
+      if (start < segment.text.length) result.push({ ...segment, text: segment.text.slice(start) });
+      offset += segment.text.length;
+    }
+  });
+  return result;
 }
 function splitSegmentsIntoLines(segments) {
   const lines = [[]];
@@ -3341,8 +3727,8 @@ var LOCKFILES = /* @__PURE__ */ new Set([
 ]);
 var MAX_FAN_IN_FILES = 250;
 var MAX_FAN_IN_TEXT_BYTES = 64 * 1024;
-function classifyChangeFileRole(filePath) {
-  const lower = filePath.toLowerCase();
+function classifyChangeFileRole(filePath2) {
+  const lower = filePath2.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";
@@ -3659,10 +4045,21 @@ function buildChangeTourManifest(startPath, options = {}) {
 }
 function applySourceChapters(source, chaptersToCompile, defaultScenes, repoRoot, imageRevisions) {
   var _a, _b;
+  const correspondence = source.correspondence ? (() => {
+    const file = (0, import_fs2.realpathSync)((0, import_path.resolve)(repoRoot, source.correspondence));
+    const name = (0, import_path.relative)((0, import_fs2.realpathSync)(repoRoot), file);
+    if ((0, import_path.isAbsolute)(name) || name === ".." || name.startsWith(`..${import_path.sep}`)) throw new Error("Correspondence artifact must be inside the repository.");
+    return loadChangeCorrespondence(repoRoot, file, { baseOid: imageRevisions.base, headOid: imageRevisions.head });
+  })() : void 0;
+  const compileSymbol = (step, focus) => {
+    if (!step.symbol) return void 0;
+    if (!correspondence) throw new Error(`Step ${step.id} requires a correspondence artifact.`);
+    return compileTourSymbol(correspondence, step.symbol, focus);
+  };
   const available = new Map(defaultScenes.map((scene) => [scene.path, scene]));
   const resolvedAnchors = /* @__PURE__ */ new Map();
   for (const [id, anchor] of Object.entries(source.anchors)) {
-    const file = available.get(anchor.file);
+    const file = available.get(anchor.file) || (anchor.revision === "base" ? defaultScenes.find((scene) => scene.previousPath === anchor.file) : void 0);
     if (!file) {
       throw new Error(`Anchor ${id} references a file outside the text change range: ${anchor.file}`);
     }
@@ -3699,7 +4096,8 @@ function applySourceChapters(source, chaptersToCompile, defaultScenes, repoRoot,
             available,
             resolvedAnchors,
             connections,
-            (image) => compileTourImage(repoRoot, image, imageRevisions[image.revision])
+            (image) => compileTourImage(repoRoot, image, imageRevisions[image.revision]),
+            compileSymbol
           );
           finalScenes.push(finalScene);
           finalSceneIds.push(finalScene.id);
@@ -3728,7 +4126,8 @@ function applySourceChapters(source, chaptersToCompile, defaultScenes, repoRoot,
         available,
         resolvedAnchors,
         connections,
-        (image) => compileTourImage(repoRoot, image, imageRevisions[image.revision])
+        (image) => compileTourImage(repoRoot, image, imageRevisions[image.revision]),
+        compileSymbol
       );
       scenes.push(scene);
       sceneIds.push(scene.id);
@@ -3833,7 +4232,7 @@ function compileSceneOverview(overview, includeComparison = true) {
     ...includeComparison && overview.comparison ? { comparison: { ...overview.comparison } } : {}
   };
 }
-function buildWalkthroughManifestScene(authoredScene, available, resolvedAnchors, connections, resolveImage) {
+function buildWalkthroughManifestScene(authoredScene, available, resolvedAnchors, connections, resolveImage, compileSymbol) {
   const overview = compileSceneOverview(authoredScene.overview, false);
   return {
     id: authoredScene.id,
@@ -3846,7 +4245,7 @@ function buildWalkthroughManifestScene(authoredScene, available, resolvedAnchors
     ...overview ? { overview } : {},
     steps: authoredScene.steps.map((step) => {
       const focus = requireResolvedAnchor(resolvedAnchors, step.focus);
-      const diff2 = available.get(focus.path);
+      const diff2 = available.get(focus.path) || (focus.revision === "base" ? [...available.values()].find((scene) => scene.previousPath === focus.path) : void 0);
       if (!diff2) throw new Error(`Step ${step.id} has no text diff for ${focus.path}.`);
       return {
         id: step.id,
@@ -3856,6 +4255,7 @@ function buildWalkthroughManifestScene(authoredScene, available, resolvedAnchors
         requirement: step.requirement,
         ...step.image ? { image: resolveImage(step.image) } : {},
         focus,
+        ...step.symbol ? { symbol: compileSymbol(step, focus) } : {},
         connection: step.connection ? connections.get(step.connection) : void 0,
         diff: { ...diff2, id: `${authoredScene.id}-${step.id}` }
       };
@@ -3875,20 +4275,20 @@ function buildDeconstructedManifestScene(repoRoot, source, baseRef, targetRef, a
     stageId: stage.id
   }))];
   const materializablePaths = new Set(compiled.baselineFiles.map((file) => file.path));
-  const includedPaths = availableFilePaths.length > 0 ? availableFilePaths.filter((filePath) => materializablePaths.has(filePath)).sort() : [...materializablePaths].sort();
-  const missingIntroducedPath = compiled.stages.flatMap((stage) => stage.introducedFiles).find((filePath) => !includedPaths.includes(filePath));
+  const includedPaths = availableFilePaths.length > 0 ? availableFilePaths.filter((filePath2) => materializablePaths.has(filePath2)).sort() : [...materializablePaths].sort();
+  const missingIntroducedPath = compiled.stages.flatMap((stage) => stage.introducedFiles).find((filePath2) => !includedPaths.includes(filePath2));
   if (missingIntroducedPath) {
     throw new Error(`Deconstructed tour file is not renderable: ${missingIntroducedPath}`);
   }
   const introducedPaths = new Set(compiled.stages.flatMap((stage) => stage.introducedFiles));
   let totalContentBytes = 0;
-  const files = includedPaths.flatMap((filePath) => {
+  const files = includedPaths.flatMap((filePath2) => {
     const states = [
-      compiled.baselineFiles.find((file) => file.path === filePath),
-      ...compiled.stages.map((stage) => stage.files.find((file) => file.path === filePath))
+      compiled.baselineFiles.find((file) => file.path === filePath2),
+      ...compiled.stages.map((stage) => stage.files.find((file) => file.path === filePath2))
     ];
     if (states.some((state) => !state)) {
-      throw new Error(`Deconstructed scene ${source.id} is missing virtual state for ${filePath}.`);
+      throw new Error(`Deconstructed scene ${source.id} is missing virtual state for ${filePath2}.`);
     }
     const fileContentBytes = states.reduce((total, state) => total + Buffer.byteLength((state == null ? void 0 : state.content) || "", "utf8"), 0);
     const exceedsFileLimit = states.some((state) => {
@@ -3897,20 +4297,20 @@ function buildDeconstructedManifestScene(repoRoot, source, baseRef, targetRef, a
     });
     const exceedsSceneLimit = totalContentBytes + fileContentBytes > DEFAULT_MAX_STACK_CONTENT_BYTES;
     if (exceedsFileLimit || exceedsSceneLimit) {
-      if (introducedPaths.has(filePath)) {
-        throw new Error(exceedsFileLimit ? `Deconstructed tour file is too large to present: ${filePath}` : `Deconstructed tour content exceeds ${DEFAULT_MAX_STACK_CONTENT_BYTES} bytes.`);
+      if (introducedPaths.has(filePath2)) {
+        throw new Error(exceedsFileLimit ? `Deconstructed tour file is too large to present: ${filePath2}` : `Deconstructed tour content exceeds ${DEFAULT_MAX_STACK_CONTENT_BYTES} bytes.`);
       }
       return [];
     }
     totalContentBytes += fileContentBytes;
     return [{
-      path: filePath,
+      path: filePath2,
       panels: states.map((state, index) => {
-        if (!state) throw new Error(`Missing virtual state for ${filePath}.`);
+        if (!state) throw new Error(`Missing virtual state for ${filePath2}.`);
         return {
           id: panels[index].id,
-          label: `${panels[index].label} / ${filePath}${state.exists ? "" : " (absent)"}`,
-          path: state.exists ? filePath : void 0,
+          label: `${panels[index].label} / ${filePath2}${state.exists ? "" : " (absent)"}`,
+          path: state.exists ? filePath2 : void 0,
           content: state.content,
           exists: state.exists
         };
@@ -4004,7 +4404,7 @@ function buildStackedScene(repoRoot, source, availableFilePaths) {
     oid: runGitText(repoRoot, ["rev-parse", "--verify", `${entry.ref}^{commit}`]),
     label: entry.label || entry.ref
   }));
-  const adjacentChanges = stack.slice(0, -1).map((entry, index) => parseNameStatusZ((0, import_child_process3.execFileSync)("git", [
+  const adjacentChanges = stack.slice(0, -1).map((entry, index) => parseNameStatusZ((0, import_child_process4.execFileSync)("git", [
     "diff",
     "--name-status",
     "-z",
@@ -4028,8 +4428,8 @@ function buildStackedScene(repoRoot, source, availableFilePaths) {
     ...source.steps.map((step) => step.file)
   ]);
   let totalContentBytes = 0;
-  const files = filePaths.flatMap((filePath) => {
-    const aliases = /* @__PURE__ */ new Set([filePath]);
+  const files = filePaths.flatMap((filePath2) => {
+    const aliases = /* @__PURE__ */ new Set([filePath2]);
     for (const changes of [...adjacentChanges].reverse()) {
       for (const change of changes) {
         if (aliases.has(change.path) || change.previousPath && aliases.has(change.previousPath)) {
@@ -4042,15 +4442,15 @@ function buildStackedScene(repoRoot, source, availableFilePaths) {
     const panels = [];
     for (const entry of stack) {
       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(", ")}`);
+      if (candidates.length > 1) throw new Error(`Ambiguous revision paths for ${filePath2} at ${entry.ref}: ${candidates.join(", ")}`);
       const resolvedPath = candidates[0];
       if (!resolvedPath) {
-        panels.push({ id: entry.id, label: `${entry.label} / ${filePath} (missing)`, content: "", exists: false });
+        panels.push({ id: entry.id, label: `${entry.label} / ${filePath2} (missing)`, content: "", exists: false });
         continue;
       }
       const content = readGitText(repoRoot, entry.oid, resolvedPath, DEFAULT_MAX_TOUR_FILE_BYTES, DEFAULT_MAX_TOUR_LINE_BYTES);
       if (content.kind !== "text") {
-        if (requiredFilePaths.has(filePath)) {
+        if (requiredFilePaths.has(filePath2)) {
           throw new Error(`Stacked tour file is binary or too large: ${resolvedPath}`);
         }
         return [];
@@ -4068,7 +4468,7 @@ function buildStackedScene(repoRoot, source, availableFilePaths) {
     if (totalContentBytes > DEFAULT_MAX_STACK_CONTENT_BYTES) {
       throw new Error(`Stacked tour content exceeds ${DEFAULT_MAX_STACK_CONTENT_BYTES} bytes.`);
     }
-    return [{ path: filePath, panels }];
+    return [{ path: filePath2, panels }];
   });
   if (files.length === 0) throw new Error(`Stacked scene ${source.id} has no materializable text files.`);
   const stackIds = stack.map((entry) => entry.id);
@@ -4108,7 +4508,7 @@ function buildStackedScene(repoRoot, source, availableFilePaths) {
 }
 function gitBlobExists(repoRoot, oid, relativePath) {
   try {
-    (0, import_child_process3.execFileSync)("git", ["cat-file", "-e", `${oid}:${relativePath}`], {
+    (0, import_child_process4.execFileSync)("git", ["cat-file", "-e", `${oid}:${relativePath}`], {
       cwd: repoRoot,
       stdio: ["ignore", "ignore", "ignore"]
     });
@@ -4118,7 +4518,7 @@ function gitBlobExists(repoRoot, oid, relativePath) {
   }
 }
 function runGitText(repoRoot, args) {
-  return (0, import_child_process3.execFileSync)("git", args, {
+  return (0, import_child_process4.execFileSync)("git", args, {
     cwd: repoRoot,
     encoding: "utf8",
     stdio: ["ignore", "pipe", "pipe"]
@@ -4201,9 +4601,9 @@ function buildChapters(records, sceneIdByPath) {
     sceneIds: records.filter(({ chapter }) => chapter.id === definition.id).map(({ scene }) => sceneIdByPath.get(scene.path)).filter((sceneId) => Boolean(sceneId))
   }));
 }
-function chapterForPath(filePath) {
-  const lower = filePath.toLowerCase();
-  const role = classifyChangeFileRole(filePath);
+function chapterForPath(filePath2) {
+  const lower = filePath2.toLowerCase();
+  const role = classifyChangeFileRole(filePath2);
   if (role === "documentation" || lower.includes("architecture")) {
     return CHAPTERS.context;
   }
@@ -4273,9 +4673,9 @@ function readGitText(repoRoot, oid, relativePath, maxBytes, maxLineBytes) {
   if (!relativePath) {
     return { kind: "text", content: "" };
   }
-  const size = Number((0, import_child_process3.execFileSync)("git", ["cat-file", "-s", `${oid}:${relativePath}`], { cwd: repoRoot, encoding: "utf8" }).trim());
+  const size = Number((0, import_child_process4.execFileSync)("git", ["cat-file", "-s", `${oid}:${relativePath}`], { cwd: repoRoot, encoding: "utf8" }).trim());
   if (size > maxBytes) return { kind: "binary-or-large", content: "" };
-  const content = (0, import_child_process3.execFileSync)("git", ["show", `${oid}:${relativePath}`], {
+  const content = (0, import_child_process4.execFileSync)("git", ["show", `${oid}:${relativePath}`], {
     cwd: repoRoot,
     encoding: "buffer",
     maxBuffer: Math.max(maxBytes + 1, DEFAULT_MAX_TOUR_FILE_BYTES + 1),
@@ -4295,15 +4695,15 @@ function hasLineLongerThan(content, maxLineBytes) {
   }
   return content.length - lineStart > maxLineBytes;
 }
-function readGitLineStats(repoRoot, baseOid, headOid, filePath, previousPath) {
-  const output = (0, import_child_process3.execFileSync)("git", [
+function readGitLineStats(repoRoot, baseOid, headOid, filePath2, previousPath) {
+  const output = (0, import_child_process4.execFileSync)("git", [
     "diff",
     "--numstat",
     "--find-renames",
     baseOid,
     headOid,
     "--",
-    ...[previousPath, filePath].filter((candidate) => Boolean(candidate))
+    ...[previousPath, filePath2].filter((candidate) => Boolean(candidate))
   ], {
     cwd: repoRoot,
     encoding: "utf8",
@@ -4341,10 +4741,10 @@ function pinTourSource(source, repoRoot, resolved, baseOid, headOid) {
   return copy;
 }
 function compileTourImage(repoRoot, source, revision) {
-  const object = `${revision}:${source.file}`;
+  const object2 = `${revision}:${source.file}`;
   let size;
   try {
-    size = Number((0, import_child_process3.execFileSync)("git", ["cat-file", "-s", object], {
+    size = Number((0, import_child_process4.execFileSync)("git", ["cat-file", "-s", object2], {
       cwd: repoRoot,
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"]
@@ -4355,7 +4755,7 @@ function compileTourImage(repoRoot, source, revision) {
   if (!Number.isSafeInteger(size) || size < 33 || size > MAX_TOUR_IMAGE_BYTES) {
     throw new Error(`Image ${source.file} must be a PNG of at most 8 MiB.`);
   }
-  const bytes = (0, import_child_process3.execFileSync)("git", ["cat-file", "blob", object], { cwd: repoRoot, maxBuffer: MAX_TOUR_IMAGE_BYTES });
+  const bytes = (0, import_child_process4.execFileSync)("git", ["cat-file", "blob", object2], { cwd: repoRoot, maxBuffer: MAX_TOUR_IMAGE_BYTES });
   validatePngHeader(bytes, source.file);
   return { path: source.file, revision, alt: source.alt, dataUrl: `data:image/png;base64,${bytes.toString("base64")}` };
 }
@@ -4402,7 +4802,11 @@ function buildTourCoverageReport(startPath, sourceValue) {
   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));
+      const endpoints = step.symbol ? [[step.symbol.before, "base"], [step.symbol.after, "head"]].flatMap(([entry, revision]) => {
+        if (!entry) return [];
+        return [{ path: entry.path, revision, startLine: entry.startLine, endLine: entry.endLine }];
+      }) : [step.focus];
+      const matches = includedUnits.filter((unit) => endpoints.some((endpoint) => evidenceIntersectsUnit(endpoint, unit)));
       if (matches.length === 0) {
         contextualOnlyEvidence.push({ sceneId: scene.id, stepId: step.id, path: step.focus.path });
         continue;