llmnav 0.8.0 → 0.9.1

package/CHANGELOG.md

@@ -6,6 +6,31 @@ The npm package follows Semantic Versioning. The `llmnav/N` source protocol is v
 
 ## [Unreleased]
 
+## [0.9.1] — 2026-09-07
+
+### Fixed
+
+* Explain unsupported or disallowed hard-link lock publication, preserve its filesystem error, and verify installed host show, bounded context, and refresh operations.
+* Prevent inherited npm `allow-scripts` environment policy from breaking isolated package installation smoke checks; installation lifecycle scripts remain disabled.
+* Synchronize the public package-version constant with 0.9.1 and check both npm manifests in the normal test suite.
+* Publish complete generation lock records atomically, clean up failed preparation, and explain repair of unreadable legacy locks.
+* Hold the generation lock throughout search and registry snapshot reads.
+* Apply context edge limits when falling back to semantic relations without a usable graph.
+
+### Performance
+
+* Distribute search postings to card-range shards in one pass while preserving byte-identical manifests and artifacts.
+* Prepare card lookups, normalized IDs and aliases, and graph validation once per session snapshot; detach query and show results to protect cached state from caller mutation.
+* Measure fresh-process session startup, graph-aware query and context latency, and refresh separately, with result parity checks against direct navigation APIs.
+* Reuse graph adjacency and traversal ordering within project sessions; refresh rebuilds that state while direct query APIs continue to accept mutable graph inputs.
+* Count removed graph partitions with keyed membership instead of scanning all current partitions for each previous key.
+
+## [0.9.0] — 2026-08-15
+
+### Added
+
+* Added `llmnav explain <file>` and `explainProjectFile` to report one file's navigation cards, module coverage, audit score evidence, reviewed disposition, and bounded next action without modifying source.
+
 ## [0.8.0] — 2026-08-15
 
 ### Added

package/README.md

@@ -47,7 +47,7 @@ npx llmnav init --agents all --package-scripts
 
 Initialization is explicit. LLMNav never edits a consumer repository from an npm `postinstall` script. Use `--agents none` when only the machine-readable control directory is desired.
 
-Before writing cards, run `npx llmnav audit`. It ranks likely architectural boundaries and explains each score. The command never edits source and remains advisory unless `--fail-on high`, `medium`, or `low` is selected. Review the candidates: a high score is evidence to inspect a file, not permission to generate semantic meaning automatically. For a reviewed false positive or implementation detail, add its exact path and a concrete reason to `audit.dispositions`; stale decisions remain visible instead of becoming permanent hidden ignores.
+Before writing cards, run `npx llmnav audit`. It ranks likely architectural boundaries and explains each score. Use `npx llmnav explain <file>` when you need to know why one file is carded, covered by another module card, ranked as a candidate, suppressed by a reviewed disposition, or omitted from the candidate list. Neither command edits source. Review the evidence: a high score is a reason to inspect a file, not permission to generate semantic meaning automatically. For a reviewed false positive or implementation detail, add its exact path and a concrete reason to `audit.dispositions`; stale decisions remain visible instead of becoming permanent hidden ignores.
 
 ## Add the first card
 
@@ -172,6 +172,7 @@ Line-comment cards require an explicit terminator and work with `//`, `#`, and `
 | --- | --- |
 | `llmnav init` | Create configuration, registry, schemas, agent instructions, and the initial cache |
 | `llmnav audit` | Rank unannotated architectural boundary candidates, with compact or file-backed output |
+| `llmnav explain` | Explain one file's card coverage, audit score, disposition, and recommended next action |
 | `llmnav check` | Validate cards, relations, coverage rules, and registry state |
 | `llmnav format` | Rewrite safe cards into canonical order and spacing |
 | `llmnav generate` | Incrementally compile and transactionally commit generated artifacts |

package/docs/agent-integration.md

@@ -49,7 +49,7 @@ The generated instruction tells an agent to:
 10. Run format, check, and generation after semantic changes.
 11. Fall back to broad search when no credible card is returned.
 
-When a host supports structured tool calls, `llmnav tools --json` returns four stable provider-neutral definitions in fixed order: `llmnav_query`, `llmnav_show`, `llmnav_context`, and `llmnav_check`. The schemas reject unknown fields and omit the repository root so the trusted host binds scope outside model-generated input.
+When a host supports structured tool calls, `llmnav tools --json` returns five stable provider-neutral definitions in fixed order: `llmnav_query`, `llmnav_show`, `llmnav_context`, `llmnav_check`, and `llmnav_explain`. The new definition is appended so the existing stable tool prefix keeps its order. The schemas reject unknown fields and omit the repository root so the trusted host binds scope outside model-generated input.
 
 The protocol does not order an agent to trust a card over source code. It uses the card to choose what source to inspect.
 
@@ -99,7 +99,7 @@ Suggested contract:
 ```json
 {
   "schemaVersion": 1,
-  "operations": ["llmnav_query", "llmnav_show", "llmnav_context", "llmnav_check"]
+  "operations": ["llmnav_query", "llmnav_show", "llmnav_context", "llmnav_check", "llmnav_explain"]
 }
 ```
 

package/docs/api.md

@@ -65,7 +65,7 @@ Attached symbol declarations expose generated `language`, `exported`, `visibilit
 ## Audit annotation coverage
 
 ```js
-import { auditHasFindings, auditProject } from "llmnav";
+import { auditHasFindings, auditProject, explainProjectFile } from "llmnav";
 
 const result = await auditProject(process.cwd());
 for (const candidate of result.candidates) {
@@ -73,9 +73,12 @@ for (const candidate of result.candidates) {
 }
 
 if (auditHasFindings(result, "high")) process.exitCode = 1;
+
+const explanation = await explainProjectFile(process.cwd(), "src/runtime.ts");
+console.log(explanation.status, explanation.candidate?.score, explanation.recommendation.action);
 ```
 
-`auditProject` is read-only and returns schemaVersion 1 data with repository-relative paths and deterministic ordering. Candidate signals are structural heuristics, not generated semantic meaning. Exact reviewed decisions from `audit.dispositions` are returned separately with `suppressed` or `stale` status; `auditHasFindings` considers only active candidates. Consumers should review high and medium candidates before adding a card and should never turn the suggested coverage rule into automatic source annotation.
+`auditProject` is read-only and returns schemaVersion 1 data with repository-relative paths and deterministic ordering. Candidate signals are structural heuristics, not generated semantic meaning. Exact reviewed decisions from `audit.dispositions` are returned separately with `suppressed` or `stale` status; `auditHasFindings` considers only active candidates. `explainProjectFile` applies the same analysis to one path, preserving candidate score evidence and package-level coverage without mutating source. Consumers should review high and medium candidates before adding a card and should never turn a suggested coverage rule or recommendation into automatic source annotation.
 
 ## Generate incrementally and transactionally
 
@@ -299,6 +302,10 @@ await session.refresh(); // after generation or checkout changes
 
 `query`, `show`, and `context` reuse the loaded index, postings, graph, lexicon, and registry. `refresh()` replaces the complete snapshot; it never mutates one layer in place. The `check` operation still scans current source and does not use session data.
 
+Sessions prepare graph adjacency and traversal order once per snapshot for reuse by `query` and `context`. Refreshing prepares a new graph, and obsolete prepared state can be garbage-collected with the previous snapshot. Direct `queryIndex` and `queryPreparedIndex` calls do not cache caller-owned graphs, so in-place changes to supplied edges remain visible on the next call.
+
+Session queries also reuse card lookup tables, normalized IDs and aliases, and graph validation. ID substring and phrase matching still scan all documents to preserve ranking. Session `query` and `show` return detached results: caller edits cannot invalidate the private prepared snapshot. These tables are rebuilt on `refresh()` and retained only with that snapshot.
+
 The typed `llmnav/examples/provider-neutral-host.mjs` export composes these APIs into a trusted-root closure. It exposes tool definitions, base and module-selected prompt partitions, one snapshot-backed operation executor, and an explicit refresh method without importing a model SDK.
 
 `buildPromptPrefixBundle(input)` constructs ordered package, repository, and module partitions with normalized newlines, SHA-256 content hashes, estimated token counts, and explicit cache-boundary hints. `renderPromptPrefixBundle` serializes it deterministically. `loadPromptPrefixBundle(root)` accepts only a schema-compatible artifact whose exact bytes match `manifest.json`.

