@davmash/bygone 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.11.0
+
+- Added experimental JS/TS and Python symbol evidence with declaration diffs, symbol trees, analysis diagnostics, and shared Files/Symbols navigation
+- Added pinned symbol tour stops and full-file context in live presentations and portable exports
+- Added the local Strand declaration matcher for JS/TS, Python, Java, Go, Rust, C#, Ruby, PHP, C, Lua, and experimental Mojo, with bounded analysis and explicit ambiguity reporting
+- Kept Java and RefactoringMiner optional: exact-only generation records partial coverage, and Strand provides local inference without a JVM
+- Added opt-in VS Code active-editor following with a live HEAD-to-buffer diff, Pin/Resume/Refresh controls, and safe handoffs to history and manual comparison
+- Fixed following for macOS directory aliases and files at the 5,000-line limit, with regression coverage on current and minimum-supported VS Code
+- Hardened correspondence artifact validation, parser budgets, and symbol owner matching
+- Updated Electron, DOMPurify, fast-uri, and packaging dependencies to resolve security advisories
+
+macOS desktop downloads are unsigned and not notarized. If Gatekeeper reports
+the app as damaged, run `xattr -cr /Applications/Bygone.app`, then reopen it.
+
+## 0.10.2
+
+- Prioritized matching named lines before brackets to preserve block correspondences across nesting and indentation changes
+- Aligned changed indentation highlights to the start of each line while preserving highlights on edited text
+
+## 0.10.1
+
+- Fixed desktop tours showing unstyled HTML after temporary asset cleanup during long-running app sessions
+- Made presentation asset read failures return HTTP 500 and added HTTP and Electron ASAR regression coverage
+
 ## 0.10.0
 
 - Restored detailed highlighting for long prose and expanded instructions; unavailable word detail now has a uniform blue fill and an explanatory `≠` marker

package/README.md

@@ -352,6 +352,10 @@ The wrapper scripts are:
 
 ## Commands
 
+- `Bygone: Follow Active Editor`
+- `Bygone: Pin Following File`
+- `Bygone: Resume Following`
+- `Bygone: Refresh Following Comparison`
 - `Bygone: Compare Active File With…`
 - `Bygone: Compare Selected Files`
 - `Bygone: Compare with Selected`
@@ -370,6 +374,34 @@ panes edit through VS Code documents, so changes participate in dirty state,
 undo, save, and external-document updates. Historical and non-local inputs are
 read-only. Desktop hand-offs are unavailable in remote extension hosts.
 
+## Follow the active VS Code editor
+
+Run **Bygone: Follow Active Editor** to open one read-only comparison beside your
+source editor without moving keyboard focus. Switching source files updates that
+same pane. The left side is the file at HEAD; the right side is your editor buffer,
+including unsaved edits. Edit, undo, and save in the source editor as usual.
+
+**Pin** keeps the current file and baseline commit while buffer edits continue to
+update. **Resume Following** selects the active or last source editor. **Refresh**
+reads HEAD again when following; a pinned comparison retains its baseline. HEAD
+also refreshes on file activation and when the VS Code window regains focus.
+After external Git changes while the window stays focused, use Refresh.
+
+The controls show the repository, relative file path, commit, and saved/unsaved
+state. Clean files say **No changes from HEAD**. Untracked files, files absent at
+the current path in HEAD, and unborn repositories use an explicitly absent
+baseline. Renames are compared at the new path; following does not infer history.
+**View File History** pauses following and opens the history viewer. **Manual
+Compare…** pauses following and compares the source with another selected file.
+Closing the pane stops following. A restored pane starts paused after reload.
+
+Following supports trusted local Git worktrees, including linked worktrees and
+files in multiple repositories. Both versions must be text, at most 128 KiB and
+5,000 lines; Git baselines must be UTF-8. Untitled, remote, virtual, notebook,
+symlink, binary, and oversized files show an unavailable state. Open the source
+file outside a native SCM diff to follow it. Git failures clear the old comparison
+and show an error instead of treating a failed read as an empty baseline.
+
 ## Limitations
 
 - Bygone is intentionally diff-focused; merge tooling is not exposed as a product feature.

package/bin/bygone.js

@@ -40,7 +40,14 @@ if (tokenMatches('completion', args[0])) {
     process.exit(0);
 }
 
