llmnav 0.6.1 → 0.6.4

package/CHANGELOG.md

@@ -6,6 +6,33 @@ The npm package follows Semantic Versioning. The `llmnav/N` source protocol is v
 
 ## [Unreleased]
 
+## [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
+
+* Added generated boundary signals for persistent dotted JSON filename protocols, versioned schema literals, and TypeScript Tauri invoke adapters.
+
+### Fixed
+
+* Stopped classifying high-fan-in domain contract hubs as broad utilities solely because they export many declarations.
+* Made tag-driven publication create an idempotent GitHub Release after npm integrity verification or publication succeeds.
+
 ## [0.6.1] — 2026-08-10
 
 ### Added

package/README.md

@@ -18,7 +18,7 @@ LLMNav is not a documentation generator, an embedding database, or a reason to a
 * Machine-readable changed-card, affected-boundary, and affected-catalog output
 * Exported API and effective configuration contract fingerprints
 * TypeScript and Go declaration enrichment with declaration-level body hashes
-* Generated route, event, schema, migration, and command boundaries
+* Generated artifact, route, event, schema, migration, runtime, and command boundaries
 * SARIF 2.1.0 diagnostic output
 * Optional deterministic card-range search shards for very large repositories
 * Strict repository-local imports for generated definition and reference indexes
@@ -250,7 +250,7 @@ Do not annotate trivial getters, generated files, obvious wrappers, every test f
 
 ## Current implementation boundary
 
-Version 0.6 adds a deterministic coverage audit that prioritizes root and nested-package entrypoints, structural boundaries, Rust/Tauri runtime signals, and high fan-in modules while suppressing declaration files, dependency caches, test support code, simple barrels, and broad utilities. It suggests narrow coverage rules but never writes cards or invents semantic roles. Use `llmnav audit --summary --json` for a compact automation result or `llmnav audit --json --output .llmnav/audit.json` to keep the full candidate report out of captured stdout.
+Version 0.6 adds a deterministic coverage audit that prioritizes root and nested-package entrypoints, structural boundaries, persistent artifact filename protocols, versioned schema literals, Rust/Tauri runtime signals, TypeScript Tauri invoke adapters, and high fan-in modules. It suppresses declaration files, dependency caches, test support code, simple barrels, and low-fan-in broad utilities. It suggests narrow coverage rules but never writes cards or invents semantic roles. Use `llmnav audit --summary --json` for a compact automation result or `llmnav audit --json --output .llmnav/audit.json` to keep the full candidate report out of captured stdout.
 
 LLMNav does not discover sibling repositories automatically and does not ship an MCP server, embedding database, hosted service, SCIP generator, or complete language-aware call graph. External tools may export the documented compact graph-input schema. Generated structure never writes derived edges into source cards.
 

package/docs/api.md

@@ -60,7 +60,7 @@ console.log(stats.parsedFiles, stats.reusedFiles);
 
 Stat hints are an optimization, not deterministic output. The returned `fileState` contains only repository-relative generated data.
 
-Attached symbol declarations expose generated `language`, `exported`, `visibility`, optional Go `receiver`, `endOffset`, and declaration `bodyHash` fields. Indexed cards also expose sorted route, event, schema, migration, and command `boundaries` with confidence and evidence.
+Attached symbol declarations expose generated `language`, `exported`, `visibility`, optional Go `receiver`, `endOffset`, and declaration `bodyHash` fields. Indexed cards also expose sorted artifact, route, event, schema, migration, runtime, and command `boundaries` with confidence and evidence.
 
 ## Audit annotation coverage
 

package/docs/architecture.md

@@ -64,13 +64,13 @@ Each card carries three independent hashes.
 
 Symbol attachment records the detected language, public/exported status, visibility, Go receiver when present, declaration span, and a declaration-level body hash. TypeScript and Go use dedicated deterministic declaration patterns; JavaScript, Rust, Python, and generic C-like declarations retain the compatible fallback patterns.
 