package/docs/architecture.md

@@ -197,6 +197,12 @@ Generation never mutates the live cache file by file. It builds a complete repla
 
 The complete source scan and cache commit are serialized by `.llmnav/generation.lock`. The lock records a process and opaque owner ID. A reader waits for a live owner to finish and only then evaluates recovery, while an abandoned lock from a dead process can be removed without granting another process authority over an active journal.
 
+Readers hold that lock until all snapshot artifacts, including the ID registry for sessions, show, and context, have been read. Lock ownership is published with an exclusive hard link to a fully written, synced, and closed candidate file in the same directory; the filesystem must support hard links. Failed preparation cannot leave an empty authoritative lock. Unused candidate files confer no ownership. An unreadable lock left by an older version is not automatically stolen: stop all LLMNav processes, remove `.llmnav/generation.lock`, then retry. A valid abandoned transaction is still recovered normally.
+
+If hard-link publication fails with `ENOSYS`, `ENOTSUP`, `EOPNOTSUPP`, `EPERM`, or `EXDEV`, the error explains the filesystem and permission requirements and retains the original cause. The unpublished candidate is cleaned up; the lock is not downgraded to a non-atomic write. `EPERM` can indicate a permission restriction, not only a filesystem capability gap.
+
+When no compatible graph is available, context falls back to semantic relations and still limits traversal with `maxEdges`, including zero. The token budget separately bounds rendered output.
+
 ```text
 write every staged artifact
 verify exact staged bytes

package/docs/benchmarking.md

@@ -63,6 +63,55 @@ LLMNAV_BENCH_FILES=500 LLMNAV_BENCH_QUERY_RUNS=5 npm run benchmark:v0.2
 
 Published repository results use the defaults. The report states that each query starts a fresh Node.js process and that the operating-system filesystem cache is not flushed. That distinction prevents a warm page cache from being mislabeled as cold disk I/O.
 
+## Graph-aware session lifecycle
+
+`npm run benchmark:navigation` generates a temporary 100-file repository with 1,000 cards and three outgoing semantic relations per card. A fresh worker process measures initial session loading, the first query, 50 repeated queries, 50 bounded graph-context requests, and refresh with unchanged source. Three direct `queryProject` calls provide a filesystem-loading comparison. The report includes medians, p95, memory, operation counters, fixture sizes, and result digests.
+
+The operating-system filesystem cache is not flushed. Module import and process launch costs are excluded from `initialSessionMs` but included in the total `workerWallMs`, which also includes reference checks. Fixture generation is outside both measurements. Query scores and reasons must match the direct graph-aware index path; context must include the requested root and graph evidence within its edge and token limits. CI uses a 100-card fixture to validate these contracts without imposing a machine-specific timing threshold.
+
+
+### Local baseline before session metadata preparation
+
+Measured on 2026-09-07 with runtime source based on `5b0d837`: Windows x64, Node v24.18.0, AMD Ryzen 5 7430U with Radeon Graphics. This is one local run with an unflushed filesystem cache, not a production latency guarantee.
+
+| Phase | Median or single sample (ms) | p95 (ms) |
+| --- | ---: | ---: |
+| Initial session load | 141.335 | — |
+| First query | 11.113 | — |
+| Repeated session query (50) | 3.859 | 7.833 |
+| Repeated session context (50) | 2.870 | 5.484 |
+| Refresh unchanged source | 70.303 | — |
+| Direct query with disk loading (3) | 90.443 | 120.859 |
+
+All 50 query rankings, scores and reasons matched the direct index path. All 50 contexts met the graph and token bounds. Query work still included 50,000 ID scans and 50,000 phrase-document scans; caching adjacency does not eliminate those passes.
+
+Result digests for comparison with subsequent optimization:
+
+```text
+query   d7545f3781f705eb2fdb5c7deb14004c7d74f1b9fc81fb21314e00f3f276e272
+context 051db2dc2b802eca7a5b3a04a08c38b447ba95659ebc2a8eef2e9b6fb0e1207b
+```
+
+### Local session metadata result
+
+On the same fixture and environment, one local run after session metadata preparation measured query median/p95 at 2.883/5.796 ms, with identical query and context digests above. Across 50 queries, ID normalizations, lookup-table builds, and graph validations were all zero; ID and phrase scans remain 50,000 each. The optimization does not narrow substring candidates or change ranking.
+
+Initial loading was 159.667 ms, first query 21.485 ms, refresh 114.610 ms, context median/p95 3.617/8.979 ms, and direct-query median 102.542 ms. Preparation shifts work to loading/refresh and result detachment adds copying. These single-run timings include local load variation; they establish neither a startup improvement nor a production speed guarantee.
+
+## Card-range shard generation
+
+`npm run benchmark:shards` compares one-pass distribution with the pre-optimization per-shard filtering implementation on 2,000 cards and 44,286 postings. It checks exact manifest and artifact bytes. A separate regression instruments posting reads and requires one visit per posting, independent of shard count; the reference visits every posting once per shard.
+
+One Windows x64 / Node v24.18.0 run on 2026-09-07, including serialization but excluding index construction:
+
+| Shard count | Reference (ms) | One pass (ms) |
+| --- | ---: | ---: |
+| 100 | 503.116 | 169.912 |
+| 20 | 247.831 | 170.843 |
+| 4 | 157.325 | 191.673 |
+
+These are single in-process samples, with the reference first, not production guarantees. Few shards can be slower because distribution adds bookkeeping. Posting distribution changes from shard-count multiplied scans to one pass, but serialization still costs the output size. Partitioned posting pairs temporarily occupy memory alongside serialized shards; completed partitions are released as serialization progresses. This benchmark does not measure peak memory. Sharding remains disabled by default.
+
 ## Measurement integrity
 
 A benchmark result is accepted only after these checks pass:
@@ -79,6 +128,8 @@ Wall-clock speed is reported exactly as measured. It is not used to invent a spe
 
 ## Repository search evaluation
 
+The [historical navigation replay pilot](navigation-replay.md) compares six fixed task paraphrases with regex file discovery. It reports candidate ranks and explicit unmeasured agent metrics; it is not a substitute for end-to-end trials.
+
 Add real task descriptions to `.llmnav/eval/queries.jsonl`.
 
 ```jsonl

package/docs/cli.md

@@ -41,6 +41,16 @@ The command never modifies source, configuration, registries, or generated cache
 
 JSON output uses schemaVersion 1, repository-relative paths, deterministic ordering, explainable `reasons` and `signals`, and a path-specific `suggestedCoverageRule` for high and medium candidates. Reviewed `audit.dispositions` appear separately as `suppressed` or `stale`; only active candidates participate in `--fail-on`. Stale reasons are `file-not-scanned`, `already-carded`, or `not-a-candidate`. `--summary` omits candidate and disposition details but retains their counters. `--output <path>` writes the selected report inside the repository and emits only a compact confirmation envelope to stdout; escaping paths and symbolic-link traversal are rejected. Suggestions require human or agent review: LLMNav cannot infer a durable role, ownership boundary, invariant, or semantic ID from structure alone.
 