-if (tokenMatches('tourCommand', args[0])) {
+if (args[0] === 'correspondence') {
+    try {
+        require('../cli/correspondence').importCorrespondenceCommand(args.slice(1), cliCwd);
+    } catch (error) {
+        process.stderr.write(`Could not import correspondence: ${error.message}\n`);
+        process.exitCode = 1;
+    }
+} else if (tokenMatches('tourCommand', args[0])) {
     try {
         runTourCommand(args.slice(1), cliCwd, packageRoot);
     } catch (error) {

package/cli/commandSpec.js

@@ -13,10 +13,11 @@ const CLI_SPEC = Object.freeze({
         'bygone --read-only <desktop-arguments...>',
         'bygone review [<head>] [--base <base>]',
         'bygone -C <directory> <command-or-path> [...]',
-        'bygone present [<head>] [--base <base>] [--tour <file.bygone>]',
+        'bygone present [<head>] [--base <base>] [--tour <file.bygone>] [--correspondence <artifact.json>]',
         'bygone tour validate <file.bygone> [--json]',
         'bygone tour compile <file.bygone> [--output <tour.json>]',
-        'bygone tour context [<head>] [--base <base>] [--output <context.json>]',
+        'bygone tour context [<head>] [--base <base>] [--output <context.json>] [--correspondence <artifact.json>]',
+        'bygone correspondence import <report.json> [<head>] [--base <base>] [--case <id>] --output <artifact.json>',
         'bygone tour coverage <file.bygone> [--json] [--minimum-coverage <0-100>]',
         'bygone tour export <file.bygone> --output <tour.html> [--profile minimal|full] [--runtime embedded|cdn]',
         'bygone <bygone://open/v1?...>',
@@ -33,6 +34,10 @@ const CLI_SPEC = Object.freeze({
             description: 'Review a committed branch against its merge base',
             argument: 'git-ref'
         },
+        {
+            id: 'correspondence', kind: 'command', tokens: ['correspondence'],
+            description: 'Import externally produced symbol correspondence evidence', argument: 'path'
+        },
         {
             id: 'completion',
             kind: 'command',
@@ -110,6 +115,10 @@ const CLI_SPEC = Object.freeze({
             description: 'Use an authored .bygone presentation',
             argument: 'path'
         },
+        {
+            id: 'correspondenceEvidence', kind: 'option', tokens: ['--correspondence'],
+            description: 'Use pinned symbol evidence in present or tour context', argument: 'path'
+        },
         {
             id: 'readOnly',
             kind: 'global',

package/cli/completions.js

@@ -35,7 +35,7 @@ function generateZshCompletion() {
     const reviewOptions = entriesByIds(['base', 'help'])
         .flatMap((entry) => entry.tokens.map((token) => `        '${token}:${escapeSingleQuoted(entry.description)}'`))
         .join('\n');
-    const presentOptions = entriesByIds(['base', 'tour', 'help'])
+    const presentOptions = entriesByIds(['base', 'tour', 'correspondenceEvidence', 'help'])
         .flatMap((entry) => entry.tokens.map((token) => `        '${token}:${escapeSingleQuoted(entry.description)}'`))
         .join('\n');
     const legacyOptions = entriesByIds(['branch', 'base', 'help'])
@@ -93,10 +93,10 @@ ${historyOptions}
             elif [[ "$words[3]" == "context" ]]; then
                 if [[ "$previous" == ${shellAlternation(tokensFor('base'))} ]]; then
                     _bygone_git_refs
-                elif [[ "$previous" == "--output" || "$previous" == "-o" ]]; then
+                elif [[ "$previous" == "--output" || "$previous" == "-o" || "$previous" == "--correspondence" ]]; then
                     _files
                 else
-                    compadd -- --base --output -o --max-patch-bytes --max-total-patch-bytes
+                    compadd -- --base --output -o --max-patch-bytes --max-total-patch-bytes --correspondence
                     _bygone_git_refs
                 fi
             elif [[ "$words[3]" == "coverage" || "$words[3]" == "validate" || "$words[3]" == "compile" ]]; then
@@ -112,7 +112,7 @@ ${historyOptions}
             fi
             ;;
         present)
-            if [[ "$previous" == ${shellAlternation(tokensFor('tour'))} ]]; then
+            if [[ "$previous" == ${shellAlternation(tokensFor('tour'))} || "$previous" == "--correspondence" ]]; then
                 _files -g '*.bygone' -g '*.bygone.yaml'
             elif [[ "$previous" == ${shellAlternation(tokensFor('base'))} ]]; then
                 _bygone_git_refs
@@ -152,7 +152,7 @@ compdef _bygone bygone
 function generateBashCompletion() {
     const rootTokens = completionEntries().flatMap((entry) => entry.tokens).join(' ');
     const reviewTokens = entriesByIds(['base', 'help']).flatMap((entry) => entry.tokens).join(' ');
-    const presentTokens = entriesByIds(['base', 'tour', 'help']).flatMap((entry) => entry.tokens).join(' ');
+    const presentTokens = entriesByIds(['base', 'tour', 'correspondenceEvidence', 'help']).flatMap((entry) => entry.tokens).join(' ');
     const legacyTokens = entriesByIds(['branch', 'base', 'help']).flatMap((entry) => entry.tokens).join(' ');
     const historyTokens = entriesByIds(['includeStaged', 'help']).flatMap((entry) => entry.tokens).join(' ');
     const baseTokens = tokensFor('base').join('|');
@@ -188,11 +188,11 @@ _bygone() {
                 refs="$(_bygone_git_refs)"
                 if [[ "$prev" =~ ^(${baseTokens})$ ]]; then
                     COMPREPLY=( $(compgen -W "$refs" -- "$cur") )
-                elif [[ "$prev" == "--output" || "$prev" == "-o" ]]; then
+                elif [[ "$prev" == "--output" || "$prev" == "-o" || "$prev" == "--correspondence" ]]; then
                     COMPREPLY=( $(compgen -f -- "$cur") )
                     compopt -o filenames 2>/dev/null || true
                 else
-                    COMPREPLY=( $(compgen -W '--base --output -o --max-patch-bytes --max-total-patch-bytes '"$refs" -- "$cur") )
+                    COMPREPLY=( $(compgen -W '--base --output -o --max-patch-bytes --max-total-patch-bytes --correspondence '"$refs" -- "$cur") )
                 fi
             else
                 COMPREPLY=( $(compgen -W '--json --output -o' -- "$cur") $(compgen -f -- "$cur") )
@@ -209,7 +209,7 @@ _bygone() {
             ;;
         present)
             refs="$(_bygone_git_refs)"
-            if [[ "$prev" == "--tour" ]]; then
+            if [[ "$prev" == "--tour" || "$prev" == "--correspondence" ]]; then
                 COMPREPLY=( $(compgen -f -- "$cur") )
                 compopt -o filenames 2>/dev/null || true
             elif [[ "$prev" =~ ^(${baseTokens})$ ]]; then
@@ -274,6 +274,7 @@ function generateFishCompletion() {
         "complete -c bygone -n '__fish_seen_subcommand_from review' -a '(__bygone_git_refs)' -d 'Git ref'",
         `complete -c bygone -n '__fish_seen_subcommand_from present' ${fishTokens(tokensFor('base'))} -r -a '(__bygone_git_refs)' -d '${escapeSingleQuoted(getCliEntry('base').description)}'`,
         `complete -c bygone -n '__fish_seen_subcommand_from present' ${fishTokens(tokensFor('tour'))} -r -d '${escapeSingleQuoted(getCliEntry('tour').description)}'`,
+        `complete -c bygone ${fishTokens(tokensFor('correspondenceEvidence'))} -r -d 'Use pinned symbol correspondence evidence'`,
         "complete -c bygone -n '__fish_seen_subcommand_from present' -a '(__bygone_git_refs)' -d 'Git ref'",
         `complete -c bygone -n 'string match -q "*--branch-diff*" -- (commandline -opc)' ${fishTokens(tokensFor('branch'))} -r -a '(__bygone_git_refs)' -d '${escapeSingleQuoted(getCliEntry('branch').description)}'`,
         `complete -c bygone -n 'string match -q "*--branch-diff*" -- (commandline -opc)' ${fishTokens(tokensFor('base'))} -r -a '(__bygone_git_refs)' -d '${escapeSingleQuoted(getCliEntry('base').description)}'`,

package/cli/correspondence.js

@@ -0,0 +1,71 @@
+const path = require('path');
+const { lstatSync, mkdirSync, statSync, writeFileSync } = require('fs');
+const { resolveBranchReviewRange } = require('../out/gitComparison');
+const { importChangeCorrespondence, readCorrespondenceJson } = require('../out/changeCorrespondence');
+
+function importCorrespondenceCommand(args, cwd, output = process.stdout) {
+    if (args[0] !== 'import') throw new Error('Usage: bygone correspondence import <report.json> [<head>] --base <base> [--case <id>] --output <artifact.json>');
+    const options = {};
+    const positional = [];
+    for (let i = 1; i < args.length; i++) {
+        const arg = args[i];
+        if (['--base', '--case', '--output', '-o'].includes(arg)) {
+            if (!args[i + 1] || args[i + 1].startsWith('-')) throw new Error(`${arg} requires a value.`);
+            options[arg === '-o' ? '--output' : arg] = args[++i];
+        } else if (arg.startsWith('-')) throw new Error(`Unknown correspondence option: ${arg}`);
+        else positional.push(arg);
+    }
+    if (!positional.length || positional.length > 2 || !options['--output']) throw new Error('Provide a producer report, at most one head ref, and --output.');
+    const reportPath = path.resolve(cwd, positional[0]);
+    const destination = path.resolve(cwd, options['--output']);
+    assertDestinationAvailable(reportPath, destination);
+    const report = readCorrespondenceJson(reportPath);
+    if (!report || typeof report !== 'object') throw new Error('Invalid correspondence report.');
+    let selected = report;
+    if (Array.isArray(report.cases)) {
+        if (!options['--case']) throw new Error('A multi-case producer report requires --case.');
+        const matches = report.cases.filter(c => c.id === options['--case']);
+        if (matches.length !== 1) throw new Error('Select exactly one existing producer case.');
+        selected = matches[0];
+    } else if (options['--case']) throw new Error('--case requires a multi-case producer report.');
+    const range = resolveBranchReviewRange(cwd, positional[1] || 'HEAD', options['--base']);
+    const artifact = importChangeCorrespondence(range.repoRoot, selected, { baseOid: range.mergeBaseOid, headOid: range.headOid });
+    mkdirSync(path.dirname(destination), { recursive: true });
+    try {
+        writeFileSync(destination, JSON.stringify(artifact, null, 2) + '\n', { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+    } catch (error) {
+        if (error?.code === 'EEXIST') throw new Error(`The correspondence output already exists at ${destination}; choose a new path.`, { cause: error });
+        throw new Error(`Could not create correspondence output at ${destination}: ${error.message}`, { cause: error });
+    }
+    output.write(`Wrote ${artifact.relations.length} inferred correspondences (${artifact.status}) to ${destination}\n`);
+    return artifact;
+}
+
+function assertDestinationAvailable(reportPath, destination) {
+    if (sameActualFile(reportPath, destination)) {
+        throw new Error('The imported artifact must not overwrite the producer report or any of its symlink/hardlink aliases.');
+    }
+    try {
+        lstatSync(destination);
+    } catch (error) {
+        if (error?.code === 'ENOENT') return;
+        throw new Error(`Could not inspect correspondence output at ${destination}: ${error.message}`, { cause: error });
+    }
+    throw new Error(`The correspondence output already exists at ${destination}; choose a new path.`);
+}
+
+function sameActualFile(first, second) {
+    if (first === second) return true;
+    try {
+        const left = statSync(first);
+        const right = statSync(second);
+        if (left.dev !== undefined && left.ino !== undefined
+            && left.dev === right.dev && left.ino === right.ino
+            && left.ino !== 0 && right.ino !== 0) return true;
+    } catch {
+        return false;
+    }
+    return false;
+}
+
+module.exports = { importCorrespondenceCommand };

package/cli/present.js

@@ -1,8 +1,9 @@
-const { createReadStream, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } = require('fs');
+const { existsSync, mkdirSync, readFile, readFileSync, realpathSync, statSync, writeFileSync } = require('fs');
 const { createServer } = require('http');
 const path = require('path');
 const { spawn } = require('child_process');
 const { buildChangeTourManifest, parseChangeTourStory } = require('../out/changeTour.js');
+const { loadChangeCorrespondence } = require('../out/changeCorrespondence');
 const { buildTourAuthoringCoverage, buildTourCoverageReport } = require('../out/tourCoverage.js');
 const { buildTourWindowTitle } = require('../out/windowTitle.js');
 const { tokenMatches } = require('./commandSpec.js');
@@ -22,7 +23,7 @@ const MIME_TYPES = new Map([
 ]);
 
 async function startPresentation(args, cwd, packageRoot, options = {}) {
-    const { headRef, baseRef, tourPath, explicitHeadRef } = parsePresentArgs(args);
+    const { headRef, baseRef, tourPath, explicitHeadRef, correspondencePath } = parsePresentArgs(args);
     const story = !options.ignoreEnvironment && process.env.BYGONE_TOUR_STORY
         ? parseChangeTourStory(JSON.parse(readFileSync(path.resolve(cwd, process.env.BYGONE_TOUR_STORY), 'utf8')))
         : undefined;
@@ -48,6 +49,21 @@ async function startPresentation(args, cwd, packageRoot, options = {}) {
         const contained = relative && relative !== '..' && !relative.startsWith('../') && !path.isAbsolute(relative);
         manifest.localSource = { repo: pathToFileURL(root).href, tour: contained ? relative : pathToFileURL(documentPath).href };
     }
+    const repositoryRoot = builtManifest.repository?.root || cwd;
+    const authoredCorrespondencePath = source?.correspondence
+        ? path.resolve(repositoryRoot, source.correspondence)
+        : undefined;
+    const explicitCorrespondencePath = correspondencePath
+        ? path.resolve(cwd, correspondencePath)
+        : undefined;
+    if (authoredCorrespondencePath && explicitCorrespondencePath
+        && !sameActualFile(authoredCorrespondencePath, explicitCorrespondencePath)) {
+        throw new Error(`Conflicting correspondence artifacts: source.correspondence (${authoredCorrespondencePath}) and --correspondence (${explicitCorrespondencePath}) must identify the same actual file.`);
+    }
+    const correspondencePathToLoad = explicitCorrespondencePath || authoredCorrespondencePath;
+    const correspondence = correspondencePathToLoad
+        ? loadChangeCorrespondence(repositoryRoot, correspondencePathToLoad, { baseOid: manifest.range.mergeBaseOid, headOid: manifest.range.headOid })
+        : null;
     const history = createTourHistory(manifest);
     const serializedManifest = `${JSON.stringify(manifest, null, 2)}\n`;
     const outputPath = options.ignoreEnvironment ? undefined : process.env.BYGONE_TOUR_OUTPUT;
@@ -60,13 +76,16 @@ async function startPresentation(args, cwd, packageRoot, options = {}) {
 
     const tourWindowTitle = buildTourWindowTitle(manifest, 'Bygone');
     const presenterIndexPath = path.join(packageRoot, 'web', 'index.html');
-    let presenterIndexTemplate;
     // Uploaded documents remain immutable, scoped to this existing repository,
     // and addressed independently so opening one cannot mutate another tab.
     const uploadedTours = new Map();
 
     const server = createServer((request, response) => {
         const requestUrl = new URL(request.url || '/', 'http://127.0.0.1');
+        if (requestUrl.pathname === '/correspondence.json') {
+            if (request.method !== 'GET') return respondJson(response, 405, { error: 'Method not allowed' });
+            return respondJson(response, correspondence ? 200 : 404, correspondence || { error: 'No correspondence supplied' });
+        }
         if (requestUrl.pathname === '/tour/open') {
             if (request.method !== 'POST') return respondJson(response, 405, { error: 'Method not allowed' });
             if (!isSameOriginLoopbackRequest(request)) return respondJson(response, 403, { error: 'Forbidden' });
@@ -159,18 +178,20 @@ async function startPresentation(args, cwd, packageRoot, options = {}) {
             return;
         }
         if (requestUrl.pathname === '/' || requestUrl.pathname === '/index.html') {
-            if (!presenterIndexTemplate) {
-                presenterIndexTemplate = readFileSync(presenterIndexPath, 'utf8');
-            }
-            const html = presenterIndexTemplate.replace(
-                /<title>Bygone Tour<\/title>/,
-                `<title>${escapeHtml(tourWindowTitle)}</title>`
-            );
-            response.writeHead(200, {
-                'Content-Type': 'text/html; charset=utf-8',
-                'Cache-Control': 'no-store'
+            // Read HTML like the runtime assets so a rebuild cannot leave a
+            // running presentation serving old controls with new JavaScript.
+            readFile(presenterIndexPath, 'utf8', (error, template) => {
+                if (error) { respond(response, 500, 'Read failed'); return; }
+                const html = template.replace(
+                    /<title>Bygone Tour<\/title>/,
+                    `<title>${escapeHtml(tourWindowTitle)}</title>`
+                );
+                response.writeHead(200, {
+                    'Content-Type': 'text/html; charset=utf-8',
+                    'Cache-Control': 'no-store'
+                });
+                response.end(html);
             });
-            response.end(html);
             return;
         }
         const targetPath = resolveAssetPath(packageRoot, requestUrl.pathname);
@@ -178,11 +199,20 @@ async function startPresentation(args, cwd, packageRoot, options = {}) {
             respond(response, 404, 'Not found');
             return;
         }
-        response.writeHead(200, {
-            'Content-Type': MIME_TYPES.get(path.extname(targetPath)) || 'application/octet-stream',
-            'Cache-Control': 'no-store'
+        // Electron streams extract ASAR entries to cached temporary files. Those
+        // can disappear during a long-running session; readFile reads the archive
+        // directly and lets us report failures before committing success headers.
+        readFile(targetPath, (error, content) => {
+            if (error) {
+                respond(response, 500, 'Read failed');
+                return;
+            }
+            response.writeHead(200, {
+                'Content-Type': MIME_TYPES.get(path.extname(targetPath)) || 'application/octet-stream',
+                'Cache-Control': 'no-store'
+            });
+            response.end(content);
         });
-        createReadStream(targetPath).on('error', () => respond(response, 500, 'Read failed')).pipe(response);
     });
     const requestedPort = readPort(options.ignoreEnvironment ? undefined : process.env.BYGONE_TOUR_PORT);
     await new Promise((resolve, reject) => {
@@ -194,7 +224,7 @@ async function startPresentation(args, cwd, packageRoot, options = {}) {
         server.close();
         throw new Error('Could not determine the presentation server address.');
     }
-    const url = `http://127.0.0.1:${address.port}/?manifest=/tour.json${options.location ? serializeDocumentFragment(options.location.mode, options.location.focus) : ''}`;
+    const url = `http://127.0.0.1:${address.port}/?manifest=/tour.json${correspondence ? '&correspondence=1' : ''}${options.location ? serializeDocumentFragment(options.location.mode, options.location.focus) : ''}`;
     if (options.announce !== false) {
         process.stdout.write(`Bygone change tour running at ${url}\n`);
         process.stdout.write('Press Ctrl+C to stop.\n');
@@ -216,6 +246,7 @@ function parsePresentArgs(args) {
     let explicitHeadRef;
     let baseRef;
     let tourPath;
+    let correspondencePath;
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (tokenMatches('base', arg)) {
@@ -225,6 +256,11 @@ function parsePresentArgs(args) {
             baseRef = args[++index];
             continue;
         }
+        if (arg === '--correspondence') {
+            if (!args[index + 1] || args[index + 1].startsWith('-')) throw new Error('--correspondence requires a file path.');
+            correspondencePath = args[++index];
+            continue;
+        }
         if (tokenMatches('tour', arg)) {
             if (!args[index + 1]) throw new Error(`${arg} requires a YAML file.`);
             tourPath = args[++index];
@@ -239,7 +275,7 @@ function parsePresentArgs(args) {
         headRef = arg;
         explicitHeadRef = arg;
     }
-    return { headRef, baseRef, tourPath, explicitHeadRef };
+    return { headRef, baseRef, tourPath, explicitHeadRef, ...(correspondencePath ? { correspondencePath } : {}) };
 }
 
 function resolveAssetPath(packageRoot, requestPath) {
@@ -306,6 +342,24 @@ function isSameOriginLoopbackRequest(request) {
     }
 }
 
+function sameActualFile(first, second) {
+    if (first === second) return true;
+    try {
+        const left = statSync(first);
+        const right = statSync(second);
+        if (left.dev !== undefined && left.ino !== undefined
+            && left.dev === right.dev && left.ino === right.ino
+            && left.ino !== 0 && right.ino !== 0) return true;
+    } catch {
+        // Fall back to canonical paths on filesystems without usable identity metadata.
+    }
+    try {
+        return realpathSync(first) === realpathSync(second);
+    } catch {
+        return false;
+    }
+}
+
 function escapeHtml(text) {
     return text
         .replaceAll('&', '&amp;')

package/cli/tour.js

@@ -37,6 +37,7 @@ function runTourCommand(args, cwd, packageRoot, output = process.stdout) {
         const context = buildChangeTourContext(cwd, {
             headRef: options.headRef,
             baseRef: options.baseRef,
+            correspondencePath: options.correspondencePath ? path.resolve(cwd, options.correspondencePath) : undefined,
             maxPatchBytes: options.maxPatchBytes,
             maxTotalPatchBytes: options.maxTotalPatchBytes
         });
@@ -147,6 +148,7 @@ function parseContextArgs(args) {
     let baseRef;
     let outputPath;
     let maxPatchBytes;
+    let correspondencePath;
     let maxTotalPatchBytes;
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
@@ -160,6 +162,11 @@ function parseContextArgs(args) {
             outputPath = args[++index];
             continue;
         }
+        if (arg === '--correspondence') {
+            if (!args[index + 1] || args[index + 1].startsWith('-')) throw new Error('--correspondence requires a file path.');
+            correspondencePath = args[++index];
+            continue;
+        }
         if (arg === '--max-patch-bytes') {
             if (!args[index + 1]) throw new Error(`${arg} requires a positive integer.`);
             maxPatchBytes = Number.parseInt(args[++index], 10);
@@ -180,7 +187,7 @@ function parseContextArgs(args) {
         if (headRef) throw new Error('tour context accepts at most one head ref.');
         headRef = arg;
     }
-    return { action: 'context', headRef, baseRef, outputPath, maxPatchBytes, maxTotalPatchBytes };
+    return { action: 'context', headRef, baseRef, outputPath, maxPatchBytes, maxTotalPatchBytes, ...(correspondencePath ? { correspondencePath } : {}) };
 }
 
 function writeJsonResult(label, value, outputPath, cwd, output) {

package/cli/tourExport.js

@@ -78,7 +78,7 @@ function materializeTour(sourcePath, profile) {
     delete manifest.localSource;
     // A source URL is optional provenance and may carry credentials or local bindings.
     delete manifest.sourceUrl;
-    const contentKeys = new Set(['leftContent', 'rightContent', 'content']);
+    const contentKeys = new Set(['leftContent', 'rightContent', 'content', 'text']);
     function pack(value) {
         if (Array.isArray(value)) return value.map(pack);
         if (!value || typeof value !== 'object') return value;

package/completions/_bygone

@@ -14,6 +14,7 @@ _bygone() {
     local -a root_items review_options present_options legacy_options history_options shells tour_actions
     root_items=(
         'review:Review a committed branch against its merge base'
+        'correspondence:Import externally produced symbol correspondence evidence'
         'completion:Print shell completion source'
         'present:Open an app-hosted tour of a committed branch range'
         'tour:Validate, compile, or inspect authored change tours'
@@ -41,6 +42,7 @@ _bygone() {
         '-m:Set the branch-review base ref'
         '--main:Set the branch-review base ref'
         '--tour:Use an authored .bygone presentation'
+        '--correspondence:Use pinned symbol evidence in present or tour context'
         '-h:Show command help'
         '--help:Show command help'
     )
@@ -78,10 +80,10 @@ _bygone() {
             elif [[ "$words[3]" == "context" ]]; then
                 if [[ "$previous" == (--base|-m|--main) ]]; then
                     _bygone_git_refs
-                elif [[ "$previous" == "--output" || "$previous" == "-o" ]]; then
+                elif [[ "$previous" == "--output" || "$previous" == "-o" || "$previous" == "--correspondence" ]]; then
                     _files
                 else
-                    compadd -- --base --output -o --max-patch-bytes --max-total-patch-bytes
+                    compadd -- --base --output -o --max-patch-bytes --max-total-patch-bytes --correspondence
                     _bygone_git_refs
                 fi
             elif [[ "$words[3]" == "coverage" || "$words[3]" == "validate" || "$words[3]" == "compile" ]]; then
@@ -97,7 +99,7 @@ _bygone() {
             fi
             ;;
         present)
-            if [[ "$previous" == (--tour) ]]; then
+            if [[ "$previous" == (--tour) || "$previous" == "--correspondence" ]]; then
                 _files -g '*.bygone' -g '*.bygone.yaml'
             elif [[ "$previous" == (--base|-m|--main) ]]; then
                 _bygone_git_refs

package/completions/bygone

@@ -12,7 +12,7 @@ _bygone() {
     first="${COMP_WORDS[1]}"
 
     if (( COMP_CWORD == 1 )); then
-        COMPREPLY=( $(compgen -W 'review completion present tour --diff --history --git-diff --branch-diff --test --read-only -C -h --help -v --version' -- "$cur") $(compgen -f -- "$cur") )
+        COMPREPLY=( $(compgen -W 'review correspondence completion present tour --diff --history --git-diff --branch-diff --test --read-only -C -h --help -v --version' -- "$cur") $(compgen -f -- "$cur") )
         compopt -o filenames 2>/dev/null || true
         return
     fi
@@ -28,11 +28,11 @@ _bygone() {
                 refs="$(_bygone_git_refs)"
                 if [[ "$prev" =~ ^(--base|-m|--main)$ ]]; then
                     COMPREPLY=( $(compgen -W "$refs" -- "$cur") )
-                elif [[ "$prev" == "--output" || "$prev" == "-o" ]]; then
+                elif [[ "$prev" == "--output" || "$prev" == "-o" || "$prev" == "--correspondence" ]]; then
                     COMPREPLY=( $(compgen -f -- "$cur") )
                     compopt -o filenames 2>/dev/null || true
                 else
-                    COMPREPLY=( $(compgen -W '--base --output -o --max-patch-bytes --max-total-patch-bytes '"$refs" -- "$cur") )
+                    COMPREPLY=( $(compgen -W '--base --output -o --max-patch-bytes --max-total-patch-bytes --correspondence '"$refs" -- "$cur") )
                 fi
             else
                 COMPREPLY=( $(compgen -W '--json --output -o' -- "$cur") $(compgen -f -- "$cur") )
@@ -49,13 +49,13 @@ _bygone() {
             ;;
         present)
             refs="$(_bygone_git_refs)"
-            if [[ "$prev" == "--tour" ]]; then
+            if [[ "$prev" == "--tour" || "$prev" == "--correspondence" ]]; then
                 COMPREPLY=( $(compgen -f -- "$cur") )
                 compopt -o filenames 2>/dev/null || true
             elif [[ "$prev" =~ ^(--base|-m|--main)$ ]]; then
                 COMPREPLY=( $(compgen -W "$refs" -- "$cur") )
             else
-                COMPREPLY=( $(compgen -W '--base -m --main --tour -h --help '"$refs" -- "$cur") )
+                COMPREPLY=( $(compgen -W '--base -m --main --tour --correspondence -h --help '"$refs" -- "$cur") )
             fi
             ;;
         --branch-diff)

package/completions/bygone.fish

@@ -5,6 +5,7 @@ function __bygone_git_refs
 end
 
 complete -c bygone -n '__fish_use_subcommand' -a review -d 'Review a committed branch against its merge base'
+complete -c bygone -n '__fish_use_subcommand' -a correspondence -r -d 'Import externally produced symbol correspondence evidence'
 complete -c bygone -n '__fish_use_subcommand' -a completion -d 'Print shell completion source'
 complete -c bygone -n '__fish_use_subcommand' -a present -d 'Open an app-hosted tour of a committed branch range'
 complete -c bygone -n '__fish_use_subcommand' -a tour -d 'Validate, compile, or inspect authored change tours'
@@ -30,6 +31,7 @@ complete -c bygone -n '__fish_seen_subcommand_from review' -l base -s m -l main
 complete -c bygone -n '__fish_seen_subcommand_from review' -a '(__bygone_git_refs)' -d 'Git ref'
 complete -c bygone -n '__fish_seen_subcommand_from present' -l base -s m -l main -r -a '(__bygone_git_refs)' -d 'Set the branch-review base ref'
 complete -c bygone -n '__fish_seen_subcommand_from present' -l tour -r -d 'Use an authored .bygone presentation'
+complete -c bygone -l correspondence -r -d 'Use pinned symbol correspondence evidence'
 complete -c bygone -n '__fish_seen_subcommand_from present' -a '(__bygone_git_refs)' -d 'Git ref'
 complete -c bygone -n 'string match -q "*--branch-diff*" -- (commandline -opc)' -s b -l branch -r -a '(__bygone_git_refs)' -d 'Set the branch-review head ref'
 complete -c bygone -n 'string match -q "*--branch-diff*" -- (commandline -opc)' -l base -s m -l main -r -a '(__bygone_git_refs)' -d 'Set the branch-review base ref'