-Generated cards may contain a sorted `boundaries` array. LLMNav detects `route`, `event`, `schema`, `migration`, and `command` boundaries from repository-relative paths and controlled semantic effects or risks. Each record includes `confidence` and explicit evidence such as `path`, `effect`, or `risk`. These hints are generated navigation data and are never copied into source comments.
+Generated cards may contain a sorted `boundaries` array. LLMNav detects `artifact`, `route`, `event`, `schema`, `migration`, `runtime`, and `command` boundaries from repository-relative paths, controlled semantic effects or risks, and narrow source evidence. Source evidence includes persistent dotted JSON filename builders, versioned schema literals, Tauri commands and invoke adapters, and platform lifecycle code. Each record includes `confidence` and explicit evidence. These hints are generated navigation data and are never copied into source comments.
 
 Generation compares the previous and current primary indexes to emit `affectedBoundaries`. The report preserves the card change and hash dimensions while adding module IDs, structural boundary records, outbound relation targets, and reverse semantic dependents. It is returned through the API and `generate --json`; it is not stored in source cards.
 
 ## Annotation coverage audit
 
-The read-only audit combines package entrypoints, public re-export reachability, generated structural boundaries, import fan-in, exported declaration counts, and source size. It lowers the priority of broad utilities, declaration files, non-production support paths, and pure re-export barrels. Every candidate retains its score inputs and deterministic repository-relative path.
+The read-only audit combines package entrypoints, public re-export reachability, generated structural boundaries, import fan-in, exported declaration counts, and source size. It lowers the priority of named utilities and low-fan-in export hubs, declaration files, non-production support paths, and pure re-export barrels. High-fan-in domain contract hubs do not receive the broad-utility penalty merely because they export many declarations. Every candidate retains its score inputs and deterministic repository-relative path.
 
 This analyzer deliberately stops before semantic generation. Structure can identify a file worth inspecting, but it cannot safely invent a durable ID, role, ownership statement, invariant, risk, or relation. Accepted boundaries become explicit source cards, path-specific coverage rules, and retrieval regression queries through normal review.
 

package/docs/publishing.md

@@ -31,7 +31,7 @@ npm run release:check
 
 ## 3. Configure npm authentication
 
-The supplied release workflow uses GitHub's OIDC token through npm Trusted Publishers. The GitHub source repository is private, so the workflow explicitly disables provenance; npm accepts provenance only from public source repositories. If the repository becomes public, enable provenance in both `package.json` and the workflow after a successful release check.
+The supplied release workflow uses GitHub's OIDC token through npm Trusted Publishers. The GitHub source repository is private, so the workflow explicitly disables provenance; npm accepts provenance only from public source repositories. If the repository becomes public, enable provenance in both `package.json` and the workflow after a successful release check. 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.
 
@@ -65,7 +65,7 @@ git tag v0.6.0
 git push origin v0.6.0
 ```
 
-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.
+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.
 
 ## 6. Verify from a clean directory
 

package/docs/quickstart.md

@@ -19,7 +19,7 @@ Source roots and evaluation files must remain inside the repository. The generat
 npx llmnav audit
 ```
 
