llmnav 0.6.2 → 0.6.6

package/CHANGELOG.md

@@ -6,6 +6,32 @@ The npm package follows Semantic Versioning. The `llmnav/N` source protocol is v
 
 ## [Unreleased]
 
+## [0.6.6] — 2026-08-12
+
+### Added
+
+* Added a read-only cross-repository conformance matrix with repository-isolated validation, retrieval, audit, repeatability, cache-freshness, and held-language evidence.
+
+### Fixed
+
+* Invalidated parsed file-state caches created by older source indexers so upgraded installations rebuild semantic and declaration hashes from source instead of silently reusing incompatible state.
+
+## [0.6.4] — 2026-08-11
+
+### Fixed
+
+* Rejected symlink and junction traversal across search caches, incremental state, and public registry reads and writes.
+* Enforced parser card limits before materialization and replaced repeated interval and line-number scans with bounded indexes.
+* Bounded aggregate declaration extraction work per source file, including malformed declarations and whitespace lookahead.
+
+## [0.6.3] — 2026-08-11
+
+### Fixed
+
+* Rejected nested symlink and junction traversal before managed cache, state, schema, and prompt-bundle filesystem operations.
+* Replaced per-marker lexical rescans with a bounded single-pass parser classification.
+* Required npm release tags to resolve to commits on the protected `origin/main` lineage.
+
 ## [0.6.2] — 2026-08-11
 
 ### Added

package/ROADMAP.md

@@ -77,6 +77,12 @@ Implemented:
 
 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.
 
+In progress:
+
+* A read-only cross-repository conformance matrix measures validation, retrieval, audit, repeatability, and cache freshness without averaging weak repositories away.
+* LLMNav, Workduck, Sairon, and AI BOM Generator currently pass repository-isolated conformance checks across JavaScript, TypeScript, Rust, Go, and Python.
+* The current evidence covers 4 repositories and 5 required languages with no held or failed repository, while 1.0 still requires sustained Windows and Linux verification and published benchmark methodology.
+
 ## Non-goals
 
 LLMNav will not become a general documentation generator, a source-of-truth call graph maintained by comments, an autonomous code modification service, a hosted source-ingestion platform, or a mandatory embedding database.

package/docs/benchmarking.md

@@ -94,6 +94,26 @@ npx llmnav eval --json
 
 Track at least Recall@1, Recall@5, and mean reciprocal rank. Record every acceptable target ID when a task has multiple valid entry points.
 
+## Cross-repository conformance matrix
+
+Run the checked-in read-only matrix from a workspace that contains the configured sibling repositories:
+
+```sh
+node benchmarks/run-conformance.js
+```
+
+Use `--matrix <path>` to select another checked-in matrix and `--output <path>` to retain a JSON report. The report schema is `benchmarks/conformance-report.schema.json`.
+
+Each repository keeps its own validation counts, retrieval thresholds, Recall@1, Recall@5, MRR, audit summary, repeatability result, and generated-cache freshness result. The harness deliberately does not average retrieval scores across repositories. A large or easy dataset must not hide a failing repository.
+
+Verdicts have asymmetric meaning:
+
+* `pass` requires valid cards, sufficient reviewed queries, repository thresholds, repeatable retrieval, and a source-current generated cache.
+* `fail` requires a reproducible validation, retrieval, repeatability, cache-freshness, or measurement failure.
+* `held` records missing adoption or insufficient reviewed cases without pretending that unmeasured language coverage passed or failed.
+
+The default matrix currently measures LLMNav and Workduck. Go and Python remain held until their candidate repositories receive reviewed cards and task-language query datasets. Matrix output is navigation evidence, not an end-to-end claim about model tokens or coding-task success.
+
 ## End-to-end agent metrics
 
 A successful deployment should reduce exploration cost without reducing task correctness.

package/docs/spec.md

@@ -351,6 +351,10 @@ For repositories with at least 50,000 scanned source bytes, LLMNav comments SHOU
 
 These are anti-bloat limits, not targets.
 
+The reference parser also rejects a single source file larger than 16 MiB and more than 10,000
+LLMNav blocks in one file. These resource budgets keep repository-controlled input from causing
+unbounded parser memory or CPU work; they do not change the `llmnav/1` comment grammar.
+
 ## Canonicalization
 
 A canonical formatter MUST refuse to erase malformed lines, unknown fields, overlapping blocks, or duplicate scalar values. Unsafe cards remain unchanged until the checker-reported issue is fixed.

package/package.json

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

package/src/declaration.js

@@ -10,7 +10,7 @@ stability=architecture
 */
 
 import path from "node:path";
