pi-fovea 0.24.0 → 0.26.0

package/README.md

@@ -58,7 +58,7 @@ and test commands in your loop. CI has the final say.
 | `fovea_sketch` | where is everything? | production-first silhouette plus explicit discovery/extraction coverage; test and fixture architecture stays collapsed |
 | `fovea_focus` | what is this? | exact symbols/routes/protocol ids, evidenced relationships, path-gap reasons, suggested reads, scopes, and deterministic `fresh` views |
 | `fovea_dwell` | what else? | widens the current focus, or expires safely when its graph generation changed |
-| `fovea_impact` | what does this touch? | hunk-precise seeds, evidenced review paths, unmet co-change companions, and bounded, revision-aware review memory |
+| `fovea_impact` | what does this touch? | hunk-precise seeds, evidenced impact paths, co-change companions, and conserved diffusion heat |
 | `grep` *(default hybrid)* | graph or text? | bare identifiers, qualified symbols, repo paths, and routes use Fovea; search options and obvious regex retain native grep |
 
 Focus normalizes camelCase and common inflections. An approximate name such as
@@ -66,7 +66,7 @@ Focus normalizes camelCase and common inflections. An approximate name such as
 match returns the nearest symbols plus their locations. Direct graph edges
 carry labels such as caller, callee, route, shared literal, and co-change, plus
 deterministic `strategy` / `rule` / `source` evidence. Every tool result includes
-a coverage ledger; an explicit missing path says whether it is unsupported,
+a coverage report; an explicit missing path says whether it is unsupported,
 ignored, oversized, generated, unreadable, Git-listed but unavailable, beyond
 the file cap, behind a closed nested-repository boundary, or absent. Symbols
 that merely share a file stay collapsed.
@@ -181,8 +181,11 @@ limits accept environment overrides:
 | `FOVEA_SPAWN_CONCURRENCY` | `3` | concurrent ast-grep/git child processes (ast-grep parallelizes parsing inside each process; values above ~4 rarely help) |
 | `FOVEA_MEMORY_HALF_LIFE_HOURS` | `48` | wall-clock half-life of the per-node sync memory (charged cascade warmth) |
 | `FOVEA_IO_CONCURRENCY` | `32` | concurrent file stat/read operations |
+| `FOVEA_GIT_UNTRACKED_CACHE` | enabled | set to `0` to disable the native Git untracked-directory cache requested by freshness probes |
 | `FOVEA_MAX_SUBMODULE_DEPTH` | `4` | recursion cap for nested submodules |
 
+Freshness probes still consult Git on every call; there is no new time-based shortcut. One porcelain-v2 status supplies both HEAD and changes, with a legacy fallback. At a verified worktree root, Fovea requests Git's native untracked-directory cache and omits the redundant dot pathspec that prevents its use. Subroots and Git environment overrides keep their explicit path scope. This can update Git index metadata, but does not change Git configuration files. Set `FOVEA_GIT_UNTRACKED_CACHE=0` to opt out; `GIT_OPTIONAL_LOCKS=0` can also prevent cache updates. Dirty files, new directories, ignore changes, and repository-boundary changes still go through freshness checks.
+
 Files over the size cap keep their place in the model's view of the repo.
 Failed extractions do the same. You find both in `/fovea status` and in tool
 details.
