@davmash/bygone 0.10.1 → 0.11.0

package/out/changeTour.js

@@ -45,6 +45,642 @@ __export(changeTour_exports, {
   pinTourSource: () => pinTourSource
 });
 module.exports = __toCommonJS(changeTour_exports);
+var import_fs2 = require("fs");
+var import_path = require("path");
+
+// src/changeCorrespondence.ts
+var import_crypto = require("crypto");
+var import_child_process = require("child_process");
+var import_fs = require("fs");
+
+// node_modules/diff/lib/index.mjs
+function Diff() {
+}
+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 = {};
+    }
+    this.options = options;
+    var self = this;
+    function done(value) {
+      if (callback) {
+        setTimeout(function() {
+          callback(void 0, value);
+        }, 0);
+        return true;
+      } else {
+        return value;
+      }
+    }
+    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);
+    }
+    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
+      }]);
+    }
+    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);
+          }
+        }
+      }
+      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;
+        }
+      }
+    }
+  },
+  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
+        }
+      };
+    }
+  },
+  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++;
+    }
+    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;
+      }
+    }
+  }
+  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();
+  }
+  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);
+}
+var lineDiff = new Diff();
+lineDiff.tokenize = function(value) {
+  if (this.options.stripTrailingCr) {
+    value = value.replace(/\r\n/g, "\n");
+  }
+  var retLines = [], linesAndNewlines = value.split(/(\n|\r\n)/);
+  if (!linesAndNewlines[linesAndNewlines.length - 1]) {
+    linesAndNewlines.pop();
+  }
+  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);
+}
+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);
+}
+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);
+  }
+  var i;
+  for (i = 0; i < stack.length; i += 1) {
+    if (stack[i] === obj) {
+      return replacementStack[i];
+    }
+  }
+  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 (obj && obj.toJSON) {
+    obj = obj.toJSON();
+  }
+  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;
+}
+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);
+}
+
+// src/changeCorrespondence.ts
+var MAX_BYTES = 16 * 1024 * 1024;
+var MAX_SOURCE_BYTES = 8 * 1024 * 1024;
+var digest = (text) => (0, import_crypto.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 list(value, max = 2e4) {
+  if (!Array.isArray(value) || value.length > max) throw new Error("Invalid or over-budget correspondence array.");
+  return value;
+}
+function string(value) {
+  if (typeof value !== "string" || !value || value.length > 4096) throw new Error("Invalid correspondence string.");
+  return value;
+}
+function integer(value) {
+  if (!Number.isSafeInteger(value) || value < 0) throw new Error("Invalid correspondence offset.");
+  return value;
+}
+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 hash(value) {
+  const result = string(value);
+  if (!/^[0-9a-f]{64}$/.test(result)) throw new Error("Invalid correspondence digest.");
+  return result;
+}
+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_process.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}`);
+      }
+      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 } : {}
+      }))
+    });
+  }
+  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) } : {}
+          };
+        })
+      };
+    }) };
+  }
+  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();
+  }
+}
 
 // src/tourImage.ts
 var MAX_TOUR_IMAGE_BYTES = 8 * 1024 * 1024;
@@ -84,17 +720,19 @@ function validatePngHeader(bytes, label) {
 }
 
 // src/changeTour.ts
-var import_child_process4 = require("child_process");
+var import_child_process5 = require("child_process");
 
 // src/gitComparison.ts
-var import_child_process = require("child_process");
+var import_child_process2 = 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], {
+  return (args, cwd) => (0, import_child_process2.execFileSync)("git", [...args], {
     cwd,
     encoding: "utf8",
     maxBuffer,
+    timeout: DEFAULT_GIT_TIMEOUT_MS,
     stdio: ["ignore", "pipe", "pipe"]
   }).trimEnd();
 }
@@ -161,12 +799,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++];
@@ -364,7 +1002,7 @@ function requireOnlyKeys(value, allowed, path) {
 }
 
 // src/changeTourSource.ts
-var CHANGE_TOUR_SOURCE_VERSION = 5;
+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(
@@ -374,7 +1012,7 @@ function parseChangeTourSource(value) {
   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) {
+  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.");
   }
   requireOnlyKeys2(value, [
@@ -382,6 +1020,7 @@ function parseChangeTourSource(value) {
     "title",
     "windowTitle",
     "sourceUrl",
+    "correspondence",
     "range",
     "anchors",
     "connections",
@@ -433,6 +1072,11 @@ function parseChangeTourSource(value) {
       throw new Error(`anchors.${id}.occurrence must be a positive integer.`);
     }
   }
+  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.");
+  }
   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.");
@@ -536,7 +1180,7 @@ function validateSourceChapters(chaptersValue, chaptersPath, version, anchors, c
           validateRealStack(scene.stack, `${path}.stack`, 2);
         }
         if (requireRealEvidence || scene.steps !== void 0) {
-          validateWalkthroughSteps(scene, path, anchors, connectionIds);
+          validateWalkthroughSteps(scene, path, anchors, connectionIds, version);
         }
         continue;
       }
@@ -555,7 +1199,7 @@ function validateSourceChapters(chaptersValue, chaptersPath, version, anchors, c
       }
       requireOnlyKeys2(scene, ["id", "kind", "title", "summary", "bullets", "tags", "takeaway", "overview", "steps"], path);
       validateSceneOverview(scene.overview, `${path}.overview`, { allowComparison: false });
-      validateWalkthroughSteps(scene, path, anchors, connectionIds);
+      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"))) {
@@ -612,7 +1256,7 @@ function validateDeconstructedScene(scene, path) {
     ));
   }
 }
-function validateWalkthroughSteps(scene, path, anchors, connectionIds) {
+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.`);
   }