-Start with high and medium candidates. The audit explains whether a file is a package entrypoint, public API, generated structural boundary, or high fan-in module. It does not write source or invent card contents. Declaration files and common non-production or utility shapes are suppressed so the result is a review queue, not a demand to annotate every file.
+Start with high and medium candidates. The audit explains whether a file is a package entrypoint, public API, generated structural boundary, or high fan-in module. Narrow source signals also identify versioned schema literals, persistent dotted JSON filename protocols, and Tauri invoke adapters. It does not write source or invent card contents. Declaration files and common non-production or low-fan-in utility shapes are suppressed so the result is a review queue, not a demand to annotate every file.
 
 After accepting a candidate, write its durable meaning by inspecting the source, add a narrow `coverageRules` entry for that exact boundary, and add a real task-language query to `.llmnav/eval/queries.jsonl`. Use `npx llmnav audit --fail-on high` in CI only after the initial review.
 

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.1",
+  "version": "0.6.4",
   "description": "A deterministic semantic navigation layer for LLM coding agents.",
   "type": "module",
   "bin": {

package/src/audit.js

@@ -66,7 +66,7 @@ export async function auditProject(root) {
     const reexportBarrel = isReexportBarrel(record.source ?? "", file);
     const basename = path.posix.basename(file, path.posix.extname(file)).toLowerCase();
     const broadUtility = UTILITY_NAME_PATTERN.test(basename) ||
-      (exportedDeclarations >= 10 && !entrypoint && !publicApi && boundaries.length === 0);
+      (exportedDeclarations >= 10 && importers <= 1 && !entrypoint && !publicApi && boundaries.length === 0);
     const nonProduction = NON_PRODUCTION_PATH_PATTERN.test(file);
     const largeSource = record.sourceBytes >= LARGE_SOURCE_BYTES;
     const hasSignal = entrypoint || publicApi || boundaries.length > 0 || importers > 0 || exportedDeclarations > 0 || largeSource;

package/src/boundaries.js

@@ -1,9 +1,9 @@
 /* llmnav/1 module
 id=llmnav.structure.boundaries
-role=Detect route, event, schema, migration, and command boundaries from generated local evidence.
+role=Detect durable artifact, route, event, schema, migration, runtime, and command boundaries from generated local evidence.
 owns=boundary kinds|confidence assignment|boundary evidence
 excludes=framework execution|source annotations
-search=boundary detection|route schema migration|command event
+search=boundary detection|artifact route schema migration|command event runtime
 rel=workflow>llmnav.index.generate
 stability=architecture
 */
@@ -11,7 +11,7 @@ stability=architecture
 import path from "node:path";
 import { compareText, toPosix } from "./util.js";
 
-export const BOUNDARY_KINDS = Object.freeze(["command", "event", "migration", "route", "runtime", "schema"]);
+export const BOUNDARY_KINDS = Object.freeze(["artifact", "command", "event", "migration", "route", "runtime", "schema"]);
 
 export function detectBoundaries(record) {
   const relativePath = toPosix(record.relativePath).toLowerCase();
@@ -40,6 +40,13 @@ export function detectBoundaries(record) {
       /(?:schema\.(?:json|ya?ml)|\.(?:proto|graphql|gql))$/u.test(relativePath)) {
     add("schema", "high", "path");
   }
+  if (/\bschemaVersion\s*:\s*["'][^"'\r\n]+\/v\d+(?:\.\d+)*["']/u.test(source)) {
+    add("schema", "high", "versioned-schema-literal");
+  }
+  if (/\bexport\s+(?:async\s+)?function\s+[A-Za-z_$][\w$]*FileName\b/u.test(source) &&
+      /["'`][^"'`\r\n]*\.[a-z0-9-]+\.json["'`]/iu.test(source)) {
+    add("artifact", "medium", "persistent-json-filename");
+  }
   if (risks.includes("migration") || /(?:^|\/)(?:migrations?|migrate)(?:\/|$)/u.test(relativePath)) {
     add("migration", "high", risks.includes("migration") ? "risk" : "path");
   }
@@ -49,6 +56,11 @@ export function detectBoundaries(record) {
   if (/\.rs$/u.test(relativePath) && /#\[tauri::command\]|tauri::generate_handler!/u.test(source)) {
     add("command", "high", "tauri-command");
   }
+  if (/\.[cm]?[jt]sx?$/u.test(relativePath) &&
+      /\bgetTauriInvoke\s*\(/u.test(source) &&
+      /\binvoke(?:\s*<[^;\r\n]+?>)?\s*\(/u.test(source)) {
+    add("command", "high", "tauri-invoke");
+  }
   if (/\.rs$/u.test(relativePath) &&
       /#\[cfg\((?:windows|unix|target_(?:os|family))/u.test(source) &&
       /\b(?:Drop|shutdown|terminate|kill|process_group|job_object)\b/iu.test(source)) {

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 = 5;
 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/index.d.ts

@@ -58,7 +58,7 @@ export interface Declaration {
 }
 
 export interface DetectedBoundary {
-  kind: "command" | "event" | "migration" | "route" | "schema";
+  kind: "artifact" | "command" | "event" | "migration" | "route" | "runtime" | "schema";
   confidence: "high" | "medium";
   evidence: string[];
 }

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