llmnav 0.9.1 → 0.9.7

package/CHANGELOG.md

@@ -4,7 +4,29 @@ All notable changes to this project are documented here.
 
 The npm package follows Semantic Versioning. The `llmnav/N` source protocol is versioned independently.
 
-## [Unreleased]
+## [0.9.7] — 2026-09-28
+
+### Fixed
+
+* Recognize Go and Rust raw string boundaries before scanning LLMNav cards, preserving real cards and leaving card-shaped literal text untouched.
+* Rank evaluation queries with the same repository graph used by project queries and sessions.
+* Read prompt bundles under the generation lock and let hosts refresh prompt partitions and search from one generation snapshot.
+* Validate the primary index against its manifest before trusting cached search and graph data, while retaining manifestless schema v1 reads.
+* Reuse persisted parsed file state only when its manifest hash, record shape, and local stat-hint generation agree; otherwise read source and rebuild safely. Explicit caller-provided state remains reusable.
+* Classify missing and ambiguous semantic IDs consistently across show and context agent operations.
+* Report whether retrieval evaluation passed, failed, was invalid, or lacks enough cases; allow API callers to require a minimum case count without changing the default CLI exit behavior.
+* Evaluate explicit no-result queries separately from positive recall, and require every no-result case to return no cards before evaluation passes.
+
+### Performance
+
+* Narrow session ID substring checks to precomputed candidates and resolve alias targets directly, preserving direct-query results and ranking.
+
+## [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
 

package/README.md

@@ -6,7 +6,7 @@ It adds compact, stable metadata to a small number of architectural and behavior
 
 LLMNav is not a documentation generator, an embedding database, or a reason to annotate every function. It is a zero-runtime-dependency Node.js CLI and ESM library for reducing broad repository scans, irrelevant context, stale hand-written links, repeated card tokenization, and avoidable cache invalidation.
 
-## What v0.7 provides
+## Current capabilities
 
 * The backward-compatible `llmnav/1` source comment specification
 * A parser and data-loss-resistant canonical formatter
@@ -295,7 +295,7 @@ The project uses the Node.js standard library and built-in test runner. There is
 
 ## Status
 
-LLMNav is an experimental protocol and a usable v0.8 CLI. The source format remains `llmnav/1`; npm package changes and source-grammar changes are versioned independently.
+LLMNav is a pre-1.0 CLI and ESM library. The source format remains `llmnav/1`, and the primary index uses schemaVersion 1. Package, source-protocol, and generated-format versions change independently; see the [compatibility policy](docs/compatibility.md) and [roadmap](ROADMAP.md) for their respective guarantees and remaining 1.0 criteria.
 
 ## License
 

package/ROADMAP.md

@@ -85,7 +85,7 @@ Implemented:
 
 ## 1.0 criteria
 
-The source grammar and generated formats will be declared stable only after use across multiple TypeScript, Go, Rust, Python, and mixed-language repositories. A 1.0 release requires migration tooling, documented compatibility guarantees, benchmark fixtures with published methodology, sustained Windows and Linux verification, and no unresolved high-severity parser or transaction ambiguity.
+The `llmnav/1` source protocol and schemaVersion 1 primary index already have compatibility guarantees. A 1.0 release requires evidence from multiple TypeScript, Go, Rust, Python, and mixed-language repositories, migration tooling, benchmark fixtures with published methodology, sustained Windows and Linux verification, and no unresolved high-severity parser or transaction ambiguity.
 
 In progress:
 

package/docs/api.md

@@ -268,9 +268,15 @@ The normative source vocabulary remains available from `llmnav/spec`.
 import { KEY_ORDER, EFFECT_KINDS, RISK_KINDS } from "llmnav/spec";
 ```
 
+## Retrieval evaluation
+
+`evaluateProject(root, { minimumCases: 1 })` requires at least one reviewed query before returning `ok: true`. The result's `status` is `passed`, `failed`, `insufficient`, `unmeasured`, or `invalid`. An empty dataset keeps the existing default `ok: true` for callers that use `eval` during setup, but always reports `status: "unmeasured"`; pass/fail gates should set `minimumCases` explicitly. The default CLI does not set this option.
+
+Each query record requires a non-empty `query`. A positive case supplies at least one non-empty ID in `expected`; multiple IDs mean **any one** is an acceptable answer. A no-result case supplies `"expectNoResults": true` and omits `expected`. Recall@1, Recall@5, and MRR use only positive cases, while every no-result case must return zero cards for `status: "passed"`. At least one positive case is needed to pass. The current format does not require every listed ID to be found.
+
 ## Agent operation protocol
 
-`getAgentToolDefinitions()` returns defensive copies of four schemaVersion 1 tool definitions in fixed order. Their JSON Schema inputs reject unknown fields and deliberately omit the repository root.
+`getAgentToolDefinitions()` returns defensive copies of five schemaVersion 1 tool definitions in fixed order. Their JSON Schema inputs reject unknown fields and deliberately omit the repository root.
 
 ```js
 import { executeAgentOperation, getAgentToolDefinitions } from "llmnav";
