@remnic/core 9.69.22 → 9.69.24

package/src/graph.ts

@@ -12,7 +12,7 @@
 
 import { appendFile, mkdir, readFile, stat } from "node:fs/promises";
 import * as path from "node:path";
-
+import { GraphEdgeAppendError } from "./graph-append-error.js";
 import { readEdgeConfidence } from "./graph-edge-reinforcement.js";
 import { emitGraphEvent } from "./graph-events.js";
 import type { GraphConstructionCapabilitySet } from "./capabilities.js";
@@ -24,6 +24,13 @@ import {
   type ActivationPredecessor,
 } from "./graph-path-reconstruction.js";
 export { reconstructActivationPath, type ActivationPredecessor };
+import {
+  assertGraphLockHeld,
+  GraphLockLostError,
+  withGraphWriteLock,
+  yieldForLockHeartbeat,
+} from "./graph-write-lock.js";
+import { isErrnoCode } from "./utils/errno.js";
 
 export type GraphType = "entity" | "time" | "causal";
 
@@ -110,44 +117,19 @@ export async function ensureGraphsDir(memoryDir: string): Promise<void> {
   await mkdir(graphsDir(memoryDir), { recursive: true });
 }
 
-// ---------------------------------------------------------------------------
-// Per-graph-file write lock (gotcha #40 promise-chain pattern).
-//
-// Both the append path (`appendEdge`) and the rewrite path used by the
-// decay maintenance job must serialize on the same lock keyed by the
-// JSONL file path. 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).
-// ---------------------------------------------------------------------------
-const graphWriteLocks = new Map<string, Promise<void>>();
-
-/**
- * Run `fn` while holding the write lock for the given graph JSONL file.
- *
- * 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`.
- */
-export function withGraphWriteLock<T>(filePath: string, fn: () => Promise<T>): Promise<T> {
-  const prev = graphWriteLocks.get(filePath) ?? Promise.resolve();
-  const next = prev.then(fn, fn);
-  graphWriteLocks.set(
-    filePath,
-    next.then(
-      () => undefined,
-      () => undefined
-    )
-  );
-  return next;
-}
+// Per-graph-file write lock lives in the graph-write-lock.ts sibling (the
+// in-process chain plus the cross-process advisory lock, issue #2330 round
+// N+18 A). Re-exported here because `@remnic/core/graph` is a public
+// subpath export whose consumers import `withGraphWriteLock` from it.
+export { withGraphWriteLock, GraphLockLostError };
 
 export async function appendEdge(memoryDir: string, edge: GraphEdge): Promise<void> {
   await ensureGraphsDir(memoryDir);
   const filePath = graphFilePath(memoryDir, edge.type);
   const line = `${JSON.stringify(edge)}\n`;
-  await withGraphWriteLock(filePath, async () => {
+  await withGraphWriteLock(filePath, async (lock) => {
+    // Round N+19 A: never append into a file a peer that broke this lock may rename over.
+    await assertGraphLockHeld(filePath, lock);
     await appendFile(filePath, line, "utf8");
   });
   // Emit edge-added event for SSE subscribers (issue #691 PR 5/5).
@@ -163,10 +145,6 @@ export async function appendEdge(memoryDir: string, edge: GraphEdge): Promise<vo
   });
 }
 
