llmnav 0.6.6 → 0.7.1

package/CHANGELOG.md

@@ -6,6 +6,19 @@ The npm package follows Semantic Versioning. The `llmnav/N` source protocol is v
 
 ## [Unreleased]
 
+## [0.7.1] — 2026-08-13
+
+### Fixed
+
+* Revalidated managed-write parent identity and symbolic-link traversal immediately before atomic replacement, preventing a concurrent directory swap from redirecting source formatting or control-file writes outside the repository.
+
+## [0.7.0] — 2026-08-13
+
+### Added
+
+* Added `llmnav migrate --check/--write` and `migrateProject` to report generated-format compatibility and apply full transactional upgrades from canonical source.
+* Added migration regression coverage for read-only planning, idempotent writes, validation blocking, and transaction rollback.
+
 ## [0.6.6] — 2026-08-12
 
 ### Added

package/README.md

@@ -179,6 +179,7 @@ Line-comment cards require an explicit terminator and work with `//`, `#`, and `
 | `llmnav context` | Build a bounded context bundle around one ID |
 | `llmnav eval` | Run repository-specific search regression queries |
 | `llmnav doctor` | Verify installation, cache integrity, transaction recovery, and drift |
+| `llmnav migrate` | Check or transactionally apply generated-format upgrades from canonical source |
 | `llmnav spec` | Print source-spec vocabularies and key order |
 | `llmnav tools` | Print stable provider-neutral agent tool schemas |
 | `llmnav bundle` | Inspect the generated prompt-prefix cache partitions |
@@ -291,7 +292,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.6 CLI. The source format remains `llmnav/1`; npm package changes and source-grammar changes are versioned independently.
+LLMNav is an experimental protocol and a usable v0.7 CLI. The source format remains `llmnav/1`; npm package changes and source-grammar changes are versioned independently.
 
 ## License
 

package/ROADMAP.md

@@ -73,12 +73,23 @@ Implemented:
 * path-specific coverage-rule suggestions without automatic source annotation
 * audit guidance in generated agent instructions and package scripts
 
+## 0.7 — generated-format migration
+
+Implemented:
+
+* read-only compatibility reports for the primary index and generated accelerators
+* full migration plans reconstructed from canonical repository source
+* explicit transactional writes with staging verification, rollback, and interrupted-process recovery
+* validation blocking before mutation and idempotent repeated writes
+* public CLI, ESM API, TypeScript declarations, and migration documentation
+
 ## 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.
 
 In progress:
 
+* Generated-format migration tooling is implemented for the current public formats; compatibility guarantees still need a documented support and deprecation policy.
 * 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.

package/docs/api.md

@@ -229,6 +229,7 @@ The package exports versioned generated-format constants:
 import {
   CONTRACT_FINGERPRINT_SCHEMA_VERSION,
   FILE_STATE_SCHEMA_VERSION,
+  MIGRATION_REPORT_SCHEMA_VERSION,
   SEARCH_INDEX_ENCODING,
   SEARCH_INDEX_SCHEMA_VERSION,
   SEARCH_SHARD_ENCODING,
@@ -240,6 +241,8 @@ import {
 } from "llmnav";
 ```
 
+`migrateProject(root, { write: false })` returns a schemaVersion 1 compatibility report and a full-regeneration plan without committing generated artifacts. With `{ write: true }`, it applies a required upgrade through the same generation lock and recoverable transaction used by `generateProject`. Source validation errors stop the operation before mutation, and successful repeated writes are no-ops.
+
 `diagnosticsToSarif(diagnostics)` maps existing diagnostics to a deterministic SARIF 2.1.0 object without discovering or mutating diagnostics.
 
 `diagnosticsToEditor(diagnostics)` groups repository-relative diagnostics into schemaVersion 1 documents with zero-based ranges and stable severity mappings. `renderEditorDiagnostics` serializes the report deterministically. `getEditorIntegration("vscode")` returns a VS Code task and custom problem matcher without modifying editor files.

package/docs/cli.md