+## `llmnav explain`
+
+```sh
+llmnav explain <file> [--json]
+```
+
+Explains one repository-relative or repository-contained absolute file path without modifying the repository. The result distinguishes active candidates, reviewed suppressions, direct cards, package-level module coverage, files with no ranked audit signal, files excluded from the scanned source set, and stale dispositions. Candidate results retain the audit's representative path, priority, score, reasons, signals, and suggested coverage rule; this matters for Go packages, where the requested file and representative candidate can differ.
+
+The recommendation is deliberately bounded. It may ask for card review, disposition review, stale-disposition cleanup, or no action, but it never invents a semantic ID or writes a source comment. A file outside the repository or an invalid positional argument exits with status 2. A valid path that is not in the scanned source set returns its explanation and exits with status 1.
+
 ## `llmnav check`
 
 ```sh

package/docs/navigation-replay.md

@@ -0,0 +1,44 @@
+# Historical navigation replay pilot
+
+## Result
+
+On 2026-09-08, six curated historical changes were replayed against runtime commit `d30d80015ea10ea43a0875bc329669fa4019a457`. Both methods included the expected source file in their first five candidates for all six cases. LLMNav ranked four expected files first; the regex baseline placed one first in alphabetical file order. These are different ordering policies, not an agent success-rate comparison.
+
+| Historical task | Source change | Expected source | Regex rank / candidates | LLMNav rank / candidates |
+| --- | --- | --- | ---: | ---: |
+| Filesystem capability required by generation locking | `5b0d837` | `src/transaction.js` | 2 / 2 | 2 / 20 |
+| Context still follows edges at a zero edge limit | `34f56a6` | `src/search.js` | 4 / 4 | 2 / 23 |
+| Explain suppressed annotation-audit candidates | `592849f` | `src/audit.js` | 3 / 6 | 1 / 17 |
+| Resolve a Go module import to its package | `fcd40cb` | `src/module-resolution.js` | 3 / 3 | 1 / 23 |
+| Upgrade generated formats without partial cache state | `839ab1c` | `src/migration.js` | 5 / 6 | 1 / 25 |
+| Remove repeated posting scans during sharding | `d30d800` | `src/search-shards.js` | 1 / 1 | 1 / 23 |
+
+Candidate counts include the complete positive-result list, not just the first five displayed paths. LLMNav returns more broad matches, while known technical keywords can narrow regex discovery much further. The two non-first LLMNav results put `src/audit.js` ahead of the locking implementation and `src/graph.js` ahead of the context-limit implementation. No query, expected target, annotation, or rank weight was tuned after this run.
+
+## Reproduce
+
+From the Git repository, run:
+
+```sh
+node benchmarks/navigation-replay.js
+```
+
+The script performs no model calls, network requests, source edits, or cache generation. It requires an existing generated LLMNav index and the referenced Git history. Expected targets must both exist in current source and occur in the cited historical change. The output includes source, harness, and case hashes so a rerun can distinguish changed inputs from changed ranking. Refresh the index through the normal generation workflow before comparing a later source revision.
+
+Both output scopes contain 37 tracked JavaScript files under `src/` and `bin/`. The baseline performs one fixed case-insensitive line-regex search per case and sorts matching paths alphabetically. LLMNav performs one query, preserves score order, deduplicates paths, and restricts output to that same source scope. Its scoring still uses the complete repository index before filtering. Source annotations remain visible to the baseline. The script refuses a truncated 100-card result instead of treating hidden hits as misses.
+
+Input identities for the recorded run:
+
+```text
+harness 706834dc4a0faf0b5111f11dc854d929f5c84a4b6757542bd3a98041d0b47f33
+cases   c23e467540d03544a68a4ffabc9cb4c91c2ecea87f655f6e3b55257adf404364
+source  2a8e5f8e2bff1f6236bd2117998d134a44cacb728d1667a5f3fb747a7fff8c7b
+```
+
+## Evidence boundary and decision
+
+The cases are author-curated English paraphrases of known changes, not verbatim user requests, representative traffic, Korean-language coverage, or a sealed holdout. They run on already corrected current source, not the pre-fix repository. The author knew the expected paths while constructing both symptom queries and regexes. This is a diagnostic retrieval pilot, not a claim that LLMNav outperforms a developer adaptively using `rg`.
+
+Each method performs one search per case, but actual agent tool calls, files opened, uncached tokens, elapsed task time, edit correctness, and task completion are **unmeasured** and reported as `null`, not inferred from candidate rank. No full agent trace was captured. The pilot therefore does not complete the end-to-end evaluation described in [benchmarking](benchmarking.md).
+
+The existing changes were delivered and their Windows/Linux CI passed before this pilot. No runtime optimization is added on the strength of these results: they do not establish that `show` or `context` latency blocks development work. Further session lookup caching and shard-memory work remain deferred. The existing ranking and substring-search behavior are unchanged.

package/docs/publishing.md

@@ -1,18 +1,41 @@
 # Publishing `llmnav` to npm
 
-The repository is release-ready except for owner-specific metadata and npm account configuration.
+Maintainers publish this repository through the existing tag-triggered GitHub Actions workflow. Initial repository and npm account setup belongs to the separate bootstrap section below; it is not part of every release.
 
-## 1. Claim the names
+## Routine release
 
-Create the GitHub repository named `llmnav`, then check the npm registry immediately before the first release:
+1. Confirm the intended version agrees across `package.json`, `package-lock.json`, `src/spec.js`, and the changelog. Review the exact diff and keep unrelated changes out of the release.
+2. Check the remote tag and npm version before creating anything. Authentication or network errors mean unknown state, not an unpublished version. Never move an existing release tag or overwrite a published version.
+3. Validate the exact payload using the commands below. Reuse passing checks only while their relevant inputs remain unchanged.
+4. Commit and push the release changes to `main`. Require successful Windows/Linux and package CI for that exact commit, not a previous commit.
+5. Create an annotated version tag on the verified commit and push only that tag. The workflow handles npm publication and GitHub Release creation.
+6. Verify the tag commit, release workflow, npm version and integrity, provenance, GitHub Release, and an installation of the published package. Publication success and branch CI are separate checks.
 
 ```sh
-npm view llmnav
+npm run check
+npm run release:check
+npm run smoke:pack
+npm pack --dry-run
+```
+
+If dependencies are missing or the lockfile changed, install them through the approved dependency workflow before these checks. The package intentionally includes the CLI, source API, type declarations, schema, templates, documentation, the typed provider-neutral host example, README, changelog, roadmap, and license. Tests, benchmarks, and development scripts remain in GitHub rather than the installed package.
+
+After choosing the version, replace the placeholder in both tag commands:
+
+```sh
+git tag -a vX.Y.Z -m "llmnav vX.Y.Z"
+git push origin refs/tags/vX.Y.Z
 ```
 
-An `E404` means no public package is visible through the registry you queried at that moment. It is not a reservation. The name remains claimable by someone else until publication succeeds.
+The workflow rejects a tag that does not match `package.json` or the protected `origin/main` lineage. If the version already exists in npm, it succeeds only when the registry integrity matches the tagged payload. A mismatch fails closed and requires a new version, not a forced tag. GitHub Release creation runs only after publication or matching-integrity verification succeeds.
+
+If publication is interrupted, inspect the existing tag, registry artifact, and workflow result before retrying. Preserve the version and tag when they already identify the intended artifact; do not assume a failed workflow means nothing was published.
+
+## One-time bootstrap for a new repository or publisher
+
+### Claim names and set owner metadata
 
-## 2. Replace release metadata
+Before a first publication, create the GitHub repository and check npm name availability. An `E404` means no public package is visible at that moment, not that the name is reserved. Do not repeat owner replacement for routine releases of this configured repository.
 
 Update only the owner-specific URLs in `package.json` and `.github/ISSUE_TEMPLATE/config.yml`.
 Do not run a repository-wide replacement: the release checker and doctor intentionally keep the literal `OWNER` sentinel in source code.
@@ -29,27 +52,15 @@ Then replace `OWNER` only in `.github/ISSUE_TEMPLATE/config.yml` and run:
 npm run release:check
 ```
 
-## 3. Configure npm authentication
+### Configure npm authentication
 
 The supplied release workflow uses GitHub's OIDC token through npm Trusted Publishers. The public GitHub source repository enables provenance in both `package.json` and the workflow, and the release check fails if either surface disables it. The same tag workflow creates an idempotent GitHub Release only after the npm registry check or publication succeeds.
 
