@remnic/core 9.69.22 → 9.69.24

package/src/graph-jsonl.ts

@@ -0,0 +1,267 @@
+/**
+ * Graph JSONL rewrite primitives (sibling of graph.ts, kept out so graph.ts
+ * stays under the 1200-LOC new-work cap of issue #1995).
+ *
+ * `appendEdge` in graph.ts is append-only by design. These helpers are the
+ * REPLACE path: callers that re-write an existing node's edges (the
+ * judge-merged target of issue #2330) must first drop the node's prior
+ * generated edges or every re-write duplicates them.
+ */
+
+import { mkdir, rename, writeFile } from "node:fs/promises";
+import * as path from "node:path";
+import { log } from "./logger.js";
+import { graphFilePath, readEdgesStrict, withGraphWriteLock, type GraphEdge, type GraphType } from "./graph.js";
+import {
+  assertGraphLockHeld,
+  yieldForLockHeartbeat,
+  type GraphWriteLockSection,
+} from "./graph-write-lock.js";
+
+/**
+ * Write a graph JSONL file atomically using temp+rename (gotcha #54: never
+ * delete-then-rename; rename is atomic on the same filesystem). Shared by
+ * the edge-decay rewrite and node-edge replacement so every JSONL rewrite
+ * path serializes on the same lock and the same atomic-write discipline.
+ */
+/** Serialize batch size at which body building yields to the event loop
+ * (round N+19 A): one `map+join` over a large corpus blocks the loop past
+ * the lock's heartbeat window. */
+const EDGE_SERIALIZE_YIELD_BATCH = 5_000;
+
+export async function writeGraphJsonlAtomic(
+  filePath: string,
+  edges: GraphEdge[],
+  lock: GraphWriteLockSection,
+): Promise<void> {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  // Chunked with event-loop yields: the caller holds the graph write lock,
+  // and its mtime heartbeat is a timer that cannot fire while a single
+  // synchronous stringify pass over a multi-hundred-thousand-row corpus
+  // blocks the loop (round N+19 A).
+  let body = "";
+  for (let i = 0; i < edges.length; i += EDGE_SERIALIZE_YIELD_BATCH) {
+    if (i > 0) await yieldForLockHeartbeat();
+    const end = Math.min(i + EDGE_SERIALIZE_YIELD_BATCH, edges.length);
+    for (let j = i; j < end; j += 1) {
+      body += `${JSON.stringify(edges[j])}\n`;
+    }
+  }
+  const tempPath = `${filePath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
+  await writeFile(tempPath, body, "utf-8");
+  // Round N+20 (A): the callers' pre-build guards cannot cover the build
+  // itself — a section paused past the stale window between the caller's
+  // check and this rename resumes to publish over the peer that broke the
+  // lock and wrote its own newer graph. Revalidate ownership immediately
+  // before the destructive rename; a lost lock aborts and leaves the peer's
+  // file untouched (the staged temp is orphaned, same as a rename failure).
+  await assertGraphLockHeld(filePath, lock);
+  await rename(tempPath, filePath);
+}
+
+/**
+ * Which edges a node's OWN write generates, per graph type (round N+7 G):
+ *  - entity: the node is the `from` side (node → entity siblings);
+ *  - time/causal: the node is the `to` side (predecessor → node) — the
+ *    write links BACK to its predecessor, so the inbound edge is the one
+ *    this node's write created. The node's outbound time/causal edges
+ *    (node → later nodes) belong to those LATER nodes' writes and are never
+ *    touched here.
+ */
+function isNodeGeneratedEdge(edge: GraphEdge, type: GraphType, memoryPath: string): boolean {
+  return type === "entity" ? edge.from === memoryPath : edge.to === memoryPath;
+}
+
+/** The edges one removal dropped from one graph file, kept for restoration. */
+export interface RemovedNodeEdges {
+  type: GraphType;
+  filePath: string;
+  removed: GraphEdge[];
+}
+
+/**
+ * Remove an existing node's prior generated edges across the given graph
+ * types so a RE-write of the same node (a judge-merged memory, issue #2330)
+ * REPLACES them instead of re-appending them into the append-only JSONL —
+ * duplicates `spreadingActivation` sums into candidate scores and that grow
+ * without bound. One shared routine covers every enabled type; there is no
+ * per-type copy. Read and rewrite run under the same per-file write lock as
+ * `appendEdge` so a concurrent append cannot be dropped (issue #729). The
+ * removed edges are RETURNED so the caller can restore them when the
+ * replacement build fails (round N+7 E).
+ */
+export async function removeNodeEdgesForRewrite(
+  memoryDir: string,
+  memoryPath: string,
+  types: readonly GraphType[],
+): Promise<RemovedNodeEdges[]> {
+  const results: RemovedNodeEdges[] = [];
+  for (const type of types) {
+    const filePath = graphFilePath(memoryDir, type);
+    let removed: GraphEdge[];
+    try {
+      removed = await withGraphWriteLock(filePath, async (lock) => {
+        const edges = await readEdgesStrict(memoryDir, type);
+        const removedEdges = edges.filter((edge) => isNodeGeneratedEdge(edge, type, memoryPath));
+        if (removedEdges.length === 0) return [];
+        // Round N+19 A: a peer may have stale-broken this lock while a large
+        // parse blocked the loop — revalidate ownership before publishing the
+        // replacement; a lost lock aborts (the catch below restores any
+        // earlier committed types, then rethrows).
+        await assertGraphLockHeld(filePath, lock);
+        await writeGraphJsonlAtomic(
+          filePath,
+          edges.filter((edge) => !isNodeGeneratedEdge(edge, type, memoryPath)),
+          lock,
+        );
+        return removedEdges;
+      });
+    } catch (err) {
+      // A partial pass (type 1 committed, type 2 failed) must not leave the
+      // committed removal stranded: undo what already landed, then surface.
+      for (const done of results) {
+        await restoreRemovedNodeEdges(memoryDir, done).catch(() => undefined);
+      }
+      throw err;
+    }
+    if (removed.length > 0) results.push({ type, filePath, removed });
+  }
+  return results;
+}
+
+/**
+ * Restore edges a {@link removeNodeEdgesForRewrite} pass dropped, after the
+ * replacement build FAILED (round N+7 E): failure must leave either the old
+ * or the new complete set, never none. Appends the removed edges back under
+ * the same per-file lock, deduped on the exact JSON row so a retry that
+ * partially succeeded cannot double them.
+ */
+export async function restoreRemovedNodeEdges(
+  memoryDir: string,
+  removed: RemovedNodeEdges,
+): Promise<number> {
+  if (removed.removed.length === 0) return 0;
+  return withGraphWriteLock(removed.filePath, async (lock) => {
+    const current = await readEdgesStrict(memoryDir, removed.type);
+    const present = new Set(current.map((edge) => JSON.stringify(edge)));
+    const toRestore = removed.removed.filter((edge) => !present.has(JSON.stringify(edge)));
+    if (toRestore.length === 0) return 0;
+    // Round N+19 A: revalidate ownership before restoring over the file —
+    // a peer that broke the lock owns the file now, and restoring our older
+    // snapshot over its write would clobber it. The throw leaves the current
+    // (peer-owned) file intact; callers log the skipped restore.
+    await assertGraphLockHeld(removed.filePath, lock);
+    await writeGraphJsonlAtomic(removed.filePath, [...current, ...toRestore], lock);
+    return toRestore.length;
+  });
+}
+
+/**
+ * Round N+10 (C) + N+14 companion to {@link removeNodeEdgesForRewrite}: the
+ * replacement build FAILED or was superseded, possibly after appending SOME
+ * of the node's new edges. Two duties, both scoped to what THIS writer did:
+ *
+ * 1. Remove the rows the failed build actually appended. When `appended` is
+ *    provided the removal is surgical — by exact JSON row identity, per
+ *    file, under the same per-file lock — so rows a NEWER writer appended
+ *    after this writer's removal (never in this writer's snapshot) survive.
+ *    Rows a newer writer already swept are simply absent and the removal is
+ *    a no-op. Since round N+16 (A) a THROWING build carries its partial row
+ *    set on `GraphEdgeAppendError`, so the surgical path holds on the throw
+ *    too; only a build that neither returns rows nor wraps its failure
+ *    falls back to the node-wide sweep of
+ *    {@link removeNodeEdgesForRewrite}: identical outcome when no newer
+ *    writer interleaved.
+ * 2. Restore the snapshot the original removal dropped — but only for graph
+ *    types whose file holds NO unexplained node rows after step 1. A type
+ *    that still has node rows this writer cannot account for is owned by the
+ *    newer writer's completed rebuild; restoring the older snapshot over it
+ *    left the memory holding B's body while graph recall reflected the
+ *    pre-A state (the N+14 finding). Types swept clean restore verbatim
+ *    (N+7 E: failure leaves the old or the new complete set, never none).
+ */
+export async function rollbackNodeEdgeRewrite(
+  memoryDir: string,
+  memoryPath: string,
+  types: readonly GraphType[],
+  removed: RemovedNodeEdges[],
+  nodeId: string,
+  appended?: readonly GraphEdge[],
+): Promise<void> {
+  let residue = new Set<GraphType>();
+  const cleanup = appended
+    ? removeAppendedNodeEdges(memoryDir, memoryPath, types, appended)
+    : removeNodeEdgesForRewrite(memoryDir, memoryPath, types).then((): Set<GraphType> => new Set());
+  await cleanup
+    .then((left) => {
+      residue = left;
+    })
+    .catch((cleanErr) =>
+      log.error(
+        `semantic-merge: partial graph edge cleanup failed for ${nodeId} — edges from the failed rebuild remain; rebuild with graph health repair: ${cleanErr instanceof Error ? cleanErr.message : String(cleanErr)}`,
+      ),
+    );
+  for (const entry of removed) {
+    if (residue.has(entry.type)) {
+      log.warn(
+        `semantic-merge: skipped ${entry.type} snapshot restore for ${nodeId} — a newer writer's rebuilt edges are live in that graph`,
+      );
+      continue;
+    }
+    await restoreRemovedNodeEdges(memoryDir, entry).catch((restoreErr) =>
+      log.error(
+        `semantic-merge: graph edge restore failed for ${nodeId} ${entry.type} graph — the prior edges may be lost; rebuild with graph health repair: ${restoreErr instanceof Error ? restoreErr.message : String(restoreErr)}`,
+      ),
+    );
+  }
+}
+
+/**
+ * Round N+14: remove exactly the rows a failed/superseded build appended,
+ * then report which of the rewrite types still hold node-generated rows this
+ * writer did NOT append (a newer writer's live rebuild) so the caller can
+ * skip restoring its older snapshot over them.
+ */
+async function removeAppendedNodeEdges(
+  memoryDir: string,
+  memoryPath: string,
+  types: readonly GraphType[],
+  appended: readonly GraphEdge[],
+): Promise<Set<GraphType>> {
+  const mineByType = new Map<GraphType, string[]>();
+  for (const edge of appended) {
+    const list = mineByType.get(edge.type) ?? [];
+    list.push(JSON.stringify(edge));
+    mineByType.set(edge.type, list);
+  }
+  const residue = new Set<GraphType>();
+  for (const type of types) {
+    const filePath = graphFilePath(memoryDir, type);
+    const mine = mineByType.get(type) ?? [];
+    await withGraphWriteLock(filePath, async (lock) => {
+      const edges = await readEdgesStrict(memoryDir, type);
+      if (mine.length > 0) {
+        const identities = new Set(mine);
+        const kept = edges.filter((edge) => !identities.has(JSON.stringify(edge)));
+        if (kept.length !== edges.length) {
+          // Round N+19 A: lost lock — a peer owns the file. Cleaning it would
+          // clobber the peer's write, so leave it, mark the type as residue,
+          // and let the caller skip restoring its older snapshot over it
+          // (our appended rows may survive as duplicates; graph health
+          // repair reconciles). Never old-plus-partial-new over a peer.
+          try {
+            await assertGraphLockHeld(filePath, lock);
+          } catch {
+            residue.add(type);
+            return;
+          }
+          await writeGraphJsonlAtomic(filePath, kept, lock);
+        }
+      }
+      if (edges.some((edge) => isNodeGeneratedEdge(edge, type, memoryPath) && !mine.includes(JSON.stringify(edge)))) {
+        residue.add(type);
+      }
+    });
+  }
+  return residue;
+}