@@ -624,10 +1268,17 @@ function validateWalkthroughSteps(scene, path, anchors, connectionIds) {
     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);
+    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 (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}`);
@@ -798,7 +1449,7 @@ function requireOnlyKeys2(value, allowed, path) {
 }
 
 // src/changeTourManifest.ts
-var CHANGE_TOUR_MANIFEST_VERSION = 5;
+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(
@@ -808,7 +1459,7 @@ function parseChangeTourManifest(value, options = {}) {
   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) {
+  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.");
@@ -866,7 +1517,7 @@ function parseChangeTourManifest(value, options = {}) {
     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.");
+    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) => {
@@ -880,10 +1531,24 @@ function parseChangeTourManifest(value, options = {}) {
     validateAuthoringCoverage(value.authoringCoverage, value.version);
   }
   if (value.tours !== void 0) {
-    if (value.version !== 4 && value.version !== 5) throw new Error("Independent tours require manifest version 4.");
+    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.");
+    }
+  }
   return { ...value, files };
 }
 function validateAuthoringCoverage(value, version) {
@@ -940,7 +1605,7 @@ function validateModeTours(value, version) {
       }
     }
     if (tour.details !== void 0) {
-      if (version !== 5) throw new Error(`tours.${mode}.details requires manifest version 5.`);
+      if (version < 5) throw new Error(`tours.${mode}.details requires manifest version 5.`);
       validateChangeTourDetails(tour.details, `tours.${mode}.details`);
     }
     if (mode === "deconstructed" && !hasDeconstructed) {
@@ -1086,6 +1751,11 @@ function validateScene(value, index, version) {
       }
       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.`);
@@ -1120,958 +1790,598 @@ function validateScene(value, index, version) {
   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.`);
-      }
-      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.`);
-      }
-      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.`);
-      }
-    }
-  }
-}
-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 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 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;
-  }
-  if (value.kind !== "omitted") {
-    throw new Error(`files[${index}].kind must be text-diff or omitted.`);
-  }
-  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);
-      }
-    }
-  }
-  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.`);
+  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 requireStringArray3(value, path) {
-  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
-    throw new Error(`${path} must be an array of strings.`);
+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.`);
   }
-}
-function requireNonNegativeInteger(value, path) {
-  if (!Number.isInteger(value) || Number(value) < 0) {
-    throw new Error(`${path} must be a non-negative 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}`);
   }
+  validateMultiPanelFiles(value.files, value.stack.length, index);
+  validateMultiPanelSteps(value.steps, value.stack.length, index, false);
 }
-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 validateDeconstructedScene2(value, index) {
+  if (value.stageLabel !== "Explanation stages") {
+    throw new Error(`scenes[${index}].stageLabel must be Explanation stages.`);
   }
-}
-function requirePositiveInteger(value, path) {
-  if (!Number.isInteger(value) || Number(value) < 1) throw new Error(`${path} must be a positive integer.`);
-}
-
-// src/changeInventory.ts
-var import_crypto = require("crypto");
-var import_child_process2 = require("child_process");
-var CHANGE_INVENTORY_VERSION = 2;
-function buildChangeInventory(startPath, options = {}) {
-  const range = resolveBranchReviewRange(startPath, options.headRef, options.baseRef);
-  const files = range.changedPaths.map((changedPath) => buildInventoryFile(
-    range.repoRoot,
-    range.mergeBaseOid,
-    range.headOid,
-    changedPath
-  ));
-  return {
-    version: CHANGE_INVENTORY_VERSION,
-    range: {
-      repoRoot: range.repoRoot,
-      baseRef: range.baseRef,
-      headRef: range.headRef,
-      baseOid: range.mergeBaseOid,
-      headOid: range.headOid
-    },
-    summary: {
-      changedFiles: files.length,
-      textualFiles: files.filter((file) => file.material === "text").length,
-      binaryFiles: files.filter((file) => file.material === "binary").length,
-      changeUnits: files.reduce((total, file) => total + file.units.length, 0),
-      additions: files.reduce((total, file) => total + (file.additions ?? 0), 0),
-      deletions: files.reduce((total, file) => total + (file.deletions ?? 0), 0)
-    },
-    files
-  };
-}
-function buildInventoryFile(repoRoot, baseOid, headOid, changedPath) {
-  const paths = [...new Set([changedPath.previousPath, changedPath.path].filter(Boolean))];
-  const numstat = runGit(repoRoot, ["diff", "--numstat", "--find-renames", baseOid, headOid, "--", ...paths]);
-  const [added = "0", deleted = "0"] = numstat.trim().split(/\s+/, 3);
-  const basePath = changedPath.kind === "added" ? void 0 : changedPath.previousPath || changedPath.path;
-  const headPath = changedPath.kind === "deleted" ? void 0 : changedPath.path;
-  const baseBlob = readGitBlob(repoRoot, baseOid, basePath);
-  const headBlob = readGitBlob(repoRoot, headOid, headPath);
-  if (!baseBlob || !headBlob) {
-    return {
-      path: changedPath.path,
-      previousPath: changedPath.previousPath,
-      changeKind: changedPath.kind,
-      material: "unsupported",
-      additions: Number.parseInt(added, 10) || 0,
-      deletions: Number.parseInt(deleted, 10) || 0,
-      units: []
-    };
+  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 binary = added === "-" || deleted === "-" || !isLosslessTextBlob(baseBlob) || !isLosslessTextBlob(headBlob);
-  if (binary) {
-    return {
-      path: changedPath.path,
-      previousPath: changedPath.previousPath,
-      changeKind: changedPath.kind,
-      material: "binary",
-      additions: null,
-      deletions: null,
-      units: []
-    };
+  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.`);
   }