-function isNodeError(err: unknown): err is NodeJS.ErrnoException {
-  return typeof err === "object" && err !== null && "code" in err;
-}
-
 function parseEdgesJsonl(raw: string, expectedType: GraphType): GraphEdge[] {
   const edges: GraphEdge[] = [];
   for (const line of raw.split("\n")) {
@@ -184,6 +162,23 @@ function parseEdgesJsonl(raw: string, expectedType: GraphType): GraphEdge[] {
   return edges;
 }
 
+/** Parse batch size at which locked-section parsing yields to the event loop
+ * so the graph lock's heartbeat timer can fire (round N+19 A). */
+const EDGE_PARSE_YIELD_BATCH = 5_000;
+
+/** Chunked {@link parseEdgesJsonl} yielding between batches; used by
+ * {@link readEdgesStrict} (the locked-section reader) — the hot recall path
+ * (`readEdges`) keeps the synchronous parse. */
+async function parseEdgesJsonlYielding(raw: string, expectedType: GraphType): Promise<GraphEdge[]> {
+  const lines = raw.split("\n");
+  const edges: GraphEdge[] = [];
+  for (let i = 0; i < lines.length; i += EDGE_PARSE_YIELD_BATCH) {
+    if (i > 0) await yieldForLockHeartbeat();
+    edges.push(...parseEdgesJsonl(lines.slice(i, i + EDGE_PARSE_YIELD_BATCH).join("\n"), expectedType));
+  }
+  return edges;
+}
+
 /**
  * Read all edges of a given type from the JSONL file.
  * Returns [] if the file doesn't exist or any read error occurs (fail-open).
@@ -214,9 +209,9 @@ export async function readEdgesStrict(memoryDir: string, type: GraphType): Promi
   const filePath = graphFilePath(memoryDir, type);
   try {
     const raw = await readFile(filePath, "utf8");
-    return parseEdgesJsonl(raw, type);
+    return await parseEdgesJsonlYielding(raw, type);
   } catch (err) {
-    if (isNodeError(err) && err.code === "ENOENT") {
+    if (isErrnoCode(err, "ENOENT")) {
       return [];
     }
     throw err;
@@ -567,6 +562,12 @@ export class GraphIndex {
   /**
    * Called after a memory is written to disk.
    *
+   * Throws when an edge append fails (after logging): the merged-target rewrite
+   * path depends on the rejection to restore the edges `removeNodeEdgesForRewrite`
+   * dropped — swallowing here left that restore dead and the prior edge set
+   * permanently lost (#2330). Fail-open is the CALLER's decision; the create
+   * paths already catch (see persistence-index.buildGraphEdge).
+   *
    * @param memoryPath - relative path from memoryDir (e.g. "facts/2026-02-22/abc.md")
    * @param entityRef  - entityRef frontmatter field (if any)
    * @param content    - full memory text (for causal detection)
@@ -595,16 +596,15 @@ export class GraphIndex {
       causalGraph: boolean;
       multiGraphMemory: boolean;
     };
-  }): Promise<void> {
+  }): Promise<GraphEdge[]> {
     const g = opts.graphCapsOverride;
     const multiGraphOn = g ? g.multiGraphMemory : this.cfg.multiGraphMemoryEnabled;
-    if (!multiGraphOn) return;
+    if (!multiGraphOn) return [];
     const entityOn = g ? g.entityGraph : this.cfg.entityGraphEnabled;
     const timeOn = g ? g.timeGraph : this.cfg.timeGraphEnabled;
     const causalOn = g ? g.causalGraph : this.cfg.causalGraphEnabled;
     const ts = new Date().toISOString();
-    // Collect the edges appended this call so a coherent single-writer push can
-    // extend the warm edge cache in place instead of nulling it (issue #1904).
+    // Appended this call: warm-cache in-place push (#1904) + surgical rollback rows (N+14).
     const appended: GraphEdge[] = [];
 
     try {
@@ -659,9 +659,12 @@ export class GraphIndex {
         }
       }
     } catch (err) {
-      // Fail-open: graph write errors must never surface to caller
+      // Log, then rethrow (#2330): the rewrite path's restore step only runs
+      // when this rejection reaches its caller (fail-open callers catch). The
+      // error carries the rows already appended (N+16 A) — surgical rollback.
       const { log } = await import("./logger.js");
       log.warn(`[graph] onMemoryWritten error: ${err}`);
+      throw new GraphEdgeAppendError(err, appended);
     } finally {
       // Edge-cache coherence (issue #1904). Legacy behavior nulled the cache on
       // every write, paying a 2-4 s full re-read + parse on the next traversal.
@@ -700,6 +703,7 @@ export class GraphIndex {
         }
       }
     }
+    return appended;
   }
 
   /**

package/src/harmonic-construction.test.ts

@@ -1190,6 +1190,335 @@ test("persistExtraction writes nodes with harmonic retrieval and gates cue ancho
   }
 });
 
+test("persistExtraction enqueues a merged target for harmonic construction (merge-only batch)", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-harmonic-merge-"));
+  const TARGET_ID = "merge-target-main";
+  const SEED = "The billing service deploys on a Tuesday cadence.";
+  const INCOMING = "The billing service deploys at 09:00 UTC sharp.";
+  try {
+    const config = parseConfig({
+      openaiApiKey: "sk-test",
+      memoryDir,
+      workspaceDir: path.join(memoryDir, "workspace"),
+      qmdEnabled: false,
+      embeddingFallbackEnabled: true,
+      chunkingEnabled: false,
+      harmonicRetrievalEnabled: true,
+      abstractionAnchorsEnabled: true,
+      versioningEnabled: true,
+      semanticMerge: { enabled: true },
+    });
+    const orchestrator = new Orchestrator(config) as unknown as PersistenceHarness & {
+      embeddingFallback: {
+        isAvailable: () => Promise<boolean>;
+        search: (
+          query: string,
+          limit: number,
+          options?: unknown,
+        ) => Promise<Array<{ id: string; score: number; path: string }>>;
+        indexFile: (id: string, content: string, path: string) => Promise<void>;
+        removeFromIndex: (id: string) => Promise<void>;
+      };
+      localLlm: {
+        chatCompletion: (
+          messages: Array<{ role: string; content: string }>,
+        ) => Promise<{ content: string } | null>;
+      };
+    };
+    const storage = await orchestrator.getStorage("default");
+    await storage.ensureDirectories();
+    // Seed a merge target with past timestamps and high importance so the
+    // incoming fact never bypasses as unpreservable metadata.
+    const created = new Date(Date.now() - 3600_000).toISOString();
+    const seededDir = path.join(memoryDir, "facts", created.slice(0, 10));
+    await mkdir(seededDir, { recursive: true });
+    await writeFile(
+      path.join(seededDir, `${TARGET_ID}.md`),
+      [
+        "---",
+        `id: ${TARGET_ID}`,
+        "category: fact",
+        `created: ${created}`,
+        `updated: ${created}`,
+        "source: extraction",
+        "confidence: 0.9",
+        "confidenceTier: explicit",
+        "status: active",
+        "importanceScore: 0.9",
+        "importanceLevel: high",
+        "---",
+        "",
+        SEED,
+        "",
+      ].join("\n"),
+      "utf8",
+    );
+    // Band neighbor for the incoming fact only ([minSimilarity, threshold)).
+    orchestrator.embeddingFallback = {
+      isAvailable: async () => true,
+      search: async (query: string) =>
+        query === INCOMING ? [{ id: TARGET_ID, score: 0.85, path: "" }] : [],
+      indexFile: async () => {},
+      removeFromIndex: async () => {},
+    };
+    // Deterministic judge: merge into the top candidate's current body.
+    orchestrator.localLlm = {
+      chatCompletion: async (messages) => {
+        if (
+          messages[0]?.role !== "system" ||
+          !messages[0].content.startsWith("You maintain a long-term memory store")
+        ) {
+          return null;
+        }
+        const input = JSON.parse(messages[1]?.content ?? "{}") as {
+          new?: { content?: string };
+          existing?: Array<{ id?: string; content?: string }>;
+        };
+        const target = input.existing?.[0];
+        if (!target?.id || typeof target.content !== "string" || typeof input.new?.content !== "string") {
+          return { content: JSON.stringify({ decision: "create", targetId: null, mergedContent: null, reason: "no candidate" }) };
+        }
+        return {
+          content: JSON.stringify({
+            decision: "merge",
+            targetId: target.id,
+            mergedContent: `${target.content} ${input.new.content}`.trim(),
+            reason: "deterministic judge for merge-only harmonic coverage",
+          }),
+        };
+      },
+    };
+    const result: ExtractionResult = {
+      facts: [
+        {
+          category: "fact",
+          content: INCOMING,
+          confidence: 0.9,
+          tags: [],
+          cueAnchors: [{ type: "tool", value: "billing deploy window" }],
+        },
+      ],
+      entities: [],
+      profileUpdates: [],
+      questions: [],
+      relationships: [],
+      episodeTitle: "Billing deploy cadence",
+    };
+    const { persistedIds } = await orchestrator.persistExtraction(result, storage, null, {
+      sessionKey: "session:harmonic-merge",
+    });
+    // Contract preserved: persistedIds stays new-fragment only — the merged
+    // target is updated in place, never reported as a new fragment.
+    assert.deepEqual(persistedIds, []);
+
+    const nodeStatus = await getAbstractionNodeStoreStatus({
+      memoryDir: storage.dir,
+      enabled: true,
+      anchorsEnabled: true,
+    });
+    assert.equal(
+      nodeStatus.nodes.total,
+      1,
+      "a merge-only batch must still derive an episode node for the committed target",
+    );
+    assert.ok(
+      nodeStatus.latestNode?.sourceMemoryIds?.includes(TARGET_ID),
+      "the episode node must cite the surviving target id",
+    );
+    const anchorStatus = await getCueAnchorStoreStatus({
+      memoryDir: storage.dir,
+      enabled: true,
+      anchorsEnabled: true,
+    });
+    assert.ok(
+      anchorStatus.anchors.total >= 1,
+      "the extracted cue anchors must reach the anchor store for the merged claims",
+    );
+    const searchResults = await searchHarmonicRetrieval({
+      memoryDir: storage.dir,
+      query: "billing deploy cadence",
+      maxResults: 5,
+      anchorsEnabled: true,
+    });
+    assert.ok(
+      searchResults.some((item) => item.node.sourceMemoryIds?.includes(TARGET_ID)),
+      "harmonic retrieval must surface the merged target's episode",
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("persistExtraction keeps a merged target in the thread episode set across extractions (round N+11 B)", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-harmonic-merge-thread-"));
+  const TARGET_ID = "merge-target-thread";
+  const SEED = "The billing service deploys on a Tuesday cadence.";
+  const INCOMING = "The billing service deploys at 09:00 UTC sharp.";
+  const LATER = "The billing service pages an on-call engineer after a failed deploy.";
+  const SESSION_KEY = "session:harmonic-merge-thread";
+  try {
+    const config = parseConfig({
+      openaiApiKey: "sk-test",
+      memoryDir,
+      workspaceDir: path.join(memoryDir, "workspace"),
+      qmdEnabled: false,
+      embeddingFallbackEnabled: true,
+      chunkingEnabled: false,
+      harmonicRetrievalEnabled: false,
+      abstractionAnchorsEnabled: false,
+      versioningEnabled: true,
+      semanticMerge: { enabled: true },
+    });
+    const orchestrator = new Orchestrator(config) as unknown as PersistenceHarness & {
+      embeddingFallback: {
+        isAvailable: () => Promise<boolean>;
+        search: (
+          query: string,
+          limit: number,
+          options?: unknown,
+        ) => Promise<Array<{ id: string; score: number; path: string }>>;
+        indexFile: (id: string, content: string, path: string) => Promise<void>;
+        removeFromIndex: (id: string) => Promise<void>;
+      };
+      localLlm: {
+        chatCompletion: (
+          messages: Array<{ role: string; content: string }>,
+        ) => Promise<{ content: string } | null>;
+      };
+      threading: {
+        processTurn: (
+          turn: { role: string; content: string; timestamp: string; sessionKey: string },
+          episodeIds: string[],
+        ) => Promise<string>;
+        loadThread: (id: string) => Promise<{ episodeIds: string[] } | null>;
+      };
+      appendPersistedThreadEpisodes: (threadId: string, persistedIds: string[]) => Promise<void>;
+    };
+    const storage = await orchestrator.getStorage("default");
+    await storage.ensureDirectories();
+    // Seed a merge target the way the sibling merge-only test does: past
+    // timestamps, high importance, active — preservable metadata only.
+    const created = new Date(Date.now() - 3600_000).toISOString();
+    const seededDir = path.join(memoryDir, "facts", created.slice(0, 10));
+    await mkdir(seededDir, { recursive: true });
+    await writeFile(
+      path.join(seededDir, `${TARGET_ID}.md`),
+      [
+        "---",
+        `id: ${TARGET_ID}`,
+        "category: fact",
+        `created: ${created}`,
+        `updated: ${created}`,
+        "source: extraction",
+        "confidence: 0.9",
+        "confidenceTier: explicit",
+        "status: active",
+        "importanceScore: 0.9",
+        "importanceLevel: high",
+        "---",
+        "",
+        SEED,
+        "",
+      ].join("\n"),
+      "utf8",
+    );
+    // Band neighbor for the incoming fact only; the later fact finds none.
+    orchestrator.embeddingFallback = {
+      isAvailable: async () => true,
+      search: async (query: string) =>
+        query === INCOMING ? [{ id: TARGET_ID, score: 0.85, path: "" }] : [],
+      indexFile: async () => {},
+      removeFromIndex: async () => {},
+    };
+    // Deterministic judge: merge into the top candidate's current body.
+    orchestrator.localLlm = {
+      chatCompletion: async (messages) => {
+        if (
+          messages[0]?.role !== "system" ||
+          !messages[0].content.startsWith("You maintain a long-term memory store")
+        ) {
+          return null;
+        }
+        const input = JSON.parse(messages[1]?.content ?? "{}") as {
+          new?: { content?: string };
+          existing?: Array<{ id?: string; content?: string }>;
+        };
+        const target = input.existing?.[0];
+        if (!target?.id || typeof target.content !== "string" || typeof input.new?.content !== "string") {
+          return { content: JSON.stringify({ decision: "create", targetId: null, mergedContent: null, reason: "no candidate" }) };
+        }
+        return {
+          content: JSON.stringify({
+            decision: "merge",
+            targetId: target.id,
+            mergedContent: `${target.content} ${input.new.content}`.trim(),
+            reason: "deterministic judge for thread-episode persistence",
+          }),
+        };
+      },
+    };
+    // Establish the thread the way runExtraction's processTurn step does,
+    // so appendEpisodeIds has a thread file to write into.
+    const threadId = await orchestrator.threading.processTurn(
+      {
+        role: "user",
+        content: "Tell me about billing deploys.",
+        timestamp: "2026-08-22T10:00:00.000Z",
+        sessionKey: SESSION_KEY,
+      },
+      [],
+    );
+    assert.ok(threadId, "thread established via processTurn");
+
+    const mergeResult: ExtractionResult = {
+      facts: [{ category: "fact", content: INCOMING, confidence: 0.9, tags: [] }],
+      entities: [],
+      profileUpdates: [],
+      questions: [],
+      relationships: [],
+    };
+    // --- Flush 1: merge-only. persistedIds stays new-fragment only. ---
+    const flush1 = await orchestrator.persistExtraction(mergeResult, storage, threadId, {
+      sessionKey: SESSION_KEY,
+    });
+    assert.deepEqual(flush1.persistedIds, [], "a merge-only batch reports no new fragments");
+    // runExtraction's append step, exactly as production runs it.
+    await orchestrator.appendPersistedThreadEpisodes(threadId, flush1.persistedIds);
+
+    // --- Flush 2: a NEW fact in the same thread + the append step. ---
+    const laterResult: ExtractionResult = {
+      facts: [{ category: "fact", content: LATER, confidence: 0.9, tags: [] }],
+      entities: [],
+      profileUpdates: [],
+      questions: [],
+      relationships: [],
+    };
+    const flush2 = await orchestrator.persistExtraction(laterResult, storage, threadId, {
+      sessionKey: SESSION_KEY,
+    });
+    await orchestrator.appendPersistedThreadEpisodes(threadId, flush2.persistedIds);
+    const laterId = flush2.persistedIds[0];
+    assert.ok(laterId, "the later fact persisted as a new fragment");
+
+    const thread = await orchestrator.threading.loadThread(threadId);
+    const episodes = thread?.episodeIds ?? [];
+    assert.ok(
+      episodes.includes(TARGET_ID),
+      `the merged target must persist into the thread episode set (got ${JSON.stringify(episodes)})`,
+    );
+    assert.ok(
+      laterId && episodes.includes(laterId),
+      "the later fragment persists into the thread episode set",
+    );
+    assert.ok(
+      episodes.indexOf(TARGET_ID) < episodes.indexOf(laterId),
+      "adjacency: the merged target precedes the fragment extracted after it",
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
 test("harmonic anchors stay scoped to projected active sources in a mixed episode", async () => {
   const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-harmonic-anchor-sources-"));
   try {

package/src/json-store.ts

@@ -13,17 +13,14 @@ import {
   type FileHandle,
 } from "node:fs/promises";
 import path from "node:path";
-
-function hasErrorCode(error: unknown, code: string): boolean {
-  return typeof error === "object" && error !== null && "code" in error && (error as { code?: unknown }).code === code;
-}
+import { isErrnoCode } from "./utils/errno.js";
 
 async function listJsonFilesStrictInner(dir: string, allowMissingDirectory: boolean): Promise<string[]> {
   let entries: Dirent[];
   try {
     entries = await readdir(dir, { withFileTypes: true });
   } catch (error) {
-    if (allowMissingDirectory && hasErrorCode(error, "ENOENT")) return [];
+    if (allowMissingDirectory && isErrnoCode(error, "ENOENT")) return [];
     throw error;
   }
   const out: string[] = [];
@@ -107,7 +104,7 @@ function jsonStoreLockTimeoutMs(): number {
 async function closeAndRemoveJsonStoreReclaimGuard(reclaimPath: string, reclaimHandle: FileHandle): Promise<void> {
   await reclaimHandle.close().catch(() => undefined);
   await unlink(reclaimPath).catch((error) => {
-    if (!hasErrorCode(error, "ENOENT")) throw error;
+    if (!isErrnoCode(error, "ENOENT")) throw error;
   });
 }
 
@@ -116,7 +113,7 @@ async function removeStaleJsonStoreReclaimGuard(reclaimPath: string): Promise<vo
   try {
     initial = await readJsonStoreLockState(reclaimPath);
   } catch (error) {
-    if (hasErrorCode(error, "ENOENT")) return;
+    if (isErrnoCode(error, "ENOENT")) return;
     throw error;
   }
   if (Date.now() - initial.mtimeMs <= jsonStoreLockStaleMs()) return;
@@ -134,12 +131,12 @@ async function removeStaleJsonStoreReclaimGuard(reclaimPath: string): Promise<vo
   try {
     confirmed = await readJsonStoreLockState(reclaimPath);
   } catch (error) {
-    if (hasErrorCode(error, "ENOENT")) return;
+    if (isErrnoCode(error, "ENOENT")) return;
     throw error;
   }
   if (!sameJsonStoreLockState(initial, confirmed)) return;
   await unlink(reclaimPath).catch((error) => {
-    if (!hasErrorCode(error, "ENOENT")) throw error;
+    if (!isErrnoCode(error, "ENOENT")) throw error;
   });
 }
 
@@ -147,12 +144,12 @@ async function acquireJsonStoreReclaimGuard(reclaimPath: string): Promise<FileHa
   try {
     return await open(reclaimPath, "wx", 0o600);
   } catch (error) {
-    if (!hasErrorCode(error, "EEXIST")) throw error;
+    if (!isErrnoCode(error, "EEXIST")) throw error;
     await removeStaleJsonStoreReclaimGuard(reclaimPath);
     try {
       return await open(reclaimPath, "wx", 0o600);
     } catch (retryError) {
-      if (hasErrorCode(retryError, "EEXIST")) return undefined;
+      if (isErrnoCode(retryError, "EEXIST")) return undefined;
       throw retryError;
     }
   }
@@ -169,7 +166,7 @@ function processIsRunning(pid: number): boolean {
     process.kill(pid, 0);
     return true;
   } catch (error) {
-    return !hasErrorCode(error, "ESRCH");
+    return !isErrnoCode(error, "ESRCH");
   }
 }
 
@@ -208,7 +205,7 @@ async function removeJsonStoreMutationLockIfOwned(lockPath: string, token: strin
     const metadata = JSON.parse(state.content) as { token?: unknown };
     if (metadata.token === token) await unlink(lockPath);
   } catch (error) {
-    if (!hasErrorCode(error, "ENOENT") && !(error instanceof SyntaxError)) throw error;
+    if (!isErrnoCode(error, "ENOENT") && !(error instanceof SyntaxError)) throw error;
   }
 }
 
@@ -224,7 +221,7 @@ async function removeStaleJsonStoreLock(lockPath: string): Promise<void> {
     try {
       initial = await readJsonStoreLockState(lockPath);
     } catch (error) {
-      if (hasErrorCode(error, "ENOENT")) return;
+      if (isErrnoCode(error, "ENOENT")) return;
       throw error;
     }
     if (Date.now() - initial.mtimeMs <= jsonStoreLockStaleMs()) return;
@@ -241,12 +238,12 @@ async function removeStaleJsonStoreLock(lockPath: string): Promise<void> {
     try {
       confirmed = await readJsonStoreLockState(lockPath);
     } catch (error) {
-      if (hasErrorCode(error, "ENOENT")) return;
+      if (isErrnoCode(error, "ENOENT")) return;
       throw error;
     }
     if (!sameJsonStoreLockState(initial, confirmed)) return;
     await unlink(lockPath).catch((error) => {
-      if (!hasErrorCode(error, "ENOENT")) throw error;
+      if (!isErrnoCode(error, "ENOENT")) throw error;
     });
   } finally {
     await closeAndRemoveJsonStoreReclaimGuard(reclaimPath, reclaimHandle);
@@ -272,7 +269,7 @@ async function confirmJsonStoreMutationLockOwnership(
         const metadata = JSON.parse(state.content) as { token?: unknown };
         return metadata.token === token;
       } catch (error) {
-        if (hasErrorCode(error, "ENOENT") || error instanceof SyntaxError) return false;
+        if (isErrnoCode(error, "ENOENT") || error instanceof SyntaxError) return false;
         throw error;
       }
     } finally {
@@ -291,9 +288,9 @@ async function acquireJsonStoreMutationFileLock(key: string): Promise<() => Prom
     try {
       handle = await open(lockPath, "wx", 0o600);
     } catch (error) {
-      if (!hasErrorCode(error, "EEXIST")) throw error;
+      if (!isErrnoCode(error, "EEXIST")) throw error;
       await removeStaleJsonStoreLock(lockPath).catch((staleError) => {
-        if (!hasErrorCode(staleError, "ENOENT")) throw staleError;
+        if (!isErrnoCode(staleError, "ENOENT")) throw staleError;
       });
       if (Date.now() >= deadline) {
         throw new Error(`Timed out acquiring JSON store mutation lock: ${lockPath}`);
@@ -338,7 +335,7 @@ async function acquireJsonStoreMutationFileLock(key: string): Promise<() => Prom
         const metadata = JSON.parse(await readFile(lockPath, "utf8")) as { token?: unknown };
         if (metadata.token === token) await unlink(lockPath);
       } catch (error) {
-        if (!hasErrorCode(error, "ENOENT")) throw error;
+        if (!isErrnoCode(error, "ENOENT")) throw error;
       }
     };
   }

package/src/live-connectors-runner.ts

@@ -29,6 +29,7 @@ import {
   type ConnectorState,
   type LiveConnector,
 } from "./connectors/live/index.js";
+import { abortError } from "./abort-error.js";
 import type { LiveConnectorsConfig } from "./types.js";
 
 export type LiveConnectorSkipReason =
@@ -428,7 +429,7 @@ function throwIfAborted(signal: AbortSignal | undefined): void {
   if (reason instanceof Error) {
     throw reason;
   }
-  throw new Error(reason === undefined ? "operation aborted" : String(reason));
+  throw abortError(reason === undefined ? "operation aborted" : String(reason));
 }
 
 async function writeConnectorErrorState(options: {

package/src/location/store.ts

@@ -21,6 +21,7 @@ import path from "node:path";
 
 import { writeFileAtomically } from "../maintenance/atomic-file.js";
 import { pathIsInside } from "../utils/path-containment.js";
+import { isErrnoCode } from "../utils/errno.js";
 import { isValidLocationDate, placeDurations } from "./intervals.js";
 import type { LocationSegment } from "./types.js";
 
@@ -376,10 +377,6 @@ export function parseLocationDaySummary(raw: string): LocationDaySummary | null
 
 // ── Containment-checked day-file IO ─────────────────────────────────────────
 
-function isErrnoCode(err: unknown, code: string): boolean {
-  return err instanceof Error && (err as NodeJS.ErrnoException).code === code;
-}
-
 async function assertNotSymlink(target: string, kind: "directory" | "day file"): Promise<void> {
   let stat: { isSymbolicLink(): boolean };
   try {