Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs: drop stale `docs/dev/cache-staleness.md` (#2710)
Maximilian Roos12e2ee25638c
diff --git a/docs/dev/cache-staleness.md b/docs/dev/cache-staleness.mddeleted file mode 100644index 9d7903913..000000000--- a/docs/dev/cache-staleness.md+++ /dev/null@@ -1,359 +0,0 @@-# Eliminating ref-keyed cache staleness--## Background--`Repository::RepoCache` (in `src/git/repository/mod.rs`) holds per-command-caches that survive any number of git operations on the same `Repository`-instance. Several of those caches are keyed on **ref names** (e.g. `"main"`,-`"refs/heads/main"`, `"HEAD"`). Ref names are not stable — their SHAs change-when wt itself updates a ref mid-command (`wt merge`'s `update-ref`,-`commit-tree` + `update-ref` in `worktree/push.rs`, future write paths). After-such a write, ref-keyed entries return the pre-write SHA and any computation-downstream of that SHA is silently wrong.--PR #2507 fixed exactly this for one call site: `Repository::is_ancestor` was-reading stale SHAs out of `commit_shas`, so `integration_reason` misclassified-a just-merged branch as unmerged. The fix added a local helper-(`ref_is_ancestor`) that bypasses the cache. It works, but every other ref-name-read through `rev_parse_commit` after a write has the same latent bug.--We want to eliminate the bug class **structurally**, not by remembering to-invalidate. Invalidation discipline scales linearly with new write call sites;-structural elimination scales with zero.--## Inventory: caches keyed on ref names today--Read `RepoCache` (`src/git/repository/mod.rs:204-316`) and treat anything-keyed by `String` ref name as a staleness vector. Concretely:--| Cache field | Key | Used by | Stale risk after a ref update? |-| --------------------------------- | ---------------------------- | ------------------------------------------- | ------------------------------- |-| `commit_shas` | ref name | `rev_parse_commit` → all SHA-keyed caches | **Yes** — primary bug source |-| `tree_shas` | tree spec (e.g. `…^{tree}`) | `rev_parse_tree` | **Yes** |-| `resolved_refs` | short name → full ref | `resolve_preferring_branch` | No (refs/heads/X doesn't move) |-| `ahead_behind` | `(base ref, head ref)` | `wt list`'s ahead/behind, upstream task | **Yes** if either ref updates |-| `effective_integration_targets` | local target ref name | `effective_integration_target` | **Yes** (depends on local tip) |-| `integration_reasons` | `(branch, target)` ref names | `integration_reason` | **Yes** (composite of above) |-| `head_shas` | worktree path | `WorkingTree::head_sha` | **Yes** (HEAD moves on commit) |-| `local_branches` inventory | n/a (one-shot scan) | every multi-branch op | **Yes** (frozen view) |--Caches keyed entirely by **SHA** (`merge_base`, `diff_stats`, the persistent-on-disk `sha_cache::*`) are structurally safe — a SHA addresses immutable-content. The risk is only at the **ref-name → SHA boundary**.--## Where ref writes happen today--`grep -rn "update-ref\|update_ref" src/`:--- `src/commands/worktree/push.rs:385` — `update-ref` on the merge target.-- `src/commands/merge.rs:286` (calls into push.rs) — `wt merge` flow.-- `src/git/repository/working_tree.rs:563` — `update-ref` for stash/branch ops.-- Any `git commit`, `git rebase`, or hook subprocess can update a local ref- too. We don't `update-ref` those ourselves but the underlying refs move.--The `wt merge` flow is the canonical example: rebase → `update-ref` target →-`finish_after_merge` → `compute_integration_reason` → reads stale `main` SHA.--## Goals & constraints (recap)--- **No invalidation logic.** "Call `cache.clear_ref(name)` after every write"- is the failure mode, not the solution.-- **Performance still matters.** `rev_parse_commit` is consulted by- `is_ancestor`, `merge_base`, `merge_integration_probe`, `branch_diff_stats`,- `has_added_changes`. In `wt list` with 100 worktrees these run hundreds of- times. Today, the `local_branches` for-each-ref pre-population dodges most- rev-parse subprocesses for branch refs.-- **Per-command lifetime.** `Repository` lives for one CLI command, so- cross-command persistence is irrelevant for in-memory caches.-- **`wt list` is read-only.** No ref writes happen during it; the staleness- bug class doesn't manifest. Whatever we choose must not regress its- performance.-- **Mutate-then-read commands are rare** (`wt merge`, `wt remove`, future- `wt rebase`?). Performance there is bounded by the git operations- themselves.--## Options--### Option 1 — Cache only by SHA at the boundary--**What it changes structurally.** Drop `commit_shas` and `tree_shas`. Public-API still takes ref names but resolves them locally with no cache. Each-ref-name → SHA conversion spawns one `git rev-parse` per call. SHA-keyed-caches (in-memory `merge_base`, on-disk `sha_cache::*`) keep working as today.--**Where the work lands.** `rev_parse_commit`/`rev_parse_tree` in-`integration.rs:509-547` lose their `DashMap::entry` wrappers. The priming in-`branches.rs:155-166` goes away. Direct callers of those helpers-(`is_ancestor`, `has_added_changes`, `has_merge_conflicts`, `branch_diff_stats`,-`merge_integration_probe`, `has_merge_conflicts_by_tree`, `would_merge_add_to_target`)-keep their signatures but pay one extra subprocess per ref per call.--**Performance impact.** For `wt list` with N worktrees and ~5 SHA-keyed ops-per row: roughly 10×N additional `git rev-parse` subprocesses (2 ref → SHA-conversions × 5 ops). At ~3-5ms each that is **300-500 ms regression on a-100-worktree repo** — same order as the entire current `wt list` runtime-budget. Mutate-then-read commands gain a handful of subprocesses; negligible.--**What it does NOT solve.** `effective_integration_targets`,-`integration_reasons`, `ahead_behind`, `head_shas`. These are keyed on refs-but their *values* are derived through ref-relative operations (upstream-relationships, ahead/behind counts), so they aren't pure functions of SHAs.-You'd still need a separate decision for each one.--**Migration cost.** Low surface area (~60 LOC) but sizable performance loss-on the read-only hot path.--### Option 2 — Two-tier API: `is_ancestor(refs)` uncached, `is_ancestor_by_sha` cached--**What it changes structurally.** Every public op exists in two forms:--```rust-// Public, ref-taking, no SHA cache:-pub fn is_ancestor(&self, base: &str, head: &str) -> Result<bool> { ... }-// Internal, SHA-taking, cached:-fn is_ancestor_by_sha(&self, base: &Sha, head: &Sha) -> Result<bool> { ... }-```--The ref-taking form runs git directly (`merge-base --is-ancestor` accepts ref-names natively, as does `rev-parse a b` for `same_commit`/`trees_match`).-Callers that want cache hits must explicitly hold SHAs.--**Where the work lands.** Same files as Option 1, but with twice as many-public methods. Each task in `commands/list/collect/tasks.rs` switches from-`repo.is_ancestor(branch, target)` to first resolving SHAs through a-snapshot (see Option 5) and then calling `is_ancestor_by_sha`.--**Performance impact.** Same as Option 1 if hot-path callers stay on the-ref-taking form. Same as today if they migrate to the SHA-taking form.-This option *enables* the fast path; it doesn't force it.--**What it does NOT solve.** Same residual risks as Option 1 — composite-caches (`integration_reasons`, `effective_integration_targets`, `ahead_behind`)-need separate treatment.--**Migration cost.** Medium. Each cached op gains a sibling. `wt list` task-code changes to thread SHAs through (~20 call sites).--### Option 3 — Type-level distinction (`Sha` newtype)--**What it changes structurally.** Introduce-`pub struct Sha(String)` (or `Sha([u8; 20])`) constructed only via-`Repository::resolve(&str) -> Sha` (uncached) or via the `for-each-ref` scan-(produces `Sha`s tied to a snapshot). Cached methods take `&Sha` and refuse-`&str`. Compiler enforces "you must resolve before caching."--**Where the work lands.** `Sha` propagates through `BranchRef`, `LocalBranch`,-task contexts in `commands/list/collect/`, every diff/integration helper.-Tests that hardcode SHA strings need conversion.--**Performance impact.** Same as Option 2 — the type system says nothing about-when you spawn rev-parse, only that you've named the conversion.--**What it does NOT solve.** Composite caches still need explicit decisions.-A `Sha` newtype prevents storing `String` ref-name keys in SHA-keyed caches,-but does not make `effective_integration_target` (whose result depends on the-upstream relationship at lookup time, not on the SHA) safe.--**Migration cost.** High. Newtype propagation reaches a lot of call sites-(`BranchRef.commit_sha: String` becomes `Sha`, every test fixture, every-JSON serialization path). The type-level guarantee is real but the surface-area touched is wide.--### Option 4 — Delete the in-memory ref-keyed caches outright--**What it changes structurally.** Drop `commit_shas`, `tree_shas`,-`effective_integration_targets`, `integration_reasons`, `ahead_behind`,-`head_shas`. Stop priming. Every cached op spawns its underlying git-command(s) every call. The persistent on-disk `sha_cache::*` survives because-its keys are SHAs.--**Where the work lands.** Delete fields and entry-block wrappers across-`integration.rs`, `diff.rs`, `working_tree.rs`. Remove the priming loop in-`branches.rs:155-166`.--**Performance impact.** Severe. `wt list` with 100 worktrees today calls-`is_ancestor`, `has_added_changes`, `merge_integration_probe`, etc. relying-on cached SHAs and (for `ahead_behind`) cached counts batched in-`batch_ahead_behind`. Without those caches you're spawning thousands of-subprocesses per command. Likely 5-10× regression on `wt list`.--**What it does NOT solve.** Removes the bug entirely, but at unacceptable-cost. Listing it for completeness — also useful as a baseline reminder that-the cache is load-bearing for the read-only hot path.--**Migration cost.** Low surface area. High user-visible impact.--### Option 5 — Resolve-once-up-front (`RefSnapshot`)--**What it changes structurally.** At command entry, one explicit-`let snapshot = repo.snapshot()?;` call performs the `for-each-ref` scan and-produces an immutable `RefSnapshot`. The snapshot holds ref name → SHA for-every local + remote branch, plus HEAD, plus any other refs of interest.-Cached SHA-keyed ops take `&Sha` (or `&str` plus `&RefSnapshot`). Repository-itself drops ambient ref-keyed caches.--After a ref-mutating operation, the caller produces a new snapshot. Old-snapshots remain valid as historical views — by name, you can see they-represent the pre-write state. This is the same shape `local_branches`-already has (a `OnceCell<LocalBranchInventory>` populated by one-for-each-ref), promoted to first-class status with explicit lifetime.--```rust-let snap = repo.snapshot()?; // implicit "ref state right now"-let target_sha = snap.resolve(target)?; // never spawns git-let branch_sha = snap.resolve(branch)?;-let integrated = repo.is_ancestor_by_sha(&branch_sha, &target_sha)?;--// ... wt merge writes the target ref ...--let snap2 = repo.snapshot()?; // explicit "after the write"-let target_sha = snap2.resolve(target)?;-// integration check against the post-write target — naturally fresh-```--**Where the work lands.** New `RefSnapshot` type (~100 LOC). Public ops in-`integration.rs`/`diff.rs` either gain `_by_sha` variants (Option 2 style)-or accept `&RefSnapshot` directly. `commands/list/collect/` builds one-snapshot during pre-skeleton, threads it through tasks instead of (or in-addition to) `Arc<RepoCache>`. `wt merge`'s `finish_after_merge` builds a-fresh snapshot post-`update-ref` and uses it for the integration check —-the post-write call gets the post-write state by construction.--**Performance impact.** Roughly neutral to positive. Today's-`local_branches` scan + `commit_shas` priming already does this work; the-proposal just names it. Subsequent SHA lookups become plain `HashMap::get`-on a frozen view (no `DashMap` shard contention). `wt list` gets one-deterministic scan up-front instead of lazy `OnceCell::get_or_try_init`-race; all parallel tasks read from the immutable snapshot. `wt merge` pays-for one extra `for-each-ref` after the ref update — ~5-15 ms.--**What it does NOT solve.** The discipline of "after a write, take a new-snapshot" is still required. The improvement is that:-1. Snapshots are *named*, so the contract is visible at every call site.-2. Forgetting to re-snapshot reads pre-write state explicitly, not- "from a cache that is supposed to be transparent."-3. The bug surface compresses to a small number of write boundaries- instead of every ref-name accessor in the codebase.--`effective_integration_targets`, `integration_reasons`, and `ahead_behind`-become functions of `(snapshot, ref pair)` — keyed by the snapshot's SHAs-they're derived from. Stale-by-construction is no longer possible: a-snapshot is internally consistent.--**Migration cost.** Medium-high. `RefSnapshot` has to be threaded through-hot paths. But the threading replaces existing `Arc<RepoCache>` usage in-`tasks.rs`, so it's a refactor, not net-new plumbing.--### Option 6 — "Take a fresh `Repository::at(...)` after writes"--**What it changes structurally.** Document and rely on the existing pattern:-`Repository::at(...)` builds a brand-new `RepoCache`. Code that reads after-its own writes constructs a fresh Repository.--**Where the work lands.** `finish_after_merge`, `handle_no_ff_merge`, every-future write call site — gain `let repo = Repository::at(...)?;` after the-write.--**Performance impact.** A second Repository pays for a duplicate-`for-each-ref` scan on the next inventory access. ~5-15 ms.--**What it does NOT solve.** This is **invalidation by another name**. It's-exactly the discipline-based approach the goals exclude — easy to forget,-new write call sites are latent bugs. List it only because the codebase-already documents this pattern for `list_worktrees`. Not a recommendation.--**Migration cost.** Trivial in code, infinite in vigilance.--## Recommendation--**Go with Option 5 (`RefSnapshot`), positioned as a refinement of the-existing `local_branches` inventory.**--The argument:--1. **The shape already exists.** `OnceCell<LocalBranchInventory>` plus- `commit_shas` priming via `for-each-ref` is a snapshot in everything but- name. Today its frozen-ness is implicit and undocumented; staleness leaks- through `commit_shas` because callers don't know the cache is a snapshot.- Promoting it to a first-class `RefSnapshot` type makes the contract- explicit at every call site.--2. **It's the only option that addresses composite caches structurally.**- Options 1-3 fix `commit_shas` but leave `effective_integration_targets`,- `integration_reasons`, and `ahead_behind` exposed. Option 5 makes all of- them derived properties of an immutable snapshot, so they're internally- consistent by construction.--3. **It preserves the read-only hot path.** `wt list` builds one snapshot- pre-skeleton and reads from it for the rest of the command. Performance- is neutral or marginally better than today's `DashMap` priming.--4. **It localizes the discipline.** Today, every ref-name accessor in the- codebase is a potential staleness vector. After Option 5, only the- write boundaries (`finish_after_merge`, `handle_no_ff_merge`,- `working_tree.rs:563`) need to think about freshness. They take a new- snapshot. That's the smallest possible surface for the discipline that- we still need.--5. **The `is_ancestor` workaround in PR #2507 dissolves.** With Option 5,- `compute_integration_reason_uncached` simply takes the post-write- snapshot — no ad-hoc `ref_is_ancestor` helper, no comments warning- future readers about cache bypass.--### Concrete shape--```rust-// New: src/git/repository/snapshot.rs-pub struct RefSnapshot {- // Frozen at construction. Local + remote branches + HEAD + a few specials.- refs: HashMap<String, Sha>,- // Derived in one pass alongside the for-each-ref scan:- upstream_of: HashMap<String, String>,- ahead_behind: HashMap<(String, String), (usize, usize)>,-}--impl RefSnapshot {- pub fn resolve(&self, name: &str) -> anyhow::Result<&Sha> { ... }- pub fn upstream_of(&self, branch: &str) -> Option<&str> { ... }- pub fn ahead_behind(&self, base: &str, head: &str) -> Option<(usize, usize)> { ... }-}--impl Repository {- /// Snapshot the current ref state: one for-each-ref + ahead-behind batch.- /// Cheap to call; no in-memory cache, by design.- pub fn snapshot(&self) -> anyhow::Result<RefSnapshot> { ... }-}-```--`Repository`'s ambient ref-keyed fields (`commit_shas`, `tree_shas`,-`effective_integration_targets`, `integration_reasons`, `ahead_behind`,-`head_shas`) all go away. The persistent `sha_cache::*` keeps its SHA keys.-Public ops gain `_by_sha` variants for cached fast paths; ref-taking variants-exist only as thin shims that resolve uncached and call the SHA form (so a-caller that doesn't need a snapshot still works, just spawns one rev-parse).--### What we accept--- One up-front `for-each-ref` per snapshot (~5-15 ms). Already the dominant- pattern.-- Discipline at write boundaries — but the boundaries are *the writes- themselves*, not every read.-- A type & lifetime story for `RefSnapshot` to thread through tasks. This- is the bulk of the migration work.--### What we don't do--- Don't add invalidation hooks.-- Don't keep `commit_shas` "with a TODO".-- Don't bake compatibility with a parallel ambient-cache path. Cut over.--## Open questions for implementation (not answered here)--- Should `RefSnapshot` be `Arc`-wrapped for parallel task fan-out, or is- cheap clone-by-value enough? (Rough size: ~200 branches × 60 bytes ≈ 12 KB.)-- Does the snapshot need to include tag refs? Audit the call sites.-- For `wt merge`, does `finish_after_merge` build the post-write snapshot- itself, or does the caller pass it in?-- Does `Sha` become a newtype, or stays a `String` typedef inside- `RefSnapshot`? The newtype upside (Option 3's static guarantee) compounds- with Option 5; the migration cost is the question.