-  let patch;
-  try {
-    patch = runGit(repoRoot, [
-      "diff",
-      "--no-ext-diff",
-      "--no-textconv",
-      "--no-color",
-      "--find-renames=20%",
-      "--diff-algorithm=default",
-      "--unified=0",
-      "--inter-hunk-context=0",
-      baseOid,
-      headOid,
-      "--",
-      ...paths
-    ]);
-  } catch {
-    return {
-      path: changedPath.path,
-      previousPath: changedPath.previousPath,
-      changeKind: changedPath.kind,
-      material: "unsupported",
-      additions: Number.parseInt(added, 10) || 0,
-      deletions: Number.parseInt(deleted, 10) || 0,
-      units: []
-    };
+  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`);
   }
-  const units = parsePatchUnits(patch, changedPath);
-  return {
-    path: changedPath.path,
-    previousPath: changedPath.previousPath,
-    changeKind: changedPath.kind,
-    material: "text",
-    additions: Number.parseInt(added, 10) || 0,
-    deletions: Number.parseInt(deleted, 10) || 0,
-    units,
-    baseContent: baseBlob.toString("utf8"),
-    headContent: headBlob.toString("utf8")
-  };
-}
-function parsePatchUnits(patch, changedPath) {
-  const lines = patch.split("\n");
-  const units = [];
-  const seenIds = /* @__PURE__ */ new Map();
-  for (let index = 0; index < lines.length; index += 1) {
-    const match = lines[index].match(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/);
-    if (!match) continue;
-    const body = [];
-    for (index += 1; index < lines.length && !lines[index].startsWith("@@ ") && !lines[index].startsWith("diff --git "); index += 1) {
-      body.push(lines[index]);
-    }
-    index -= 1;
-    const { oldText, newText } = parseHunkText(body);
-    const contextHash = (0, import_crypto.createHash)("sha256").update(JSON.stringify([oldText, newText])).digest("hex").slice(0, 16);
-    const baseId = `hunk-${(0, import_crypto.createHash)("sha256").update(JSON.stringify([
-      changedPath.previousPath || changedPath.path,
-      changedPath.path,
-      oldText,
-      newText
-    ])).digest("hex").slice(0, 12)}`;
-    const occurrence = (seenIds.get(baseId) || 0) + 1;
-    seenIds.set(baseId, occurrence);
-    units.push({
-      id: occurrence === 1 ? baseId : `${baseId}-${occurrence}`,
-      path: changedPath.path,
-      previousPath: changedPath.previousPath,
-      changeKind: changedPath.kind,
-      baseStart: Number.parseInt(match[1], 10),
-      baseCount: match[2] === void 0 ? 1 : Number.parseInt(match[2], 10),
-      headStart: Number.parseInt(match[3], 10),
-      headCount: match[4] === void 0 ? 1 : Number.parseInt(match[4], 10),
-      additions: body.filter((line) => line.startsWith("+") && !line.startsWith("+++")).length,
-      deletions: body.filter((line) => line.startsWith("-") && !line.startsWith("---")).length,
-      contextHash,
-      oldText,
-      newText
+  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.`);
+      }
+      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.`);
+      }
+      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.`);
+      }
     });
-  }
-  return units;
-}
-function materializeChangeUnits(baseContent, units, selectedUnitIds) {
-  const selected = new Set(selectedUnitIds);
-  const knownIds = new Set(units.map((unit) => unit.id));
-  for (const id of selected) {
-    if (!knownIds.has(id)) {
-      throw new Error(`Unknown change unit: ${id}`);
+    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.`);
+      }
     }
   }
-  const offsets = buildLineBoundaryOffsets(baseContent);
-  const ordered = [...units].sort((left, right) => {
-    const leftRange = resolveBaseRange(left, offsets, baseContent.length);
-    const rightRange = resolveBaseRange(right, offsets, baseContent.length);
-    return leftRange.start - rightRange.start || leftRange.end - rightRange.end;
-  });
-  const chunks = [];
-  let cursor = 0;
-  let previousEnd = 0;
-  for (const unit of ordered) {
-    const range = resolveBaseRange(unit, offsets, baseContent.length);
-    if (range.start < previousEnd) {
-      throw new Error(`Overlapping change units cannot be materialized independently: ${unit.id}`);
-    }
-    if (baseContent.slice(range.start, range.end) !== unit.oldText) {
-      throw new Error(`Change unit ${unit.id} no longer matches its base content.`);
+}
+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.`);
     }
-    if (selected.has(unit.id)) {
-      chunks.push(baseContent.slice(cursor, range.start), unit.newText);
-      cursor = range.end;
+    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.`);
     }
-    previousEnd = Math.max(previousEnd, range.end);
   }
-  chunks.push(baseContent.slice(cursor));
-  return chunks.join("");
 }
-function parseHunkText(body) {
-  let oldText = "";
-  let newText = "";
-  let previousPrefix = "";
-  for (const line of body) {
-    if (line === "\") {
-      if (previousPrefix === "-" || previousPrefix === " ") oldText = removeFinalNewline(oldText);
-      if (previousPrefix === "+" || previousPrefix === " ") newText = removeFinalNewline(newText);
-      continue;
+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.`);
     }
-    const prefix = line[0];
-    const content = line.slice(1);
-    if (prefix === "-" || prefix === " ") oldText += `${content}
-`;
-    if (prefix === "+" || prefix === " ") newText += `${content}
-`;
-    previousPrefix = prefix;
+    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 { oldText, newText };
-}
-function removeFinalNewline(value) {
-  return value.endsWith("\n") ? value.slice(0, -1) : value;
 }
-function buildLineBoundaryOffsets(content) {
-  const offsets = [0];
-  for (let index = 0; index < content.length; index += 1) {
-    if (content[index] === "\n") offsets.push(index + 1);
+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;
   }
-  if (offsets[offsets.length - 1] !== content.length) offsets.push(content.length);
-  return offsets;
-}
-function resolveBaseRange(unit, offsets, contentLength) {
-  const startIndex = unit.baseCount === 0 ? unit.baseStart : unit.baseStart - 1;
-  const endIndex = unit.baseCount === 0 ? startIndex : startIndex + unit.baseCount;
-  const start = offsets[startIndex];
-  const end = offsets[endIndex];
-  if (start === void 0 || end === void 0 || start > contentLength || end > contentLength) {
-    throw new Error(`Change unit ${unit.id} has an invalid base range.`);
+  if (value.kind !== "omitted") {
+    throw new Error(`files[${index}].kind must be text-diff or omitted.`);
   }
-  return { start, end };
-}
-function isLosslessTextBlob(content) {
-  if (content.includes(0)) return false;
-  const decoded = content.toString("utf8");
-  return Buffer.from(decoded, "utf8").equals(content);
-}
-function readGitBlob(repoRoot, oid, relativePath) {
-  if (!relativePath) return Buffer.alloc(0);
-  try {
-    return (0, import_child_process2.execFileSync)("git", ["show", `${oid}:${relativePath}`], {
-      cwd: repoRoot,
-      encoding: "buffer",
-      maxBuffer: 16 * 1024 * 1024,
-      stdio: ["ignore", "pipe", "pipe"]
-    });
-  } catch {
-    return null;
+  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 runGit(repoRoot, args) {
-  return (0, import_child_process2.execFileSync)("git", args, {
-    cwd: repoRoot,
-    encoding: "utf8",
-    maxBuffer: 16 * 1024 * 1024,
-    stdio: ["ignore", "pipe", "pipe"]
-  });
-}
-
-// 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);
-  }
-  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}.`);
-      }
+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;
     }
-    for (const unit of file.units) {
-      if (!ownership.has(unitKey(file, unit.id))) {
-        throw new Error(`Unassigned change unit in ${file.path}: ${unit.id}`);
+    if (scene.kind === "walkthrough") {
+      for (const step of scene.steps) {
+        if (!files.has(step.diff.path)) files.set(step.diff.path, step.diff);
       }
     }
   }
-  for (const file of inventory.files) {
-    cumulativeByFile.set(file, new Set(excludedByFile.get(file) || []));
+  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.`);
   }