package/src/graph-write-lock.test.ts

@@ -0,0 +1,228 @@
+/**
+ * Cross-process safety of the graph JSONL write lock (issue #2330 round
+ * N+18 A). The in-process promise chain cannot see a peer Remnic process
+ * sharing the memory directory: a peer append landing between this
+ * process's read-snapshot and its rename-backed rewrite was silently
+ * discarded by the stale snapshot. Every withGraphWriteLock section must
+ * serialize against peers through the shared withHeldFileLock advisory
+ * lock (the same primitive the page-versioning manifest uses).
+ */
+
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir, mkdtemp, readFile, unlink, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+import { test } from "node:test";
+import { graphFilePath } from "./graph.js";
+import {
+  assertGraphLockHeld,
+  GraphLockLostError,
+  withGraphWriteLock,
+} from "./graph-write-lock.js";
+import { removeNodeEdgesForRewrite, writeGraphJsonlAtomic } from "./graph-jsonl.js";
+
+test("withGraphWriteLock: a peer append between read and rewrite is never discarded (round N+18 A)", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-graph-xproc-"));
+  const jsonlUrl = new URL("./graph-jsonl.ts", import.meta.url).href;
+  const graphUrl = new URL("./graph.ts", import.meta.url).href;
+  const APPENDS = 60;
+  const REWRITES = 30;
+  // Large labels widen the read/write windows so the pre-lock race window
+  // is exercised on every round, not just occasionally.
+  const pad = "y".repeat(2048);
+
+  // Worker source: plain JS, no nested template literals (tombstones.test.ts
+  // pattern). Worker 0 seeds node-owned edges, then alternates
+  // removeNodeEdgesForRewrite/restoreRemovedNodeEdges — each round is a
+  // read-modify-rename of entity.jsonl. Worker 1 appends distinct edges
+  // through appendEdge. Without the cross-process lock, the rewriter's
+  // stale snapshot discards appends that land inside its read→rename window.
+  const workerSource = [
+    "(async () => {",
+    "const jsonl = await import(process.argv[1]);",
+    "const graph = await import(process.argv[2]);",
+    "const dir = process.argv[3];",
+    "const workerId = Number(process.argv[4]);",
+    "const appends = Number(process.argv[5]);",
+    "const rewrites = Number(process.argv[6]);",
+    "const pad = process.argv[7];",
+    "const node = 'facts/w-a.md';",
+    "if (workerId === 0) {",
+    "  for (let i = 0; i < 3; i += 1) {",
+    "    await graph.appendEdge(dir, { from: node, to: 'facts/w-a-peer-' + i + '.md', type: 'entity', weight: 1, label: 'seed' + i + pad, ts: new Date().toISOString() });",
+    "  }",
+    "  for (let i = 0; i < rewrites; i += 1) {",
+    "    const removed = await jsonl.removeNodeEdgesForRewrite(dir, node, ['entity']);",
+    "    for (const entry of removed) await jsonl.restoreRemovedNodeEdges(dir, entry);",
+    "  }",
+    "} else {",
+    "  for (let i = 0; i < appends; i += 1) {",
+    "    await graph.appendEdge(dir, { from: 'facts/w-b.md', to: 'facts/w-b-target-' + i + '.md', type: 'entity', weight: 1, label: 'peer' + i + pad, ts: new Date().toISOString() });",
+    "  }",
+    "}",
+    "})();",
+  ].join("\n");
+
+  function runWorker(workerId: number): Promise<void> {
+    // The workers below resolve their modules from argv URLs at runtime —
+    // a static import cannot express "the file under test, by URL".
+    const { promise, resolve, reject } = Promise.withResolvers<void>();
+    const child = spawn(
+      process.execPath,
+      [
+        "--import", "tsx", "-e", workerSource,
+        jsonlUrl, graphUrl, dir, String(workerId), String(APPENDS), String(REWRITES), pad,
+      ],
+      { stdio: ["ignore", "pipe", "pipe"] },
+    );
+    let stderr = "";
+    child.stderr.setEncoding("utf8");
+    child.stderr.on("data", (chunk: string) => {
+      stderr += chunk;
+    });
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`worker ${workerId} exited ${code}: ${stderr}`));
+    });
+    return promise;
+  }
+  await Promise.all([runWorker(0), runWorker(1)]);
+
+  const raw = await readFile(graphFilePath(dir, "entity"), "utf8");
+  const rows = raw
+    .split("\n")
+    .filter((line) => line.trim().length > 0)
+    .map((line) => JSON.parse(line) as { from: string });
+  const peerAppended = rows.filter((edge) => edge.from === "facts/w-b.md");
+  assert.equal(
+    peerAppended.length,
+    APPENDS,
+    `every peer-appended edge must survive the concurrent rewrites (found ${peerAppended.length} of ${APPENDS})`,
+  );
+});
+
+// ── Round N+19 (A): the lock's mtime heartbeat is a timer; it cannot fire
+// while a synchronous parse/serialize blocks the event loop, so a peer can
+// stale-break the lock past the 30s window and publish its own write. A
+// section about to publish must revalidate ownership and abort on loss.
+
+test("withGraphWriteLock: refresh reports a peer-replaced lock and the guarded publish refuses (round N+19 A)", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-graph-locklost-"));
+  const filePath = graphFilePath(dir, "entity");
+  await mkdir(path.dirname(filePath), { recursive: true });
+  const PEER_ROW = `${JSON.stringify({
+    from: "facts/peer.md",
+    to: "facts/peer-target.md",
+    type: "entity",
+    weight: 1,
+    label: "peer",
+    ts: "2026-08-22T00:00:00.000Z",
+  })}\n`;
+  await writeFile(filePath, PEER_ROW, "utf8");
+
+  await withGraphWriteLock(filePath, async (lock) => {
+    assert.equal(await lock.refresh(), true, "an unbroken lock refreshes");
+    // Simulate the stalled-section consequence: a peer stale-broke our lock
+    // and published its own (the row above is its write).
+    const lockPath = `${filePath}.lock`;
+    await unlink(lockPath).catch(() => undefined);
+    await writeFile(lockPath, `${process.pid} peer-${randomUUID()} ${new Date().toISOString()}\n`, "utf8");
+    assert.equal(await lock.refresh(), false, "ownership was lost to the peer");
+    await assert.rejects(assertGraphLockHeld(filePath, lock), GraphLockLostError);
+    assert.equal(await readFile(filePath, "utf8"), PEER_ROW, "the refused publish left the peer's write intact");
+  });
+});
+
+test("removeNodeEdgesForRewrite: a stale-broken lock aborts the rewrite instead of clobbering the peer (round N+19 A)", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-graph-abort-"));
+  const filePath = graphFilePath(dir, "entity");
+  await mkdir(path.dirname(filePath), { recursive: true });
+  const NODE = "facts/mine.md";
+  // A corpus large enough that the section's chunked parse yields to the
+  // event loop many times, giving the simulated peer's break a guaranteed
+  // landing window inside the section (before the publish guard).
+  const rows: string[] = [];
+  for (let i = 0; i < 59_999; i += 1) {
+    rows.push(
+      JSON.stringify({
+        from: "facts/other.md",
+        to: `facts/x-${i}.md`,
+        type: "entity",
+        weight: 1,
+        label: `row${i}`,
+        ts: "2026-08-22T00:00:00.000Z",
+      }),
+    );
+  }
+  rows.push(
+    JSON.stringify({
+      from: NODE,
+      to: "facts/mine-target.md",
+      type: "entity",
+      weight: 1,
+      label: "mine",
+      ts: "2026-08-22T00:00:00.000Z",
+    }),
+  );
+  await writeFile(filePath, `${rows.join("\n")}\n`, "utf8");
+
+  const lockPath = `${filePath}.lock`;
+  const breakAsPeer = (async () => {
+    while (!existsSync(lockPath)) await new Promise<void>((resolve) => setImmediate(resolve));
+    await unlink(lockPath).catch(() => undefined);
+    await writeFile(lockPath, `${process.pid} peer-${randomUUID()} ${new Date().toISOString()}\n`, "utf8");
+  })();
+
+  await assert.rejects(
+    removeNodeEdgesForRewrite(dir, NODE, ["entity"]),
+    (err: unknown) => err instanceof Error && /lost mid-section/.test(err.message),
+    "a rewrite whose lock was stale-broken mid-section must abort, not publish",
+  );
+  await breakAsPeer;
+  const after = await readFile(filePath, "utf8");
+  assert.equal(
+    after.includes(`"from":"${NODE}"`),
+    true,
+    "the aborted rewrite must leave the node's edges untouched (the peer that broke the lock owns the file)",
+  );
+  assert.equal(after.split("\n").filter((line) => line.trim().length > 0).length, 60_000);
+});
+
+test("writeGraphJsonlAtomic: the rename itself revalidates ownership and refuses a broken lock (round N+20 A)", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-graph-rename-guard-"));
+  const filePath = graphFilePath(dir, "entity");
+  await mkdir(path.dirname(filePath), { recursive: true });
+  const PEER_ROW = `${JSON.stringify({
+    from: "facts/peer.md",
+    to: "facts/peer-target.md",
+    type: "entity",
+    weight: 1,
+    label: "peer",
+    ts: "2026-08-22T00:00:00.000Z",
+  })}\n`;
+  await writeFile(filePath, PEER_ROW, "utf8");
+
+  await withGraphWriteLock(filePath, async (lock) => {
+    assert.equal(await lock.refresh(), true, "an unbroken lock refreshes");
+    // The N+20 A window: the CALLER's ownership check has passed, then the
+    // section stalls past the 30s stale window — a peer breaks the lock and
+    // publishes its own write — and the section resumes at the rename.
+    const lockPath = `${filePath}.lock`;
+    await unlink(lockPath).catch(() => undefined);
+    await writeFile(lockPath, `${process.pid} peer-${randomUUID()} ${new Date().toISOString()}\n`, "utf8");
+    await assert.rejects(
+      writeGraphJsonlAtomic(
+        filePath,
+        [{ from: "facts/mine.md", to: "facts/mine-target.md", type: "entity", weight: 1, label: "mine", ts: "2026-08-22T00:00:00.000Z" }],
+        lock,
+      ),
+      GraphLockLostError,
+      "the publish step must revalidate ownership immediately before the rename",
+    );
+    assert.equal(await readFile(filePath, "utf8"), PEER_ROW, "the refused rename left the peer's write intact");
+  });
+});