@@ -212,6 +212,19 @@ Checks:
 
 `doctor` may perform transaction recovery, but it does not regenerate stale cache content.
 
+## `llmnav migrate`
+
+```sh
+llmnav migrate [--check] [--json]
+llmnav migrate --write [--json]
+```
+
+The default and `--check` modes inspect the primary index, search accelerator, file state, graph, graph state, prompt-prefix bundle, and manifest against the formats supported by the installed LLMNav version. They also perform a full source reconstruction in check mode. No generated artifacts are committed. Exit status 1 means migration is required or source validation blocks a safe migration.
+
+`--write` first builds the same plan from canonical source. If source validation succeeds and migration is required, it performs a full regeneration through the normal generation lock, staging verification, directory transaction, rollback, and interrupted-process recovery boundaries. It never rewrites source cards or reassigns semantic IDs. Repeating `--write` after a successful migration makes no changes and exits successfully.
+
+`--check` and `--write` are mutually exclusive. Review JSON `formats`, `changedFiles`, and `diagnostics` before applying an upgrade in automation.
+
 ## `llmnav spec`
 
 ```sh

package/docs/migration.md

@@ -1,23 +1,24 @@
 # Gradual migration
 
-## Upgrade to 0.5
+## Upgrade to 0.7
 
 No source-card migration is required. Keep every `llmnav/1` comment and the existing `.llmnav/cache/index.json` consumer contract.
 
 Upgrade and regenerate:
 
 ```sh
-npm install --save-dev llmnav@^0.6.0
+npm install --save-dev llmnav@^0.7.0
 npx llmnav init --agents all
-npx llmnav generate
+npx llmnav migrate --check
+npx llmnav migrate --write
 npx llmnav doctor
 ```
 
-The regeneration preserves the schemaVersion 1 primary index and existing graph artifacts, then adds deterministic `prompt-prefix.json`. Initialization refreshes the managed agent protocol so structured-tool hosts learn the trusted-root boundary. Volatile `state/`, `.transactions/`, and `generation-transaction.json` remain ignored.
+The migration planner preserves the `llmnav/1` source comments and schemaVersion 1 primary-index contract. It reports incompatible or missing generated formats before applying a full transactional regeneration from canonical source. Initialization refreshes the managed agent protocol so structured-tool hosts learn the trusted-root boundary. Volatile `state/`, `.transactions/`, and `generation-transaction.json` remain ignored.
 
-Review `generate --json` during the first upgrade. Existing cards are reported as added only when no previous compatible primary index exists. The prompt-prefix artifact appears in affected catalogs when its bytes change. `LNV009` remains a non-failing contract-fingerprint review signal.
+Review `migrate --check --json` during the first upgrade. Exit status 1 means generated formats need migration or source validation prevents a safe write. `migrate --write` stages and verifies a complete replacement before swapping the cache, and a repeated write is a no-op. Existing cards are reported as added only when no previous compatible primary index exists. `LNV009` remains a non-failing contract-fingerprint review signal.
 
-Do not delete `index.json`, rewrite semantic IDs, or copy generated paths or graph edges into comments. v0.5 tool schemas, prompt partitions, editor diagnostics, and host examples are additive; no source-card migration is required.
+Do not delete `index.json`, rewrite semantic IDs, or copy generated paths or graph edges into comments. The migration command never edits source cards or the semantic ID registry; it upgrades disposable generated formats from their canonical inputs.
 
 ## Do not annotate the whole repository
 

package/package.json

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

package/src/agents.js

@@ -42,19 +42,19 @@ export async function installAgentInstructions(root, adapters = ["agents"]) {
     if (adapter === "agents") {
       const target = path.join(root, "AGENTS.md");
       await assertNoSymlinkTraversal(root, target, "AGENTS.md");
-      if (await upsertMarkdown(target, "# Repository instructions", AGENT_PROTOCOL)) {
+      if (await upsertMarkdown(root, target, "# Repository instructions", AGENT_PROTOCOL)) {
         changed.push("AGENTS.md");
       }
     } else if (adapter === "claude") {
       const target = path.join(root, "CLAUDE.md");
       await assertNoSymlinkTraversal(root, target, "CLAUDE.md");
-      if (await upsertMarkdown(target, "# Claude Code instructions", AGENT_PROTOCOL)) {
+      if (await upsertMarkdown(root, target, "# Claude Code instructions", AGENT_PROTOCOL)) {
         changed.push("CLAUDE.md");
       }
     } else if (adapter === "copilot") {
       const target = path.join(root, ".github", "copilot-instructions.md");
       await assertNoSymlinkTraversal(root, target, ".github/copilot-instructions.md");
-      if (await upsertMarkdown(target, "# GitHub Copilot instructions", AGENT_PROTOCOL)) {
+      if (await upsertMarkdown(root, target, "# GitHub Copilot instructions", AGENT_PROTOCOL)) {
         changed.push(".github/copilot-instructions.md");
       }
     } else if (adapter === "cursor") {
@@ -63,7 +63,7 @@ export async function installAgentInstructions(root, adapters = ["agents"]) {
       const content = `---\ndescription: Use LLMNav before broad codebase exploration\nalwaysApply: true\n---\n\n${AGENT_PROTOCOL}\n`;
       const existing = await readText(target, "");
       if (existing !== content) {
-        await atomicWrite(target, content);
+        await atomicWrite(root, target, content);
         changed.push(".cursor/rules/llmnav.mdc");
       }
     }
@@ -73,7 +73,7 @@ export async function installAgentInstructions(root, adapters = ["agents"]) {
   await assertNoSymlinkTraversal(root, canonicalPath, ".llmnav/AGENT_INSTRUCTIONS.md");
   const canonical = `# LLMNav agent protocol\n\n${AGENT_PROTOCOL}\n`;
   if ((await readText(canonicalPath, "")) !== canonical) {
-    await atomicWrite(canonicalPath, canonical);
+    await atomicWrite(root, canonicalPath, canonical);
     changed.push(".llmnav/AGENT_INSTRUCTIONS.md");
   }
   return changed;
