llmnav 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -6,6 +6,32 @@ The npm package follows Semantic Versioning. The `llmnav/N` source protocol is v
 
 ## [Unreleased]
 
+## [0.9.2] — 2026-09-09
+
+### Fixed
+
+* Recognize JavaScript/TypeScript regular-expression literals while masking source strings, so quotes and comment-like text inside regexes do not hide later cards or create false cards. Preserve division expressions and ordinary JSX closing tags.
+* Invalidate older parsed-file caches so unchanged consumer files receive the corrected parsing behavior.
+
+## [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

package/docs/api.md

@@ -302,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/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.9.0",
+  "version": "0.9.2",
   "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/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/incremental.js

@@ -27,7 +27,7 @@ import {
 } from "./util.js";
 
 export const FILE_STATE_SCHEMA_VERSION = 1;
-export const SOURCE_INDEXER_VERSION = 6;
+export const SOURCE_INDEXER_VERSION = 7;
 const STAT_HINTS_SCHEMA_VERSION = 1;
 
 export async function scanProjectIncremental(root, options = {}) {

package/src/index.d.ts

@@ -231,6 +231,9 @@ export interface SearchMetrics {
   phraseDocumentsScanned?: number;
   idDocumentsScanned?: number;
   graphEdgesVisited?: number;
+  idNormalizations?: number;
+  lookupBuilds?: number;
+  graphValidations?: number;
 }
 
 export interface SearchResult {
@@ -244,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>;

package/src/parser.js

@@ -39,6 +39,11 @@ const BLOCK_PATTERNS = [
 ];
 const MAX_SOURCE_BYTES = 16 * 1024 * 1024;
 const MAX_BLOCKS_PER_FILE = 10_000;
+const JAVASCRIPT_EXTENSIONS = new Set([".js", ".mjs", ".cjs", ".jsx", ".ts", ".tsx"]);
+const REGEX_PREFIX_KEYWORDS = new Set([
+  "await", "case", "delete", "do", "else", "in", "instanceof", "new", "return", "throw", "typeof", "void", "yield",
+]);
+const CONTROL_PAREN_KEYWORDS = new Set(["if", "while", "for", "with", "switch", "catch"]);
 
 export function parseLlmnavBlocks(source, filePath = "<memory>") {
   if (Buffer.byteLength(source) > MAX_SOURCE_BYTES) {
@@ -217,6 +222,12 @@ function buildLiteralMask(source, filePath) {
   const hashComments = [".py", ".rb", ".sh", ".bash", ".zsh"].includes(extension);
   const dashComments = extension === ".sql";
   const tripleQuotes = extension === ".py";
+  const javascript = JAVASCRIPT_EXTENSIONS.has(extension);
+  let regexAllowed = true;
+  let regexCharacterClass = false;
+  let previousToken = "";
+  const controlParentheses = [];
+  const expressionBraces = [];
   let state = "normal";
   let escaped = false;
   const mask = new Uint8Array(source.length);
@@ -260,6 +271,21 @@ function buildLiteralMask(source, filePath) {
       }
       continue;
     }
+    if (state === "regex") {
+      if (character === "\n" || character === "\r") {
+        state = "normal";
+        escaped = false;
+      } else if (escaped) escaped = false;
+      else if (character === "\\") escaped = true;
+      else if (character === "[") regexCharacterClass = true;
+      else if (character === "]") regexCharacterClass = false;
+      else if (character === "/" && !regexCharacterClass) {
+        state = "normal";
+        regexAllowed = false;
+        previousToken = "value";
+      }
+      continue;
+    }
     if (state === "single" || state === "double" || state === "backtick") {
       if (escaped) {
         escaped = false;
@@ -270,7 +296,11 @@ function buildLiteralMask(source, filePath) {
         continue;
       }
       const terminator = state === "single" ? "'" : state === "double" ? '"' : "`";
-      if (character === terminator) state = "normal";
+      if (character === terminator) {
+        state = "normal";
+        regexAllowed = false;
+        previousToken = "value";
+      }
       continue;
     }
 
@@ -283,6 +313,10 @@ function buildLiteralMask(source, filePath) {
     } else if (character === "/" && next === "/") {
       state = "line-comment";
       index += 1;
+    } else if (javascript && character === "/" && regexAllowed) {
+      state = "regex";
+      regexCharacterClass = false;
+      escaped = false;
     } else if (hashComments && character === "#") {
       state = "line-comment";
     } else if (dashComments && character === "-" && next === "-") {
@@ -303,6 +337,40 @@ function buildLiteralMask(source, filePath) {
     } else if (character === "`") {
       state = "backtick";
       escaped = false;
+    } else if (javascript && !/\s/u.test(character)) {
+      // Track lexical expression position without rescanning prefixes. Comments do
+      // not change it; a control-condition ')' permits a following regex statement.
+      if (/[A-Za-z_$]/u.test(character)) {
+        const start = index;
+        const memberName = previousToken === ".";
+        while (index + 1 < source.length && /[\w$]/u.test(source[index + 1])) index += 1;
+        previousToken = source.slice(start, index + 1);
+        regexAllowed = !memberName && REGEX_PREFIX_KEYWORDS.has(previousToken);
+      } else if (character === "(") {
+        controlParentheses.push(CONTROL_PAREN_KEYWORDS.has(previousToken));
+        regexAllowed = true;
+        previousToken = character;
+      } else if (character === ")") {
+        regexAllowed = controlParentheses.pop() === true;
+        previousToken = character;
+      } else if (character === "{") {
+        expressionBraces.push(regexAllowed && !["", ";", "else", "do", "try", "finally", ")"].includes(previousToken));
+        regexAllowed = true;
+        previousToken = character;
+      } else if (character === "}") {
+        regexAllowed = expressionBraces.pop() !== true;
+        previousToken = character;
+      } else if ((character === "+" || character === "-") && next === character) {
+        previousToken = character + next;
+        index += 1;
+      } else if (character === "=" && next === ">") {
+        regexAllowed = true;
+        previousToken = "=>";
+        index += 1;
+      } else {
+        regexAllowed = "=(:,!&|?;[+-*%~^>/".includes(character);
+        previousToken = character;
+      }
     }
   }
 

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.9.0";
+export const PACKAGE_VERSION = "0.9.2";
 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) {