-The workflow references a GitHub environment named `npm`. Create that environment for release protection, or remove the `environment` line when no environment gate is desired.
+The workflow references a GitHub environment named `npm`. Configure that environment and its protection rules as part of bootstrap. Do not remove an existing approval gate merely to unblock a release.
 
 A classic or granular access token can be used for a manual first publication. Do not commit `.npmrc` credentials or an npm token. npm may still require browser-backed two-factor authentication.
 
-## 4. Validate the exact package payload
-
-```sh
-npm ci
-npm run check
-npm run release:check
-npm run smoke:pack
-npm pack --dry-run
-```
-
-Inspect the tarball list. The package intentionally includes the CLI, source API, type declarations, schema, templates, documentation, the typed provider-neutral host example, README, changelog, roadmap, and license. Tests, benchmark harnesses, and development scripts remain in GitHub but are not installed into consumer projects. `npm run smoke:pack` verifies the exact tarball and example export in a clean temporary project.
-
-## 5. Publish the first release
+### Manual first publication, only when required
 
 Manual publication:
 
@@ -58,22 +69,17 @@ npm login
 npm publish --provenance --access public
 ```
 
-Automated publication:
-
-```sh
-git tag vX.Y.Z
-git push origin vX.Y.Z
-```
+## Verify a published version from a clean directory
 
-The release workflow rejects a tag that does not match `package.json`. If the exact version is already present in npm, the workflow succeeds only when the registry tarball integrity matches the tagged package; a mismatched package fails closed. It then reuses an existing GitHub Release for the tag or creates one with generated release notes. Registry, GitHub API, and Release creation errors other than an expected missing Release fail the workflow.
+Use an explicit published version instead of the moving default tag. The temporary project must be outside the source repository. Do not commit installed files or credentials.
 
-## 6. Verify from a clean directory
+From a source checkout, `npm run smoke:pack -- --published=X.Y.Z` runs the existing CLI/API/host assertions against that exact npm version in a temporary project with lifecycle scripts disabled. Without the option, it tests a locally packed tarball instead.
 
 ```sh
 mkdir llmnav-smoke
 cd llmnav-smoke
 npm init -y
-npm install --save-dev llmnav
+npm install --save-dev --ignore-scripts llmnav@X.Y.Z
 npx llmnav --version
 npx llmnav init --agents all --package-scripts
 npx llmnav doctor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llmnav",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "A deterministic semantic navigation layer for LLM coding agents.",
   "type": "module",
   "bin": {
@@ -48,6 +48,8 @@
     "release:tag": "node ./scripts/verify-tag.js",
     "test:performance": "node --test tests/performance.test.js",
     "benchmark:v0.2": "node ./benchmarks/run-v0.2.js",
+    "benchmark:navigation": "node ./benchmarks/navigation.js",
+    "benchmark:shards": "node ./benchmarks/search-shards.js",
     "smoke:pack": "node ./scripts/pack-smoke.js"
   },
   "keywords": [

package/src/agent-protocol.js

@@ -6,6 +6,7 @@ excludes=provider SDK transport|repository discovery|source mutation
 search=agent tool schema|provider neutral tools|tool dispatcher|agent operation protocol
 rel=workflow>llmnav.search.query
 rel=workflow>llmnav.rules.validate
+rel=workflow>llmnav.audit.coverage
 stability=contract
 */
 
@@ -14,6 +15,7 @@ import { scanProject } from "./project.js";
 import { buildContext, queryProject, showProjectCard } from "./search.js";
 import { countDiagnostics, validateProject } from "./validator.js";
 import { getAgentToolDefinitions } from "./agent-tools.js";
+import { explainProjectFile } from "./audit.js";
 
 export { AGENT_TOOL_SCHEMA_VERSION, getAgentToolDefinitions } from "./agent-tools.js";
 export const AGENT_OPERATION_SCHEMA_VERSION = 1;
@@ -25,6 +27,7 @@ const OPERATIONS = new Map([
   ["llmnav_show", "show"],
   ["llmnav_context", "context"],
   ["llmnav_check", "check"],
+  ["llmnav_explain", "explain"],
 ]);
 
 export async function executeAgentOperation(root, name, input = {}, options = {}) {
@@ -58,6 +61,9 @@ export async function executeAgentOperation(root, name, input = {}, options = {}
         ? options.session.context(input.id.trim(), contextOptions)
         : await buildContext(root, input.id.trim(), contextOptions));
     }
+    if (operation === "explain") {
+      return success(operation, await explainProjectFile(root, input.file.trim()));
+    }
     const project = await scanProject(root, { paths: input.paths ?? [] });
     const graphInputs = await loadGraphInputs(root, project.config);
     const diagnostics = [...validateProject(project), ...graphInputs.diagnostics].sort(compareDiagnostics);

package/src/agent-tools.js

@@ -32,6 +32,9 @@ const DEFINITIONS = [
       default: [],
     },
   }),
