@remnic/core 9.3.719 → 9.3.721

package/src/extraction-faithfulness.ts

@@ -34,6 +34,10 @@ import { log } from "./logger.js";
 import type { PluginConfig, MemoryFrontmatter, FaithfulnessFrontmatter } from "./types.js";
 import type { LocalLlmClient } from "./local-llm.js";
 import { type FallbackLlmClient, gatewayTaskChainOptions } from "./fallback-llm.js";
+import {
+  callOpenAiCompatibleChat,
+  resolveFaithfulnessGateEndpoint,
+} from "./local-model-endpoint.js";
 import { extractJsonCandidates } from "./json-extract.js";
 
 // Re-export for callers importing from this module.
@@ -280,13 +284,54 @@ async function callFaithfulnessLlm(
   fallbackLlm: FallbackLlmClient | null,
   timeoutMs: number,
   signal?: AbortSignal,
+  fetchImpl: typeof fetch = fetch,
 ): Promise<LlmCallResult> {
   const messages: Array<{ role: "system" | "user"; content: string }> = [
     { role: "system", content: systemPrompt },
     { role: "user", content: userPrompt },
   ];
 
-  const modelOverride = config.extractionFaithfulnessModel || undefined;
+  // Issue #1585 model-lab pointer: when an explicit local fine-tuned endpoint
+  // is configured (base URL + model name), try it FIRST — it is the cheapest,
+  // deterministic path the operator opted into by setting
+  // extractionFaithfulnessBaseUrl. Unset (the default) skips this entirely,
+  // preserving byte-identical pre-feature routing (rule 39). Any failure
+  // (network, non-2xx, malformed body, timeout) returns null and falls through
+  // to the configured chain (checklist §4 graceful degradation).
+  const localEndpoint = resolveFaithfulnessGateEndpoint(config);
+  if (localEndpoint) {
+    // Give the local probe a SMALLER budget than the outer batch timeout so a
+    // wedged local model returns null (and falls through to the configured
+    // chain) before the batch timer fires. The local endpoint is meant to be
+    // the fast path; if it cannot answer within half the budget (min 500ms),
+    // abandon it and let the fallback chain use the remainder (codex P2 — the
+    // advertised graceful fallback must actually reach the chain, not be starved
+    // by a hanging probe sharing the full batch budget).
+    const probeBudgetMs = Math.max(500, Math.floor(timeoutMs / 2));
+    const result = await callOpenAiCompatibleChat(
+      localEndpoint,
+      messages,
+      { temperature: 0.1, maxTokens: 2048, responseFormatJson: true, timeoutMs: probeBudgetMs },
+      fetchImpl,
+    );
+    if (result?.content) {
+      return { content: result.content, modelUsed: result.modelUsed };
+    }
+    log.debug(
+      "extraction-faithfulness: local model-lab endpoint unavailable, trying configured chain",
+    );
+  }
+
+  // extractionFaithfulnessModel is the LOCAL served model's name (e.g.
+  // remnic-faithfulness-gate-v1). When a local endpoint is configured it
+  // belongs to that endpoint ONLY — it must NOT leak into the fallback chain
+  // as a gateway/local-LLM override, or a local outage forces the configured
+  // chain onto an unavailable local-only model and turns graceful fallback
+  // into backend_unavailable (codex P2 PRRT_kwDORJXyws6Otp-L). Decouple: the
+  // override reaches the fallback chain only when NO local endpoint is
+  // configured (the pre-feature model-override contract, preserved
+  // byte-identical — rule 39).
+  const modelOverride = localEndpoint ? undefined : (config.extractionFaithfulnessModel || undefined);
 
   // Skip the local backend when (a) modelSource is "gateway", or (b) a
   // faithfulness model override is set. The local client always sends
@@ -415,6 +460,12 @@ export async function checkFaithfulnessBatch(
   config: PluginConfig,
   localLlm: LocalLlmClient | null,
   fallbackLlm: FallbackLlmClient | null,
+  /**
+   * Optional fetch injection (issue #1585). The orchestrator does not pass it
+   * (uses global fetch); tests pass a stub to exercise the local model-lab
+   * endpoint path without a live server. See callFaithfulnessLlm.
+   */
+  fetchImpl?: typeof fetch,
 ): Promise<FaithfulnessBatchResult> {
   const timeoutMs =
     typeof config.extractionFaithfulnessTimeoutMs === "number" &&
@@ -486,6 +537,7 @@ export async function checkFaithfulnessBatch(
       fallbackLlm,
       timeoutMs,
       controller.signal,
+      fetchImpl,
     );
     const settled = await Promise.race([
       callPromise.then(

package/src/faithfulness-config.test.ts

@@ -0,0 +1,96 @@
+/**
+ * Tests for the extracted faithfulness + correction-intent config parser
+ * (issue #1576 / #1585). Pins the behavior-preserving extraction: defaults
+ * are byte-identical to the pre-extraction inline block, validation rejects
+ * the same inputs with the same messages, and the new model-lab pointer keys
+ * default empty (byte-identical pre-feature path, rule 39).
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { parseFaithfulnessGateConfig, parseCorrectionIntentConfig } from "./faithfulness-config.js";
+
+test("parseFaithfulnessGateConfig: empty input → byte-identical defaults (rule 39)", () => {
+  const out = parseFaithfulnessGateConfig({});
+  assert.equal(out.extractionFaithfulnessGate, "off");
+  assert.equal(out.extractionFaithfulnessModel, "");
+  assert.equal(out.extractionFaithfulnessBaseUrl, "");
+  assert.equal(out.extractionFaithfulnessContextChars, 400);
+  assert.equal(out.extractionFaithfulnessTimeoutMs, 8000);
+});
+
+test("parseFaithfulnessGateConfig: null/undefined gate → off (not rejected)", () => {
+  assert.equal(parseFaithfulnessGateConfig({ extractionFaithfulnessGate: undefined }).extractionFaithfulnessGate, "off");
+  assert.equal(parseFaithfulnessGateConfig({ extractionFaithfulnessGate: null }).extractionFaithfulnessGate, "off");
+});
+
+test("parseFaithfulnessGateConfig: valid gate modes accepted (case-insensitive, trimmed)", () => {
+  for (const v of ["off", "shadow", "enforce", "SHADOW", " Enforce "]) {
+    const mode = parseFaithfulnessGateConfig({ extractionFaithfulnessGate: v }).extractionFaithfulnessGate;
+    assert.ok(mode === "off" || mode === "shadow" || mode === "enforce", `${v} → ${mode}`);
+  }
+  assert.equal(parseFaithfulnessGateConfig({ extractionFaithfulnessGate: "SHADOW" }).extractionFaithfulnessGate, "shadow");
+});
+
+test("parseFaithfulnessGateConfig: present-but-invalid gate rejects (Ob4RQ — never silently off)", () => {
+  for (const bad of [true, 1, {}, "maybe", "on"]) {
+    assert.throws(
+      () => parseFaithfulnessGateConfig({ extractionFaithfulnessGate: bad }),
+      /extractionFaithfulnessGate must be one of "off" \| "shadow" \| "enforce"/,
+    );
+  }
+});
+
+test("parseFaithfulnessGateConfig: context chars clamp to [1, 4000]; invalid rejects (#1634)", () => {
+  assert.equal(parseFaithfulnessGateConfig({ extractionFaithfulnessContextChars: 100000 }).extractionFaithfulnessContextChars, 4000);
+  assert.equal(parseFaithfulnessGateConfig({ extractionFaithfulnessContextChars: "400" }).extractionFaithfulnessContextChars, 400);
+  for (const bad of [0, -1, 1.5, true, NaN, "abc"]) {
+    assert.throws(
+      () => parseFaithfulnessGateConfig({ extractionFaithfulnessContextChars: bad }),
+      /extractionFaithfulnessContextChars must be an integer/,
+    );
+  }
+});
+
+test("parseFaithfulnessGateConfig: timeout clamps to [1, 60000]; invalid rejects", () => {
+  assert.equal(parseFaithfulnessGateConfig({ extractionFaithfulnessTimeoutMs: 999999 }).extractionFaithfulnessTimeoutMs, 60_000);
+  for (const bad of [0, -5, 2.5, false, "no"]) {
+    assert.throws(
+      () => parseFaithfulnessGateConfig({ extractionFaithfulnessTimeoutMs: bad }),
+      /extractionFaithfulnessTimeoutMs must be an integer/,
+    );
+  }
+});
+
+test("parseFaithfulnessGateConfig: model-lab pointer keys default empty + accept strings (#1585)", () => {
+  // Defaults preserve the existing routing chain exactly.
+  assert.equal(parseFaithfulnessGateConfig({}).extractionFaithfulnessBaseUrl, "");
+  assert.equal(parseFaithfulnessGateConfig({}).extractionFaithfulnessModel, "");
+  // Non-string values are ignored → empty (not rejected; mirrors model key).
+  assert.equal(parseFaithfulnessGateConfig({ extractionFaithfulnessBaseUrl: 123 }).extractionFaithfulnessBaseUrl, "");
+  // Real pointer values round-trip.
+  const out = parseFaithfulnessGateConfig({
+    extractionFaithfulnessModel: "remnic-faithfulness-gate-v1",
+    extractionFaithfulnessBaseUrl: "http://localhost:11434/v1",
+  });
+  assert.equal(out.extractionFaithfulnessModel, "remnic-faithfulness-gate-v1");
+  assert.equal(out.extractionFaithfulnessBaseUrl, "http://localhost:11434/v1");
+});
+
+test("parseCorrectionIntentConfig: empty input → empty pointers (rule-based detector stays default)", () => {
+  const out = parseCorrectionIntentConfig({});
+  assert.equal(out.correctionIntentModel, "");
+  assert.equal(out.correctionIntentBaseUrl, "");
+});
+
+test("parseCorrectionIntentConfig: pointers round-trip; non-strings → empty", () => {
+  const out = parseCorrectionIntentConfig({
+    correctionIntentModel: "remnic-correction-intent-v1",
+    correctionIntentBaseUrl: "http://localhost:8000/v1",
+  });
+  assert.equal(out.correctionIntentModel, "remnic-correction-intent-v1");
+  assert.equal(out.correctionIntentBaseUrl, "http://localhost:8000/v1");
+  assert.equal(parseCorrectionIntentConfig({ correctionIntentModel: true }).correctionIntentModel, "");
+  assert.equal(parseCorrectionIntentConfig({ correctionIntentBaseUrl: 5 }).correctionIntentBaseUrl, "");
+});

package/src/faithfulness-config.ts

@@ -0,0 +1,138 @@
+/**
+ * Faithfulness-gate + correction-intent config parsing (issue #1576 / #1585).
+ *
+ * Extracted verbatim from `config.ts` (a watchlisted god file) so the gate
+ * config block can grow — the model-lab pointer keys
+ * `extractionFaithfulnessBaseUrl` (#1585) and the correction-intent pointers
+ * (`correctionIntentModel` / `correctionIntentBaseUrl`) — without growing the
+ * god file. This is a behavior-preserving extraction (#1526-style): the
+ * validation, defaults, and error messages are byte-identical to the inline
+ * block it replaces, which the existing extraction-faithfulness + config
+ * tests pin.
+ *
+ * Why a dedicated module (and not inline): the ratchet
+ * (`scripts/check-ratchets.mjs`) forbids `config.ts` from growing, and the
+ * model-lab integration needs three new optional keys. Centralizing the whole
+ * gate+intent parsing here keeps it unit-testable in isolation and lets
+ * `config.ts` spread the result in one line.
+ */
+
+import { coerceNumber } from "./connectors/coerce.js";
+
+/**
+ * Parse a value as a strict integer >= `min`, throwing on anything else.
+ *
+ * Mirrors `parseIntegerAtLeast` in `config.ts` byte-for-byte (issue #1634:
+ * reject non-numeric, <=0, non-integer, NaN, Infinity, booleans, objects —
+ * gotcha #51). Reimplemented locally rather than exported from `config.ts`
+ * so this module has no dependency on the god file (and vice versa).
+ */
+function parseIntegerAtLeast(
+  value: unknown,
+  fallback: number,
+  min: number,
+  keyName: string,
+): number {
+  if (value === undefined || value === null) return fallback;
+  const coerced = coerceNumber(value);
+  if (
+    coerced === undefined ||
+    !Number.isFinite(coerced) ||
+    !Number.isInteger(coerced) ||
+    coerced < min
+  ) {
+    throw new Error(
+      `${keyName} must be an integer greater than or equal to ${min}; got ${JSON.stringify(value)}`,
+    );
+  }
+  return coerced;
+}
+
+/**
+ * Parse the extraction faithfulness gate config block.
+ *
+ * Returns exactly the `PluginConfig` fields this block owns. Defaults preserve
+ * the byte-identical pre-feature pipeline (rule 39): gate "off", empty model
+ * + base URL, context 400 chars, timeout 8000 ms. Invalid `gate` values reject
+ * listing valid options (rule 51); invalid integers throw (issue #1634).
+ *
+ * `extractionFaithfulnessBaseUrl` (issue #1585) is the model-lab pointer: when
+ * set together with `extractionFaithfulnessModel`, the gate routes to that
+ * local openai-compatible endpoint before the configured chain; empty string
+ * (default) preserves the existing routing exactly.
+ */
+export function parseFaithfulnessGateConfig(cfg: Record<string, unknown>): {
+  extractionFaithfulnessGate: "off" | "shadow" | "enforce";
+  extractionFaithfulnessModel: string;
+  extractionFaithfulnessBaseUrl: string;
+  extractionFaithfulnessContextChars: number;
+  extractionFaithfulnessTimeoutMs: number;
+} {
+  const gateValue = cfg.extractionFaithfulnessGate;
+  let extractionFaithfulnessGate: "off" | "shadow" | "enforce";
+  if (gateValue === undefined || gateValue === null) {
+    extractionFaithfulnessGate = "off";
+  } else {
+    // Present-but-invalid (true/1/{}) must reject, not silently disable the gate (Ob4RQ).
+    const raw = typeof gateValue === "string" ? gateValue.trim().toLowerCase() : gateValue;
+    if (raw === "off" || raw === "shadow" || raw === "enforce") {
+      extractionFaithfulnessGate = raw;
+    } else {
+      throw new Error(
+        `extractionFaithfulnessGate must be one of "off" | "shadow" | "enforce" (got ${JSON.stringify(gateValue)})`,
+      );
+    }
+  }
+
+  const extractionFaithfulnessModel =
+    typeof cfg.extractionFaithfulnessModel === "string" ? cfg.extractionFaithfulnessModel : "";
+
+  // Issue #1585: model-lab pointer. Empty default → gate uses its existing
+  // routing chain (byte-identical). Non-empty + a model name → gate prefers
+  // the local served endpoint, falling back to the chain on failure.
+  const extractionFaithfulnessBaseUrl =
+    typeof cfg.extractionFaithfulnessBaseUrl === "string"
+      ? cfg.extractionFaithfulnessBaseUrl
+      : "";
+
+  const extractionFaithfulnessContextChars = Math.min(
+    parseIntegerAtLeast(cfg.extractionFaithfulnessContextChars, 400, 1, "extractionFaithfulnessContextChars"),
+    4000,
+  );
+
+  const extractionFaithfulnessTimeoutMs = Math.min(
+    parseIntegerAtLeast(cfg.extractionFaithfulnessTimeoutMs, 8000, 1, "extractionFaithfulnessTimeoutMs"),
+    60_000,
+  );
+
+  return {
+    extractionFaithfulnessGate,
+    extractionFaithfulnessModel,
+    extractionFaithfulnessBaseUrl,
+    extractionFaithfulnessContextChars,
+    extractionFaithfulnessTimeoutMs,
+  };
+}
+
+/**
+ * Parse the correction-intent config block (issue #1581 / #1585).
+ *
+ * The model-lab pointer for passive-correction detection: when both
+ * `correctionIntentModel` and `correctionIntentBaseUrl` are set, the detection
+ * path can route to that local fine-tuned classifier; empty defaults (the
+ * common case) keep the rule-based `detectPassiveCorrections` heuristic as the
+ * sole detector — byte-identical to the pre-feature path. Consumption by the
+ * detector is the consuming child's job (#1581's detector is a pure function;
+ * wiring a model call into it is out of scope for this config-pointer PR).
+ */
+export function parseCorrectionIntentConfig(cfg: Record<string, unknown>): {
+  correctionIntentModel: string;
+  correctionIntentBaseUrl: string;
+} {
+  return {
+    correctionIntentModel:
+      typeof cfg.correctionIntentModel === "string" ? cfg.correctionIntentModel : "",
+    correctionIntentBaseUrl:
+      typeof cfg.correctionIntentBaseUrl === "string" ? cfg.correctionIntentBaseUrl : "",
+  };
+}

package/src/graph-snapshot.ts

@@ -132,9 +132,9 @@ export function parseGraphSnapshotSince(raw: string | undefined): number | undef
 export async function buildGraphSnapshot(opts: {
   memoryDir: string;
   graphConfig: {
-    entityGraphEnabled: boolean;
-    timeGraphEnabled: boolean;
-    causalGraphEnabled: boolean;
+    entityGraph: boolean;
+    timeGraph: boolean;
+    causalGraph: boolean;
   };
   request: GraphSnapshotRequest;
   loadNode: GraphSnapshotNodeLoader;

package/src/graph.ts

@@ -15,6 +15,7 @@ import * as path from "node:path";
 
 import { readEdgeConfidence } from "./graph-edge-reinforcement.js";
 import { emitGraphEvent } from "./graph-events.js";
+import type { GraphConstructionCapabilitySet } from "./capabilities.js";
 
 export type GraphType = "entity" | "time" | "causal";
 
@@ -198,12 +199,12 @@ export async function readEdgesStrict(memoryDir: string, type: GraphType): Promi
  */
 export async function readAllEdges(
   memoryDir: string,
-  config: Pick<GraphConfig, "entityGraphEnabled" | "timeGraphEnabled" | "causalGraphEnabled">
+  graphCaps: Pick<GraphConstructionCapabilitySet, "entityGraph" | "timeGraph" | "causalGraph">,
 ): Promise<GraphEdge[]> {
   const parts: GraphEdge[][] = await Promise.all([
-    config.entityGraphEnabled ? readEdges(memoryDir, "entity") : Promise.resolve([]),
-    config.timeGraphEnabled ? readEdges(memoryDir, "time") : Promise.resolve([]),
-    config.causalGraphEnabled ? readEdges(memoryDir, "causal") : Promise.resolve([]),
+    graphCaps.entityGraph ? readEdges(memoryDir, "entity") : Promise.resolve([]),
+    graphCaps.timeGraph ? readEdges(memoryDir, "time") : Promise.resolve([]),
+    graphCaps.causalGraph ? readEdges(memoryDir, "causal") : Promise.resolve([]),
   ]);
   return parts.flat();
 }
@@ -396,9 +397,9 @@ export class GraphIndex {
       return this.edgeCache.allEdges;
     }
     const allEdges = await readAllEdges(this.memoryDir, {
-      entityGraphEnabled: this.cfg.entityGraphEnabled,
-      timeGraphEnabled: this.cfg.timeGraphEnabled,
-      causalGraphEnabled: this.cfg.causalGraphEnabled,
+      entityGraph: this.cfg.entityGraphEnabled,
+      timeGraph: this.cfg.timeGraphEnabled,
+      causalGraph: this.cfg.causalGraphEnabled,
     });
     this.edgeCache = { allEdges, loadedAt: Date.now() };
     return allEdges;

package/src/lifecycle/tombstones.test.ts

@@ -1,7 +1,9 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtemp, readFile, writeFile, rm, mkdir, appendFile } from "node:fs/promises";
+import { mkdtemp, readFile, writeFile, rm, mkdir, appendFile, utimes } from "node:fs/promises";
 import { tmpdir } from "node:os";
+import { spawn } from "node:child_process";
+import { statSync } from "node:fs";
 import path from "node:path";
 import { createHash } from "node:crypto";
 import {
@@ -345,6 +347,245 @@ describe("TombstoneStore — enabled gate (rule 30)", () => {
   });
 });
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Cross-process tombstone write lock (issue #1639)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * A read-merge-write file io that simulates the secure-store append path
+ * (read encrypted → decrypt → concat → re-encrypt → atomic rename). Unlike a
+ * raw O_APPEND, this is NOT atomic across processes: two writers that each
+ * read the same contents and write back drop the other line — the exact
+ * lost-write race the #1639 cross-process lock closes. The setImmediate yield
+ * widens the race window so a missing lock would demonstrably lose entries.
+ */
+function makeReadMergeWriteIo() {
+  return {
+    read: (p: string) => readFile(p, "utf8"),
+    append: async (p: string, c: string) => {
+      await mkdir(path.dirname(p), { recursive: true });
+      let existing = "";
+      try {
+        existing = await readFile(p, "utf8");
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+      }
+      // Yield so two concurrent read-merge-write appends observably overlap
+      // when the cross-process lock is absent.
+      await new Promise<void>((resolve) => setImmediate(resolve));
+      await writeFile(p, existing + c, "utf8");
+    },
+    write: async (p: string, c: string) => {
+      await mkdir(path.dirname(p), { recursive: true });
+      await writeFile(p, c, "utf8");
+    },
+    stat: (p: string) => statSync(p),
+  };
+}
+
+describe("TombstoneStore — cross-process write lock (issue #1639)", () => {
+  it("two processes appending concurrently produce no lost entries", async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), "tomb-xproc-"));
+    const moduleUrl = new URL("./tombstones.ts", import.meta.url).href;
+    const entriesPerWorker = 15;
+
+    // Worker source: plain JS, no nested template literals. Each child imports
+    // the store, points it at the shared tombstones.jsonl with a read-merge-
+    // write io, and appends N entries. The cross-process lock serializes the
+    // appends across the two processes so no entry is dropped.
+    const workerSource = [
+      "(async () => {",
+      "const { TombstoneStore } = await import(process.argv[1]);",
+      "const { mkdir, readFile, writeFile } = await import(\"node:fs/promises\");",
+      "const { statSync } = await import(\"node:fs\");",
+      "const path = await import(\"node:path\");",
+      "const { createHash } = await import(\"node:crypto\");",
+      "const dir = process.argv[2];",
+      "const workerId = Number(process.argv[3]);",
+      "const count = Number(process.argv[4]);",
+      "const filePath = path.join(dir, \"tombstones.jsonl\");",
+      "function hash(c){return createHash(\"sha256\").update(c).digest(\"hex\");}",
+      "function normalize(c){return c;}",
+      "const io = {",
+      "  read: (p) => readFile(p, \"utf8\"),",
+      "  append: async (p, c) => {",
+      "    await mkdir(path.dirname(p), { recursive: true });",
+      "    let existing = \"\";",
+      "    try { existing = await readFile(p, \"utf8\"); } catch (e) { if (e.code !== \"ENOENT\") throw e; }",
+      "    await new Promise((r) => setImmediate(r));",
+      "    await writeFile(p, existing + c, \"utf8\");",
+      "  },",
+      "  write: async (p, c) => { await mkdir(path.dirname(p), { recursive: true }); await writeFile(p, c, \"utf8\"); },",
+      "  stat: (p) => statSync(p),",
+      "};",
+      "const store = new TombstoneStore(filePath, \"default\", { enabled: true, semanticMatch: false, semanticThreshold: 0.9, hashContent: hash, normalizeText: normalize }, io);",
+      "await store.load();",
+      "for (let i = 0; i < count; i += 1) {",
+      "  await store.appendTombstone({ reason: \"correction\", createdBy: \"user_correction\", sourceMemoryId: \"w\" + workerId + \"-f\" + i, rawContent: \"worker \" + workerId + \" fact \" + i });",
+      "}",
+      "})();",
+    ].join("\n");
+
+    function runWorker(workerId: number): Promise<void> {
+      return new Promise((resolve, reject) => {
+        const child = spawn(
+          process.execPath,
+          ["--import", "tsx", "-e", workerSource, moduleUrl, dir, String(workerId), String(entriesPerWorker)],
+          { stdio: ["ignore", "pipe", "pipe"] },
+        );
+        let stderr = "";
+        child.stderr.setEncoding("utf8");
+        child.stderr.on("data", (chunk) => { stderr += chunk; });
+        child.on("error", reject);
+        child.on("close", (code) => {
+          if (code === 0) resolve();
+          else reject(new Error(`worker ${workerId} exited ${code}: ${stderr}`));
+        });
+      });
+    }
+
+    // Two genuinely concurrent processes contending on the same lockfile.
+    await Promise.all([runWorker(0), runWorker(1)]);
+
+    const raw = await readFile(path.join(dir, "tombstones.jsonl"), "utf8");
+    const fileLines = raw.split("\n").filter((l) => l.trim().length > 0);
+    // No lost entries: every line parses and the total is exactly 2 × N.
+    assert.equal(fileLines.length, entriesPerWorker * 2);
+    for (const line of fileLines) {
+      assert.doesNotThrow(() => JSON.parse(line));
+    }
+    // Every worker entry is present (none dropped by a lost write).
+    const sourceIds = new Set(fileLines.map((l) => JSON.parse(l).sourceMemoryId));
+    for (let w = 0; w < 2; w += 1) {
+      for (let i = 0; i < entriesPerWorker; i += 1) {
+        assert.ok(sourceIds.has(`w${w}-f${i}`), `missing w${w}-f${i} — lost write`);
+      }
+    }
+    // The advisory lockfile is released after the run (no lingering lock).
+    await rm(path.join(dir, "tombstones.lock"), { force: true });
+  });
+
+  it("recovers from a stale lock left by a crashed holder", async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), "tomb-stale-lock-"));
+    const filePath = path.join(dir, "tombstones.jsonl");
+    const lockPath = path.join(dir, "tombstones.lock");
+    // Seed a lockfile written by a (now-crashed) holder: <pid> <uuid> <iso>.
+    await mkdir(dir, { recursive: true });
+    await writeFile(
+      lockPath,
+      `${process.pid} 00000000-0000-0000-0000-000000000000 2000-01-01T00:00:00.000Z\n`,
+      "utf8",
+    );
+    // Make it older than staleMs so the next acquire breaks it.
+    const old = new Date(Date.now() - 120_000);
+    await utimes(lockPath, old, old);
+
+    const store = new TombstoneStore(
+      filePath,
+      "default",
+      { enabled: true, semanticMatch: false, semanticThreshold: 0.9, hashContent: computeHash, normalizeText: normalizeContent, lockStaleMs: 1_000 },
+      makeReadMergeWriteIo(),
+    );
+    // The append must break the stale lock, acquire a fresh one, and succeed.
+    const id = await store.appendTombstone({
+      reason: "correction",
+      createdBy: "user_correction",
+      sourceMemoryId: "fact-stale",
+      rawContent: "Recovered from a stale lock.",
+    });
+    assert.match(id, /^tomb-/);
+    // The tombstone landed durably.
+    const raw = await readFile(filePath, "utf8");
+    const lines2 = raw.split("\n").filter((l) => l.trim().length > 0);
+    assert.equal(lines2.length, 1);
+    // Our fresh lock was released on completion (the stale one was broken).
+    await rm(lockPath, { force: true });
+  });
+
+  it("rebuild preserves a peer's revocation appended before rebuild acquired the lock (cursor/codex #1639)", async () => {
+    // Regression for the rebuild race: rebuild must re-read the log under the
+    // lock (ensureFreshAgainstDisk) before computing its payload, otherwise a
+    // revocation a peer wrote while rebuild waited for the lock is dropped and
+    // the retired fact silently un-revokes (resurrection).
+    const dir = await mkdtemp(path.join(tmpdir(), "tomb-rebuild-race-"));
+    const filePath = path.join(dir, "tombstones.jsonl");
+    const opts = { enabled: true, semanticMatch: false, semanticThreshold: 0.9, hashContent: computeHash, normalizeText: normalizeContent };
+    const io = makeReadMergeWriteIo();
+    // Store A writes tombstone-1, then goes stale (never sees the peer write).
+    const storeA = new TombstoneStore(filePath, "default", opts, io);
+    const t1 = await storeA.appendTombstone({
+      reason: "correction",
+      createdBy: "user_correction",
+      sourceMemoryId: "fact-rebuild-1",
+      rawContent: "The DB is MySQL.",
+    });
+    // Peer (store B, same file) revokes t1 durably. Store A's in-memory index
+    // is now stale (it still thinks t1 is active).
+    const storeB = new TombstoneStore(filePath, "default", opts, io);
+    await storeB.revoke(t1, "user_correction");
+    // Store A rebuilds from a retired-memory corpus that reconstructs t1.
+    // Without the under-lock re-read, A computes existingRevocations from its
+    // stale index (empty), overwrites the file with [rebuilt-t1], and the
+    // revocation is LOST — t1 is active again (resurrection). With the fix,
+    // ensureFreshAgainstDisk reloads the revocation under the lock and rebuild
+    // preserves it.
+    await storeA.rebuild([
+      {
+        memoryId: "fact-rebuild-1",
+        rawContent: "The DB is MySQL.",
+        reason: "correction" as const,
+        createdBy: "user_correction" as const,
+        createdAt: "2026-01-01T00:00:00.000Z",
+      },
+    ]);
+    // The rebuilt file must still contain the revocation (the retired fact
+    // stays revoked, not silently un-revoked by the rebuild).
+    const raw = await readFile(filePath, "utf8");
+    const rebuiltLines = raw.split("\n").filter((l) => l.trim().length > 0);
+    const hasRevocation = rebuiltLines.some((l) => {
+      try { return JSON.parse(l).kind === "revocation"; } catch { return false; }
+    });
+    assert.ok(hasRevocation, "rebuild dropped the peer's revocation — resurrection risk");
+    // And the rebuilt store A must report the fact as revoked (lookup returns null).
+    await storeA.load();
+    assert.equal(
+      storeA.lookup({ namespace: "default", contentHash: computeHash("The DB is MySQL.") }),
+      null,
+      "revoked fact resurrected after rebuild",
+    );
+    await rm(path.join(dir, "tombstones.lock"), { force: true });
+  });
+
+  it("in-process concurrent appends still serialize under the lock", async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), "tomb-inproc-lock-"));
+    const filePath = path.join(dir, "tombstones.jsonl");
+    const store = new TombstoneStore(
+      filePath,
+      "default",
+      { enabled: true, semanticMatch: false, semanticThreshold: 0.9, hashContent: computeHash, normalizeText: normalizeContent },
+      makeReadMergeWriteIo(),
+    );
+    const contents = Array.from({ length: 25 }, (_, i) => `locked content ${i}`);
+    await Promise.all(
+      contents.map((c) =>
+        store.appendTombstone({
+          reason: "correction",
+          createdBy: "user_correction",
+          sourceMemoryId: `fact-${c}`,
+          rawContent: c,
+        }),
+      ),
+    );
+    await store.load();
+    const raw = await readFile(filePath, "utf8");
+    const lines3 = raw.split("\n").filter((l) => l.trim().length > 0);
+    // No lost writes despite the read-merge-write io + concurrent appends.
+    assert.equal(lines3.length, contents.length);
+    assert.equal(store.stats().count, contents.length);
+    await rm(path.join(dir, "tombstones.lock"), { force: true });
+  });
+});
+
 describe("parseTombstoneLine", () => {
   it("rejects malformed input", () => {
     assert.equal(parseTombstoneLine(""), null);