@@ -303,29 +306,21 @@ environment override still turns sync off with:
 FOVEA_TURN_SYNC=off pi
 ```
 
-## Salience and review memory
+## Change impact as heat
 
-`fovea_impact` separates current salience from remembered source exposure.
+`fovea_impact` ranks relevant context under a strict token budget. It does not track inspection or certify feature completeness.
 
-Heat finds what matters now. Seeds come from the diff. Hunk parsing maps each change to the symbols that contain it. One unit of mass goes to each changed file: `0.2` on the file node, `0.8` over the touched symbols in proportion to `sqrt(changed lines)`. Heat then spreads along static edges and along co-change partners, and decays with wall-clock time. Edits that resist symbol-level location fall back to the old file-node seed. New files, deletions, renames, untracked paths, and oversized diffs all take that path.
+Seeds come from the diff. Hunk parsing maps each change to the symbols that contain it. One unit of mass goes to each changed file: `0.2` on the file node, `0.8` over the touched symbols in proportion to `sqrt(changed lines)`. Heat then spreads along static relationships, with historical co-change partners added as decaying seed heat. Edits that resist symbol-level location fall back to the file-node seed. New files, deletions, renames, untracked paths, and oversized diffs all take that path.
 
 Historical co-change is a decaying **heat prior**, never a permanent graph edge. It counts up to 400 first-parent integration boundaries: merge net changes count once, not again through their constituent commits. Explicit `fixup!`/`squash!` followups join only uniquely resolved older subjects in that window. Time, author, shared issue numbers, and unlabeled "forgot this" do not group work. Boundaries are not proof of a semantic feature (release merges can mix work). Aggregates above 24 tracked files emit no pairs but retain directional touch counts; two distinct retained units are needed for a pair, three for expectations. Raw history caching includes shallow-state identity; recency still applies at use. Focus, sketch, and the structural diffusion operator remain unchanged.
 
-Review memory is **hysteretic**, not conserved work: like a resettable thermal history indicator, its state remembers an earlier event after the heat changes. Each suggested file has independent current `salience` and exposure state: `unseen`, `seen`, or `stale`. Repeated impact calls replace salience rather than accumulating invocation-count debt. Cooling and disclosure do not acknowledge a read. This memory neither proves correctness nor gates completion or starts turns.
-
-A successful local `read` records only returned source windows at a content SHA-1. `seen` means source exposure, not whole-file inspection or understanding. The host checks matching text and stable before/after snapshots; requested limits are not treated as returned lines. Failed, diagnostic-only, rewritten, or racing reads earn no acknowledgment. Snapshot capture is bounded to 1 MiB per retained file, with at most 16 merged windows per revision (`windowsOmitted` reports loss). Reads before a file enters review memory are not tracked. Thus `unread` means **no matching read observed while retained**, not proof that nobody read it.
-
-A changed content hash makes previous exposure `stale`, including comment-only, shell, Fabric, and editor changes when the graph next refreshes. Reverting a file does not erase the stale marker; another matching read does. This is file-local exposure history, not a sound dependency-based verification system. Semantic surprise and turn steering retain their existing separate rules.
+Impact details describe the current cascade:
 
-Memory holds at most 512 files, preferring current salience. `evicted` counts retained entries actually forgotten; `omitted` counts new candidates not retained in the latest cascade. Repeated omitted candidates do not accumulate debt. A disjoint seed set starts a new review epoch and reports the discarded totals as `review.previous`; overlapping/growing changes retain their epoch. Reset, reload, and session replacement clear this advisory memory rather than persist it.
+- `warmedMass`, `warmedReasons`, and `warmedEvidence`: per-file heat and the causal channels supporting the ranking.
+- `expectedButUnchanged`: likely companions inferred from directional co-change history, not required edits.
+- `conservedMass`: degree-corrected random-walk heat, reported separately from the raw scale used by sync.
 
-Impact details carry three distinct signals:
-
-- `expectedButUnchanged`: likely missing companions inferred from directional co-change history. These are review suggestions, not required edits.
-- `conservedMass`: degree-corrected random-walk heat; mathematical conservation of diffusion mass is unrelated to review accounting. Sync keeps its raw scale.
-- `review`: retained entries with salience, reasons, revision, exposure windows, `unseen`/`seen`/`stale` totals, epoch, and retention-loss information. This replaces the former `obligations` and top-level `epoch` fields; the verification transition has been removed rather than relabeled.
-
-The budgeted trailer says `review memory · 3 unread · 1 stale · 2 seen (windows only)` and names the strongest pending suggestions. Evictions and prior-epoch loss appear there when budget permits and always in structured details. Cold pending entries remain accessible in the full impact overflow list. Zero unread or stale entries means no pending *retained review suggestions*, never feature completion. The CLI has no host read events; inspection tracking belongs to the in-session extension.
+Repeated impact calls do not accumulate pending work. The result and its overflow list describe the current seeds, graph, and historical heat prior; a seedless query does not carry earlier suggestions forward. Focus and dwell retain only their own progressive-disclosure context, while graph refresh and turn sync keep navigation current after source changes.
 
 `docs/heat-diffusion.md` has the full mechanics.
 
@@ -350,10 +345,7 @@ effective while its global default is being edited.
 | `tools.grepMode` | `"augment"` | `"augment"\u0020keeps native grep and appends a Fovea graph section to symbol-query results (works with `pi.grep` inside fabric_exec too); `"replace"` keeps the legacy takeover where bare symbol queries navigate the graph instead of returning lines; `"off"` is native grep only. The legacy boolean `tools.replaceGrep` still parses (`true`\u2192`"replace"`, `false`\u2192`"off"`) and loses to an explicit `grepMode`. |
 | `tools.grepAugmentBudget` | `512` | token cap for the appended graph section |
 