-import { lineAtOffset, normalizeNewlines, sha256 } from "./util.js";
+import { buildLineStarts, lineAtOffsetFromStarts, normalizeNewlines, sha256 } from "./util.js";
 
 const DECLARATION_PATTERNS = {
   javascript: [
@@ -42,8 +42,18 @@ const DECLARATION_PATTERNS = {
     { kind: "function", pattern: /^(?:public\s+|private\s+|protected\s+|internal\s+|static\s+|final\s+|async\s+)*(?:[A-Za-z_][\w<>?\[\],.]*\s+)+([A-Za-z_][A-Za-z0-9_]*)\s*\(/u },
   ],
 };
+const JAVASCRIPT_REGEX_PREFIX_KEYWORDS = new Set([
+  "case", "delete", "do", "else", "in", "instanceof", "new", "return", "throw", "typeof", "void", "yield",
+]);
 
-export function findAttachedDeclaration(source, block, filePath) {
+export function createDeclarationScanContext(source) {
+  return {
+    lineStarts: buildLineStarts(source),
+    remainingScanUnits: Math.max(1, source.length * 2),
+  };
+}
+
+export function findAttachedDeclaration(source, block, filePath, scanContext = createDeclarationScanContext(source)) {
   if (block.scope !== "symbol") return null;
   const window = source.slice(block.end, block.end + 3000);
   const skipped = skipTrivia(window);
@@ -61,11 +71,12 @@ export function findAttachedDeclaration(source, block, filePath) {
     const declarationOffset = block.end + skipped;
     const signature = extractSignature(collapsed);
     const exported = isExportedDeclaration(language, match[1], signature);
-    const endOffset = findDeclarationEnd(source, declarationOffset, family);
+    const endOffset = findDeclarationEnd(source, declarationOffset, family, scanContext);
+    if (endOffset === null) return null;
     return {
       symbol: match[1],
       kind: definition.kind,
-      line: lineAtOffset(source, declarationOffset),
+      line: lineAtOffsetFromStarts(scanContext.lineStarts, declarationOffset),
       signature,
       language,
       exported,
@@ -155,8 +166,8 @@ function extractGoReceiver(candidate) {
   return (parts.at(-1) ?? "").replace(/^\*+/u, "") || null;
 }
 
-function findDeclarationEnd(source, start, family) {
-  if (family === "python") return findPythonDeclarationEnd(source, start);
+function findDeclarationEnd(source, start, family, scanContext) {
+  if (family === "python") return findPythonDeclarationEnd(source, start, scanContext);
   let state = "normal";
   let escaped = false;
   let regexCharacterClass = false;
@@ -166,6 +177,7 @@ function findDeclarationEnd(source, start, family) {
   let openedBody = false;
 
   for (let index = start; index < source.length; index += 1) {
+    if (!consumeDeclarationScan(scanContext)) return null;
     const character = source[index];
     const next = source[index + 1];
     if (state === "line-comment") {
@@ -230,15 +242,16 @@ function findDeclarationEnd(source, start, family) {
     } else if (character === ";" && !openedBody && parentheses === 0 && brackets === 0) {
       return index + 1;
     } else if (character === "\n" && !openedBody && parentheses === 0 && brackets === 0) {
-      const current = source.slice(start, index).trimEnd();
-      const nextCharacter = source.slice(index + 1).match(/^\s*(.)/u)?.[1] ?? "";
-      if (nextCharacter !== "{" && !/(?:=>|[=|&,([{])$/u.test(current)) return index;
+      const continuation = declarationContinuesBefore(source, start, index, scanContext);
+      const next = nextSignificantCharacter(source, index + 1, scanContext);
+      if (continuation === null || next.exhausted) return null;
+      if (next.character !== "{" && !continuation) return index;
     }
   }
   return source.length;
 }
 
-function findPythonDeclarationEnd(source, start) {
+function findPythonDeclarationEnd(source, start, scanContext) {
   const declarationLineStart = source.lastIndexOf("\n", start - 1) + 1;
   const baseIndent = indentationWidth(source.slice(declarationLineStart, start));
   let cursor = source.indexOf("\n", start);
@@ -248,6 +261,7 @@ function findPythonDeclarationEnd(source, start) {
   while (cursor < source.length) {
     const lineEnd = source.indexOf("\n", cursor);
     const end = lineEnd < 0 ? source.length : lineEnd + 1;
+    if (!consumeDeclarationScan(scanContext, Math.max(1, end - cursor))) return null;
     const line = source.slice(cursor, lineEnd < 0 ? source.length : lineEnd);
     if (/^\s*(?:#.*)?$/u.test(line)) {
       cursor = end;
@@ -261,6 +275,15 @@ function findPythonDeclarationEnd(source, start) {
   return source.length;
 }
 
+function consumeDeclarationScan(scanContext, units = 1) {
+  if (scanContext.remainingScanUnits < units) {
+    scanContext.remainingScanUnits = 0;
+    return false;
+  }
+  scanContext.remainingScanUnits -= units;
+  return true;
+}
+
 function indentationWidth(value) {
   let width = 0;
   for (const character of value) width += character === "\t" ? 8 - (width % 8) : 1;
@@ -268,11 +291,36 @@ function indentationWidth(value) {
 }
 
 function canStartJavaScriptRegex(source, start, offset) {
-  const prefix = source.slice(start, offset).trimEnd();
-  if (!prefix) return true;
-  const previous = prefix.at(-1);
+  let cursor = offset - 1;
+  while (cursor >= start && /\s/u.test(source[cursor])) cursor -= 1;
+  if (cursor < start) return true;
+  const previous = source[cursor];
   if (/[=(:,!&|?{};\[]/u.test(previous)) return true;
-  return /(?:^|\W)(?:case|delete|do|else|in|instanceof|new|return|throw|typeof|void|yield)\s*$/u.test(prefix);
+  if (!/[A-Za-z]/u.test(previous)) return false;
+  const wordEnd = cursor + 1;
+  while (cursor >= start && /[A-Za-z]/u.test(source[cursor])) cursor -= 1;
+  return JAVASCRIPT_REGEX_PREFIX_KEYWORDS.has(source.slice(cursor + 1, wordEnd));
+}
+
+function declarationContinuesBefore(source, start, offset, scanContext) {
+  let cursor = offset - 1;
+  while (cursor >= start && /\s/u.test(source[cursor])) {
+    if (!consumeDeclarationScan(scanContext)) return null;
+    cursor -= 1;
+  }
+  if (cursor < start) return false;
+  const character = source[cursor];
+  if (/[=|&,([{]/u.test(character)) return true;
+  return character === ">" && source[cursor - 1] === "=";
+}
+
+function nextSignificantCharacter(source, offset, scanContext) {
+  let cursor = offset;
+  while (cursor < source.length && /\s/u.test(source[cursor])) {
+    if (!consumeDeclarationScan(scanContext)) return { character: "", exhausted: true };
+    cursor += 1;
+  }
+  return { character: source[cursor] ?? "", exhausted: false };
 }
 
 function looksLikeRustCharacterLiteral(source, offset) {

package/src/generator.js

@@ -217,7 +217,7 @@ async function generateProjectLocked(root, options) {
 
     if (statHints && hintsPath) {
       try {
-        await persistStatHints(hintsPath, statHints);
+        await persistStatHints(root, hintsPath, statHints);
         statHintsPersisted = true;
       } catch (error) {
         statHintsError = error instanceof Error ? error.message : String(error);

package/src/incremental.js

@@ -11,11 +11,12 @@ stability=architecture
 import { readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { loadConfig } from "./config.js";
-import { findAttachedDeclaration, extractImports } from "./declaration.js";
+import { createDeclarationScanContext, findAttachedDeclaration, extractImports } from "./declaration.js";
 import { collectSourceFiles } from "./files.js";
 import { parseLlmnavBlocks } from "./parser.js";
 import { loadRegistry } from "./registry.js";
 import {
+  assertNoSymlinkTraversal,
   atomicWrite,
   compareText,
   readJsonSafe,
@@ -25,15 +26,19 @@ import {
 } from "./util.js";
 
 export const FILE_STATE_SCHEMA_VERSION = 1;
-export const SOURCE_INDEXER_VERSION = 4;
+export const SOURCE_INDEXER_VERSION = 6;
 const STAT_HINTS_SCHEMA_VERSION = 1;
 
 export async function scanProjectIncremental(root, options = {}) {
   const { config, configPath } = await loadConfig(root);
   const files = await collectSourceFiles(root, config, options.paths ?? []);
   const cacheDirectory = path.join(root, config.generation.cacheDirectory);
-  const previousState = options.previousState ?? await readJsonSafe(path.join(cacheDirectory, "file-state.json"), null);
+  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 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);
@@ -133,8 +138,9 @@ export async function scanProjectIncremental(root, options = {}) {
 export function buildFileStateFromProject(project) {
   const files = project.fileRecords.map((fileRecord) => {
     const source = fileRecord.source ?? "";
+    const declarationScanContext = createDeclarationScanContext(source);
     const declarations = fileRecord.blocks.map((block) =>
-      findAttachedDeclaration(source, block, fileRecord.relativePath),
+      findAttachedDeclaration(source, block, fileRecord.relativePath, declarationScanContext),
     );
     return normalizeStateFile(
       {
@@ -157,7 +163,8 @@ export function buildFileStateFromProject(project) {
   };
 }
 
-export async function persistStatHints(hintsPath, statHints) {
+export async function persistStatHints(root, hintsPath, statHints) {
+  await assertNoSymlinkTraversal(root, hintsPath, relativePosix(root, hintsPath));
   await atomicWrite(hintsPath, stableStringify(statHints));
 }
 
@@ -176,6 +183,7 @@ export function usableFileState(value) {
 
 function analyzeFile(relativePath, source) {
   const blocks = parseLlmnavBlocks(source, relativePath);
+  const declarationScanContext = createDeclarationScanContext(source);
   return {
     path: relativePath,
     contentHash: sha256(source),
@@ -183,7 +191,7 @@ function analyzeFile(relativePath, source) {
     semanticBytes: blocks.reduce((sum, block) => sum + Buffer.byteLength(block.raw), 0),
     imports: extractImports(source, relativePath),
     blocks,
-    declarations: blocks.map((block) => findAttachedDeclaration(source, block, relativePath)),
+    declarations: blocks.map((block) => findAttachedDeclaration(source, block, relativePath, declarationScanContext)),
   };
 }
 

package/src/initializer.js

@@ -20,9 +20,14 @@ import { assertNoSymlinkTraversal, atomicWrite, readJson, readText, stableString
 const PACKAGE_ROOT = fileURLToPath(new URL("..", import.meta.url));
 
 export async function initializeProject(root, options = {}) {
-  await assertNoSymlinkTraversal(root, path.join(root, ".llmnav"), ".llmnav");
-  await mkdir(path.join(root, ".llmnav", "eval"), { recursive: true });
-  await mkdir(path.join(root, ".llmnav", "schema"), { recursive: true });
+  const controlDirectory = path.join(root, ".llmnav");
+  const evalDirectory = path.join(controlDirectory, "eval");
+  const schemaDirectory = path.join(controlDirectory, "schema");
+  await assertNoSymlinkTraversal(root, controlDirectory, ".llmnav");
+  await assertNoSymlinkTraversal(root, evalDirectory, ".llmnav/eval");
+  await assertNoSymlinkTraversal(root, schemaDirectory, ".llmnav/schema");
+  await mkdir(evalDirectory, { recursive: true });
+  await mkdir(schemaDirectory, { recursive: true });
   const repositoryId = await inferRepositoryId(root);
   const changed = [];
 
@@ -30,6 +35,7 @@ export async function initializeProject(root, options = {}) {
   config.repositoryId = repositoryId;
   config.$schema = "./schema/config.schema.json";
   await writeIfMissingOrForced(
+    root,
     path.join(root, ".llmnav", "config.json"),
     stableStringify(config),
     options.force,
@@ -38,6 +44,7 @@ export async function initializeProject(root, options = {}) {
   );
 
   await writeIfMissingOrForced(
+    root,
     path.join(root, ".llmnav", "lexicon.json"),
     stableStringify({ version: 1, aliases: {} }),
     false,
@@ -45,6 +52,7 @@ export async function initializeProject(root, options = {}) {
     ".llmnav/lexicon.json",
   );
   await writeIfMissingOrForced(
+    root,
     path.join(root, ".llmnav", "ids.jsonl"),
     "",
     false,
@@ -52,6 +60,7 @@ export async function initializeProject(root, options = {}) {
     ".llmnav/ids.jsonl",
   );
   await writeIfMissingOrForced(
+    root,
     path.join(root, ".llmnav", "order.lock"),
     "",
     false,
@@ -59,6 +68,7 @@ export async function initializeProject(root, options = {}) {
     ".llmnav/order.lock",
   );
   await writeIfMissingOrForced(
+    root,
     path.join(root, ".llmnav", "eval", "queries.jsonl"),
     '# One JSON object per line: {"query":"...","expected":["domain.feature.action"]}\n',
     false,
@@ -66,6 +76,7 @@ export async function initializeProject(root, options = {}) {
     ".llmnav/eval/queries.jsonl",
   );
   await writeIfMissingOrForced(
+    root,
     path.join(root, ".llmnav", ".gitignore"),
     "tmp/\nstate/\n.transactions/\ngeneration-transaction.json\ngeneration.lock\ngeneration.lock.release-*\n*.tmp-*\n",
     options.force,
@@ -75,6 +86,7 @@ export async function initializeProject(root, options = {}) {
 
   const schemaSource = path.join(PACKAGE_ROOT, "schema", "config.schema.json");
   const schemaTarget = path.join(root, ".llmnav", "schema", "config.schema.json");
+  await assertNoSymlinkTraversal(root, schemaTarget, ".llmnav/schema/config.schema.json");
   if (options.force || (await readText(schemaTarget, null)) === null) {
     await copyFile(schemaSource, schemaTarget);
     changed.push(".llmnav/schema/config.schema.json");
@@ -106,7 +118,8 @@ async function inferRepositoryId(root) {
   return normalized || "repository";
 }
 
-async function writeIfMissingOrForced(filePath, content, force, changed, displayPath) {
+async function writeIfMissingOrForced(root, filePath, content, force, changed, displayPath) {
+  await assertNoSymlinkTraversal(root, filePath, displayPath);
   const existing = await readText(filePath, null);
   if (existing !== null && !force) return;
   if (existing === content) return;
@@ -116,6 +129,7 @@ async function writeIfMissingOrForced(filePath, content, force, changed, display
 
 async function addPackageScripts(root) {
   const packagePath = path.join(root, "package.json");
+  await assertNoSymlinkTraversal(root, packagePath, "package.json");
   const text = await readText(packagePath, null);
   if (text === null) return false;
   const parsed = JSON.parse(text);

package/src/parser.js

@@ -15,7 +15,13 @@ import {
   SCOPES,
   SPEC_VERSION,
 } from "./spec.js";
-import { detectNewline, lineAtOffset, normalizeNewlines, splitPipe } from "./util.js";
+import {
+  buildLineStarts,
+  detectNewline,
+  lineAtOffsetFromStarts,
+  normalizeNewlines,
+  splitPipe,
+} from "./util.js";
 
 const BLOCK_PATTERNS = [
   {
@@ -31,24 +37,33 @@ const BLOCK_PATTERNS = [
     terminator: "-->",
   },
 ];
+const MAX_SOURCE_BYTES = 16 * 1024 * 1024;
+const MAX_BLOCKS_PER_FILE = 10_000;
 
 export function parseLlmnavBlocks(source, filePath = "<memory>") {
+  if (Buffer.byteLength(source) > MAX_SOURCE_BYTES) {
+    throw new Error(`${filePath} exceeds the ${MAX_SOURCE_BYTES}-byte parser byte limit.`);
+  }
+  const literalMask = buildLiteralMask(source, filePath);
+  const lineStarts = buildLineStarts(source);
+  const blockBudget = { count: 0 };
   const blocks = [];
   for (const definition of BLOCK_PATTERNS) {
     definition.pattern.lastIndex = 0;
     for (const match of source.matchAll(definition.pattern)) {
       const matchedRaw = match[0];
       const matchStart = match.index ?? 0;
-      if (isInsideStringLiteral(source, matchStart, filePath)) continue;
+      if (literalMask[matchStart] === 1) continue;
       const lineStart = source.lastIndexOf("\n", matchStart - 1) + 1;
       const leading = source.slice(lineStart, matchStart);
       const start = /^\s*$/u.test(leading) ? lineStart : matchStart;
       const end = matchStart + matchedRaw.length;
       const indent = start === lineStart ? leading : "";
       const raw = source.slice(start, end);
+      reserveBlock(blockBudget, filePath);
       blocks.push(
         createBlock({
-          source,
+          lineStarts,
           filePath,
           raw,
           body: match[2],
@@ -63,8 +78,8 @@ export function parseLlmnavBlocks(source, filePath = "<memory>") {
     }
   }
 
-  blocks.push(...parseLineBlocks(source, filePath));
-  blocks.push(...parseUnterminatedBlockComments(source, filePath, blocks));
+  blocks.push(...parseLineBlocks(source, filePath, literalMask, lineStarts, blockBudget));
+  blocks.push(...parseUnterminatedBlockComments(source, filePath, blocks, literalMask, lineStarts, blockBudget));
   blocks.sort((left, right) => left.start - right.start);
 
   const overlapping = [];
@@ -85,7 +100,7 @@ export function parseLlmnavBlocks(source, filePath = "<memory>") {
   return blocks;
 }
 
-function parseLineBlocks(source, filePath) {
+function parseLineBlocks(source, filePath, literalMask, lineStarts, blockBudget) {
   const blocks = [];
   const lines = source.split(/(?<=\n)/u);
   const offsets = [];
@@ -101,7 +116,7 @@ function parseLineBlocks(source, filePath) {
     if (!header) continue;
 
     const start = offsets[index];
-    if (isInsideStringLiteral(source, start, filePath)) continue;
+    if (literalMask[start] === 1) continue;
     const indent = header[1];
     const prefix = header[2];
     const scope = header[3].toLowerCase();
@@ -127,8 +142,9 @@ function parseLineBlocks(source, filePath) {
     }
 
     const raw = source.slice(start, end);
+    reserveBlock(blockBudget, filePath);
     const block = createBlock({
-      source,
+      lineStarts,
       filePath,
       raw,
       body: bodyLines.join("\n"),
@@ -154,24 +170,28 @@ function parseLineBlocks(source, filePath) {
   return blocks;
 }
 
-function parseUnterminatedBlockComments(source, filePath, parsedBlocks) {
+function parseUnterminatedBlockComments(source, filePath, parsedBlocks, literalMask, lineStarts, blockBudget) {
   const blocks = [];
+  const parsedIntervals = [...parsedBlocks].sort((left, right) => left.start - right.start);
   for (const definition of BLOCK_PATTERNS) {
+    let intervalIndex = 0;
     definition.opening.lastIndex = 0;
     for (const match of source.matchAll(definition.opening)) {
       const tokenStart = match.index ?? 0;
-      if (isInsideStringLiteral(source, tokenStart, filePath)) continue;
-      if (parsedBlocks.some((block) => tokenStart >= block.start && tokenStart < block.end)) continue;
+      if (literalMask[tokenStart] === 1) continue;
+      while (parsedIntervals[intervalIndex]?.end <= tokenStart) intervalIndex += 1;
+      const interval = parsedIntervals[intervalIndex];
+      if (interval && tokenStart >= interval.start && tokenStart < interval.end) continue;
       const bodyStart = tokenStart + match[0].length;
-      if (source.indexOf(definition.terminator, bodyStart) >= 0) continue;
 
       const lineStart = source.lastIndexOf("\n", tokenStart - 1) + 1;
       const leading = source.slice(lineStart, tokenStart);
       const start = /^\s*$/u.test(leading) ? lineStart : tokenStart;
       const indent = start === lineStart ? leading : "";
       const end = source.length;
+      reserveBlock(blockBudget, filePath);
       const block = createBlock({
-        source,
+        lineStarts,
         filePath,
         raw: source.slice(start, end),
         body: source.slice(bodyStart),
@@ -192,15 +212,17 @@ function parseUnterminatedBlockComments(source, filePath, parsedBlocks) {
   return blocks;
 }
 
-function isInsideStringLiteral(source, targetOffset, filePath) {
+function buildLiteralMask(source, filePath) {
   const extension = filePath.toLowerCase().match(/\.[a-z0-9]+$/u)?.[0] ?? "";
   const hashComments = [".py", ".rb", ".sh", ".bash", ".zsh"].includes(extension);
   const dashComments = extension === ".sql";
   const tripleQuotes = extension === ".py";
   let state = "normal";
   let escaped = false;
+  const mask = new Uint8Array(source.length);
 
-  for (let index = 0; index < targetOffset; index += 1) {
+  for (let index = 0; index < source.length; index += 1) {
+    mask[index] = state === "normal" ? 0 : 1;
     const character = source[index];
     const next = source[index + 1];
     const nextTwo = source.slice(index, index + 3);
@@ -284,15 +306,22 @@ function isInsideStringLiteral(source, targetOffset, filePath) {
     }
   }
 
-  return state !== "normal";
+  return mask;
 }
 
 function looksLikeRustCharacterLiteral(source, offset) {
   return /^'(?:\\.|[^'\\\r\n])'/u.test(source.slice(offset));
 }
 
-function createBlock({ source, filePath, raw, body, scope, style, start, end, indent, prefix }) {
-  const startLine = lineAtOffset(source, start);
+function reserveBlock(blockBudget, filePath) {
+  blockBudget.count += 1;
+  if (blockBudget.count > MAX_BLOCKS_PER_FILE) {
+    throw new Error(`${filePath} exceeds the ${MAX_BLOCKS_PER_FILE}-block parser limit.`);
+  }
+}
+
+function createBlock({ lineStarts, filePath, raw, body, scope, style, start, end, indent, prefix }) {
+  const startLine = lineAtOffsetFromStarts(lineStarts, start);
   const bodyStartLine = style === "line" ? startLine + 1 : startLine;
   const parsed = parseBody(body, bodyStartLine);
   const card = materializeCard(scope, parsed.entries);
@@ -310,7 +339,7 @@ function createBlock({ source, filePath, raw, body, scope, style, start, end, in
     start,
     end,
     startLine,
-    endLine: lineAtOffset(source, Math.max(start, end - 1)),
+    endLine: lineAtOffsetFromStarts(lineStarts, Math.max(start, end - 1)),
     newline: detectNewline(raw),
   };
 }

package/src/project.js

@@ -12,7 +12,7 @@ stability=architecture
 
 import { readFile } from "node:fs/promises";
 import { loadConfig } from "./config.js";
-import { findAttachedDeclaration, extractImports } from "./declaration.js";
+import { createDeclarationScanContext, findAttachedDeclaration, extractImports } from "./declaration.js";
 import { collectSourceFiles } from "./files.js";
 import { parseLlmnavBlocks } from "./parser.js";
 import { loadRegistry } from "./registry.js";
@@ -34,6 +34,7 @@ export async function scanProject(root, options = {}) {
     sourceBytes += Buffer.byteLength(source);
     semanticBytes += blocks.reduce((sum, block) => sum + Buffer.byteLength(block.raw), 0);
     const imports = extractImports(source, relativePath);
+    const declarationScanContext = createDeclarationScanContext(source);
     const fileRecord = {
       absolutePath,
       relativePath,
@@ -47,7 +48,7 @@ export async function scanProject(root, options = {}) {
     };
     fileRecords.push(fileRecord);
     for (const block of blocks) {
-      const declaration = findAttachedDeclaration(source, block, relativePath);
+      const declaration = findAttachedDeclaration(source, block, relativePath, declarationScanContext);
       records.push({
         root,
         absolutePath,

package/src/prompt-bundle.js

@@ -12,7 +12,7 @@ stability=architecture
 
 import path from "node:path";
 import { loadConfig } from "./config.js";
-import { approximateTokens, compareText, readText, sha256, stableJson, stableStringify, toPosix } from "./util.js";
+import { approximateTokens, assertNoSymlinkTraversal, compareText, readText, sha256, stableJson, stableStringify, toPosix } from "./util.js";
 
 export const PROMPT_BUNDLE_SCHEMA_VERSION = 1;
 
@@ -62,7 +62,11 @@ export function isCompatiblePromptPrefixBundle(bundle, repositoryId = undefined)
 export async function loadPromptPrefixBundle(root) {
   const { config } = await loadConfig(root);
   const relativePath = `${toPosix(config.generation.cacheDirectory).replace(/\/+$/u, "")}/prompt-prefix.json`;
-  const content = await readText(path.join(root, relativePath), "");
+  const bundlePath = path.join(root, relativePath);
+  const manifestPath = path.join(root, config.generation.cacheDirectory, "manifest.json");
+  await assertNoSymlinkTraversal(root, bundlePath, relativePath);
+  await assertNoSymlinkTraversal(root, manifestPath, `${config.generation.cacheDirectory}/manifest.json`);
+  const content = await readText(bundlePath, "");
   if (!content) throw new Error(`Missing generated prompt bundle ${relativePath}.`);
   let bundle;
   try {
@@ -73,7 +77,7 @@ export async function loadPromptPrefixBundle(root) {
   if (!isCompatiblePromptPrefixBundle(bundle, config.repositoryId)) {
     throw new Error(`Incompatible generated prompt bundle ${relativePath}.`);
   }
-  const manifestContent = await readText(path.join(root, config.generation.cacheDirectory, "manifest.json"), "");
+  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;

package/src/registry.js

@@ -11,13 +11,14 @@ stability=contract
 
 import path from "node:path";
 import { ID_PATTERN } from "./spec.js";
-import { atomicWrite, parseJsonLines, readText } from "./util.js";
+import { assertNoSymlinkTraversal, atomicWrite, parseJsonLines, readText } from "./util.js";
 
 const REGISTRY_STATES = new Set(["active", "redirect", "replaced", "retired"]);
 const REGISTRY_KEYS = new Set(["id", "state", "to", "by"]);
 
 export async function loadRegistry(root) {
   const registryPath = path.join(root, ".llmnav", "ids.jsonl");
+  await assertNoSymlinkTraversal(root, registryPath, ".llmnav/ids.jsonl");
   const text = await readText(registryPath, "");
   const parsed = parseJsonLines(text, registryPath);
   const byId = new Map();
@@ -72,8 +73,13 @@ export async function loadRegistry(root) {
 }
 
 export async function ensureActiveIds(root, registry, ids) {
+  const registryPath = path.join(root, ".llmnav", "ids.jsonl");
+  if (path.resolve(registry.registryPath) !== path.resolve(registryPath)) {
+    throw new Error("Registry path does not belong to the requested project root.");
+  }
+  await assertNoSymlinkTraversal(root, registryPath, ".llmnav/ids.jsonl");
   const { records, changed } = mergeActiveIds(registry, ids);
-  if (changed) await atomicWrite(registry.registryPath, renderRegistryRecords(records));
+  if (changed) await atomicWrite(registryPath, renderRegistryRecords(records));
   return { records, changed };
 }
 

package/src/search.js

@@ -14,7 +14,7 @@ import path from "node:path";
 import { loadConfig } from "./config.js";
 import { resolveRegistryId, loadRegistry } from "./registry.js";
 import { renderCompactCard } from "./generator.js";
-import { approximateTokens, compareText, readJsonSafe, readText, sha256, toPosix, truncateToTokenBudget } from "./util.js";
+import { assertNoSymlinkTraversal, approximateTokens, compareText, readJsonSafe, readText, sha256, toPosix, truncateToTokenBudget } from "./util.js";
 import {
   buildInvertedIndex,
   isCompatibleSearchIndex,
@@ -33,12 +33,21 @@ export async function loadSearchData(root) {
   const { config } = await loadConfig(root);
   await recoverGenerationTransaction(root, { cacheDirectory: config.generation.cacheDirectory });
   const cacheRoot = path.join(root, config.generation.cacheDirectory);
-  const index = await readJsonSafe(path.join(cacheRoot, "index.json"), null);
+  await assertNoSymlinkTraversal(root, cacheRoot, config.generation.cacheDirectory);
+  const indexPath = path.join(cacheRoot, "index.json");
+  const manifestPath = path.join(cacheRoot, "manifest.json");
+  const graphPath = path.join(cacheRoot, "graph.json");
+  const searchPath = path.join(cacheRoot, "search-index.json");
+  const lexiconPath = path.join(root, ".llmnav", "lexicon.json");
+  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 lexicon = await readJsonSafe(path.join(root, ".llmnav", "lexicon.json"), { version: 1, aliases: {} });
-  const manifest = await readJsonSafe(path.join(cacheRoot, "manifest.json"), null);
+  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 graphText = await readText(path.join(cacheRoot, "graph.json"), null);
+  const graphText = await readText(graphPath, null);
   let graph = null;
   if (graphText !== null) {
     try {
@@ -54,7 +63,7 @@ export async function loadSearchData(root) {
   );
   if (!graphMatches) graph = null;
   const searchRelative = `${toPosix(config.generation.cacheDirectory).replace(/\/+$/u, "")}/search-index.json`;
-  const searchText = await readText(path.join(cacheRoot, "search-index.json"), null);
+  const searchText = await readText(searchPath, null);
   let searchIndex = null;
   if (searchText !== null) {
     try {

package/src/spec.js

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

package/src/transaction.js

@@ -47,6 +47,7 @@ export async function acquireGenerationLock(root, options = {}) {
   const controlDirectory = path.join(root, ".llmnav");
   const lockPath = path.join(controlDirectory, "generation.lock");
   await assertNoSymlinkTraversal(root, controlDirectory, ".llmnav");
+  await assertNoSymlinkTraversal(root, lockPath, ".llmnav/generation.lock");
   await mkdir(controlDirectory, { recursive: true });
   const ownerId = options.ownerId ?? createTransactionId();
   const timeoutMs = options.timeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS;
@@ -95,6 +96,8 @@ export async function commitGeneratedCache(root, cacheDirectory, artifacts, opti
   const transactionsDirectory = path.join(controlDirectory, ".transactions");
   const journalPath = path.join(controlDirectory, "generation-transaction.json");
   await assertNoSymlinkTraversal(root, controlDirectory, ".llmnav");
+  await assertNoSymlinkTraversal(root, transactionsDirectory, ".llmnav/.transactions");
+  await assertNoSymlinkTraversal(root, journalPath, ".llmnav/generation-transaction.json");
   await assertNoSymlinkTraversal(root, cachePath, cacheRelative);
   const recovery = await recoverGenerationTransaction(root, {
     cacheDirectory: cacheRelative,
@@ -106,6 +109,7 @@ export async function commitGeneratedCache(root, cacheDirectory, artifacts, opti
   const transactionPath = path.join(transactionsDirectory, transactionId);
   const stagePath = path.join(transactionPath, "stage");
   const backupPath = path.join(transactionPath, "backup");
+  await assertNoSymlinkTraversal(root, transactionPath, relativePosix(root, transactionPath));
   const hadExistingCacheAtStart = await pathExists(cachePath);
   let controlRecords = [];
   await mkdir(stagePath, { recursive: true });
@@ -218,6 +222,11 @@ export async function recoverGenerationTransaction(root, options = {}) {
   const controlDirectory = path.join(root, ".llmnav");
   await assertNoSymlinkTraversal(root, controlDirectory, ".llmnav");
   const journalPath = path.join(controlDirectory, "generation-transaction.json");
+  await assertNoSymlinkTraversal(root, journalPath, ".llmnav/generation-transaction.json");
+  if (options.cacheDirectory) {
+    const configuredCacheDirectory = projectRelativePath(options.cacheDirectory, "cacheDirectory");
+    await assertNoSymlinkTraversal(root, path.join(root, configuredCacheDirectory), configuredCacheDirectory);
+  }
   const journal = await readJson(journalPath, null);
   if (!journal) return { recovered: false, action: "none" };
   validateJournal(root, journal, options.cacheDirectory);

package/src/util.js

@@ -77,11 +77,26 @@ export function relativePosix(root, absolutePath) {
 }
 
 export function lineAtOffset(source, offset) {
-  let line = 1;
-  for (let index = 0; index < offset; index += 1) {
-    if (source.charCodeAt(index) === 10) line += 1;
+  return lineAtOffsetFromStarts(buildLineStarts(source), offset);
+}
+
+export function buildLineStarts(source) {
+  const starts = [0];
+  for (let index = 0; index < source.length; index += 1) {
+    if (source.charCodeAt(index) === 10) starts.push(index + 1);
+  }
+  return starts;
+}
+
+export function lineAtOffsetFromStarts(lineStarts, offset) {
+  let low = 0;
+  let high = lineStarts.length;
+  while (low < high) {
+    const middle = Math.floor((low + high) / 2);
+    if (lineStarts[middle] <= offset) low = middle + 1;
+    else high = middle;
   }
-  return line;
+  return Math.max(1, low);
 }
 
 export function offsetAtLine(source, targetLine) {