+  tool("llmnav_explain", "Explain one file's card coverage, audit evidence, disposition, and recommended next action.", {
+    file: stringProperty("Repository-relative or repository-contained absolute file path."),
+  }, ["file"]),
 ];
 
 export function getAgentToolDefinitions() {

package/src/agents.js

@@ -32,6 +32,8 @@ Do not add hand-maintained \`calls\`, \`imports\`, \`references\`, \`implements\
 
 After initialization and whenever public entrypoints, commands, routes, schemas, migrations, or high fan-in modules change, run \`npm exec -- llmnav audit\`. Review high and medium candidates; never add cards automatically. Add a module card only after confirming a durable responsibility, then encode the accepted boundary in a path-specific \`coverageRules\` entry and add a representative retrieval query. When a reviewed candidate has no durable navigation responsibility, record its exact path and a concrete reason in \`audit.dispositions\`; never use a glob or broad directory suppression.
 
+When deciding whether one specific file needs a card, run \`npm exec -- llmnav explain <file>\`. Use its coverage, score, and disposition evidence to guide review, but never turn its recommendation into automatic source annotation.
+
 After semantic changes, run \`npm exec -- llmnav format\`, \`npm exec -- llmnav check\`, and \`npm exec -- llmnav generate\`. Use broad text search only when LLMNav returns no credible candidate.
 ${END}`;
 

package/src/audit.js

@@ -1,9 +1,9 @@
 /* llmnav/1 module
 id=llmnav.audit.coverage
 role=Identify high-value source modules that lack semantic navigation boundaries without modifying source.
-owns=annotation coverage audit|candidate prioritization|coverage rule suggestions
+owns=annotation coverage audit|candidate prioritization|file explanation|coverage rule suggestions
 excludes=automatic source annotation|semantic role generation
-search=llmnav audit|missing module cards|coverage suggestions
+search=llmnav audit|missing module cards|explain missing annotation|coverage suggestions
 invariant=Audit output is deterministic, repository-relative, and advisory unless an explicit fail threshold is selected.
 rel=workflow>llmnav.project.scan
 stability=contract
@@ -17,6 +17,7 @@ import { compareText, readJsonSafe, toPosix } from "./util.js";
 
 export const AUDIT_SCHEMA_VERSION = 1;
 export const AUDIT_PRIORITIES = Object.freeze(["high", "medium", "low"]);
+export const FILE_EXPLANATION_SCHEMA_VERSION = 1;
 
 const SOURCE_EXTENSIONS = Object.freeze([
   ".astro", ".c", ".cc", ".cjs", ".cpp", ".cs", ".cts", ".dart", ".go", ".h", ".hpp", ".java",
@@ -28,6 +29,65 @@ const NON_PRODUCTION_PATH_PATTERN = /(?:^|\/)(?:__tests__|benchmarks?|fixtures?|
 const LARGE_SOURCE_BYTES = 12_000;
 
 export async function auditProject(root) {
+  return (await analyzeAuditProject(root)).result;
+}
+
+export async function explainProjectFile(root, inputPath) {
+  const file = normalizeExplanationPath(root, inputPath);
+  const analysis = await analyzeAuditProject(root);
+  const { project, fileByPath, candidates, result } = analysis;
+  const moduleKey = fileByPath.has(file) ? moduleKeyForFile(file) : null;
+  const navigationCards = project.records
+    .filter((record) => toPosix(record.relativePath) === file)
+    .map((record) => ({ id: record.card.id, scope: record.card.scope, path: file }))
+    .sort((left, right) => compareText(left.id, right.id));
+  const coverageCards = moduleKey === null ? [] : project.records
+    .filter((record) => {
+      const cardPath = toPosix(record.relativePath);
+      if (record.card.scope === "file") return cardPath === file;
+      return record.card.scope === "module" && moduleKeyForFile(cardPath) === moduleKey;
+    })
+    .map((record) => ({ id: record.card.id, scope: record.card.scope, path: toPosix(record.relativePath) }))
+    .sort((left, right) => compareText(left.id, right.id));
+  const candidate = moduleKey === null ? null : candidates.find((item) => moduleKeyForFile(item.path) === moduleKey) ?? null;
+  const dispositionPath = candidate?.path ?? file;
+  const disposition = result.dispositions.find((item) => item.path === dispositionPath) ??
+    result.dispositions.find((item) => item.path === file) ?? null;
+
+  if (disposition?.status === "stale") {
+    return buildFileExplanation(result.repositoryId, file, moduleKey, "stale-disposition", navigationCards, coverageCards, candidate, disposition, [
+      `stale-disposition:${disposition.staleReason}`,
+    ], "remove-or-review-disposition", "Remove or update the stale exact-path disposition after reviewing the current file state.");
+  }
+  if (!fileByPath.has(file)) {
+    return buildFileExplanation(result.repositoryId, file, null, "not-scanned", [], [], null, disposition, ["file-not-scanned"],
+      "check-scan-configuration", "Check that the file exists under a source root and is not excluded by extension, directory, or file rules.");
+  }
+  if (coverageCards.length > 0) {
+    const status = coverageCards.some((card) => card.path === file) ? "carded" : "covered";
+    return buildFileExplanation(result.repositoryId, file, moduleKey, status, navigationCards, coverageCards, null, disposition,
+      [status === "carded" ? "file-has-coverage-card" : "module-covered-by-card"],
+      "keep-current-coverage", "No additional file or module card is needed unless this file gains a separate durable responsibility.");
+  }
+  if (candidate && disposition?.status === "suppressed") {
+    return buildFileExplanation(result.repositoryId, file, moduleKey, "suppressed", navigationCards, coverageCards, candidate, disposition,
+      ["reviewed-exact-path-disposition", ...candidate.reasons], "keep-or-review-disposition",
+      "Keep the disposition while its reason remains true; remove it if the file gains a durable navigation responsibility.");
+  }
+  if (candidate) {
+    const action = candidate.priority === "low" ? "review-or-disposition" : "review-card";
+    const message = candidate.priority === "low"
+      ? "Review the low-priority signal, but do not add a card unless the file owns a durable navigation responsibility."
+      : "Review the candidate and either add one durable card with exact coverage or record an exact-path disposition with a concrete reason.";
+    return buildFileExplanation(result.repositoryId, file, moduleKey, "candidate", navigationCards, coverageCards, candidate, null,
+      candidate.reasons, action, message);
+  }
+  const reasons = /\.d\.[cm]?ts$/u.test(file) ? ["declaration-file"] : ["no-ranked-audit-signal"];
+  return buildFileExplanation(result.repositoryId, file, moduleKey, "not-candidate", navigationCards, coverageCards, null, disposition, reasons,
+    "no-card-needed", "Do not add a card solely for coverage; revisit only if the file gains a durable responsibility or stronger structural signals.");
+}
+
+async function analyzeAuditProject(root) {
   const project = await scanProject(root);
   const fileByPath = new Map(
     project.fileRecords.map((record) => [toPosix(record.relativePath), record]),
@@ -197,13 +257,41 @@ export async function auditProject(root) {
     suppressedCandidates: dispositions.filter((disposition) => disposition.status === "suppressed").length,
     staleDispositions: dispositions.filter((disposition) => disposition.status === "stale").length,
   };
-  return {
+  const result = {
     schemaVersion: AUDIT_SCHEMA_VERSION,
     repositoryId: project.config.repositoryId,
     summary,
     candidates: activeCandidates,
     dispositions,
   };
+  return { project, fileByPath, candidates, result };
+}
+
+function normalizeExplanationPath(root, inputPath) {
+  if (typeof inputPath !== "string" || inputPath.trim() === "") throw new TypeError("explain requires one file path.");
+  const rootPath = path.resolve(root);
+  const absolutePath = path.resolve(rootPath, inputPath);
+  const relativePath = path.relative(rootPath, absolutePath);
+  if (relativePath === "" || relativePath === ".." || relativePath.startsWith(`..${path.sep}`) || path.isAbsolute(relativePath)) {
+    throw new RangeError("explain path must name one file inside the repository root.");
+  }
+  return toPosix(relativePath);
+}
+
+function buildFileExplanation(repositoryId, file, moduleKey, status, navigationCards, coverageCards, candidate, disposition, reasons, action, message) {
+  return {
+    schemaVersion: FILE_EXPLANATION_SCHEMA_VERSION,
+    repositoryId,
+    path: file,
+    moduleKey,
+    status,
+    navigationCards,
+    coverageCards,
+    candidate,
+    disposition,
+    reasons,
+    recommendation: { action, message },
+  };
 }
 
 function classifyStaleDisposition(file, fileByPath, exactCardPaths, coveredModules) {

package/src/cli.js

@@ -38,7 +38,7 @@ import { renderGraphNode } from "./graph.js";
 import { getAgentToolDefinitions } from "./agent-protocol.js";
 import { loadPromptPrefixBundle } from "./prompt-bundle.js";
 import { diagnosticsToEditor, getEditorIntegration } from "./editor.js";
-import { AUDIT_PRIORITIES, auditHasFindings, auditProject } from "./audit.js";
+import { AUDIT_PRIORITIES, auditHasFindings, auditProject, explainProjectFile } from "./audit.js";
 import { migrateProject } from "./migration.js";
 
 const VALUE_OPTIONS = new Set(["--root", "--format", "--top", "--depth", "--budget", "--max-edges", "--agents", "--file", "--fail-on", "--output"]);
@@ -56,6 +56,7 @@ const COMMAND_OPTIONS = Object.freeze({
   doctor: new Set(["--root", "--json"]),
   migrate: new Set(["--check", "--write", "--root", "--json"]),
   audit: new Set(["--root", "--json", "--summary", "--fail-on", "--output"]),
+  explain: new Set(["--root", "--json"]),
   spec: new Set(["--root", "--json"]),
   tools: new Set(["--json"]),
   bundle: new Set(["--root", "--json"]),
@@ -106,6 +107,8 @@ export async function runCli(argv) {
       return runMigrate(root, args, json);
     case "audit":
       return runAudit(root, args, json);
+    case "explain":
+      return runExplain(root, args, json);
     case "spec":
       return runSpec(json);
     case "bundle":
@@ -364,6 +367,44 @@ async function runAudit(root, args, json) {
   return auditHasFindings(result, failOn) ? 1 : 0;
 }
 
+async function runExplain(root, args, json) {
+  const files = getPositionals(args);
+  if (files.length !== 1) throw usageError("explain requires exactly one file path.");
+  let result;
+  try {
+    result = await explainProjectFile(root, files[0]);
+  } catch (error) {
+    if ((error instanceof TypeError || error instanceof RangeError) && /^explain (?:requires|path)/u.test(error.message)) {
+      throw usageError(error.message);
+    }
+    throw error;
+  }
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(`file ${result.path}`);
+    console.log(`status ${result.status}`);
+    if (result.moduleKey) console.log(`module ${result.moduleKey}`);
+    for (const card of result.navigationCards) console.log(`card ${card.scope} @${card.id} ${card.path}`);
+    for (const card of result.coverageCards) {
+      if (!result.navigationCards.some((item) => item.id === card.id && item.path === card.path)) {
+        console.log(`coverage ${card.scope} @${card.id} ${card.path}`);
+      }
+    }
+    if (result.candidate) {
+      console.log(`candidate ${result.candidate.priority} ${result.candidate.path} score=${result.candidate.score}`);
+      console.log(`why ${result.candidate.reasons.join(",")}`);
+      const signals = Object.entries(result.candidate.signals)
+        .filter(([, value]) => Array.isArray(value) ? value.length > 0 : Boolean(value))
+        .map(([name, value]) => `${name}=${Array.isArray(value) ? value.join("|") : value}`);
+      if (signals.length > 0) console.log(`signals ${signals.join(",")}`);
+    }
+    if (result.disposition) console.log(`disposition ${result.disposition.status}: ${result.disposition.reason}`);
+    console.log(`next ${result.recommendation.action}: ${result.recommendation.message}`);
+  }
+  return result.status === "not-scanned" ? 1 : 0;
+}
+
 function runSpec(json) {
   const spec = {
     specVersion: SPEC_VERSION,
@@ -522,6 +563,7 @@ Usage
   llmnav doctor
   llmnav migrate [--check|--write]
   llmnav audit [--summary] [--output path] [--fail-on none|high|medium|low]
+  llmnav explain <file>
   llmnav spec
   llmnav tools [--json]
   llmnav bundle [--json]

package/src/graph.js

@@ -79,6 +79,7 @@ export function buildRepositoryGraphIncremental(project, index, previousState =
   }
 
   partitions.sort((left, right) => compareText(left.key, right.key));
+  const partitionKeys = new Set(partitions.map((partition) => partition.key));
   const nodes = new Map();
   const edges = new Map();
   for (const partition of partitions) {
@@ -115,7 +116,7 @@ export function buildRepositoryGraphIncremental(project, index, previousState =
       totalPartitions: partitions.length,
       reusedPartitions,
       rebuiltPartitions,
-      removedPartitions: [...previousPartitions.keys()].filter((key) => !partitions.some((item) => item.key === key)).length,
+      removedPartitions: [...previousPartitions.keys()].filter((key) => !partitionKeys.has(key)).length,
     },
   };
 }

package/src/index.d.ts

@@ -3,6 +3,7 @@ export type LlmnavStability = "architecture" | "contract" | "implementation";
 export type DiagnosticSeverity = "error" | "warning" | "info";
 export type AuditPriority = "high" | "medium" | "low";
 export type AuditDispositionStaleReason = "file-not-scanned" | "already-carded" | "not-a-candidate";
+export type FileExplanationStatus = "candidate" | "suppressed" | "carded" | "covered" | "not-candidate" | "not-scanned" | "stale-disposition";
 
 export interface LlmnavCard {
   scope: LlmnavScope;
@@ -119,6 +120,23 @@ export interface AuditResult {
   >;
 }
 
+export interface FileExplanationResult {
+  schemaVersion: 1;
+  repositoryId: string;
+  path: string;
+  moduleKey: string | null;
+  status: FileExplanationStatus;
+  navigationCards: Array<{ id: string; scope: LlmnavScope; path: string }>;
+  coverageCards: Array<{ id: string; scope: "file" | "module"; path: string }>;
+  candidate: AuditCandidate | null;
+  disposition: AuditResult["dispositions"][number] | null;
+  reasons: string[];
+  recommendation: {
+    action: "review-card" | "review-or-disposition" | "keep-or-review-disposition" | "keep-current-coverage" | "no-card-needed" | "check-scan-configuration" | "remove-or-review-disposition";
+    message: string;
+  };
+}
+
 export interface IndexedLocation {
   path: string;
   startLine: number;
@@ -213,6 +231,9 @@ export interface SearchMetrics {
   phraseDocumentsScanned?: number;
   idDocumentsScanned?: number;
   graphEdgesVisited?: number;
+  idNormalizations?: number;
+  lookupBuilds?: number;
+  graphValidations?: number;
 }
 
 export interface SearchResult {
@@ -226,7 +247,7 @@ export interface SearchResult {
 
 export interface ProjectSession {
   root: string;
-  query(query: string, options?: { top?: number }): SearchResult[];
+  query(query: string, options?: { top?: number; metrics?: SearchMetrics }): SearchResult[];
   show(id: string): { card: IndexedCard | null; node: GraphNode | null; resolvedFrom: unknown };
   context(id: string, options?: { depth?: number; budget?: number; maxEdges?: number }): { id: string; depth: number; budget: number; maxEdges: number; included: string[]; includedEdges: string[]; text: string };
   refresh(): Promise<ProjectSession>;
@@ -297,7 +318,7 @@ export interface LlmnavConfig {
 
 export interface AgentToolDefinition {
   schemaVersion: 1;
-  name: "llmnav_query" | "llmnav_show" | "llmnav_context" | "llmnav_check";
+  name: "llmnav_query" | "llmnav_show" | "llmnav_context" | "llmnav_check" | "llmnav_explain";
   description: string;
   inputSchema: {
     type: "object";
@@ -309,7 +330,7 @@ export interface AgentToolDefinition {
 
 export interface AgentOperationResult<T = unknown> {
   schemaVersion: 1;
-  operation: "query" | "show" | "context" | "check" | "unknown";
+  operation: "query" | "show" | "context" | "check" | "explain" | "unknown";
   ok: boolean;
   data: T | null;
   error: { code: string; message: string } | null;
@@ -621,6 +642,7 @@ export interface EvaluationResult {
 export const AGENT_PROTOCOL: string;
 export const AUDIT_PRIORITIES: readonly AuditPriority[];
 export const AUDIT_SCHEMA_VERSION: 1;
+export const FILE_EXPLANATION_SCHEMA_VERSION: 1;
 export const AGENT_OPERATION_SCHEMA_VERSION: 1;
 export const AGENT_TOOL_SCHEMA_VERSION: 1;
 export const BOUNDARY_KINDS: readonly DetectedBoundary["kind"][];
@@ -698,6 +720,7 @@ export function loadConfig(root: string): Promise<{ config: LlmnavConfig; config
 export function validateConfig(config: LlmnavConfig, configPath?: string): void;
 export function auditProject(root: string): Promise<AuditResult>;
 export function auditHasFindings(result: AuditResult, minimumPriority?: AuditPriority | "none"): boolean;
+export function explainProjectFile(root: string, file: string): Promise<FileExplanationResult>;
 export function findAttachedDeclaration(source: string, block: LlmnavBlock, filePath: string): Declaration | null;
 export function extractImports(source: string, filePath: string): string[];
 export function doctorProject(root: string): Promise<{ ok: boolean; checks: Array<{ name: string; ok: boolean; message: string }> }>;

package/src/index.js

@@ -14,7 +14,14 @@ export {
 } from "./prompt-bundle.js";
 export { compareCardIndexes, describeAffectedBoundaries, describeAffectedCatalogs } from "./changes.js";
 export { loadConfig, validateConfig } from "./config.js";
-export { AUDIT_PRIORITIES, AUDIT_SCHEMA_VERSION, auditHasFindings, auditProject } from "./audit.js";
+export {
+  AUDIT_PRIORITIES,
+  AUDIT_SCHEMA_VERSION,
+  FILE_EXPLANATION_SCHEMA_VERSION,
+  auditHasFindings,
+  auditProject,
+  explainProjectFile,
+} from "./audit.js";
 export { BOUNDARY_KINDS, detectBoundaries } from "./boundaries.js";
 export {
   diagnosticsToEditor,

package/src/search-shards.js

@@ -24,20 +24,26 @@ export function buildSearchShards(index, searchIndex, shardSize) {
   const cardsById = new Map(index.cards.map((card) => [card.id, card]));
   const shards = new Map();
   const records = [];
+  const partitions = Array.from({ length: Math.ceil(searchIndex.cardIds.length / shardSize) }, () => ({ tokens: [], postings: [] }));
+  for (const [tokenIndex, token] of searchIndex.tokens.entries()) {
+    const selectedByShard = new Map();
+    for (const [cardIndex, vector] of searchIndex.postings[tokenIndex] ?? []) {
+      if (!(cardIndex >= 0 && cardIndex < searchIndex.cardIds.length)) continue;
+      const ordinal = Math.floor(cardIndex / shardSize);
+      const selected = selectedByShard.get(ordinal) ?? [];
+      selected.push([cardIndex - ordinal * shardSize, vector]);
+      selectedByShard.set(ordinal, selected);
+    }
+    for (const [ordinal, selected] of selectedByShard) {
+      partitions[ordinal].tokens.push(token);
+      partitions[ordinal].postings.push(selected);
+    }
+  }
   for (let start = 0, ordinal = 0; start < searchIndex.cardIds.length; start += shardSize, ordinal += 1) {
     const end = Math.min(start + shardSize, searchIndex.cardIds.length);
     const cardIds = searchIndex.cardIds.slice(start, end);
     const cards = cardIds.map((id) => cardsById.get(id)).filter(Boolean);
-    const tokens = [];
-    const postings = [];
-    for (const [tokenIndex, token] of searchIndex.tokens.entries()) {
-      const selected = (searchIndex.postings[tokenIndex] ?? [])
-        .filter(([cardIndex]) => cardIndex >= start && cardIndex < end)
-        .map(([cardIndex, vector]) => [cardIndex - start, vector]);
-      if (selected.length === 0) continue;
-      tokens.push(token);
-      postings.push(selected);
-    }
+    const { tokens, postings } = partitions[ordinal];
     const shard = {
       ...searchIndex,
       cardSetHash: searchCardSetHash(cards),
@@ -49,6 +55,7 @@ export function buildSearchShards(index, searchIndex, shardSize) {
     };
     const file = `search-shards/${String(ordinal).padStart(4, "0")}.json`;
     const content = stableStringify(shard);
+    partitions[ordinal] = null;
     shards.set(file, content);
     records.push({
       file,

package/src/search.js

@@ -23,15 +23,21 @@ import {
   verifySearchIndex,
 } from "./inverted-index.js";
 import { normalizeSearchText, tokenize } from "./tokenizer.js";
-import { recoverGenerationTransaction } from "./transaction.js";
+import { recoverGenerationTransaction, withGenerationLock } from "./transaction.js";
 import { isCompatibleRepositoryGraph, renderGraphNode, resolveGraphNode } from "./graph.js";
 
 const preparedIndexCache = new WeakMap();
 const preparedSearchIndexCache = new WeakMap();
+const sessionGraphAdjacencyCache = new WeakMap();
+const sessionSearchMetadataCache = new WeakMap();
 
 export async function loadSearchData(root) {
+  return withGenerationLock(root, (lock) => loadSearchDataLocked(root, lock));
+}
+
+async function loadSearchDataLocked(root, lock) {
   const { config } = await loadConfig(root);
-  await recoverGenerationTransaction(root, { cacheDirectory: config.generation.cacheDirectory });
+  await recoverGenerationTransaction(root, { cacheDirectory: config.generation.cacheDirectory, lockOwnerId: lock.ownerId });
   const cacheRoot = path.join(root, config.generation.cacheDirectory);
   await assertNoSymlinkTraversal(root, cacheRoot, config.generation.cacheDirectory);
   const indexPath = path.join(cacheRoot, "index.json");
@@ -91,34 +97,54 @@ export async function queryProject(root, query, options = {}) {
 }
 
 export async function createProjectSession(root) {
-  let snapshot = await loadProjectSnapshot(root);
+  let snapshot = await loadSessionSnapshot(root);
   const session = {
     root,
     query(query, options = {}) {
-      return queryPreparedIndex(snapshot.index, snapshot.searchIndex, query, {
+      return structuredClone(queryPreparedIndex(snapshot.index, snapshot.searchIndex, query, {
         ...options,
         lexicon: snapshot.lexicon,
         graph: snapshot.graph,
-      });
+      }));
     },
     show(id) {
-      return showSnapshotCard(snapshot, id);
+      return structuredClone(showSnapshotCard(snapshot, id));
     },
     context(id, options = {}) {
       return buildSnapshotContext(snapshot, id, options);
     },
     async refresh() {
-      snapshot = await loadProjectSnapshot(root);
+      snapshot = await loadSessionSnapshot(root);
       return session;
     },
   };
   return session;
 }
 
+async function loadSessionSnapshot(root) {
+  const snapshot = await loadProjectSnapshot(root);
+  // Only session-owned graphs are cached: public query inputs may be mutable.
+  if (snapshot.graph) sessionGraphAdjacencyCache.set(snapshot.graph, buildGraphAdjacency(snapshot.graph));
+  sessionSearchMetadataCache.set(snapshot.index, prepareSearchMetadata(snapshot.index, snapshot.lexicon, snapshot.graph));
+  return snapshot;
+}
+
+function prepareSearchMetadata(index, lexicon, graph) {
+  return {
+    byId: new Map(index.cards.map((card) => [card.id, card])),
+    cardOrder: new Map(index.cards.map((card, position) => [card.id, position])),
+    normalizedIds: index.cards.map((card) => normalizeSearchText(card.id)),
+    aliases: Object.entries(lexicon.aliases ?? {}).map(([alias, targets]) => [alias, targets, normalizeSearchText(alias)]),
+    graphCompatible: isCompatibleRepositoryGraph(graph, index.repositoryId),
+  };
+}
+
 async function loadProjectSnapshot(root) {
-  const { index, lexicon, searchIndex, graph } = await loadSearchData(root);
-  const registry = await loadRegistry(root);
-  return { index, lexicon, searchIndex, graph, registry };
+  return withGenerationLock(root, async (lock) => {
+    const { index, lexicon, searchIndex, graph } = await loadSearchDataLocked(root, lock);
+    const registry = await loadRegistry(root);
+    return { index, lexicon, searchIndex, graph, registry };
+  });
 }
 
 export function queryIndex(index, query, options = {}) {
@@ -139,11 +165,12 @@ export function queryPreparedIndex(index, searchIndex, query, options = {}) {
   const metrics = options.metrics ?? null;
   const normalizedQuery = normalizeSearchText(query);
   const queryTokens = tokenize(query);
-  const aliases = Object.entries(lexicon.aliases ?? {});
+  const cached = sessionSearchMetadataCache.get(index);
+  const prepared = cached ?? prepareSearchMetadata(index, lexicon, options.graph);
+  const aliases = prepared.aliases;
   const aliasTargets = new Set();
   const aliasReasons = new Map();
-  const byId = new Map(index.cards.map((card) => [card.id, card]));
-  const cardOrder = new Map(index.cards.map((card, cardIndex) => [card.id, cardIndex]));
+  const { byId, cardOrder } = prepared;
   const resultsById = new Map();
 
   if (metrics) {
@@ -153,10 +180,12 @@ export function queryPreparedIndex(index, searchIndex, query, options = {}) {
     metrics.phraseDocumentsScanned = 0;
     metrics.idDocumentsScanned = 0;
     metrics.graphEdgesVisited = 0;
+    metrics.idNormalizations = cached ? 0 : index.cards.length;
+    metrics.lookupBuilds = cached ? 0 : 2;
+    metrics.graphValidations = cached ? 0 : 1;
   }
 
-  for (const [alias, targetValue] of aliases) {
-    const normalizedAlias = normalizeSearchText(alias);
+  for (const [alias, targetValue, normalizedAlias] of aliases) {
     if (!normalizedAlias || !normalizedQuery.includes(normalizedAlias)) continue;
     const targets = Array.isArray(targetValue) ? targetValue : [targetValue];
     for (const target of targets) {
@@ -167,11 +196,12 @@ export function queryPreparedIndex(index, searchIndex, query, options = {}) {
     }
   }
 
-  for (const card of index.cards) {
+  for (const [position, card] of index.cards.entries()) {
     if (metrics) metrics.idDocumentsScanned += 1;
-    if (normalizeSearchText(card.id) === normalizedQuery) {
+    const normalizedId = prepared.normalizedIds[position];
+    if (normalizedId === normalizedQuery) {
       addScore(resultsById, card, 1000, "exact semantic ID");
-    } else if (normalizeSearchText(card.id).includes(normalizedQuery) && normalizedQuery.length > 2) {
+    } else if (normalizedId.includes(normalizedQuery) && normalizedQuery.length > 2) {
       addScore(resultsById, card, 100, "semantic ID phrase");
     }
     if (aliasTargets.has(card.id)) {
@@ -215,7 +245,7 @@ export function queryPreparedIndex(index, searchIndex, query, options = {}) {
   const seeds = [...results]
     .sort((left, right) => right.score - left.score || (cardOrder.get(left.card.id) ?? 0) - (cardOrder.get(right.card.id) ?? 0))
     .slice(0, 3);
-  if (isCompatibleRepositoryGraph(options.graph, index.repositoryId)) {
+  if (prepared.graphCompatible) {
     applyGraphBonuses(index, options.graph, seeds, byId, resultsById, metrics);
   } else {
     applyLegacyRelationBonuses(seeds, byId, resultsById);
@@ -491,8 +521,9 @@ function buildLegacyContext(index, rootId, options) {
   const queue = [{ id: rootId, depth: 0 }];
   const visited = new Set();
   const selected = [];
-  while (queue.length > 0) {
-    const current = queue.shift();
+  let traversedEdges = 0;
+  for (let cursor = 0; cursor < queue.length; cursor += 1) {
+    const current = queue[cursor];
     if (!current || visited.has(current.id)) continue;
     visited.add(current.id);
     const card = byId.get(current.id);
@@ -500,10 +531,16 @@ function buildLegacyContext(index, rootId, options) {
     selected.push(card);
     if (current.depth >= depth) continue;
     for (const relation of card.rel ?? []) {
+      if (traversedEdges >= maxEdges) break;
       const target = relation.slice(relation.indexOf(">") + 1);
       queue.push({ id: target, depth: current.depth + 1 });
+      traversedEdges += 1;
+    }
+    for (const source of reverse.get(card.id) ?? []) {
+      if (traversedEdges >= maxEdges) break;
+      queue.push({ id: source, depth: current.depth + 1 });
+      traversedEdges += 1;
     }
-    for (const source of reverse.get(card.id) ?? []) queue.push({ id: source, depth: current.depth + 1 });
   }
 
   const header = `llmnav-context/1 root=${rootId} depth=${depth}\n`;
@@ -575,6 +612,8 @@ function applyLegacyRelationBonuses(seeds, byId, resultsById) {
 }
 
 function buildGraphAdjacency(graph) {
+  const cached = sessionGraphAdjacencyCache.get(graph);
+  if (cached) return cached;
   const adjacency = new Map();
   for (const edge of [...graph.edges].sort(compareGraphEdgesForTraversal)) {
     appendGraphNeighbor(adjacency, edge.from, { neighbor: edge.to, direction: "out", edge });

package/src/spec.js

@@ -10,7 +10,7 @@ rel=workflow>llmnav.rules.validate
 stability=contract
 */
 
-export const PACKAGE_VERSION = "0.8.0";
+export const PACKAGE_VERSION = "0.9.1";
 export const SPEC_VERSION = "1";
 
 export const SCOPES = Object.freeze(["file", "module", "symbol"]);

package/src/transaction.js

@@ -9,7 +9,7 @@ stability=architecture
 */
 
 import { randomBytes } from "node:crypto";
-import { lstat, mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { link, lstat, mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
 import {
@@ -32,6 +32,7 @@ const DEFAULT_RETRY_DELAYS = Object.freeze([0, 8, 16, 32, 64, 128, 256, 512]);
 const JOURNAL_PHASES = new Set(["prepared", "old-moved", "new-installed", "committed"]);
 const DEFAULT_LOCK_TIMEOUT_MS = 30_000;
 const DEFAULT_LOCK_POLL_MS = 50;
+const LOCK_LINK_CAPABILITY_ERRORS = new Set(["ENOSYS", "ENOTSUP", "EOPNOTSUPP", "EPERM", "EXDEV"]);
 const CONTROL_ARTIFACT_PATHS = new Set([".llmnav/ids.jsonl", ".llmnav/order.lock"]);
 
 export async function withGenerationLock(root, callback, options = {}) {
@@ -54,28 +55,50 @@ export async function acquireGenerationLock(root, options = {}) {
   const pollMs = options.pollMs ?? DEFAULT_LOCK_POLL_MS;
   const delays = options.delays ?? [0, ...Array.from({ length: Math.ceil(timeoutMs / pollMs) }, () => pollMs)];
   const openImpl = options.openImpl ?? open;
+  const linkImpl = options.linkImpl ?? link;
   const sleepImpl = options.sleepImpl ?? sleep;
-
-  for (const delay of delays) {
-    if (delay > 0) await sleepImpl(delay);
+  const candidatePath = `${lockPath}.tmp-${process.pid}-${randomBytes(8).toString("hex")}`;
+  // Publish only a closed, complete owner record. A crash before publication
+  // leaves an unused candidate, never an unreadable authoritative lock.
+  let candidateCreated = false;
+  try {
+    const handle = await openImpl(candidatePath, "wx");
+    candidateCreated = true;
     try {
-      const handle = await openImpl(lockPath, "wx");
+      await handle.writeFile(stableStringify({ schemaVersion: 1, ownerId, pid: process.pid }));
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+
+    for (const delay of delays) {
+      if (delay > 0) await sleepImpl(delay);
       try {
-        await handle.writeFile(stableStringify({ schemaVersion: 1, ownerId, pid: process.pid }));
-        await handle.sync();
-      } finally {
-        await handle.close();
-      }
-      return { root, lockPath, ownerId };
-    } catch (error) {
-      if (!error || typeof error !== "object" || error.code !== "EEXIST") throw error;
-      const existing = await readJsonSafe(lockPath, null);
-      if (existing && Number.isInteger(existing.pid) && !isProcessAlive(existing.pid)) {
-        await removeOwnedLock(lockPath, existing.ownerId);
+        await linkImpl(candidatePath, lockPath);
+        return { root, lockPath, ownerId };
+      } catch (error) {
+        if (error && typeof error === "object" && LOCK_LINK_CAPABILITY_ERRORS.has(error.code)) {
+          throw new Error(
+            `Cannot publish the LLMNav generation lock (${error.code}). The repository filesystem must support hard links and permit their creation. Check filesystem permissions or move the repository to a filesystem with hard-link support.`,
+            { cause: error },
+          );
+        }
+        if (!error || typeof error !== "object" || error.code !== "EEXIST") throw error;
+        const existing = await readJsonSafe(lockPath, null);
+        if (existing && Number.isInteger(existing.pid) && !isProcessAlive(existing.pid)) {
+          await removeOwnedLock(lockPath, existing.ownerId);
+        }
       }
     }
+    const existing = await readJsonSafe(lockPath, null);
+    if (!existing || !Number.isInteger(existing.pid) || !existing.ownerId) {
+      throw new Error("The LLMNav generation lock has no valid owner record. After stopping all LLMNav processes, remove .llmnav/generation.lock and retry.");
+    }
+    throw new Error("Timed out waiting for the LLMNav generation lock.");
+  } finally {
+    // Candidate cleanup must not turn successful acquisition into a leaked lock.
+    if (candidateCreated) await removeWithRetry(candidatePath).catch(() => {});
   }
-  throw new Error("Timed out waiting for the LLMNav generation lock.");
 }
 
 export async function releaseGenerationLock(lock) {