llmnav 0.7.0 → 0.7.2

package/CHANGELOG.md

@@ -6,6 +6,18 @@ The npm package follows Semantic Versioning. The `llmnav/N` source protocol is v
 
 ## [Unreleased]
 
+## [0.7.2] — 2026-08-13
+
+### Added
+
+* Documented pre-1.0 stability classes, a one-minor and 90-day public API deprecation window, generated-format migration guarantees, and the limited security exception.
+
+## [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

package/README.md

@@ -6,7 +6,7 @@ It adds compact, stable metadata to a small number of architectural and behavior
 
 LLMNav is not a documentation generator, an embedding database, or a reason to annotate every function. It is a zero-runtime-dependency Node.js CLI and ESM library for reducing broad repository scans, irrelevant context, stale hand-written links, repeated card tokenization, and avoidable cache invalidation.
 
-## What v0.6 provides
+## What v0.7 provides
 
 * The backward-compatible `llmnav/1` source comment specification
 * A parser and data-loss-resistant canonical formatter
@@ -36,6 +36,8 @@ LLMNav is not a documentation generator, an embedding database, or a reason to a
 
 The package supports Node.js 22 or newer, uses ESM, performs no network requests, and has no runtime dependencies.
 
+Public compatibility rules are documented in [Compatibility and deprecation policy](docs/compatibility.md). In short, `llmnav/1` source cards and the schemaVersion 1 primary index are stable contracts; disposable generated accelerators may be rebuilt, and documented CLI or library removals receive a replacement and a minimum one-minor/90-day deprecation window.
+
 ## Install
 
 ```sh

package/ROADMAP.md

@@ -89,7 +89,7 @@ The source grammar and generated formats will be declared stable only after use
 
 In progress:
 
-* Generated-format migration tooling is implemented for the current public formats; compatibility guarantees still need a documented support and deprecation policy.
+* Generated-format migration tooling and the public support and deprecation policy are implemented for the current formats.
 * 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

@@ -306,3 +306,5 @@ The typed `llmnav/examples/provider-neutral-host.mjs` export composes these APIs
 ## Compatibility boundary
 
 The public API follows package semantic versioning. `index.json` schemaVersion 1 and `llmnav/1` source syntax remain compatible. Contract fingerprints are optional additive index fields. `search-index.json`, `file-state.json`, `graph-state.json`, transaction journals, and performance metrics retain their own schema or implementation versions.
+
+See [Compatibility and deprecation policy](compatibility.md) for the pre-1.0 stability classes, removal window, migration guarantees, and security exception.

package/docs/compatibility.md

@@ -0,0 +1,40 @@
+# Compatibility and deprecation policy
+
+This policy applies to LLMNav releases before 1.0 and defines which surfaces are durable enough for repositories and integrations to depend on.
+
+## Stability classes
+
+| Surface | Stability before 1.0 | Compatibility rule |
+| --- | --- | --- |
+| `llmnav/1` source cards | Stable protocol | Existing valid cards keep their meaning. A breaking grammar or semantic change requires a new protocol header such as `llmnav/2`; LLMNav will not reinterpret `llmnav/1` incompatibly. |
+| `.llmnav/cache/index.json` schemaVersion 1 | Stable primary generated contract | Additive optional fields are allowed. Removing or changing an existing field requires a new schema version and a migration path. |
+| CLI commands, flags, exit codes, JSON fields, ESM exports, and TypeScript declarations documented in this repository | SemVer public API | Compatible additions may ship in a minor release. Removal or incompatible behavior requires a minor release before 1.0, a documented replacement, and the deprecation window below. |
+| Diagnostic codes | Stable identifiers | A code may gain clearer wording, but its documented category and remediation meaning remain compatible. Retiring a code follows the deprecation window. |
+| Search ranking and performance | Behavioral contract | Determinism and published regression thresholds are protected. Exact scores or ordering may change in a minor release when benchmarks justify the change and the changelog explains it. |
+| `search-index.json`, `file-state.json`, `graph-state.json`, prompt bundles, shards, transaction journals, locks, and other generated accelerators | Disposable versioned formats | Consumers must not treat these as source truth. LLMNav may replace an incompatible format after `migrate --check`; it must rebuild or fail closed rather than silently misread it. |
+| Undocumented internals and test helpers | Unstable | They may change in any release. Importing source files outside the documented package exports is unsupported. |
+
+Package versions follow Semantic Versioning. Before 1.0, an incompatible change to a documented package API may use a minor version, while patches remain backward compatible. Protocol and generated-schema versions are independent from the npm package version.
+
+## Deprecation window
+
+For a documented CLI, JSON, ESM, or TypeScript surface:
+
+1. The introducing release documents the deprecated surface, its replacement, and any automated migration.
+2. The old surface remains functional for at least one subsequent minor release and for at least 90 days. Removal waits until both conditions are satisfied.
+3. `llmnav doctor`, `check`, or `migrate --check` reports a stable diagnostic when repository action is required. A warning must not silently become destructive behavior.
+4. The removal release records the change in `CHANGELOG.md` and `docs/migration.md`.
+
+Immediate removal is reserved for an actively exploitable security issue or behavior that can corrupt source or repository state. The security release must explain the exception and provide the safest available migration.
+
+## Upgrade guarantees
+
+* Canonical source cards and `.llmnav/ids.jsonl` remain the recovery authority; disposable caches do not.
+* `migrate --check` is read-only. `migrate --write` validates canonical source before mutation and publishes a complete recoverable cache transaction.
+* A supported upgrade path covers the latest release of the previous minor line to the current release. Skipping several minor lines may require running the newest migration tool directly, but must not require installing every intermediate package version.
+* Downgrade compatibility is not guaranteed for generated caches. Restore caches by regenerating them with the target version; never hand-edit generated schema versions.
+* Node.js runtime support follows the declared `engines` range. Dropping a supported Node.js major is an incompatible documented API change and follows the deprecation window unless that runtime is no longer receiving security updates.
+
+## 1.0 commitment
+
+At 1.0, incompatible changes to documented package APIs require a new major package version. The `llmnav/1` and primary-index rules above already apply and do not wait for 1.0. The remaining 1.0 gates are sustained cross-platform evidence, published benchmark methodology, and closure of high-severity parser or transaction ambiguity.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llmnav",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "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

@@ -339,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

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/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/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.7.0";
+export const PACKAGE_VERSION = "0.7.2";
 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);