-  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 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.`);
   }
-  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}.`);
-    }
+}
+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 {
-    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 requireNonNegativeInteger(value, path) {
+  if (!Number.isInteger(value) || Number(value) < 0) {
+    throw new Error(`${path} must be a non-negative integer.`);
+  }
 }
-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 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 unitKey(file, id) {
-  return `${file.previousPath || ""}\0${file.path}\0${id}`;
+function requirePositiveInteger(value, path) {
+  if (!Number.isInteger(value) || Number(value) < 1) throw new Error(`${path} must be a positive integer.`);
 }
-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);
+
+// src/changeInventory.ts
+var import_crypto2 = require("crypto");
+var import_child_process3 = require("child_process");
+var CHANGE_INVENTORY_VERSION = 2;
+function buildChangeInventory(startPath, options = {}) {
+  const range = resolveBranchReviewRange(startPath, options.headRef, options.baseRef);
+  const files = range.changedPaths.map((changedPath) => buildInventoryFile(
+    range.repoRoot,
+    range.mergeBaseOid,
+    range.headOid,
+    changedPath
+  ));
   return {
-    path: file.path,
-    previousPath: file.previousPath,
-    changeKind: file.changeKind,
-    exists,
-    content: exists ? content : "",
-    appliedHunks: [...selected]
+    version: CHANGE_INVENTORY_VERSION,
+    range: {
+      repoRoot: range.repoRoot,
+      baseRef: range.baseRef,
+      headRef: range.headRef,
+      baseOid: range.mergeBaseOid,
+      headOid: range.headOid
+    },
+    summary: {
+      changedFiles: files.length,
+      textualFiles: files.filter((file) => file.material === "text").length,
+      binaryFiles: files.filter((file) => file.material === "binary").length,
+      changeUnits: files.reduce((total, file) => total + file.units.length, 0),
+      additions: files.reduce((total, file) => total + (file.additions ?? 0), 0),
+      deletions: files.reduce((total, file) => total + (file.deletions ?? 0), 0)
+    },
+    files
   };
 }
-
-// node_modules/diff/lib/index.mjs
-function Diff() {
+function buildInventoryFile(repoRoot, baseOid, headOid, changedPath) {
+  const paths = [...new Set([changedPath.previousPath, changedPath.path].filter(Boolean))];
+  const numstat = runGit(repoRoot, ["diff", "--numstat", "--find-renames", baseOid, headOid, "--", ...paths]);
+  const [added = "0", deleted = "0"] = numstat.trim().split(/\s+/, 3);
+  const basePath = changedPath.kind === "added" ? void 0 : changedPath.previousPath || changedPath.path;
+  const headPath = changedPath.kind === "deleted" ? void 0 : changedPath.path;
+  const baseBlob = readGitBlob(repoRoot, baseOid, basePath);
+  const headBlob = readGitBlob(repoRoot, headOid, headPath);
+  if (!baseBlob || !headBlob) {
+    return {
+      path: changedPath.path,
+      previousPath: changedPath.previousPath,
+      changeKind: changedPath.kind,
+      material: "unsupported",
+      additions: Number.parseInt(added, 10) || 0,
+      deletions: Number.parseInt(deleted, 10) || 0,
+      units: []
+    };
+  }
+  const binary = added === "-" || deleted === "-" || !isLosslessTextBlob(baseBlob) || !isLosslessTextBlob(headBlob);
+  if (binary) {
+    return {
+      path: changedPath.path,
+      previousPath: changedPath.previousPath,
+      changeKind: changedPath.kind,
+      material: "binary",
+      additions: null,
+      deletions: null,
+      units: []
+    };
+  }
+  let patch;
+  try {
+    patch = runGit(repoRoot, [
+      "diff",
+      "--no-ext-diff",
+      "--no-textconv",
+      "--no-color",
+      "--find-renames=20%",
+      "--diff-algorithm=default",
+      "--unified=0",
+      "--inter-hunk-context=0",
+      baseOid,
+      headOid,
+      "--",
+      ...paths
+    ]);
+  } catch {
+    return {
+      path: changedPath.path,
+      previousPath: changedPath.previousPath,
+      changeKind: changedPath.kind,
+      material: "unsupported",
+      additions: Number.parseInt(added, 10) || 0,
+      deletions: Number.parseInt(deleted, 10) || 0,
+      units: []
+    };
+  }
+  const units = parsePatchUnits(patch, changedPath);
+  return {
+    path: changedPath.path,
+    previousPath: changedPath.previousPath,
+    changeKind: changedPath.kind,
+    material: "text",
+    additions: Number.parseInt(added, 10) || 0,
+    deletions: Number.parseInt(deleted, 10) || 0,
+    units,
+    baseContent: baseBlob.toString("utf8"),
+    headContent: headBlob.toString("utf8")
+  };
 }
-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 = {};
-    }
-    this.options = options;
-    var self = this;
-    function done(value) {
-      if (callback) {
-        setTimeout(function() {
-          callback(void 0, value);
-        }, 0);
-        return true;
-      } else {
-        return value;
-      }
-    }
-    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);
-    }
-    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
-      }]);
-    }
-    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);
-          }
-        }
-      }
-      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;
-        }
-      }
-    }
-  },
-  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 parsePatchUnits(patch, changedPath) {
+  const lines = patch.split("\n");
+  const units = [];
+  const seenIds = /* @__PURE__ */ new Map();
+  for (let index = 0; index < lines.length; index += 1) {
+    const match = lines[index].match(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/);
+    if (!match) continue;
+    const body = [];
+    for (index += 1; index < lines.length && !lines[index].startsWith("@@ ") && !lines[index].startsWith("diff --git "); index += 1) {
+      body.push(lines[index]);
     }
-  },
-  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++;
+    index -= 1;
+    const { oldText, newText } = parseHunkText(body);
+    const contextHash = (0, import_crypto2.createHash)("sha256").update(JSON.stringify([oldText, newText])).digest("hex").slice(0, 16);
+    const baseId = `hunk-${(0, import_crypto2.createHash)("sha256").update(JSON.stringify([
+      changedPath.previousPath || changedPath.path,
+      changedPath.path,
+      oldText,
+      newText
+    ])).digest("hex").slice(0, 12)}`;
+    const occurrence = (seenIds.get(baseId) || 0) + 1;
+    seenIds.set(baseId, occurrence);
+    units.push({
+      id: occurrence === 1 ? baseId : `${baseId}-${occurrence}`,
+      path: changedPath.path,
+      previousPath: changedPath.previousPath,
+      changeKind: changedPath.kind,
+      baseStart: Number.parseInt(match[1], 10),
+      baseCount: match[2] === void 0 ? 1 : Number.parseInt(match[2], 10),
+      headStart: Number.parseInt(match[3], 10),
+      headCount: match[4] === void 0 ? 1 : Number.parseInt(match[4], 10),
+      additions: body.filter((line) => line.startsWith("+") && !line.startsWith("+++")).length,
+      deletions: body.filter((line) => line.startsWith("-") && !line.startsWith("---")).length,
+      contextHash,
+      oldText,
+      newText
+    });
+  }
+  return units;
+}
+function materializeChangeUnits(baseContent, units, selectedUnitIds) {
+  const selected = new Set(selectedUnitIds);
+  const knownIds = new Set(units.map((unit) => unit.id));
+  for (const id of selected) {
+    if (!knownIds.has(id)) {
+      throw new Error(`Unknown change unit: ${id}`);
     }
-    if (commonCount) {
-      basePath.lastComponent = {
-        count: commonCount,
-        previousComponent: basePath.lastComponent
-      };
+  }
+  const offsets = buildLineBoundaryOffsets(baseContent);
+  const ordered = [...units].sort((left, right) => {
+    const leftRange = resolveBaseRange(left, offsets, baseContent.length);
+    const rightRange = resolveBaseRange(right, offsets, baseContent.length);
+    return leftRange.start - rightRange.start || leftRange.end - rightRange.end;
+  });
+  const chunks = [];
+  let cursor = 0;
+  let previousEnd = 0;
+  for (const unit of ordered) {
+    const range = resolveBaseRange(unit, offsets, baseContent.length);
+    if (range.start < previousEnd) {
+      throw new Error(`Overlapping change units cannot be materialized independently: ${unit.id}`);
     }
-    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 (baseContent.slice(range.start, range.end) !== unit.oldText) {
+      throw new Error(`Change unit ${unit.id} no longer matches its base content.`);
     }
-  },
-  removeEmpty: function removeEmpty(array) {
-    var ret = [];
-    for (var i = 0; i < array.length; i++) {
-      if (array[i]) {
-        ret.push(array[i]);
-      }
+    if (selected.has(unit.id)) {
+      chunks.push(baseContent.slice(cursor, range.start), unit.newText);
+      cursor = range.end;
     }
-    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;
+    previousEnd = Math.max(previousEnd, range.end);
   }
-  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;
-      }
+  chunks.push(baseContent.slice(cursor));
+  return chunks.join("");
+}
+function parseHunkText(body) {
+  let oldText = "";
+  let newText = "";
+  let previousPrefix = "";
+  for (const line of body) {
+    if (line === "\") {
+      if (previousPrefix === "-" || previousPrefix === " ") oldText = removeFinalNewline(oldText);
+      if (previousPrefix === "+" || previousPrefix === " ") newText = removeFinalNewline(newText);
+      continue;
     }
+    const prefix = line[0];
+    const content = line.slice(1);
+    if (prefix === "-" || prefix === " ") oldText += `${content}
+`;
+    if (prefix === "+" || prefix === " ") newText += `${content}
+`;
+    previousPrefix = prefix;
   }
-  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;
+  return { oldText, newText };
 }
-var characterDiff = new Diff();
-function diffChars(oldStr, newStr, options) {
-  return characterDiff.diff(oldStr, newStr, options);
+function removeFinalNewline(value) {
+  return value.endsWith("\n") ? value.slice(0, -1) : value;
 }
-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();
-  }
-  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 buildLineBoundaryOffsets(content) {
+  const offsets = [0];
+  for (let index = 0; index < content.length; index += 1) {
+    if (content[index] === "\n") offsets.push(index + 1);
   }
-  return tokens;
-};
-function diffWordsWithSpace(oldStr, newStr, options) {
-  return wordDiff.diff(oldStr, newStr, options);
+  if (offsets[offsets.length - 1] !== content.length) offsets.push(content.length);
+  return offsets;
 }
-var lineDiff = new Diff();
-lineDiff.tokenize = function(value) {
-  if (this.options.stripTrailingCr) {
-    value = value.replace(/\r\n/g, "\n");
-  }
-  var retLines = [], linesAndNewlines = value.split(/(\n|\r\n)/);
-  if (!linesAndNewlines[linesAndNewlines.length - 1]) {
-    linesAndNewlines.pop();
-  }
-  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);
-    }
+function resolveBaseRange(unit, offsets, contentLength) {
+  const startIndex = unit.baseCount === 0 ? unit.baseStart : unit.baseStart - 1;
+  const endIndex = unit.baseCount === 0 ? startIndex : startIndex + unit.baseCount;
+  const start = offsets[startIndex];
+  const end = offsets[endIndex];
+  if (start === void 0 || end === void 0 || start > contentLength || end > contentLength) {
+    throw new Error(`Change unit ${unit.id} has an invalid base range.`);
   }
-  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 { start, end };
+}
+function isLosslessTextBlob(content) {
+  if (content.includes(0)) return false;
+  const decoded = content.toString("utf8");
+  return Buffer.from(decoded, "utf8").equals(content);
+}
+function readGitBlob(repoRoot, oid, relativePath) {
+  if (!relativePath) return Buffer.alloc(0);
+  try {
+    return (0, import_child_process3.execFileSync)("git", ["show", `${oid}:${relativePath}`], {
+      cwd: repoRoot,
+      encoding: "buffer",
+      maxBuffer: 16 * 1024 * 1024,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+  } catch {
+    return null;
   }
-  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);
-  }
-  var i;
-  for (i = 0; i < stack.length; i += 1) {
-    if (stack[i] === obj) {
-      return replacementStack[i];
+function runGit(repoRoot, args) {
+  return (0, import_child_process3.execFileSync)("git", args, {
+    cwd: repoRoot,
+    encoding: "utf8",
+    maxBuffer: 16 * 1024 * 1024,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+}
+
+// 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
@@ -2104,17 +2414,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 = [];
@@ -2229,6 +2532,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 = [];
@@ -3209,8 +3560,8 @@ function buildInlineSegments(leftContent, rightContent) {
     }
   }
   return {
-    leftSegments,
-    rightSegments,
+    leftSegments: normalizeIndentationHighlights(leftSegments),
+    rightSegments: normalizeIndentationHighlights(rightSegments),
     hasInlineChanges
   };
 }
@@ -3244,7 +3595,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 = [[]];
@@ -3380,8 +3764,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";
@@ -3487,7 +3871,7 @@ function isTestForFocus(testPath, focusPaths) {
 }
 
 // src/changeTourContext.ts
-var import_child_process3 = require("child_process");
+var import_child_process4 = require("child_process");
 var CHANGE_TOUR_CONTEXT_VERSION = 1;
 var DEFAULT_MAX_PATCH_BYTES = 128 * 1024;
 var DEFAULT_MAX_TOTAL_PATCH_BYTES = 2 * 1024 * 1024;
@@ -3517,6 +3901,7 @@ function buildChangeTourContext(startPath, options = {}) {
   for (const file of files) filesByRole[file.role] += 1;
   return {
     version: CHANGE_TOUR_CONTEXT_VERSION,
+    ...options.correspondencePath ? { correspondence: loadChangeCorrespondence(range.repoRoot, options.correspondencePath, { baseOid: range.mergeBaseOid, headOid: range.headOid }) } : {},
     generatedAt: options.generatedAt || (/* @__PURE__ */ new Date()).toISOString(),
     range: {
       baseRef: range.baseRef,
@@ -3587,7 +3972,7 @@ function readLineStats(repoRoot, baseOid, headOid, paths) {
 function readPatch(repoRoot, baseOid, headOid, paths, binary, maxPatchBytes) {
   if (binary) return { included: false, content: "", bytes: 0, reason: "binary" };
   try {
-    const buffer = (0, import_child_process3.execFileSync)("git", [
+    const buffer = (0, import_child_process4.execFileSync)("git", [
       "diff",
       "--no-ext-diff",
       "--no-color",
@@ -3648,7 +4033,7 @@ function findSymbolHints(content, ranges) {
 }
 function readGitText(repoRoot, oid, relativePath, maxBytes) {
   try {
-    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: maxBytes + 1,
@@ -3661,7 +4046,7 @@ function readGitText(repoRoot, oid, relativePath, maxBytes) {
   }
 }
 function runGit2(repoRoot, args) {
-  return (0, import_child_process3.execFileSync)("git", args, {
+  return (0, import_child_process4.execFileSync)("git", args, {
     cwd: repoRoot,
     encoding: "utf8",
     maxBuffer: MAX_CAPTURE_BYTES,
@@ -3878,10 +4263,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}`);
     }
@@ -3918,7 +4314,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);
@@ -3947,7 +4344,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);
@@ -4052,7 +4450,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,
@@ -4065,7 +4463,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,
@@ -4075,6 +4473,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}` }
       };
@@ -4094,20 +4493,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) => {
@@ -4116,20 +4515,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
         };
@@ -4223,7 +4622,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_process4.execFileSync)("git", [
+  const adjacentChanges = stack.slice(0, -1).map((entry, index) => parseNameStatusZ((0, import_child_process5.execFileSync)("git", [
     "diff",
     "--name-status",
     "-z",
@@ -4247,8 +4646,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)) {
@@ -4261,15 +4660,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 = readGitText2(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 [];
@@ -4287,7 +4686,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);
@@ -4327,7 +4726,7 @@ function buildStackedScene(repoRoot, source, availableFilePaths) {
 }
 function gitBlobExists(repoRoot, oid, relativePath) {
   try {
-    (0, import_child_process4.execFileSync)("git", ["cat-file", "-e", `${oid}:${relativePath}`], {
+    (0, import_child_process5.execFileSync)("git", ["cat-file", "-e", `${oid}:${relativePath}`], {
       cwd: repoRoot,
       stdio: ["ignore", "ignore", "ignore"]
     });
@@ -4337,7 +4736,7 @@ function gitBlobExists(repoRoot, oid, relativePath) {
   }
 }
 function runGitText(repoRoot, args) {
-  return (0, import_child_process4.execFileSync)("git", args, {
+  return (0, import_child_process5.execFileSync)("git", args, {
     cwd: repoRoot,
     encoding: "utf8",
     stdio: ["ignore", "pipe", "pipe"]
@@ -4420,9 +4819,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;
   }
@@ -4492,9 +4891,9 @@ function readGitText2(repoRoot, oid, relativePath, maxBytes, maxLineBytes) {
   if (!relativePath) {
     return { kind: "text", content: "" };
   }
-  const size = Number((0, import_child_process4.execFileSync)("git", ["cat-file", "-s", `${oid}:${relativePath}`], { cwd: repoRoot, encoding: "utf8" }).trim());
+  const size = Number((0, import_child_process5.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_process4.execFileSync)("git", ["show", `${oid}:${relativePath}`], {
+  const content = (0, import_child_process5.execFileSync)("git", ["show", `${oid}:${relativePath}`], {
     cwd: repoRoot,
     encoding: "buffer",
     maxBuffer: Math.max(maxBytes + 1, DEFAULT_MAX_TOUR_FILE_BYTES + 1),
@@ -4514,15 +4913,15 @@ function hasLineLongerThan(content, maxLineBytes) {
   }
   return content.length - lineStart > maxLineBytes;
 }
-function readGitLineStats(repoRoot, baseOid, headOid, filePath, previousPath) {
-  const output = (0, import_child_process4.execFileSync)("git", [
+function readGitLineStats(repoRoot, baseOid, headOid, filePath2, previousPath) {
+  const output = (0, import_child_process5.execFileSync)("git", [
     "diff",
     "--numstat",
     "--find-renames",
     baseOid,
     headOid,
     "--",
-    ...[previousPath, filePath].filter((candidate) => Boolean(candidate))
+    ...[previousPath, filePath2].filter((candidate) => Boolean(candidate))
   ], {
     cwd: repoRoot,
     encoding: "utf8",
@@ -4560,10 +4959,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_process4.execFileSync)("git", ["cat-file", "-s", object], {
+    size = Number((0, import_child_process5.execFileSync)("git", ["cat-file", "-s", object2], {
       cwd: repoRoot,
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"]
@@ -4574,7 +4973,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_process4.execFileSync)("git", ["cat-file", "blob", object], { cwd: repoRoot, maxBuffer: MAX_TOUR_IMAGE_BYTES });
+  const bytes = (0, import_child_process5.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")}` };
 }