-Budgets cap the rendered view, not the map: whenever sketch, focus, dwell, or
-impact truncate results for budget, the full list spills to
-`$TMPDIR/pi-fovea-<op>-<hash>.txt` and the footer names the path — read or grep
-the file for the remainder. `fovea_dwell` remains the semantic widen.
+Budgets cap the rendered view, not the map. Focus and dwell keep every eligible candidate recoverable beyond both the token budget and the 400-candidate display cap. Their `details.lit` counts the full eligible set, while `details.candidateOmitted` counts display-cap exclusions. Whenever a view truncates, the full list spills to `$TMPDIR/pi-fovea-<op>-<hash>.txt` if writable, and the footer names the path. Read or grep that artifact for the remainder; a failed write never produces a false path. Scope filters, already-disclosed nodes, and nodes below the heat cutoff are not added to overflow. `fovea_dwell` remains the semantic widen.
 
 ## How routes are found
 
@@ -472,6 +464,12 @@ filesystem walk reports an unknown omission count instead of inventing one.
 `/fovea status` and `fovea status` use this same ledger rather than comparing
 unlike tracked and supported file counts.
 
+Import diagnostics live in `details.coverage.imports`: captured sites are classified as resolved, possible, or unresolved, with bounded examples, cap counts, and languages lacking import readers. Unresolved includes external packages and unmodeled resolution—not necessarily broken code. JS/TS literal `import()` and `require()` targets resolve normally. A relative one-hole expression such as `import('./plugins/' + name + '.js')` or ``require(`./plugins/${name}.js`)`` can connect up to 32 matching in-scope files through explicitly **possible** import edges. A family scans at most 4,096 files; exceeding either limit emits no partial family and reports the cap. Unknown expressions remain unresolved. Possible imports do not become exact call or test edges.
+
+This is a finite candidate approximation, not a bound on runtime values: variables can contain traversal segments or name generated, external, or excluded modules. Conductance encodes a prior, not a calibrated probability. Selected files have file nodes by construction; relationship completeness, future edits, runtime behavior, and business requirements do not follow from that membership.
+
+The [39-repository paired corpus](docs/coverage-corpus.md) checks this boundary without repository execution or useful co-change history. It distinguishes ordinary diffused probes from uniform-field display-cap stress, records unsupported/excluded files, and retains failures rather than replacing repositories. The dynamic-family observation is limited to one Vue build utility; regression fixtures separately exercise runtime plugin loading and capped/unknown cases.
+
 ## How it works
 
 The repo compiles to a typed graph. Your question becomes a source vector $s$
@@ -522,6 +520,12 @@ special case of this field. [docs/heat-diffusion.md](docs/heat-diffusion.md)
 walks through conductance tiers, specificity bridges, hub gravity, and inferred
 regions.
 
+## Snapshot substrate API
+
+`pi-fovea/substrate` exposes a versioned, session-free graph and heat interface for
+consumers such as pi-contour. It assembles caller-supplied immutable facts without
+discovering files or reading a live worktree. See [docs/substrate.md](docs/substrate.md).
+
 ## Languages
 
 Full symbol and call extraction: **TypeScript, TSX, JavaScript, Python, Go, and Rust**.
@@ -533,11 +537,15 @@ Exact contract topology: **Protocol Buffers (`.proto`) and GraphQL (`.graphql`,
 
 ```sh
 bun install
-bun run check        # typecheck + full vitest suite
+bun run check        # typecheck + full vitest suite + knip
 bun run bench        # rate–distortion and refresh bench against ../pi-fabric
 bun run bench tests/fixtures/mini  # self-contained smoke run
 ```
 
+The [warm-path performance report](docs/performance.md) compares the coverage-complete implementation with the optimized version. `bun run corpus:performance <coverage-work> <before-source> <after-source> [rounds]` runs alternating, isolated comparisons with a shared extraction snapshot, independent Git indexes, and exact graph, focus/dwell/sketch, and overflow-content checks. It does not trade fewer candidates or weaker freshness checks for speed. For Node, run `NODE_OPTIONS='--import tsx' node scripts/performance-corpus.mjs ...`; development dependencies are required.
+
+Warm matching derives query terms once and caches normalized symbol names by weak node identity, checking renames before reuse. Focus builds only the heat orders currently needed; dwell appends missing orders without replacing its existing basis. No new kernel or review state is introduced. Independent cold extraction can select different literal-join locations when capture order varies, so this paired benchmark deliberately makes no cold-extraction speedup claim.
+
 The developer benchmark gates timings on semantic equivalence: cold versus
 cached builds, and forced refresh versus clean rebuild after unchanged,
 location-only, semantic, added-file, and deleted-file scenarios in disposable