@@ -102,7 +102,7 @@ function adapterUsageError(message) {
   return error;
 }
 
-async function upsertMarkdown(filePath, title, block) {
+async function upsertMarkdown(root, filePath, title, block) {
   await mkdir(path.dirname(filePath), { recursive: true });
   const existing = await readText(filePath, "");
   let next;
@@ -124,6 +124,6 @@ async function upsertMarkdown(filePath, title, block) {
     next = `${existing.trimEnd()}\n\n${block}\n`;
   }
   if (next === existing) return false;
-  await atomicWrite(filePath, next);
+  await atomicWrite(root, filePath, next);
   return true;
 }

package/src/cli.js

@@ -39,6 +39,7 @@ import { getAgentToolDefinitions } from "./agent-protocol.js";
 import { loadPromptPrefixBundle } from "./prompt-bundle.js";
 import { diagnosticsToEditor, getEditorIntegration } from "./editor.js";
 import { AUDIT_PRIORITIES, auditHasFindings, auditProject } from "./audit.js";
+import { migrateProject } from "./migration.js";
 
 const VALUE_OPTIONS = new Set(["--root", "--format", "--top", "--depth", "--budget", "--max-edges", "--agents", "--file", "--fail-on", "--output"]);
 
@@ -53,6 +54,7 @@ const COMMAND_OPTIONS = Object.freeze({
   context: new Set(["--depth", "--budget", "--max-edges", "--root", "--json"]),
   eval: new Set(["--file", "--top", "--root", "--json"]),
   doctor: new Set(["--root", "--json"]),
+  migrate: new Set(["--check", "--write", "--root", "--json"]),
   audit: new Set(["--root", "--json", "--summary", "--fail-on", "--output"]),
   spec: new Set(["--root", "--json"]),
   tools: new Set(["--json"]),
@@ -100,6 +102,8 @@ export async function runCli(argv) {
       return runEval(root, args, json);
     case "doctor":
       return runDoctor(root, json);
+    case "migrate":
+      return runMigrate(root, args, json);
     case "audit":
       return runAudit(root, args, json);
     case "spec":
@@ -295,6 +299,26 @@ async function runDoctor(root, json) {
   return result.ok ? 0 : 1;
 }
 
+async function runMigrate(root, args, json) {
+  if (hasFlag(args, "--check") && hasFlag(args, "--write")) {
+    throw usageError("migrate accepts either --check or --write, not both.");
+  }
+  const result = await migrateProject(root, { write: hasFlag(args, "--write") });
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    for (const format of result.formats) {
+      console.log(`${format.status} ${format.id}: ${format.path}${format.detail ? ` (${format.detail})` : ""}`);
+    }
+    if (result.diagnostics.length > 0) printDiagnostics(result.diagnostics, "text");
+    if (result.ok && result.applied) console.log(`Migrated ${result.changedFiles.length} generated file(s) transactionally.`);
+    else if (result.ok) console.log("Generated LLMNav formats are current.");
+    else if (result.required && result.mode === "check") console.log("Migration is required. Run llmnav migrate --write after reviewing this plan.");
+    else if (result.required) console.error("Migration was not applied because source validation failed.");
+  }
+  return result.ok ? 0 : 1;
+}
+
 async function runAudit(root, args, json) {
   const failOn = getOption(args, "--fail-on") ?? "none";
   if (failOn !== "none" && !AUDIT_PRIORITIES.includes(failOn)) {
@@ -315,7 +339,7 @@ async function runAudit(root, args, json) {
     ? { schemaVersion: result.schemaVersion, repositoryId: result.repositoryId, summary: result.summary, failOn }
     : report;
   if (outputPath) {
-    await atomicWrite(outputPath, `${JSON.stringify(selectedReport, null, 2)}\n`);
+    await atomicWrite(root, outputPath, `${JSON.stringify(selectedReport, null, 2)}\n`);
   }
   if (json) {
     console.log(JSON.stringify(outputPath
@@ -492,6 +516,7 @@ Usage
   llmnav context <semantic-id> [--depth 1] [--budget 2500] [--max-edges 24]
   llmnav eval [--file path] [--top 5]
   llmnav doctor
+  llmnav migrate [--check|--write]
   llmnav audit [--summary] [--output path] [--fail-on none|high|medium|low]
   llmnav spec
   llmnav tools [--json]

package/src/formatter.js

@@ -27,7 +27,7 @@ export async function formatProject(root, options = {}) {
     errors.push(...result.errors.map((error) => ({ file: relativePath, ...error })));
     if (!result.changed) continue;
     changedFiles.push(relativePath);
-    if (!options.check) await atomicWrite(filePath, result.source);
+    if (!options.check) await atomicWrite(root, filePath, result.source, options.atomicWriteOptions);
   }
   const ok = errors.length === 0 && (options.check ? changedFiles.length === 0 : true);
   return { ok, changedFiles, errors };

package/src/incremental.js

@@ -165,7 +165,7 @@ export function buildFileStateFromProject(project) {
 
 export async function persistStatHints(root, hintsPath, statHints) {
   await assertNoSymlinkTraversal(root, hintsPath, relativePosix(root, hintsPath));
-  await atomicWrite(hintsPath, stableStringify(statHints));
+  await atomicWrite(root, hintsPath, stableStringify(statHints));
 }
 
 export function renderFileState(fileState) {

package/src/index.d.ts

@@ -561,6 +561,27 @@ export interface GenerationResult {
   transaction: TransactionResult;
 }
 
+export interface MigrationFormatRecord {
+  id: string;
+  path: string;
+  status: "current" | "missing" | "incompatible";
+  expected: string;
+  detail: string | null;
+}
+
+export interface MigrationResult {
+  schemaVersion: 1;
+  ok: boolean;
+  mode: "check" | "write";
+  required: boolean;
+  applied: boolean;
+  changedFiles: string[];
+  formats: MigrationFormatRecord[];
+  previousFormats?: MigrationFormatRecord[];
+  diagnostics: Diagnostic[];
+  transaction: TransactionResult;
+}
+
 export interface EvaluationResult {
   ok: boolean;
   errors: string[];
@@ -588,6 +609,7 @@ export const AGENT_OPERATION_SCHEMA_VERSION: 1;
 export const AGENT_TOOL_SCHEMA_VERSION: 1;
 export const BOUNDARY_KINDS: readonly DetectedBoundary["kind"][];
 export const GRAPH_INPUT_SCHEMA_VERSION: 1;
+export const MIGRATION_REPORT_SCHEMA_VERSION: 1;
 export const EDITOR_DIAGNOSTIC_SCHEMA_VERSION: 1;
 export const EDITOR_INTEGRATION_SCHEMA_VERSION: 1;
 export const GRAPH_SCHEMA_VERSION: 1;
@@ -663,6 +685,7 @@ export function auditHasFindings(result: AuditResult, minimumPriority?: AuditPri
 export function findAttachedDeclaration(source: string, block: LlmnavBlock, filePath: string): Declaration | null;
 export function extractImports(source: string, filePath: string): string[];
 export function doctorProject(root: string): Promise<{ ok: boolean; checks: Array<{ name: string; ok: boolean; message: string }> }>;
+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 collectSourceFiles(root: string, config: LlmnavConfig, requestedPaths?: string[]): Promise<string[]>;
 export function findProjectRoot(start?: string): Promise<string>;

package/src/index.js

@@ -49,6 +49,7 @@ export {
 } from "./contracts.js";
 export { findAttachedDeclaration, extractImports } from "./declaration.js";
 export { doctorProject } from "./doctor.js";
+export { MIGRATION_REPORT_SCHEMA_VERSION, migrateProject } from "./migration.js";
 export { evaluateProject } from "./evaluation.js";
 export { collectSourceFiles, findProjectRoot } from "./files.js";
 export { formatProject } from "./formatter.js";

package/src/initializer.js

@@ -123,7 +123,7 @@ async function writeIfMissingOrForced(root, filePath, content, force, changed, d
   const existing = await readText(filePath, null);
   if (existing !== null && !force) return;
   if (existing === content) return;
-  await atomicWrite(filePath, content);
+  await atomicWrite(root, filePath, content);
   changed.push(displayPath);
 }
 
@@ -147,6 +147,6 @@ async function addPackageScripts(root) {
     parsed.scripts[name] = command;
     changed = true;
   }
-  if (changed) await atomicWrite(packagePath, `${JSON.stringify(parsed, null, 2)}\n`);
+  if (changed) await atomicWrite(root, packagePath, `${JSON.stringify(parsed, null, 2)}\n`);
   return changed;
 }

package/src/migration.js

@@ -0,0 +1,194 @@
+/* llmnav/1 module
+id=llmnav.project.migrate
+role=Plan and apply safe generated-format upgrades from canonical repository source.
+owns=migration planning|format compatibility reporting|full transactional regeneration
+excludes=source-card rewriting|semantic ID reassignment
+search=llmnav migrate|cache format upgrade|migration dry run
+invariant=Check mode never commits generated artifacts.
+invariant=Write mode stops before mutation when canonical source validation fails.
+rel=workflow>llmnav.index.generate
+rel=workflow>llmnav.index.transaction
+stability=contract
+*/
+
+import path from "node:path";
+import { loadConfig } from "./config.js";
+import { generateProject } from "./generator.js";
+import { compatibleGraphState, GRAPH_SCHEMA_VERSION, GRAPH_STATE_SCHEMA_VERSION, isCompatibleRepositoryGraph } from "./graph.js";
+import { FILE_STATE_SCHEMA_VERSION, SOURCE_INDEXER_VERSION, usableFileState } from "./incremental.js";
+import { isCompatibleSearchIndex, SEARCH_INDEX_ENCODING, SEARCH_INDEX_SCHEMA_VERSION } from "./inverted-index.js";
+import { isCompatiblePromptPrefixBundle, PROMPT_BUNDLE_SCHEMA_VERSION } from "./prompt-bundle.js";
+import { SEARCH_SHARD_SCHEMA_VERSION } from "./search-shards.js";
+import { assertNoSymlinkTraversal, readText, toPosix } from "./util.js";
+
+export const MIGRATION_REPORT_SCHEMA_VERSION = 1;
+
+export async function migrateProject(root, options = {}) {
+  const write = options.write === true;
+  const { config } = await loadConfig(root);
+  const before = await inspectGeneratedFormats(root, config);
+  const plan = await generateProject(root, {
+    check: true,
+    incremental: false,
+    lockOptions: options.lockOptions,
+    renameOptions: options.renameOptions,
+  });
+  const required = plan.changedFiles.length > 0 || before.some((format) => format.status !== "current");
+  const blocked = plan.counts.error > 0;
+
+  if (!write || blocked || !required) {
+    return {
+      schemaVersion: MIGRATION_REPORT_SCHEMA_VERSION,
+      ok: !blocked && !required,
+      mode: write ? "write" : "check",
+      required,
+      applied: false,
+      changedFiles: plan.changedFiles,
+      formats: before,
+      diagnostics: plan.diagnostics,
+      transaction: plan.transaction,
+    };
+  }
+
+  const applied = await generateProject(root, {
+    check: false,
+    incremental: false,
+    failpoint: options.failpoint,
+    lockOptions: options.lockOptions,
+    renameOptions: options.renameOptions,
+    onTransactionPhase: options.onTransactionPhase,
+  });
+  const after = applied.ok ? await inspectGeneratedFormats(root, config) : before;
+  return {
+    schemaVersion: MIGRATION_REPORT_SCHEMA_VERSION,
+    ok: applied.ok && after.every((format) => format.status === "current"),
+    mode: "write",
+    required,
+    applied: applied.ok,
+    changedFiles: plan.changedFiles,
+    formats: after,
+    previousFormats: before,
+    diagnostics: applied.diagnostics,
+    transaction: applied.transaction,
+  };
+}
+
+async function inspectGeneratedFormats(root, config) {
+  const cacheDirectory = toPosix(config.generation.cacheDirectory).replace(/\/+$/u, "");
+  const cacheRoot = path.join(root, cacheDirectory);
+  await assertNoSymlinkTraversal(root, cacheRoot, cacheDirectory);
+  const repositoryId = config.repositoryId;
+  const records = [];
+
+  const index = await inspectJson(root, path.join(cacheRoot, "index.json"), `${cacheDirectory}/index.json`);
+  records.push(formatRecord(
+    "primary-index",
+    `${cacheDirectory}/index.json`,
+    index,
+    (value) => value?.schemaVersion === 1 && value.repositoryId === repositoryId && Array.isArray(value.cards),
+    "schemaVersion 1",
+  ));
+
+  const search = await inspectJson(root, path.join(cacheRoot, "search-index.json"), `${cacheDirectory}/search-index.json`);
+  records.push(formatRecord(
+    "search-index",
+    `${cacheDirectory}/search-index.json`,
+    search,
+    (value) => isCompatibleSearchIndex(value, repositoryId),
+    `schemaVersion ${SEARCH_INDEX_SCHEMA_VERSION} ${SEARCH_INDEX_ENCODING}`,
+  ));
+
+  const fileState = await inspectJson(root, path.join(cacheRoot, "file-state.json"), `${cacheDirectory}/file-state.json`);
+  records.push(formatRecord(
+    "file-state",
+    `${cacheDirectory}/file-state.json`,
+    fileState,
+    usableFileState,
+    `schemaVersion ${FILE_STATE_SCHEMA_VERSION} indexerVersion ${SOURCE_INDEXER_VERSION}`,
+  ));
+
+  const graph = await inspectJson(root, path.join(cacheRoot, "graph.json"), `${cacheDirectory}/graph.json`);
+  records.push(formatRecord(
+    "repository-graph",
+    `${cacheDirectory}/graph.json`,
+    graph,
+    (value) => isCompatibleRepositoryGraph(value, repositoryId),
+    `schemaVersion ${GRAPH_SCHEMA_VERSION}`,
+  ));
+
+  const graphState = await inspectJson(root, path.join(cacheRoot, "graph-state.json"), `${cacheDirectory}/graph-state.json`);
+  records.push(formatRecord(
+    "graph-state",
+    `${cacheDirectory}/graph-state.json`,
+    graphState,
+    (value) => compatibleGraphState(value, repositoryId),
+    `schemaVersion ${GRAPH_STATE_SCHEMA_VERSION}`,
+  ));
+
+  const prompt = await inspectJson(root, path.join(cacheRoot, "prompt-prefix.json"), `${cacheDirectory}/prompt-prefix.json`);
+  records.push(formatRecord(
+    "prompt-prefix",
+    `${cacheDirectory}/prompt-prefix.json`,
+    prompt,
+    (value) => isCompatiblePromptPrefixBundle(value, repositoryId),
+    `schemaVersion ${PROMPT_BUNDLE_SCHEMA_VERSION}`,
+  ));
+
+  const manifest = await inspectJson(root, path.join(cacheRoot, "manifest.json"), `${cacheDirectory}/manifest.json`);
+  records.push(formatRecord(
+    "manifest",
+    `${cacheDirectory}/manifest.json`,
+    manifest,
+    (value) => compatibleManifest(value, repositoryId),
+    "schemaVersion 1 with current generated format versions",
+  ));
+
+  return records;
+}
+
+function compatibleManifest(value, repositoryId) {
+  return Boolean(
+    value &&
+      value.schemaVersion === 1 &&
+      value.repositoryId === repositoryId &&
+      value.fileStateSchemaVersion === FILE_STATE_SCHEMA_VERSION &&
+      value.searchIndexSchemaVersion === SEARCH_INDEX_SCHEMA_VERSION &&
+      value.graphSchemaVersion === GRAPH_SCHEMA_VERSION &&
+      value.graphStateSchemaVersion === GRAPH_STATE_SCHEMA_VERSION &&
+      value.promptBundleSchemaVersion === PROMPT_BUNDLE_SCHEMA_VERSION &&
+      (value.searchShardSchemaVersion === null || value.searchShardSchemaVersion === SEARCH_SHARD_SCHEMA_VERSION) &&
+      value.files && typeof value.files === "object",
+  );
+}
+
+async function inspectJson(root, filePath, label) {
+  await assertNoSymlinkTraversal(root, filePath, label);
+  const text = await readText(filePath, null);
+  if (text === null) return { state: "missing", value: null, detail: "file is missing" };
+  try {
+    return { state: "present", value: JSON.parse(text), detail: null };
+  } catch (error) {
+    return { state: "malformed", value: null, detail: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+function formatRecord(id, relativePath, inspected, compatible, expected) {
+  if (inspected.state === "missing") return { id, path: relativePath, status: "missing", expected, detail: inspected.detail };
+  if (inspected.state === "malformed") return { id, path: relativePath, status: "incompatible", expected, detail: inspected.detail };
+  const current = compatible(inspected.value);
+  return {
+    id,
+    path: relativePath,
+    status: current ? "current" : "incompatible",
+    expected,
+    detail: current ? null : describeVersion(inspected.value),
+  };
+}
+
+function describeVersion(value) {
+  if (!value || typeof value !== "object") return "expected a JSON object";
+  const fields = ["schemaVersion", "indexerVersion", "encoding", "tokenizerVersion"]
+    .filter((name) => value[name] !== undefined)
+    .map((name) => `${name}=${JSON.stringify(value[name])}`);
+  return fields.length > 0 ? `found ${fields.join(" ")}` : "version fields are missing";
+}

package/src/registry.js

@@ -79,7 +79,7 @@ export async function ensureActiveIds(root, registry, ids) {
   }
   await assertNoSymlinkTraversal(root, registryPath, ".llmnav/ids.jsonl");
   const { records, changed } = mergeActiveIds(registry, ids);
-  if (changed) await atomicWrite(registryPath, renderRegistryRecords(records));
+  if (changed) await atomicWrite(root, registryPath, renderRegistryRecords(records));
   return { records, changed };
 }
 

package/src/spec.js

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

package/src/transaction.js

@@ -152,7 +152,7 @@ export async function commitGeneratedCache(root, cacheDirectory, artifacts, opti
       controlArtifacts: controlRecords,
       phase: "prepared",
     };
-    await atomicWrite(journalPath, stableStringify(journal));
+    await atomicWrite(root, journalPath, stableStringify(journal));
     await invokeFailpoint("after-journal", options);
 
     if (hadExistingCache) {
@@ -160,19 +160,19 @@ export async function commitGeneratedCache(root, cacheDirectory, artifacts, opti
     }
     await moveControlArtifactsToBackup(root, controlRecords, options.renameOptions);
     journal = { ...journal, phase: "old-moved" };
-    await atomicWrite(journalPath, stableStringify(journal));
+    await atomicWrite(root, journalPath, stableStringify(journal));
     await invokeFailpoint("after-cache-moved", options);
 
     await renameWithRetry(stagePath, cachePath, options.renameOptions);
     await installControlArtifacts(root, controlRecords, options.renameOptions);
     journal = { ...journal, phase: "new-installed" };
-    await atomicWrite(journalPath, stableStringify(journal));
+    await atomicWrite(root, journalPath, stableStringify(journal));
     await verifyCommittedCache(cachePath, cacheRelative);
     await verifyControlArtifacts(root, controlRecords);
     await invokeFailpoint("after-new-installed", options);
 
     journal = { ...journal, phase: "committed" };
-    await atomicWrite(journalPath, stableStringify(journal));
+    await atomicWrite(root, journalPath, stableStringify(journal));
     if (hadExistingCache) await removeWithRetry(backupPath, options.renameOptions);
     await removeWithRetry(transactionPath, options.renameOptions);
     await removeWithRetry(journalPath, options.renameOptions);

package/src/util.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { lstat, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { lstat, mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 
 export function normalizeNewlines(value) {
@@ -137,18 +137,41 @@ export async function readJsonSafe(filePath, fallback = null) {
   }
 }
 
-export async function atomicWrite(filePath, content) {
-  await mkdir(path.dirname(filePath), { recursive: true });
+export async function atomicWrite(root, filePath, content, options = {}) {
+  const parent = path.dirname(filePath);
+  const label = options.label ?? relativePosix(root, filePath);
+  await assertNoSymlinkTraversal(root, filePath, label);
+  await mkdir(parent, { recursive: true });
+  const parentIdentity = await directoryIdentity(root, parent, label);
   const temporaryPath = `${filePath}.tmp-${process.pid}-${Math.random().toString(16).slice(2)}`;
-  await writeFile(temporaryPath, content, "utf8");
+  await writeFile(temporaryPath, content, { encoding: "utf8", flag: "wx" });
   try {
+    await options.beforeCommit?.({ filePath, temporaryPath });
+    await assertNoSymlinkTraversal(root, filePath, label);
+    const currentIdentity = await directoryIdentity(root, parent, label);
+    if (currentIdentity !== parentIdentity) throw new Error(`${label} parent directory changed during atomic write.`);
     await rename(temporaryPath, filePath);
   } catch (error) {
-    await rm(temporaryPath, { force: true });
+    if (await parentHasIdentity(root, parent, parentIdentity)) await rm(temporaryPath, { force: true });
     throw error;
   }
 }
 
+async function directoryIdentity(root, directory, label) {
+  await assertNoSymlinkTraversal(root, directory, label);
+  const [details, canonical] = await Promise.all([lstat(directory), realpath(directory)]);
+  if (!details.isDirectory()) throw new Error(`${label} parent is not a directory.`);
+  return `${details.dev}:${details.ino}:${path.normalize(canonical)}`;
+}
+
+async function parentHasIdentity(root, parent, expected) {
+  try {
+    return (await directoryIdentity(root, parent, parent)) === expected;
+  } catch {
+    return false;
+  }
+}
+
 export async function assertNoSymlinkTraversal(root, targetPath, label = targetPath) {
   const rootPath = path.resolve(root);
   const target = path.resolve(targetPath);