@@ -283,7 +289,7 @@ const result = await executeAgentOperation(
 );
 ```
 
-The trusted wrapper binds `root`; the model supplies only the validated operation input. Results use one schemaVersion 1 envelope containing `operation`, `ok`, `data`, and `error`. Input errors use `LNVAP002`, missing IDs use `LNVAP404`, and unexpected operation failures use `LNVAP500`.
+The trusted wrapper binds `root`; the model supplies only the validated operation input. Results use one schemaVersion 1 envelope containing `operation`, `ok`, `data`, and `error`. Input errors use `LNVAP002`, missing IDs use `LNVAP404`, ambiguous IDs use `LNVAP409`, and unexpected operation failures use `LNVAP500`.
 
 Long-lived hosts can load one explicit snapshot for repeated navigation calls:
 
@@ -302,11 +308,13 @@ 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.
 
+Pass `{ withPromptBundle: true }` to `createProjectSession` when a host needs prompt partitions and navigation from the same generation. The returned session exposes `promptBundle` and a content-derived `generationHash`; `refresh()` replaces both alongside the search snapshot. The hash identifies generated cache content, not whether ungenerated source edits exist in the working tree.
+
 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.
+Session queries also reuse card lookup tables, normalized IDs and aliases, and graph validation. Session ID substring checks use precomputed three-code-unit candidates before exact verification; direct queries retain their full ID scan. Phrase matching still scans 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.
+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, the generation hash, one snapshot-backed operation executor, and an explicit refresh method without importing a model SDK. Refresh prepares a complete replacement before switching the host's prompt and search references.
 
 `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/examples/provider-neutral-host.d.mts

