@davmash/bygone 0.10.1 → 0.11.1

package/docs/correspondence.md

@@ -0,0 +1,259 @@
+# Try symbol correspondence evidence
+
+This experimental integration connects externally produced symbol mappings to
+Bygone's authoring context and presentation viewer. It does not run a matcher
+or model automatically. RefactoringMiner and Java remain optional external
+research tools; neither is a new Bygone runtime dependency.
+
+## Generate evidence in this checkout
+
+The development command inventories changed JS/TS, Python, Java, Go, Rust, C#, Ruby, PHP, C, Lua and
+Mojo regular files from committed
+Git blobs, runs the bounded analysis adapter and imports its result into the
+validated viewer format. It uses the review merge base, just like `present`;
+working-tree edits are excluded. No second branch or saved research report is
+required.
+
+Start without Java:
+
+```sh
+npm run correspondence:analyze -- feature --base main \
+  --output /tmp/correspondence.json
+```
+
+With no Java engine configuration, this inventories symbols and pairs only
+unambiguous declarations with identical bytes. It records partial coverage:
+edited or renamed declarations can remain unmatched, so unmatched does not
+prove an addition or removal. Use `--exact-only` to choose this mode even when
+Java engine environment variables are set.
+
+To use the local Strand correspondence engine:
+
+```sh
+npm run correspondence:analyze -- feature --base main --engine bygone-strand \
+  --output /tmp/correspondence-strand.json
+```
+
+Bygone Strand is an original declaration matcher in the private
+[`bygone-strand` workspace package](../packages/strand/README.md). It supports
+JS/TS, Python, Java, Go, Rust, C#, Ruby, PHP, C, Lua and experimental Mojo. TypeScript and isolated
+CPython parsers retain their existing behavior; the other languages share a
+bounded Tree-sitter WASM frontend with pinned, locally shipped grammars. Scoped
+declaration identities and syntax/token similarity infer edited continuations,
+moves and renames. Strand requires no JVM, native addon or runtime downloads. The explicit selection ignores ambient Java configuration and
+cannot be combined with `--exact-only` or Java flags. The default mode is
+unchanged. See [the engine contract](../scripts/change-analysis/javascript-engine.md)
+for evidence, ambiguity and resource limits.
+
+This version produces one-to-one continuations. Extraction/inline detection,
+binding resolution, editing history and behavior preservation are unassessed.
+Python functions, async functions, classes, methods and nested declarations
+support inferred edits and moves. Decorators and complete source diffs remain
+visible. Python `.pyi` stubs retain inventory/exact matching only.
+
+Go receiver and Rust impl/trait identities are conservative: receiver/type
+renames are not inferred across owners. Mojo (`.mojo`/`.🔥`) uses a pinned
+community grammar and remains experimental; legacy `fn` syntax is unsupported.
+See the [package coverage and exclusions](../packages/strand/README.md) and
+[grammar provenance](../packages/strand/src/grammars/README.md) for exact scope.
+Parser errors/timeouts fail closed, and duplicate origins remain ambiguous.
+`npm run test:strand` runs package and artifact integration checks.
+
+For broader inference, build the pinned external engine following
+[scripts/change-analysis/README.md](../scripts/change-analysis/README.md), then
+supply its verified build digest and JDK explicitly:
+
+```sh
+export MAPPING_JAVA=/absolute/path/to/jdk/bin/java
+export MAPPING_JAR=/absolute/path/to/RefactoringMiner/build/libs/RM-fat.jar
+export MAPPING_JAR_SHA256=<verified-build-sha256>
+npm run correspondence:analyze -- feature --base main \
+  --output /tmp/correspondence.json
+```
+
+Use `--repo /absolute/path/to/checkout` to analyze another repository without
+copying its source into this one. `--java`, `--jar` and `--jar-sha256` override
+the environment. Supply all three engine settings together; incomplete settings,
+unavailable/incompatible toolchains and digest mismatches fail instead of silently
+switching modes. The adapter needs a JDK 21+ with sibling `java` and `javac`
+(verified with JDK 21). `--exact-only` cannot be combined with Java engine flags.
+Python comparisons additionally use `--python` or
+`MAPPING_PYTHON` (default `python3`), CPython 3.8+ with syntax support determined
+by that interpreter. Named Python functions/classes/methods include decorators
+and attached terminal comments; lambdas and variable bindings are excluded.
+Python `.pyi` files have inventory/exact matching only and explicitly mark the
+comparison partial because the pinned engine does not parse them. Validated
+matches between analyzed implementation declarations can still be accepted.
+
+The output must be a new file. Import creates it exclusively and refuses an
+existing path, including the producer report itself and symlink or hardlink
+aliases. It never overwrites existing bytes; choose another output path.
+Artifacts contain source text;
+keep private repositories' evidence outside this repository.
+
+When presenting a tour, an authored `source.correspondence` path and an
+explicit `--correspondence` path must identify the same actual file. Symlink
+and hardlink aliases are accepted, but a separate copy with identical bytes is
+still a different artifact and is rejected before the manifest output or server
+is created.
+
+Changed files bound the candidate universe: unchanged files, unsupported
+languages, symlinks and submodules are excluded. The artifact records this
+scope, the engine/bridge digests, parser version, limits and failure reason.
+Engine/bridge digests are present only when that engine is configured.
+Timeout, truncation or process failure produces explicitly partial evidence;
+only independent exact declarations can survive. Invalid source encoding or
+an input budget violation fails without writing an artifact. A comparison with
+no supported source documents is explicitly unavailable.
+
+Generation currently runs from a source checkout with development dependencies.
+Java and RefactoringMiner are explicit external tools, not npm
+`optionalDependencies`: npm does not install their toolchain, and Bygone does not
+bundle or download them. Python is needed only to generate Python inventories.
+Viewing/importing saved evidence and opening symbol tour stops needs neither
+Java nor Python. This keeps engine size, native parser support and runtime updates
+outside the viewer's installation path; optional does not imply reduced evidence
+is equivalent to a complete engine result.
+
+## Import an existing report
+
+Normalized reports may contain one `analysis` or a `cases` array. Select a case
+explicitly when importing a batch:
+
+```sh
+bygone correspondence import mappings.json feature --base main \
+  --case module-split --output /tmp/imported-correspondence.json
+```
+
+The import resolves the selected review's merge-base/head to immutable commit
+IDs. It checks every supplied document digest, symbol span and symbol digest
+against those Git blobs, resolves endpoints uniquely, rejects conflicting or
+ambiguous accepted continuations, and recomputes complete declaration diffs.
+Producer-supplied quotations, line numbers, local diffs and equality flags are
+not trusted. The artifact records analysis status, supplied document scope,
+producer, unmatched counts, syntax exclusions and competing origins.
+
+Only the selected producer case's supplied scope is checked. Source integrity
+checks do not independently adjudicate the producer's symbol identities,
+parsing, completeness or semantic claims. All mappings remain inferred and
+behavior remains unassessed. Partial analysis suppresses engine-only mappings
+unless the producer explicitly records complete search coverage for that pair.
+The adapter permits this for analyzed implementations when only stubs are
+skipped, or unique same-file/scope/name continuations when skipped implementation
+files are unchanged. Skipped changed implementations, invalid parsing, engine
+failure and truncation still prevent that claim. Import rejects complete pair
+coverage from a failed or truncated engine; saved artifacts preserve the claim
+and revalidate source bytes and endpoints. This remains producer-supplied search
+evidence, not independently established lineage. Older partial artifacts without
+pair coverage retain the exact-only guard. Independent exact-declaration
+evidence can remain available. Extraction/inline
+groups expose their endpoints in Analysis details; they are not accepted continuations.
+
+Exact matching first checks unique same-file, same-scope, same-name bindings
+with identical declaration bytes and binding context. Repeated constants in
+different files can therefore retain their local continuations. Cross-scope
+matching still considers all identical occurrences, including retained sources;
+remaining competing origins are reported for variables as well as callables.
+Local evidence does not override a conflicting engine candidate.
+
+## Use the same artifact in both places
+
+```sh
+bygone tour context feature --base main \
+  --correspondence /tmp/correspondence.json --output /tmp/context.json
+bygone present feature --base main --correspondence /tmp/correspondence.json
+```
+
+No authored `.bygone` file is required. In the viewer, select **Symbols**, filter
+by name or path, and select a mapping to compare its complete old and new
+source symbol slices, including edits within moved code. Variable slices can
+exclude enclosing export/const/let syntax; inspect the complete file for that
+context and for surrounding binding/import changes. The labels identify
+both paths, source lines and revisions. Editor line numbers are relative to
+the declaration slice. **Show file context** opens complete source and destination
+files and highlights the declarations at their original lines, including moves
+between files. **Return to symbol comparison** restores the declaration slices.
+The **Files** rail also nests the same filtered symbol tree beneath each file.
+Use the arrow on the right of a file (**Show Symbols** on hover) to reveal or
+hide its symbols directly underneath. Each file starts folded and keeps its own
+expansion state; selecting files, symbols, or tour stops does not change it.
+Symbol names use green for after-only declarations, red for before-only declarations,
+and amber for accepted mappings with edits, moves, renames, or reparenting. Ambiguous
+origins and unchanged declarations stay neutral. One-sided colors describe the
+inventory; they do not confirm additions or deletions.
+Symbols and Files share selection; both endpoints of a move are highlighted.
+Selecting a file opens its complete diff without advancing the tour.
+Symbols groups declarations by file and nests classes, methods and functions
+using their source ranges. Expand or collapse branches with the disclosure
+buttons (also keyboard accessible). The default filter includes moved, renamed,
+edited and unmatched declarations. **Include added or removed local symbols**
+is checked by default; uncheck it to hide before-only and after-only declarations
+without accepted matches, including ambiguous endpoints. These are not confirmed
+additions or deletions. Enable **Include unchanged local symbols** to also show
+unchanged matched declarations. Search retains ancestor paths and opens
+matching branches. Ancestors retained only for context are dimmed.
+Moved or reparented declarations appear at both locations; the old location is
+labeled **Before location** and opens the same before/after comparison. Counts
+include each accepted mapping once. **Before only**, **After only** and
+**Ambiguous** entries have no accepted match; selecting one shows its available
+source slice, without claiming a confirmed addition or deletion.
+Open **Analysis details** for separate counts and expandable records for paths
+outside analysis, syntax not inventoried, rejected engine containers, unmatched
+symbols and competing origins, other relationships, and analysis problems.
+Records retain reported reasons, revision sides and source locations. Links open
+complete file context or inventoried symbols, including unchanged declarations;
+symbol links clear search and enable both include options.
+Ambiguous groups link every competing endpoint without picking an origin.
+Invalid producer ranges retain paths without trusted offsets. A missing candidate
+is distinguished from a rejected candidate; when the producer gives no explanation,
+the viewer says so. Categories overlap, use explicit units and are not a coverage
+percentage. Unchanged files outside a changed-file search are described as a scope
+limit, not enumerated as missing symbols. Older artifacts retain their summaries
+and show **Detailed diagnostics unavailable** rather than zero diagnostic counts.
+The status always names the artifact's pinned base/head, even when exploring
+other history comparisons. An uploaded tour does not inherit this evidence.
+
+Both consumers revalidate the artifact against their selected comparison.
+Advancing a branch does not silently reuse old evidence: a different head or
+merge base requires a new import. Context's ordinary patches, counts and limits
+are unchanged; correspondence is a separate optional field with its own
+budgets (16 MiB artifact, 128 documents per side, 1 MiB per Git blob, 8 MiB total
+source and 8 MiB total symbol text). Nested symbols overlap, so their diffs
+must not be summed as coverage or subtracted from changed-line accounting.
+For a declaration diff exceeding the comparison effort budget, its entire old
+and new slices are retained as removal/addition rather than omitting content.
+
+## Use symbols in authored tours
+
+Version 6 walkthrough steps can select an accepted relation or one unmatched
+symbol from a source's `correspondence` artifact. The compiler pins declaration
+text and full file context into each stop, preserving one-sided ambiguous
+endpoints. See [Symbol-focused stops](change-tour-format.md#symbol-focused-stops)
+for the source contract, validation, coverage, and offline behavior.
+
+## Run this checkout's real example
+
+With the explicit engine environment above:
+
+```sh
+npm run correspondence:analyze -- 726796b1fe --base '726796b1fe^' \
+  --output /tmp/bygone-correspondence.json
+BYGONE_FORCE_BUNDLED=1 node bin/bygone.js present 726796b1fe \
+  --base '726796b1fe^' --correspondence /tmp/bygone-correspondence.json
+```
+
+Search for `validateChangeTourDetails`. The declaration comparison retains the
+removed `validateAssessment(...)` call, removed context parameter and changed
+allowed-key list. The artifact includes six moved functions and other inferred
+continuations. `BYGONE_FORCE_BUNDLED=1` selects the newly built checkout instead
+of an older installed desktop application.
+
+`npm run test:correspondence` runs the source/CLI/server checks and an Electron
+browser smoke using a portable fixture taken from that real module split.
+This slice does not construct intermediate refactoring stages, hide raw edits,
+add model annotations, or establish reviewer benefit.
+
+`npm run test:correspondence:engine` uses the same explicit engine environment.
+It runs the adapter tests, Git snapshot tests, real JVM timeout/truncation/output
+failure checks, Python ranges/moves/renames and fresh module-split generation accepted by the viewer's
+consumer. Large archived reports and evaluations stay on the research branch.

package/docs/dependencies.md

@@ -0,0 +1,94 @@
+# Dependency evidence
+
+The Node CLI (npm installation or `node bin/bygone.js` in a source checkout)
+compares JS/TS module dependencies at the merge base and head of a committed
+review range:
+
+```sh
+bygone dependencies HEAD --base main
+bygone dependencies HEAD --base main --json
+bygone dependencies HEAD --base main --output dependencies.json
+bygone tour context HEAD --base main --dependencies --output context.json
+```
+
+The text report lists added/removed module edges and direct, unchanged consumers
+of changed files. Each site includes a `bygone://` link to its committed source.
+JSON includes both bounded snapshot graphs, potential initialization calls and
+constructors, diagnostics, and exact evidence coordinates. Ordinary tour context
+generation is unchanged. The desktop and VS Code interfaces do not yet have a
+graph view; these commands use the Node CLI rather than the desktop launcher.
+
+## Reading an edge
+
+Relationship, phase, and loading are separate fields. Static evidence can describe
+initialization or later invocation; it is not a runtime trace.
+
+- `import`, `reexport`, `require`, and `dynamic-import` describe syntax.
+- `type` marks explicitly type-only dependencies and dependencies in declaration files. `module-init` marks syntax
+  evaluated while a module initializes; a lazy-loaded module can initialize much
+  later than process startup. `invocation` marks function/callback bodies.
+  `unknown` retains sites where the extractor cannot assign a phase safely.
+- `eager` distinguishes ordinary imports/require from `deferred` dynamic imports and namespace `import defer` declarations. Deferred namespace evaluation has `unknown` phase because namespace use determines when evaluation occurs.
+  A dynamic import at top level is still labeled `module-init`. A `require` inside
+  a function is `invocation` even though the require operation itself is eager.
+- `resolution: resolved` means the TypeScript resolver found a committed target
+  under the selected compiler options. It does not prove execution, runtime loader
+  equivalence, or the identity of a shadowable `require` binding.
+- `unresolved`, `computed`, and `invalid-config` preserve unknown targets. Builtins,
+  external packages, and computed specifiers commonly remain unresolved.
+
+Potential initialization calls are syntax sites, not inferred function-call
+edges. Registration calls can appear here; their callback bodies are classified
+separately. IIFE bodies are conservatively labeled invocation with a diagnostic.
+Instance field initializers have unknown timing; static fields and class static
+blocks inherit the enclosing evaluation phase. Conditions are not evaluated.
+Non-explicit type import elision and transpiler-specific emission are not modeled.
+
+## Historical resolution and coverage
+
+Both graphs are built from Git tree/blob objects at immutable OIDs. Dirty files,
+installed packages, symlink targets, compiler plugins and target code are never
+read or executed for resolution. The nearest committed `tsconfig.json` (or
+`jsconfig.json`) supplies compiler options, including relative `extends`, `baseUrl`
+and `paths`. Missing/invalid config is diagnosed. Without a config, analysis uses
+TypeScript's Node-style resolution with JavaScript enabled. The report records
+the analyzer's TypeScript version; it need not match the target project's compiler.
+The dependency analyzer uses an isolated TypeScript 5.9.3 parser/resolver (without changing Strand or the extension compiler), including `bundler` resolution and modern syntax such as `using`. Package-based config extension and bundler runtime plugins remain outside scope. Malformed package metadata produces partial coverage; resolution that needs that metadata is `invalid-config`, without a fallback target.
+Project references do not provide symbol binding or build output reconstruction.
+
+Limits apply per snapshot: 2,000 source/config files, 1 MiB per file, 16 MiB total
+input and 20,000 dependency/initialization records. Source-ancestor package.json, tsconfig.json and jsconfig.json files, plus their relative config inheritance closure, share the input budget and are read first. Directory imports can load other required package metadata on demand through the same bounds. Unrelated JSON, package files and lockfiles do not consume this budget. Relative inheritance supports transitive and array parents within the same bounds. Only UTF-8 text is parsed.
+The dependency analysis budget is 30 seconds, including standalone Git range
+discovery and both snapshots. It is checked between parsing/resolution operations;
+it is not a hard interrupt inside the parser. Tour context reuses its pinned range,
+and its ordinary context generation is outside this budget. Git tree enumeration is
+bounded to 16 MiB. Up to 1,000 diagnostics per snapshot are retained with an omitted
+count. Programmatic callers may lower these limits.
+
+`coverage` reports supported source candidates, indexed/omitted files, unresolved
+edges and whether indexing completed within the supported scope. Configuration,
+parser and scope diagnostics matter even when an endpoint was found. A resolved
+target can itself be outside the indexed subset. Partial graphs produce provisional
+deltas and consumer lists; missing edges never establish independence. Submodules,
+non-JS/TS languages and installed `node_modules` are outside scope.
+
+The delta compares module endpoints, relationship, phase and loading, aligning
+Git-detected renames. Source spelling/location and repeated occurrences alone do
+not constitute new module edges. When a module edge changes, all matching source
+sites appear in the delta. Alias/config retargeting can change dependencies of an
+unchanged file. Consumer lists are one hop and include type-only edges, with phases
+retained so callers can filter them. They are not a transitive impact analysis.
+
+Every source reference contains a commit OID, Git blob OID, repository-relative
+path, UTF-16 half-open range, one-based line/column, and SHA-256 of the selected
+UTF-8 text. Links are local to the repository that generated the report. Equal
+base/head revisions and paths outside the deep-link grammar retain coordinates
+without a link. No source content is embedded in the dependency report itself.
+
+Runtime trace ingestion, resolved symbol/call graphs and visual graph layout are
+later slices. No workload is run to generate this evidence.
+
+The [validation corpus and measured results](../scripts/dependency-benchmark/README.md)
+cover labeled module edges, source evidence, bounded scale and pinned public
+repositories. The historical baseline documents compatibility and metadata gaps; the follow-up validation records their fixes. Complete indexing is not proof that runtime
+loading is valid.

package/docs/evidence-review.md

@@ -0,0 +1,163 @@
+# Pinned evidence and live repair
+
+Evidence Review connects a saved requirement to exact Git source, then offers an
+explicit handoff to Bygone's existing synchronized VS Code editor. The saved
+review stays pinned while you edit. This is an inspection aid: a valid source
+reference, a passing recorded command, and a human inspection are separate facts.
+None is an automatic approval or proof that a requirement is fulfilled.
+
+## Load and inspect
+
+Use **Bygone: Open Evidence Review** in a trusted local VS Code workspace and
+choose a version 2 review JSON file. The selected workspace binds the artifact to
+a local repository. Bygone requires both immutable commits to exist there and
+validates referenced text against Git; the repository label is descriptive, not
+an authenticated remote identity. Dirty files are excluded from the review.
+
+The view shows quoted source material, questions, valid and broken links,
+recorded executions, inspection notes, analysis limits, and changed files with
+no valid evidence link. A linked file can still contain unexplained changes.
+Use **Pinned source** for the exact range or **Pinned file diff** for context.
+Both are read-only. Deleted/missing counterparts remain historical evidence.
+
+The CLI exposes the same inspection and refresh policy:
+
+```sh
+bygone -C /path/to/repo evidence inspect review.json
+bygone -C /path/to/repo evidence import exported-review.json --output imported.json
+bygone -C /path/to/repo evidence inspect imported.json --dependencies dependencies.json
+bygone -C /path/to/repo evidence tour imported.json --output evidence.bygone
+bygone -C /path/to/repo present --tour evidence.bygone
+```
+
+Import validates source references and removes carried inspection decisions.
+The versioned review model is in `src/requirements.ts`. Old exports with only
+branch names or timestamps cannot be imported as pinned evidence. All output
+commands require new files; existing artifacts are never overwritten.
+
+## Edit, return, refresh
+
+**Edit working counterpart** maps the exact cited snapshot/range to the current
+working document. Whole-declaration mapping uses existing Strand JS/TS analysis.
+Identical file content can retain an exact range. Ambiguous mappings, partial
+ranges in changed files, and unsupported syntax fall back to full-file context;
+no match is inferred from a name or reused offset. Git-reported renames preserve before/after paths. An absent working counterpart
+opens read-only historical source instead. **Edit working file** explicitly opens full-file
+context without symbol mapping.
+
+The left side is the cited immutable snapshot; the right side is the live VS Code
+`TextDocument`. The existing version/range-guarded bridge owns edits, dirty state,
+save, undo, and recovery. Staging remains VS Code Git's responsibility. Returning
+with the **Return to Evidence Review** toolbar button or command restores the pinned review panel and
+its scroll position while that panel remains open; a closed panel is recreated.
+Editing or saving does not change its claims. Following's
+**Resume** deliberately leaves the review snapshot and returns to ordinary HEAD
+following.
+
+After committing a repair, choose **Refresh to committed revision**. Supply a
+validated correspondence artifact for old-head → new-head to relocate changed
+whole declarations, or refresh unchanged files only and leave changed evidence
+unresolved. The new head must descend from the captured head; rewritten or unrelated history
+requires a separately imported review. The original PR baseline is preserved. A head delta is not a new
+whole-PR comparison. New comparisons require renewed inspection, even if cited
+bytes match; notes remain visible.
+
+```sh
+bygone evidence refresh review.json --head <new-commit> \
+  --correspondence old-head-to-new-head.json --output refreshed.json
+bygone evidence refresh review.json --head <same-commit> \
+  --requirements edited-review.json --output reworded.json
+bygone evidence tour refreshed.json --output refreshed.bygone
+```
+
+The requirement-only option takes the edited requirement array from a complete
+review document with the same repository/base/head identity; its IDs must remain compatible with existing links/questions.
+Regenerate a current tour after repairs. Keep deliberately historical tours and
+reviews pinned. **Record inspection in new artifact** saves a fingerprint and
+note, not approval, and never overwrites the source artifact.
+
+## Producer boundary
+
+Bygone consumes the version 2 review shape from compatible producers, including
+the PR Reviewer bridge. Producers must capture immutable comparison identities
+and retain the original source quotations in their saved snapshots. A later push
+must not relabel historical evidence.
+
+Unmapped anchors, producer-reported unexplained hunks, overflow counts, and
+unavailable discussion capture are listed as limitations; producer assessments
+remain rationale. Unexplained-change line labels are retained as unvalidated
+producer context, not source anchors. File-level linked coverage does not
+establish coverage of every hunk. Checklists, discussions, publication state,
+and approvals remain in the producing system; they are not Bygone decisions or
+execution records. Exports without immutable capture cannot be imported as pinned
+evidence.
+
+The producer receipt digest identifies the initial exported projection. Its hashing recipe is recorded in the analysis scope: replace that receipt digest with 64 zeroes, serialize sorted keys as compact UTF-8 JSON without ASCII escaping, then SHA-256. It is not authentication or a checksum of later review edits; refresh retains historical provenance.
+
+## Dependency-guided inspection and limits
+
+Load an existing `bygone dependencies` report for exactly the review's merge-base
+and head. Navigation includes reported added/removed module edges, direct
+unchanged consumers, and initialization sites, with phase, loading, and resolution labels.
+Source ranges, content digests, blob IDs, and comparison identities are checked
+against Git. Producer coverage, omissions, diagnostics, and assumptions remain
+visible. Imported summaries must match all inventory identity fields. Validation
+checks referenced file counts and bytes against reported coverage and declared
+limits (up to 16 MiB per snapshot, 32 MiB across both), and applies the declared time budget to local validation/Git reads.
+Records provide only a lower bound on producer input: files without sites and
+resolver-only inputs are not reconstructible from the report, nor is the original
+producer's elapsed time independently verifiable.
+
+This is syntactic module evidence, not a semantic call graph or runtime trace.
+Changing an imported binding within the same module can leave graph edges
+unchanged. New TypeScript syntax/options, malformed package metadata, and input
+budgets can limit resolution. No graph change is never proof of behavioral safety.
+
+Hosts bound JSON/source sizes and refuse oversized or non-text evidence rather
+than silently reporting it as complete. Live editing retains its existing
+128 KiB/5,000-line limit. Remote workspaces and untrusted workspaces are not
+supported by this first host. The web viewer explains when Symbols is unavailable
+because no validated correspondence artifact was supplied.
+
+Keep issue decisions, CI, approval, and merge in their existing systems. A review
+can use ordinary diffs and equivalent source links; a tour is optional. Evidence
+artifacts should be retained only when they help inspect, reproduce, or hand off
+the review, not as a mandatory second task ledger.
+
+## Verification record
+
+Implementation was based on `dda37567` after the dependency validation work
+landed. Local verification on 2026-10-26 covered:
+
+- Bygone's legacy runner and all 503 Node tests, TypeScript checking, ESLint,
+  bundle budgets, VSIX packaging, and npm packaging/dry-run. The staged npm CLI
+  also inspected a real pinned review successfully.
+- Producer interoperability: exported review → Bygone import → validated tour.
+- A fresh Linux ARM64 Lima checkout: 9 evidence handoff checks, 29 SCM checks,
+  and 16 original following checks on each of VS Code 1.74.0 and 1.143.1. These
+  exercise the real Extension Host and Monaco, including dirty text, shared undo,
+  intervening native edits, slice boundaries, index preservation, rename/missing
+  counterparts, explicit refresh, and unsupported-symbol fallback.
+  The evidence suite was repeated after the workflow fixes; the SCM/following
+  results cover the unchanged editing bridges from earlier in this implementation.
+  The final evidence rerun includes switching or closing the review while a real
+  symbol worker is pending; a stale result cannot replace the comparison or its
+  return context. Import rejects inconsistent file and unresolved-edge counters.
+
+To rerun the handoff suite after compiling:
+
+```sh
+BYGONE_EVIDENCE_TEST=1 BYGONE_VSCODE_EXECUTABLE=/path/to/code \
+  xvfb-run -a node scripts/test-following.mjs
+```
+
+A retrospective fixture for merged SCM repair `c7219ed0` validated one quoted
+requirement and two exact implementation/test links, generated a pinned tour,
+and left three other changed files explicitly uncovered. It recorded no test
+execution or approval merely because the linked test exists. The same source
+was inspected through an ordinary diff. The evidence view retains requirement,
+range, and freshness context; no human review-time or comprehension advantage
+was measured. This is a functional comparison, not a usability study.
+
+Not verified here: live producer API/model runs, manual browser visual QA, Windows/macOS Extension Hosts, remote workspaces, or a human paired
+review trial. No release was published by these checks.

package/docs/generating-change-tours.md

@@ -176,3 +176,6 @@ matters. A new scene or file does not inherently mean a new comparison. Close
 by connecting the mechanism back to the promised behavior and stating material
 limits, rather than reciting the chapter titles. Include any remaining checks without adding
 fake code stops. See [the format](change-tour-format.md) for the fields.
+
+For experimental revision-pinned symbol evidence in authoring context and the
+viewer, see [symbol correspondence](correspondence.md).

package/docs/present.md

@@ -289,3 +289,6 @@ revisions or constructed stages; a chapter or scene boundary does not itself
 mean the comparison changed. Intro, chapter, and Conclusion passages fill the
 reading area. Exploring Files restores the prose/code split, and “Return to
 passage” restores the full-height passage.
+
+For experimental revision-pinned symbol evidence in authoring context and the
+viewer, see [symbol correspondence](correspondence.md).

package/docs/product-surface.md

@@ -139,7 +139,8 @@ VS Code's native Search rather than another bundled ripgrep process.
 | --- | --- | --- |
 | `bygone`, paths, `--diff`, `--history`, `--git-diff`, `--read-only`, `review` | Launch Explore sessions | Core launcher; desktop owns writes; `--read-only` is a persisted capability ceiling for that launch |
 | `present` and `present --tour` | Launch Present sessions | Core, read-only presentation |
-| `tour context` | Produce a bounded provider-neutral change dossier | Authoring support, read-only |
+| `tour context` | Produce a bounded provider-neutral change dossier; optional `--dependencies` adds static JS/TS evidence | Node CLI authoring support, read-only |
+| `dependencies` | Compare committed module edges and identify unchanged consumers, with source navigation links | Experimental Node CLI analysis, read-only except explicit output files; no runtime execution |
 | `tour validate`, `compile`, `schema`, and coverage options | Validate exact evidence and build repository-bound manifests | Advanced authoring, read-only except explicit output files |
 | `completion` | Generate shell completions from the shared command specification | Supporting tooling |
 

package/docs/releasing.md

@@ -82,6 +82,17 @@ Related packaging commands:
 
 Before publishing, verify:
 
+### Packaging dependency override
+
+The development toolchain scopes an `@azure/msal-node` 7.1.0 override to
+`@azure/identity`, which is used by `@vscode/vsce`. The version requested by
+Azure Identity is affected by
+[GHSA-xcx6-jx8p-x3h5](https://github.com/advisories/GHSA-xcx6-jx8p-x3h5).
+Remove the override once Azure Identity requests a patched version. Local
+credential construction and VSIX packaging are checked; interactive Azure
+authentication still requires a separate authenticated check before publishing
+through that flow. This dependency is not bundled into the shipped extension.
+
 ## Accounts You Need
 
 You need accounts on three services: