llmnav 0.6.6 → 0.7.0

package/CHANGELOG.md

@@ -6,6 +6,13 @@ The npm package follows Semantic Versioning. The `llmnav/N` source protocol is v
 
 ## [Unreleased]
 
+## [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.0",
   "description": "A deterministic semantic navigation layer for LLM coding agents.",
   "type": "module",
   "bin": {

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)) {
@@ -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/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/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/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.0";
 export const SPEC_VERSION = "1";
 
 export const SCOPES = Object.freeze(["file", "module", "symbol"]);