@@ -8,6 +8,7 @@ import type {
 export interface LlmnavHost {
   toolDefinitions: AgentToolDefinition[];
   basePromptPartitions: PromptPrefixPartition[];
+  generationHash: string;
   selectPromptPartitions(moduleIds?: string[]): PromptPrefixPartition[];
   execute(call: { name: string; input?: Record<string, unknown> }): Promise<AgentOperationResult>;
   refresh(): Promise<LlmnavHost>;

package/examples/provider-neutral-host.mjs

@@ -13,15 +13,15 @@ import {
   executeAgentOperation,
   createProjectSession,
   getAgentToolDefinitions,
-  loadPromptPrefixBundle,
 } from "llmnav";
 
 export async function createLlmnavHost(root) {
-  let bundle = await loadPromptPrefixBundle(root);
-  let session = await createProjectSession(root);
+  let session = await createProjectSession(root, { withPromptBundle: true });
+  let bundle = session.promptBundle;
   const host = {
     toolDefinitions: getAgentToolDefinitions(),
     basePromptPartitions: selectPromptPartitions(bundle),
+    generationHash: session.generationHash,
     selectPromptPartitions(moduleIds = []) {
       return selectPromptPartitions(bundle, moduleIds);
     },
@@ -29,11 +29,13 @@ export async function createLlmnavHost(root) {
       return executeAgentOperation(root, call.name, call.input ?? {}, { session });
     },
     async refresh() {
-      [bundle, session] = await Promise.all([
-        loadPromptPrefixBundle(root),
-        createProjectSession(root),
-      ]);
-      host.basePromptPartitions = selectPromptPartitions(bundle);
+      const nextSession = await createProjectSession(root, { withPromptBundle: true });
+      const nextBundle = nextSession.promptBundle;
+      const nextBase = selectPromptPartitions(nextBundle);
+      session = nextSession;
+      bundle = nextBundle;
+      host.basePromptPartitions = nextBase;
+      host.generationHash = nextSession.generationHash;
       return host;
     },
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llmnav",
-  "version": "0.9.1",
+  "version": "0.9.7",
   "description": "A deterministic semantic navigation layer for LLM coding agents.",
   "type": "module",
   "bin": {

package/src/agent-protocol.js

@@ -12,7 +12,7 @@ stability=contract
 
 import { loadGraphInputs } from "./graph-input.js";
 import { scanProject } from "./project.js";
-import { buildContext, queryProject, showProjectCard } from "./search.js";
+import { buildContext, queryProject, SemanticIdLookupError, showProjectCard } from "./search.js";
 import { countDiagnostics, validateProject } from "./validator.js";
 import { getAgentToolDefinitions } from "./agent-tools.js";
 import { explainProjectFile } from "./audit.js";
@@ -48,7 +48,12 @@ export async function executeAgentOperation(root, name, input = {}, options = {}
       const result = options.session
         ? options.session.show(input.id.trim())
         : await showProjectCard(root, input.id.trim());
-      if (!result.card && !result.node) return failure(operation, "LNVAP404", `Unknown or inactive semantic ID ${input.id}.`, result);
+      if (!result.card && !result.node) {
+        const state = result.resolvedFrom?.state;
+        if (state === "ambiguous") return failure(operation, "LNVAP409", `Ambiguous semantic ID ${input.id}; qualify or replace it with one candidate.`, result);
+        if (state === "cycle") return failure(operation, "LNVAP500", `Registry cycle prevents resolving semantic ID ${input.id}.`, result);
+        return failure(operation, "LNVAP404", `Unknown or inactive semantic ID ${input.id}.`, result);
+      }
       return success(operation, result);
     }
     if (operation === "context") {
@@ -76,6 +81,10 @@ export async function executeAgentOperation(root, name, input = {}, options = {}
       error: null,
     };
   } catch (error) {
+    if (error instanceof SemanticIdLookupError) {
+      return failure(operation, error.reason === "not_found" ? "LNVAP404" :
+        error.reason === "ambiguous" ? "LNVAP409" : "LNVAP500", error.message);
+    }
     return failure(operation, "LNVAP500", error instanceof Error ? error.message : String(error));
   }
 }

package/src/evaluation.js

@@ -14,54 +14,78 @@ import { loadSearchData, queryPreparedIndex } from "./search.js";
 import { assertNoSymlinkTraversal, parseJsonLines, readText } from "./util.js";
 
 export async function evaluateProject(root, options = {}) {
+  const minimumCases = options.minimumCases ?? 0;
+  if (!Number.isSafeInteger(minimumCases) || minimumCases < 0) {
+    throw new RangeError("minimumCases must be a non-negative safe integer.");
+  }
   const { config } = await loadConfig(root);
-  const { index, lexicon, searchIndex } = await loadSearchData(root);
+  const { index, lexicon, searchIndex, graph } = await loadSearchData(root);
   const queryPath = path.resolve(root, options.file ?? config.evaluation.queryFile);
   await assertNoSymlinkTraversal(root, queryPath, "evaluation query file");
   const parsed = parseJsonLines(await readText(queryPath, ""), queryPath);
   if (parsed.errors.length > 0) {
-    return { ok: false, errors: parsed.errors, cases: [], metrics: emptyMetrics() };
+    return { ok: false, status: "invalid", minimumCases, errors: parsed.errors, cases: [], metrics: emptyMetrics() };
   }
 
   const cases = [];
   for (const record of parsed.records) {
-    if (!record || typeof record.query !== "string" || !Array.isArray(record.expected) || record.expected.length === 0) {
+    const expectNoResults = record?.expectNoResults === true;
+    const expected = expectNoResults ? [] : record?.expected;
+    if (!record || typeof record.query !== "string" || !record.query.trim() ||
+      (Object.hasOwn(record, "expectNoResults") && !expectNoResults) ||
+      (expectNoResults ? record.expected !== undefined :
+        !Array.isArray(expected) || expected.length === 0 ||
+          !expected.every((id) => typeof id === "string" && id.trim()))) {
       return {
         ok: false,
-        errors: [`${queryPath}: each record requires query:string and expected:string[]`],
+        status: "invalid",
+        minimumCases,
+        errors: [`${queryPath}: each record requires a non-empty query and either non-empty expected IDs or expectNoResults:true`],
         cases,
         metrics: emptyMetrics(),
       };
     }
-    const results = queryPreparedIndex(index, searchIndex, record.query, { top: Math.max(options.top ?? 5, 5), lexicon });
+    const results = queryPreparedIndex(index, searchIndex, record.query, { top: Math.max(options.top ?? 5, 5), lexicon, graph });
     const ids = results.map((result) => result.id);
-    const firstRank = ids.findIndex((id) => record.expected.includes(id));
+    const firstRank = expectNoResults ? -1 : ids.findIndex((id) => expected.includes(id));
+    const noResultPass = expectNoResults && ids.length === 0;
     cases.push({
       query: record.query,
-      expected: record.expected,
+      expected,
+      expectNoResults,
       actual: ids,
       rank: firstRank < 0 ? null : firstRank + 1,
-      passAt1: firstRank === 0,
-      passAt5: firstRank >= 0 && firstRank < 5,
+      passAt1: noResultPass || firstRank === 0,
+      passAt5: noResultPass || (firstRank >= 0 && firstRank < 5),
     });
   }
 
   const total = cases.length;
+  const positiveCases = cases.filter((item) => !item.expectNoResults);
+  const positiveTotal = positiveCases.length;
+  const negativeTotal = total - positiveTotal;
+  const negativePassed = cases.filter((item) => item.expectNoResults && item.passAt5).length;
   const metrics = total === 0
     ? emptyMetrics()
     : {
         total,
-        recallAt1: cases.filter((item) => item.passAt1).length / total,
-        recallAt5: cases.filter((item) => item.passAt5).length / total,
-        meanReciprocalRank: cases.reduce((sum, item) => sum + (item.rank ? 1 / item.rank : 0), 0) / total,
+        positiveTotal,
+        negativeTotal,
+        negativePassed,
+        recallAt1: positiveTotal === 0 ? 0 : positiveCases.filter((item) => item.passAt1).length / positiveTotal,
+        recallAt5: positiveTotal === 0 ? 0 : positiveCases.filter((item) => item.passAt5).length / positiveTotal,
+        meanReciprocalRank: positiveTotal === 0 ? 0 :
+          positiveCases.reduce((sum, item) => sum + (item.rank ? 1 / item.rank : 0), 0) / positiveTotal,
       };
-  const ok =
-    total === 0 ||
-    (metrics.recallAt1 >= config.evaluation.minimumRecallAt1 &&
-      metrics.recallAt5 >= config.evaluation.minimumRecallAt5);
-  return { ok, errors: [], cases, metrics, thresholds: config.evaluation };
+  const thresholdsPassed = positiveTotal > 0 && negativePassed === negativeTotal &&
+    metrics.recallAt1 >= config.evaluation.minimumRecallAt1 &&
+    metrics.recallAt5 >= config.evaluation.minimumRecallAt5;
+  const status = total === 0 ? "unmeasured" :
+    total < minimumCases ? "insufficient" : thresholdsPassed ? "passed" : "failed";
+  const ok = status === "passed" || (status === "unmeasured" && minimumCases === 0);
+  return { ok, status, minimumCases, errors: [], cases, metrics, thresholds: config.evaluation };
 }
 
 function emptyMetrics() {
-  return { total: 0, recallAt1: 0, recallAt5: 0, meanReciprocalRank: 0 };
+  return { total: 0, positiveTotal: 0, negativeTotal: 0, negativePassed: 0, recallAt1: 0, recallAt5: 0, meanReciprocalRank: 0 };
 }

package/src/incremental.js

@@ -21,14 +21,15 @@ import {
   atomicWrite,
   compareText,
   readJsonSafe,
+  readText,
   relativePosix,
   sha256,
   stableStringify,
 } from "./util.js";
 
 export const FILE_STATE_SCHEMA_VERSION = 1;
-export const SOURCE_INDEXER_VERSION = 6;
-const STAT_HINTS_SCHEMA_VERSION = 1;
+export const SOURCE_INDEXER_VERSION = 8;
+const STAT_HINTS_SCHEMA_VERSION = 2;
 
 export async function scanProjectIncremental(root, options = {}) {
   const { config, configPath } = await loadConfig(root);
@@ -37,14 +38,30 @@ export async function scanProjectIncremental(root, options = {}) {
   await assertNoSymlinkTraversal(root, cacheDirectory, config.generation.cacheDirectory);
   const fileStatePath = path.join(cacheDirectory, "file-state.json");
   await assertNoSymlinkTraversal(root, fileStatePath, relativePosix(root, fileStatePath));
-  const previousState = options.previousState ?? await readJsonSafe(fileStatePath, null);
+  const fileStateSource = options.previousState
+    ? renderFileState(options.previousState)
+    : await readText(fileStatePath, null);
+  let previousState = null;
+  try {
+    previousState = fileStateSource === null ? null : JSON.parse(fileStateSource);
+  } catch (error) {
+    if (!(error instanceof SyntaxError)) throw error;
+  }
+  const manifest = await readJsonSafe(path.join(cacheDirectory, "manifest.json"), null);
+  const previousStateHash = fileStateSource === null ? null : sha256(fileStateSource);
+  const fileStateKey = `${relativePosix(root, cacheDirectory)}/file-state.json`;
+  const trustedPreviousState = usableFileState(previousState) &&
+    (options.previousState != null ||
+      (manifest?.schemaVersion === 1 && manifest.repositoryId === config.repositoryId &&
+        manifest.files?.[fileStateKey] === previousStateHash));
   const hintsPath = path.join(root, ".llmnav", "state", "stat-hints.json");
   await assertNoSymlinkTraversal(root, hintsPath, relativePosix(root, hintsPath));
   const previousHints = options.useStatHints === false
     ? null
     : await readJsonSafe(hintsPath, null);
-  const previousFiles = usableFileState(previousState) ? mapStateFiles(previousState.files) : new Map();
-  const hintFiles = usableStatHints(previousHints) ? previousHints.files ?? {} : {};
+  const previousFiles = trustedPreviousState ? mapStateFiles(previousState.files) : new Map();
+  const hintFiles = trustedPreviousState && usableStatHints(previousHints) &&
+    previousHints.fileStateHash === previousStateHash ? previousHints.files : {};
 
   const fileRecords = [];
   const records = [];
@@ -69,13 +86,13 @@ export async function scanProjectIncremental(root, options = {}) {
     const relativePath = relativePosix(root, absolutePath);
     const details = await stat(absolutePath, { bigint: true });
     const fingerprint = statFingerprint(details);
-    nextHintFiles[relativePath] = fingerprint;
     seenPaths.add(relativePath);
     const previousFile = previousFiles.get(relativePath);
     const previousHint = hintFiles[relativePath];
     let stateFile;
 
-    if (previousFile && fingerprintsEqual(previousHint, fingerprint)) {
+    if (previousFile && previousHint?.contentHash === previousFile.contentHash &&
+      fingerprintsEqual(previousHint, fingerprint)) {
       stateFile = previousFile;
       stats.reusedFiles += 1;
       stats.reusedFilesByStat += 1;
@@ -97,6 +114,7 @@ export async function scanProjectIncremental(root, options = {}) {
     }
 
     const normalizedStateFile = normalizeStateFile(stateFile, relativePath);
+    nextHintFiles[relativePath] = { ...fingerprint, contentHash: normalizedStateFile.contentHash };
     nextStateFiles.push(normalizedStateFile);
     sourceBytes += normalizedStateFile.sourceBytes;
     semanticBytes += normalizedStateFile.semanticBytes;
@@ -117,6 +135,7 @@ export async function scanProjectIncremental(root, options = {}) {
   };
   const statHints = {
     schemaVersion: STAT_HINTS_SCHEMA_VERSION,
+    fileStateHash: sha256(renderFileState(fileState)),
     files: Object.fromEntries(Object.entries(nextHintFiles).sort(([left], [right]) => compareText(left, right))),
   };
   const registry = await loadRegistry(root);
@@ -176,12 +195,22 @@ export function renderFileState(fileState) {
 }
 
 export function usableFileState(value) {
-  return Boolean(
-    value &&
-      value.schemaVersion === FILE_STATE_SCHEMA_VERSION &&
-      value.indexerVersion === SOURCE_INDEXER_VERSION &&
-      Array.isArray(value.files),
-  );
+  if (!value || value.schemaVersion !== FILE_STATE_SCHEMA_VERSION ||
+    value.indexerVersion !== SOURCE_INDEXER_VERSION || !Array.isArray(value.files)) return false;
+  const paths = new Set();
+  for (const file of value.files) {
+    if (!file || typeof file.path !== "string" || !file.path || file.path.startsWith("/") ||
+      file.path.includes("\\") || file.path.split("/").includes("..") || paths.has(file.path) ||
+      !/^[0-9a-f]{64}$/u.test(file.contentHash) ||
+      !Number.isSafeInteger(file.sourceBytes) || file.sourceBytes < 0 ||
+      !Number.isSafeInteger(file.semanticBytes) || file.semanticBytes < 0 ||
+      !Array.isArray(file.imports) || !file.imports.every((item) => typeof item === "string") ||
+      !Array.isArray(file.blocks) || !file.blocks.every((block) => block &&
+        typeof block.raw === "string" && block.card && typeof block.card.id === "string") ||
+      !Array.isArray(file.declarations) || file.declarations.length !== file.blocks.length) return false;
+    paths.add(file.path);
+  }
+  return true;
 }
 
 function analyzeFile(relativePath, source) {
@@ -269,5 +298,7 @@ function fingerprintsEqual(left, right) {
 }
 
 function usableStatHints(value) {
-  return Boolean(value && value.schemaVersion === STAT_HINTS_SCHEMA_VERSION && value.files && typeof value.files === "object");
+  return Boolean(value && value.schemaVersion === STAT_HINTS_SCHEMA_VERSION &&
+    /^[0-9a-f]{64}$/u.test(value.fileStateHash) && value.files &&
+    typeof value.files === "object" && !Array.isArray(value.files));
 }

package/src/index.d.ts

@@ -253,6 +253,12 @@ export interface ProjectSession {
   refresh(): Promise<ProjectSession>;
 }
 
+export interface ProjectSessionWithPromptBundle extends ProjectSession {
+  promptBundle: PromptPrefixBundle;
+  generationHash: string;
+  refresh(): Promise<ProjectSessionWithPromptBundle>;
+}
+
 export interface RegistryRecord {
   id: string;
   state: "active" | "redirect" | "replaced" | "retired" | string;
@@ -621,10 +627,13 @@ export interface MigrationResult {
 
 export interface EvaluationResult {
   ok: boolean;
+  status: "invalid" | "unmeasured" | "insufficient" | "passed" | "failed";
+  minimumCases: number;
   errors: string[];
   cases: Array<{
     query: string;
     expected: string[];
+    expectNoResults: boolean;
     actual: string[];
     rank: number | null;
     passAt1: boolean;
@@ -632,6 +641,9 @@ export interface EvaluationResult {
   }>;
   metrics: {
     total: number;
+    positiveTotal: number;
+    negativeTotal: number;
+    negativePassed: number;
     recallAt1: number;
     recallAt5: number;
     meanReciprocalRank: number;
@@ -725,7 +737,7 @@ export function findAttachedDeclaration(source: string, block: LlmnavBlock, file
 export function extractImports(source: string, filePath: string): string[];
 export function doctorProject(root: string): Promise<{ ok: boolean; checks: Array<{ name: string; ok: boolean; message: string }> }>;
 export function migrateProject(root: string, options?: { write?: boolean; failpoint?: string; renameOptions?: Record<string, unknown>; lockOptions?: Record<string, unknown>; onTransactionPhase?: (phase: string) => void | Promise<void> }): Promise<MigrationResult>;
-export function evaluateProject(root: string, options?: { top?: number; file?: string }): Promise<EvaluationResult>;
+export function evaluateProject(root: string, options?: { top?: number; file?: string; minimumCases?: number }): Promise<EvaluationResult>;
 export function collectSourceFiles(root: string, config: LlmnavConfig, requestedPaths?: string[]): Promise<string[]>;
 export function findProjectRoot(start?: string): Promise<string>;
 export function formatProject(root: string, options?: { check?: boolean; paths?: string[] }): Promise<{ ok: boolean; changedFiles: string[]; errors: Array<{ file: string; line: number; message: string }> }>;
@@ -757,7 +769,8 @@ export function renderRegistryRecords(records: RegistryRecord[]): string;
 export function loadRegistry(root: string): Promise<Registry>;
 export function resolveRegistryId(registry: Registry, id: string): { id: string; state: string; [key: string]: unknown };
 export function buildContext(root: string, id: string, options?: { depth?: number; budget?: number; maxEdges?: number }): Promise<{ id: string; depth: number; budget: number; maxEdges: number; included: string[]; includedEdges: string[]; text: string }>;
-export function createProjectSession(root: string): Promise<ProjectSession>;
+export function createProjectSession(root: string, options: { withPromptBundle: true }): Promise<ProjectSessionWithPromptBundle>;
+export function createProjectSession(root: string, options?: { withPromptBundle?: false }): Promise<ProjectSession>;
 export function loadSearchData(root: string): Promise<{ index: LlmnavIndex; searchIndex: LlmnavSearchIndex; lexicon: { version?: number; aliases: Record<string, string | string[]> }; graph: RepositoryGraph | null }>;
 export function queryIndex(index: LlmnavIndex, query: string, options?: { top?: number; lexicon?: { aliases: Record<string, string | string[]> }; invertedIndex?: LlmnavSearchIndex; metrics?: SearchMetrics; graph?: RepositoryGraph | null }): SearchResult[];
 export function queryPreparedIndex(index: LlmnavIndex, searchIndex: LlmnavSearchIndex, query: string, options?: { top?: number; lexicon?: { aliases: Record<string, string | string[]> }; metrics?: SearchMetrics; graph?: RepositoryGraph | null }): SearchResult[];

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,8 +222,15 @@ 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;
+  let rustRawTerminator = "";
   const mask = new Uint8Array(source.length);
 
   for (let index = 0; index < source.length; index += 1) {
@@ -260,21 +272,51 @@ 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 === "rust-raw") {
+      if (source.startsWith(rustRawTerminator, index)) {
+        state = "normal";
+        index += rustRawTerminator.length - 1;
+      }
+      continue;
+    }
     if (state === "single" || state === "double" || state === "backtick") {
       if (escaped) {
         escaped = false;
         continue;
       }
-      if (character === "\\") {
+      if (character === "\\" && (state !== "backtick" || extension !== ".go")) {
         escaped = true;
         continue;
       }
       const terminator = state === "single" ? "'" : state === "double" ? '"' : "`";
-      if (character === terminator) state = "normal";
+      if (character === terminator) {
+        state = "normal";
+        regexAllowed = false;
+        previousToken = "value";
+      }
       continue;
     }
 
-    if (nextFour === "<!--") {
+    const rawTerminator = extension === ".rs" ? rustRawStringTerminator(source, index) : null;
+    if (rawTerminator !== null) {
+      state = "rust-raw";
+      rustRawTerminator = rawTerminator;
+    } else if (nextFour === "<!--") {
       state = "html-comment";
       index += 3;
     } else if (character === "/" && next === "*") {
@@ -283,6 +325,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,12 +349,61 @@ 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;
+      }
     }
   }
 
   return mask;
 }
 
+function rustRawStringTerminator(source, index) {
+  let cursor;
+  if (source[index] === "r") cursor = index + 1;
+  else if (source[index] === "b" && source[index + 1] === "r") cursor = index + 2;
+  else return null;
+  if (index > 0 && /[\p{ID_Continue}]/u.test(source[index - 1])) return null;
+  let hashes = 0;
+  while (source[cursor] === "#" && hashes <= 255) {
+    hashes += 1;
+    cursor += 1;
+  }
+  if (hashes > 255 || source[cursor] !== '"') return null;
+  return `"${"#".repeat(hashes)}`;
+}
+
 function looksLikeRustCharacterLiteral(source, offset) {
   return /^'(?:\\.|[^'\\\r\n])'/u.test(source.slice(offset));
 }

package/src/prompt-bundle.js

@@ -12,6 +12,7 @@ stability=architecture
 
 import path from "node:path";
 import { loadConfig } from "./config.js";
+import { recoverGenerationTransaction, withGenerationLock } from "./transaction.js";
 import { approximateTokens, assertNoSymlinkTraversal, compareText, readText, sha256, stableJson, stableStringify, toPosix } from "./util.js";
 
 export const PROMPT_BUNDLE_SCHEMA_VERSION = 1;
@@ -60,7 +61,12 @@ export function isCompatiblePromptPrefixBundle(bundle, repositoryId = undefined)
 }
 
 export async function loadPromptPrefixBundle(root) {
+  return withGenerationLock(root, async (lock) => (await loadPromptPrefixBundleLocked(root, lock)).bundle);
+}
+
+export async function loadPromptPrefixBundleLocked(root, lock) {
   const { config } = await loadConfig(root);
+  await recoverGenerationTransaction(root, { cacheDirectory: config.generation.cacheDirectory, lockOwnerId: lock.ownerId });
   const relativePath = `${toPosix(config.generation.cacheDirectory).replace(/\/+$/u, "")}/prompt-prefix.json`;
   const bundlePath = path.join(root, relativePath);
   const manifestPath = path.join(root, config.generation.cacheDirectory, "manifest.json");
@@ -80,7 +86,7 @@ export async function loadPromptPrefixBundle(root) {
   const manifestContent = await readText(manifestPath, "");
   const manifest = manifestContent ? JSON.parse(manifestContent) : null;
   if (manifest?.files?.[relativePath] !== sha256(content)) throw new Error(`Prompt bundle hash does not match manifest.json.`);
-  return bundle;
+  return { bundle, generationHash: sha256(manifestContent) };
 }
 
 function partition(id, cacheScope, contentType, content) {

package/src/search.js

@@ -23,6 +23,7 @@ import {
   verifySearchIndex,
 } from "./inverted-index.js";
 import { normalizeSearchText, tokenize } from "./tokenizer.js";
+import { loadPromptPrefixBundleLocked } from "./prompt-bundle.js";
 import { recoverGenerationTransaction, withGenerationLock } from "./transaction.js";
 import { isCompatibleRepositoryGraph, renderGraphNode, resolveGraphNode } from "./graph.js";
 
@@ -31,6 +32,14 @@ const preparedSearchIndexCache = new WeakMap();
 const sessionGraphAdjacencyCache = new WeakMap();
 const sessionSearchMetadataCache = new WeakMap();
 
+export class SemanticIdLookupError extends Error {
+  constructor(reason, message) {
+    super(message);
+    this.name = "SemanticIdLookupError";
+    this.reason = reason;
+  }
+}
+
 export async function loadSearchData(root) {
   return withGenerationLock(root, (lock) => loadSearchDataLocked(root, lock));
 }
@@ -48,11 +57,33 @@ async function loadSearchDataLocked(root, lock) {
   for (const managedPath of [indexPath, manifestPath, graphPath, searchPath, lexiconPath]) {
     await assertNoSymlinkTraversal(root, managedPath, toPosix(path.relative(root, managedPath)));
   }
-  const index = await readJsonSafe(indexPath, null);
-  if (!index) throw new Error("No generated index found. Run `llmnav generate` first.");
+  const indexText = await readText(indexPath, null);
+  if (indexText === null) throw new Error("No generated index found. Run `llmnav generate` first.");
+  let index;
+  try {
+    index = JSON.parse(indexText);
+  } catch {
+    throw new Error("Malformed primary index.json. Run `llmnav generate` to rebuild it.");
+  }
+  if (!isUsablePrimaryIndex(index, config.repositoryId)) {
+    throw new Error("Incompatible primary index.json. Run `llmnav generate` to rebuild it.");
+  }
   const lexicon = await readJsonSafe(lexiconPath, { version: 1, aliases: {} });
-  const manifest = await readJsonSafe(manifestPath, null);
-  const graphRelative = `${toPosix(config.generation.cacheDirectory).replace(/\/+$/u, "")}/graph.json`;
+  const cacheRelative = toPosix(config.generation.cacheDirectory).replace(/\/+$/u, "");
+  const manifestText = await readText(manifestPath, null);
+  let manifest = null;
+  if (manifestText !== null) {
+    try {
+      manifest = JSON.parse(manifestText);
+    } catch {
+      throw new Error("Malformed generated manifest.json. Run `llmnav generate` to rebuild it.");
+    }
+    if (manifest?.repositoryId !== config.repositoryId ||
+      manifest.files?.[`${cacheRelative}/index.json`] !== sha256(indexText)) {
+      throw new Error("Primary index.json hash does not match manifest.json. Run `llmnav generate` to rebuild it.");
+    }
+  }
+  const graphRelative = `${cacheRelative}/graph.json`;
   const graphText = await readText(graphPath, null);
   let graph = null;
   if (graphText !== null) {
@@ -68,7 +99,7 @@ async function loadSearchDataLocked(root, lock) {
       isCompatibleRepositoryGraph(graph, index.repositoryId),
   );
   if (!graphMatches) graph = null;
-  const searchRelative = `${toPosix(config.generation.cacheDirectory).replace(/\/+$/u, "")}/search-index.json`;
+  const searchRelative = `${cacheRelative}/search-index.json`;
   const searchText = await readText(searchPath, null);
   let searchIndex = null;
   if (searchText !== null) {
@@ -91,15 +122,30 @@ async function loadSearchDataLocked(root, lock) {
   return { index, lexicon, searchIndex, graph };
 }
 
+function isUsablePrimaryIndex(index, repositoryId) {
+  if (!index || index.schemaVersion !== 1 || index.repositoryId !== repositoryId || !Array.isArray(index.cards)) return false;
+  const ids = new Set();
+  for (const card of index.cards) {
+    if (!card || typeof card.id !== "string" || !card.id || typeof card.role !== "string" || ids.has(card.id)) return false;
+    ids.add(card.id);
+    for (const field of ["search", "owns", "excludes", "invariant", "effect", "risk", "rel"]) {
+      if (card[field] !== undefined && (!Array.isArray(card[field]) || card[field].some((value) => typeof value !== "string"))) return false;
+    }
+  }
+  return true;
+}
+
 export async function queryProject(root, query, options = {}) {
   const { index, lexicon, searchIndex, graph } = await loadSearchData(root);
   return queryPreparedIndex(index, searchIndex, query, { ...options, lexicon, graph });
 }
 
-export async function createProjectSession(root) {
-  let snapshot = await loadSessionSnapshot(root);
+export async function createProjectSession(root, options = {}) {
+  const withPromptBundle = options.withPromptBundle === true;
+  let snapshot = await loadSessionSnapshot(root, { withPromptBundle });
   const session = {
     root,
+    ...(withPromptBundle ? { promptBundle: snapshot.promptBundle, generationHash: snapshot.generationHash } : {}),
     query(query, options = {}) {
       return structuredClone(queryPreparedIndex(snapshot.index, snapshot.searchIndex, query, {
         ...options,
@@ -114,36 +160,74 @@ export async function createProjectSession(root) {
       return buildSnapshotContext(snapshot, id, options);
     },
     async refresh() {
-      snapshot = await loadSessionSnapshot(root);
+      const next = await loadSessionSnapshot(root, { withPromptBundle });
+      snapshot = next;
+      if (withPromptBundle) {
+        session.promptBundle = next.promptBundle;
+        session.generationHash = next.generationHash;
+      }
       return session;
     },
   };
   return session;
 }
 
-async function loadSessionSnapshot(root) {
-  const snapshot = await loadProjectSnapshot(root);
+async function loadSessionSnapshot(root, options = {}) {
+  const snapshot = await loadProjectSnapshot(root, options);
   // 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));
+  sessionSearchMetadataCache.set(snapshot.index, prepareSearchMetadata(snapshot.index, snapshot.lexicon, snapshot.graph, true));
   return snapshot;
 }
 
-function prepareSearchMetadata(index, lexicon, graph) {
+function prepareSearchMetadata(index, lexicon, graph, forSession = false) {
+  const normalizedIds = index.cards.map((card) => normalizeSearchText(card.id));
   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)),
+    normalizedIds,
+    idCandidates: forSession ? buildIdCandidates(normalizedIds) : null,
     aliases: Object.entries(lexicon.aliases ?? {}).map(([alias, targets]) => [alias, targets, normalizeSearchText(alias)]),
     graphCompatible: isCompatibleRepositoryGraph(graph, index.repositoryId),
   };
 }
 
-async function loadProjectSnapshot(root) {
+function buildIdCandidates(normalizedIds) {
+  const exact = new Map();
+  const grams = new Map();
+  for (const [position, id] of normalizedIds.entries()) {
+    if (!exact.has(id)) exact.set(id, []);
+    exact.get(id).push(position);
+    const seen = new Set();
+    for (let offset = 0; offset <= id.length - 3; offset += 1) {
+      const gram = id.slice(offset, offset + 3);
+      if (seen.has(gram)) continue;
+      seen.add(gram);
+      if (!grams.has(gram)) grams.set(gram, []);
+      grams.get(gram).push(position);
+    }
+  }
+  return { exact, grams };
+}
+
+function idCandidatePositions(prepared, normalizedQuery) {
+  if (!prepared.idCandidates) return prepared.normalizedIds.keys();
+  if (normalizedQuery.length < 3) return prepared.idCandidates.exact.get(normalizedQuery) ?? [];
+  let smallest = null;
+  for (let offset = 0; offset <= normalizedQuery.length - 3; offset += 1) {
+    const positions = prepared.idCandidates.grams.get(normalizedQuery.slice(offset, offset + 3));
+    if (!positions) return [];
+    if (!smallest || positions.length < smallest.length) smallest = positions;
+  }
+  return smallest ?? [];
+}
+
+async function loadProjectSnapshot(root, options = {}) {
   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 };
+    const prompt = options.withPromptBundle ? await loadPromptPrefixBundleLocked(root, lock) : null;
+    return { index, lexicon, searchIndex, graph, registry, promptBundle: prompt?.bundle, generationHash: prompt?.generationHash };
   });
 }
 
@@ -196,17 +280,19 @@ export function queryPreparedIndex(index, searchIndex, query, options = {}) {
     }
   }
 
-  for (const [position, card] of index.cards.entries()) {
+  for (const position of idCandidatePositions(prepared, normalizedQuery)) {
     if (metrics) metrics.idDocumentsScanned += 1;
+    const card = index.cards[position];
     const normalizedId = prepared.normalizedIds[position];
     if (normalizedId === normalizedQuery) {
       addScore(resultsById, card, 1000, "exact semantic ID");
     } else if (normalizedId.includes(normalizedQuery) && normalizedQuery.length > 2) {
       addScore(resultsById, card, 100, "semantic ID phrase");
     }
-    if (aliasTargets.has(card.id)) {
-      addScore(resultsById, card, 500, aliasReasons.get(card.id) ?? []);
-    }
+  }
+  for (const target of aliasTargets) {
+    const card = byId.get(target);
+    if (card) addScore(resultsById, card, 500, aliasReasons.get(target) ?? []);
   }
 
   const preparedSearchIndex = prepareCompactSearchIndex(searchIndex);
@@ -423,21 +509,21 @@ function buildSnapshotContext(snapshot, id, options = {}) {
     const resolved = resolveRegistryId(registry, id);
     if (resolved.state === "active" && index.cards.some((card) => card.id === resolved.id)) rootId = resolved.id;
     if (resolved.state === "ambiguous") {
-      throw new Error(`Ambiguous replaced semantic ID ${id}; choose one of ${resolved.candidates.join(", ")}.`);
+      throw new SemanticIdLookupError("ambiguous", `Ambiguous replaced semantic ID ${id}; choose one of ${resolved.candidates.join(", ")}.`);
     }
-    if (resolved.state === "cycle") throw new Error(`Registry cycle prevents resolving semantic ID ${id}.`);
+    if (resolved.state === "cycle") throw new SemanticIdLookupError("registry_cycle", `Registry cycle prevents resolving semantic ID ${id}.`);
   }
   if (isCompatibleRepositoryGraph(graph, index.repositoryId)) {
     const resolution = rootId
       ? resolveGraphNode(graph, `${index.repositoryId}/${rootId}`, index.repositoryId)
       : resolveGraphNode(graph, id, index.repositoryId);
     if (resolution.state === "ambiguous") {
-      throw new Error(`Ambiguous semantic ID ${id}; qualify one of ${resolution.candidates.join(", ")}.`);
+      throw new SemanticIdLookupError("ambiguous", `Ambiguous semantic ID ${id}; qualify one of ${resolution.candidates.join(", ")}.`);
     }
-    if (resolution.state !== "resolved") throw new Error(`Unknown or inactive semantic ID ${id}.`);
+    if (resolution.state !== "resolved") throw new SemanticIdLookupError("not_found", `Unknown or inactive semantic ID ${id}.`);
     return buildGraphContext(index, graph, resolution.node, { depth, budget, maxEdges });
   }
-  if (!rootId) throw new Error(`Unknown or inactive semantic ID ${id}.`);
+  if (!rootId) throw new SemanticIdLookupError("not_found", `Unknown or inactive semantic ID ${id}.`);
   return buildLegacyContext(index, rootId, { depth, budget, maxEdges });
 }
 

package/src/spec.js

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