package/src/graph-write-lock.ts

@@ -0,0 +1,132 @@
+/**
+ * Cross-process-safe write lock for graph JSONL files (issue #2330 round
+ * N+18 A). Sibling of graph.ts — extracted there so graph.ts stays within
+ * its file-size ratchet; graph.ts re-exports {@link withGraphWriteLock}
+ * because `@remnic/core/graph` is a public subpath export.
+ *
+ * Three layers, one per section:
+ *
+ * 1. An in-process promise chain keyed by JSONL file path (gotcha #40):
+ *    the append path (`appendEdge`) and the rewrite path used by the decay
+ *    maintenance job serialize on the same lock. Without this, an
+ *    extraction can append a new edge between the decay job's
+ *    read-snapshot and rewrite, silently dropping the appended edge during
+ *    active traffic (issue #729 / Codex P1).
+ *
+ * 2. A cross-process advisory lock: the promise chain only serializes THIS
+ *    process. A peer Remnic process sharing the memory directory could
+ *    append an edge after this process reads its JSONL snapshot but before
+ *    the rename-backed rewrite publishes, permanently discarding the
+ *    peer's edge — so every section also holds the established
+ *    `withHeldFileLock` advisory lock (the same primitive round N+16 gave
+ *    the page-versioning manifest) as a sibling `<file>.lock`. A lock that
+ *    cannot be taken within the bounded wait FAILS the write (strict,
+ *    matching the manifest): proceeding unsynchronized would reintroduce
+ *    the lost-write race the lock exists to prevent. Graph write callers
+ *    are fail-open, so the surfaced error degrades to a logged skip.
+ *
+ * 3. Ownership revalidation before destructive writes (round N+19 A): the
+ *    lock's mtime heartbeat is a TIMER — it cannot fire while a
+ *    synchronous parse/serialize of a large graph blocks the event loop.
+ *    A peer can then judge the lock stale past the 30s window, break it,
+ *    and publish its own write. Every section therefore receives the
+ *    lock's {@link GraphWriteLockSection} controller and MUST pass it to
+ *    {@link assertGraphLockHeld} immediately before publishing a
+ *    replacement (or appending): a lost lock aborts THIS write with
+ *    {@link GraphLockLostError} instead of clobbering the peer's. Long
+ *    CPU passes inside a section should await {@link
+ *    yieldForLockHeartbeat} every few thousand rows so the heartbeat
+ *    timer gets a turn and the section is less likely to be broken in
+ *    the first place.
+ */
+
+import { withHeldFileLock, type HeldFileLockController } from "./utils/serialize-mutations.js";
+
+const graphWriteLocks = new Map<string, Promise<void>>();
+
+/** Stale-lock window for the cross-process graph lock (crashed holder). */
+const GRAPH_LOCK_STALE_MS = 30_000;
+/** Bounded acquisition wait for the cross-process graph lock. */
+const GRAPH_LOCK_MAX_WAIT_MS = 10_000;
+
+/** Control surface handed to a graph write-lock section (round N+19 A). */
+export type GraphWriteLockSection = HeldFileLockController;
+
+/**
+ * A graph write section lost its advisory lock mid-critical-section — a peer
+ * stale-broke and replaced it while this process's event loop was blocked.
+ * The thrower has NOT published its write; callers treat it like any other
+ * write failure (graph callers are fail-open).
+ */
+export class GraphLockLostError extends Error {
+  constructor(filePath: string) {
+    super(
+      `graph: the write lock for ${filePath} was lost mid-section — a peer stale-broke and replaced it; aborting this write instead of clobbering the peer's`,
+    );
+    this.name = "GraphLockLostError";
+  }
+}
+
+/**
+ * Revalidate lock ownership immediately before a destructive graph write.
+ * Throws {@link GraphLockLostError} when the lock was broken/replaced, so the
+ * caller aborts and leaves the peer's write intact.
+ */
+export async function assertGraphLockHeld(
+  filePath: string,
+  lock: GraphWriteLockSection,
+): Promise<void> {
+  if (!(await lock.refresh())) throw new GraphLockLostError(filePath);
+}
+
+/**
+ * Yield one event-loop turn so the lock's heartbeat timer can fire during a
+ * long, CPU-bound parse/serialize/decay pass inside a held graph lock
+ * section (round N+19 A). `setImmediate` runs in the check phase, after any
+ * due timers, so each yield lets an overdue heartbeat stamp the lock's mtime
+ * before a peer judges it stale.
+ */
+export function yieldForLockHeartbeat(): Promise<void> {
+  return new Promise<void>((resolve) => setImmediate(resolve));
+}
+
+/**
+ * Run `fn` while holding the write lock for the given graph JSONL file,
+ * handing it the section's {@link GraphWriteLockSection} controller.
+ *
+ * The lock is keyed by absolute file path so concurrent writes to
+ * different graph types proceed independently. The chain recovers from
+ * rejection (gotcha #40) so a single I/O failure does not poison all
+ * future writers, but the original error is still surfaced to the
+ * caller of `withGraphWriteLock`. The in-process chain runs INSIDE the
+ * cross-process advisory lock, so peers serialize against every section
+ * this process runs, one section at a time.
+ */
+export function withGraphWriteLock<T>(
+  filePath: string,
+  fn: (lock: GraphWriteLockSection) => Promise<T>,
+): Promise<T> {
+  const run = () =>
+    withHeldFileLock(
+      `${filePath}.lock`,
+      { staleMs: GRAPH_LOCK_STALE_MS, maxWaitMs: GRAPH_LOCK_MAX_WAIT_MS },
+      (acquired, lock) => {
+        if (!acquired) {
+          throw new Error(
+            `graph: could not acquire the graph write lock for ${filePath} within ${GRAPH_LOCK_MAX_WAIT_MS}ms — another process holds it`,
+          );
+        }
+        return fn(lock);
+      },
+    );
+  const prev = graphWriteLocks.get(filePath) ?? Promise.resolve();
+  const next = prev.then(run, run);
+  graphWriteLocks.set(
+    filePath,
+    next.then(
+      () => undefined,
+      () => undefined
+    )
+  );
+  return next;
+}