@remnic/core 9.69.22 → 9.69.24

package/src/maintenance/graph-edge-decay.ts

@@ -31,6 +31,9 @@ import {
   readEdgeConfidence,
   type DecayOptions,
 } from "../graph-edge-reinforcement.js";
+import { writeGraphJsonlAtomic } from "../graph-jsonl.js";
+import { log } from "../logger.js";
+import { assertGraphLockHeld, yieldForLockHeartbeat } from "../graph-write-lock.js";
 import {
   graphFilePath,
   graphsDir,
@@ -94,17 +97,6 @@ export function graphEdgeDecayStatusPath(memoryDir: string): string {
   return path.join(memoryDir, "state", "graph-edge-decay-status.json");
 }
 
-/** Write a JSONL file atomically using temp+rename (CLAUDE.md gotcha #54). */
-async function writeJsonlAtomic(filePath: string, edges: GraphEdge[]): Promise<void> {
-  await mkdir(path.dirname(filePath), { recursive: true });
-  const body = edges.length === 0 ? "" : edges.map((e) => JSON.stringify(e)).join("\n") + "\n";
-  // Codex P2 / gotcha #54: write to temp then rename. Never rmSync(target)
-  // before the rename succeeds; rename is atomic on the same filesystem.
-  // Include pid + monotonic-ish suffix so concurrent runs cannot collide.
-  const tempPath = `${filePath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
-  await writeFile(tempPath, body, "utf-8");
-  await rename(tempPath, filePath);
-}
 
 /**
  * Run a single decay pass over every edge type.
@@ -160,7 +152,7 @@ export async function runGraphEdgeDecayMaintenance(
       typeDecayed,
       typeBelow,
       typeTotal,
-    } = await withGraphWriteLock(filePath, async () => {
+    } = await withGraphWriteLock(filePath, async (lock) => {
       const edges = await readEdgesStrict(memoryDir, type);
       const updated: GraphEdge[] = new Array(edges.length);
 
@@ -169,6 +161,10 @@ export async function runGraphEdgeDecayMaintenance(
       let localChangedAny = false;
 
       for (let i = 0; i < edges.length; i += 1) {
+        // Round N+19 A: the per-edge decay pass is CPU-bound; yield
+        // periodically so the lock's mtime heartbeat timer can fire and a
+        // peer does not judge the lock stale mid-run.
+        if (i > 0 && i % 5_000 === 0) await yieldForLockHeartbeat();
         const edge = edges[i];
         const before = readEdgeConfidence(edge);
         const decayed = decayEdgeConfidence(edge, ranAt, { windowMs, perWindow, floor });
@@ -209,7 +205,22 @@ export async function runGraphEdgeDecayMaintenance(
       }
 
       if (!dryRun && localChangedAny && edges.length > 0) {
-        await writeJsonlAtomic(filePath, updated);
+        // Round N+19 A: revalidate ownership before the rename-backed
+        // replace — a peer that stale-broke this lock during the (yielding)
+        // decay pass owns the file now. Leave it untouched; the next run
+        // re-decays from whatever the peer published. The pass reports zero
+        // decayed edges for this type so the telemetry never claims a
+        // rewrite that did not land (per-label drop totals may still include
+        // the skipped pass — the warning names it).
+        try {
+          await assertGraphLockHeld(filePath, lock);
+        } catch (err) {
+          log.warn(
+            `graph decay: skipped the ${type} rewrite — ${err instanceof Error ? err.message : String(err)}; per-label drop totals may include this skipped pass`,
+          );
+          return { typeDecayed: 0, typeBelow: localBelow, typeTotal: edges.length };
+        }
+        await writeGraphJsonlAtomic(filePath, updated, lock);
       }
 
       return {

package/src/maintenance/purge.ts

@@ -25,6 +25,7 @@ import type { StorageManager } from "../storage.js";
 import type { MemoryFile } from "../types.js";
 import { markProjectedMemoryPathInvalid } from "../memory-projection-store.js";
 import type { SearchBackend } from "../search/port.js";
+import { isErrnoCode } from "../utils/errno.js";
 
 export type PurgeTierFilter = "cold" | "all";
 
@@ -87,10 +88,6 @@ export interface PurgeMemoriesResult {
   errors: Array<{ id: string; path: string; error: string }>;
 }
 
-function hasErrorCode(err: unknown, code: string): boolean {
-  return typeof err === "object" && err !== null && "code" in err && (err as { code?: unknown }).code === code;
-}
-
 function resolveTimestamp(memory: MemoryFile): string {
   const fm = memory.frontmatter as unknown as Record<string, unknown>;
   const updated = typeof fm.updated === "string" ? (fm.updated as string) : "";
@@ -247,7 +244,7 @@ export async function purgeMemories(
       }
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
-      if (hasErrorCode(err, "ENOENT")) {
+      if (isErrnoCode(err, "ENOENT")) {
         alreadyAbsent.push(candidate);
         addCollectionForCandidate(candidate);
         markProjectedMemoryPathInvalid(storage.dir, candidate.id);

package/src/maintenance/rebuild-memory-lifecycle-ledger.ts

@@ -18,6 +18,7 @@ import {
 } from "../memory-lifecycle-ledger-utils.js";
 import { withHeldFileLock, type HeldFileLockOptions, type HeldFileLockController } from "../utils/serialize-mutations.js";
 import { probeEncryptedRegularFileHeader } from "../secure-store/secure-fs.js";
+import { isErrnoCode } from "../utils/errno.js";
 
 
 export interface RebuildMemoryLifecycleLedgerOptions {
@@ -115,10 +116,6 @@ export interface RebuildMemoryLifecycleLedgerResult {
   rewritten?: boolean;
 }
 
-function isNodeError(err: unknown): err is NodeJS.ErrnoException {
-  return typeof err === "object" && err !== null && "code" in err;
-}
-
 /** Serialized on-disk size (bytes, incl. trailing newline) of one ledger row. */
 function lifecycleRowBytes(event: MemoryLifecycleEvent): number {
   return Buffer.byteLength(`${JSON.stringify(event)}\n`, "utf8");
@@ -174,7 +171,7 @@ export async function backupExistingLedger(
   try {
     await stat(outputPath);
   } catch (err) {
-    if (isNodeError(err) && err.code === "ENOENT") {
+    if (isErrnoCode(err, "ENOENT")) {
       return undefined;
     }
     throw err;
@@ -397,7 +394,7 @@ export async function rebuildMemoryLifecycleLedger(
         currentEncrypted = await probeEncryptedRegularFileHeader(outputPath);
         priorRawBuffer = await storage.readMemoryLifecycleLedgerRawBufferForCompaction();
       } catch (err) {
-        if (!isNodeError(err) || err.code !== "ENOENT") throw err;
+        if (!isErrnoCode(err, "ENOENT")) throw err;
       }
       // Preserve encryption at rest (#2033). An already-encrypted ledger (or its
       // encrypted backup) MUST be rewritten encrypted even when the

package/src/maintenance/rebuild-memory-projection.ts

@@ -76,6 +76,7 @@ import type {
   SkippedDuplicateMemory,
   SkippedDuplicateTimelineEvent,
 } from "./projection-support.js";
+import { isErrnoCode } from "../utils/errno.js";
 
 
 export interface RebuildMemoryProjectionResult {
@@ -150,10 +151,6 @@ export interface RepairMemoryProjectionResult {
   rebuild?: RebuildMemoryProjectionResult;
 }
 
-function isNodeError(err: unknown): err is NodeJS.ErrnoException {
-  return typeof err === "object" && err !== null && "code" in err;
-}
-
 export async function backupExistingProjection(
   memoryDir: string,
   outputPath: string,
@@ -162,7 +159,7 @@ export async function backupExistingProjection(
   try {
     await stat(outputPath);
   } catch (err) {
-    if (isNodeError(err) && err.code === "ENOENT") {
+    if (isErrnoCode(err, "ENOENT")) {
       return undefined;
     }
     throw err;

package/src/namespaces/catalog.ts

@@ -22,6 +22,7 @@ import { isSafeRouteNamespace } from "../routing/engine.js";
 import { namespaceIdentityFromToken, namespaceIdentityLegacyToken, namespaceIdentityToken, normalizeNamespaceIdentity } from "./identity.js";
 import { resolveDefaultNamespaceRoot, resolveNamespaceStorageRoot } from "./storage.js";
 import { ALL_CATEGORY_DIRS } from "../utils/category-dir.js";
+import { isNotFoundError } from "../utils/errno.js";
 
 /**
  * Rebuildable namespace catalog (issue #1499).
@@ -191,15 +192,6 @@ type MemoryDataRootStatus = {
   invalidMarker?: string;
 };
 
-function isNotFoundError(err: unknown): boolean {
-  return (
-    typeof err === "object" &&
-    err !== null &&
-    "code" in err &&
-    (err as { code?: string }).code === "ENOENT"
-  );
-}
-
 /**
  * Inspect `child` under `rootDir` as a memory-data marker (NIw0F / PR #1506).
  * Existence alone is not enough: a bogus marker — e.g. `facts` as a symlink or a

package/src/offline-sync-file-io.test.ts

@@ -0,0 +1,39 @@
+import assert from "node:assert/strict";
+import { mkdtemp, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { sha256OfflineSyncFile } from "./offline-sync-file-io.js";
+
+async function tempFile(name: string, content: string): Promise<string> {
+  const dir = await mkdtemp(path.join(os.tmpdir(), `${name}-`));
+  const filePath = path.join(dir, `${name}.txt`);
+  await writeFile(filePath, content);
+  return filePath;
+}
+
+/** The abort guards must surface `name === "AbortError"`, not a plain Error (issue #2795). */
+async function assertRejectsWithAbortError(promise: Promise<unknown>): Promise<void> {
+  await assert.rejects(promise, (err: unknown) => {
+    assert.ok(err instanceof Error, "abort must surface an Error");
+    assert.equal(err.name, "AbortError", "abort must preserve the AbortError name");
+    return true;
+  });
+}
+
+test("sha256OfflineSyncFile rejects with AbortError name via the per-chunk guard", async () => {
+  const filePath = await tempFile("offline-sync-abort", "chunk-of-bytes");
+  const controller = new AbortController();
+  controller.abort();
+  // A non-empty file yields at least one chunk, so the in-loop guard fires first.
+  await assertRejectsWithAbortError(sha256OfflineSyncFile(filePath, controller.signal));
+});
+
+test("sha256OfflineSyncFile rejects with AbortError name via the post-loop guard", async () => {
+  const filePath = await tempFile("offline-sync-abort-empty", "");
+  const controller = new AbortController();
+  controller.abort();
+  // An empty file yields no chunks, so only the trailing guard runs.
+  await assertRejectsWithAbortError(sha256OfflineSyncFile(filePath, controller.signal));
+});

package/src/offline-sync-file-io.ts

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { open } from "node:fs/promises";
+import { throwIfAborted } from "./abort-error.js";
 import { MAGIC_HEADER_SIZE, isEncryptedFile } from "./secure-store/secure-fs.js";
 
 export interface OfflineSyncFileTarget {
@@ -10,11 +11,6 @@ export interface OfflineSyncFileTarget {
 }
 
 export type OfflineSyncExcludeFile = (target: OfflineSyncFileTarget) => boolean | Promise<boolean>;
-
-function throwIfAborted(signal: AbortSignal | undefined): void {
-  if (signal?.aborted) throw new Error("offline sync request aborted");
-}
-
 export async function shouldExcludeOfflineSyncFile(
   excludeFile: OfflineSyncExcludeFile | undefined,
   target: OfflineSyncFileTarget
@@ -29,12 +25,12 @@ export async function sha256OfflineSyncFile(
   const hash = createHash("sha256");
   let bytes = 0;
   for await (const chunk of createReadStream(filePath)) {
-    throwIfAborted(signal);
+    throwIfAborted(signal, "offline sync request aborted");
     const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
     hash.update(buffer);
     bytes += buffer.length;
   }
-  throwIfAborted(signal);
+  throwIfAborted(signal, "offline sync request aborted");
   return { sha256: hash.digest("hex"), bytes };
 }
 

package/src/orchestration/contradiction-localization.integration.test.ts

@@ -431,6 +431,41 @@ test("anchor snapshot prefers an active cold copy over a path-archived hot dupli
   assert.deepEqual(await snapshots.get(storage, "person:alice"), [cold]);
 });
 
+test("replace refreshes a cold-tier target via the cold-aware id lookup (final round B)", async () => {
+  const storageDir = "/tmp/remnic-anchor-snapshot-cold-replace";
+  const coldPath = path.join(storageDir, "cold", "2026-08-01", "fact-cold-target.md");
+  const preMerge = {
+    path: coldPath,
+    content: "pre-merge body",
+    frontmatter: {
+      id: "fact-cold-target",
+      category: "fact",
+      entityRef: "person:alice",
+      status: "active",
+    },
+  } as unknown as MemoryFile;
+  const merged = { ...preMerge, content: "merged body" } as unknown as MemoryFile;
+  const storage = {
+    dir: storageDir,
+    readAllMemories: async () => [],
+    readAllColdMemories: async () => [preMerge],
+    // A pre-existing cold target has no pathById entry, so replace() derives
+    // the hot fallback path (facts/fact-cold-target.md) — this stub answers
+    // ONLY the real cold path, mirroring the miss that left the stale body.
+    readMemoryByPath: async (p: string) => (p === coldPath ? merged : null),
+    getMemoryByIdIncludingArchived: async (id: string) =>
+      id === "fact-cold-target" ? merged : null,
+  } as unknown as StorageManager;
+  const snapshots = new ExtractionAnchorSnapshot();
+
+  // A first same-entity fact warms the cache with the pre-merge cold body.
+  assert.deepEqual(await snapshots.get(storage, "person:alice"), [preMerge]);
+  await snapshots.replace(storage, "fact-cold-target", "fact", new Map());
+  // A later same-entity fact in the same extraction localizes against this
+  // cache; it must see the merged body, not the stale pre-merge one.
+  assert.deepEqual(await snapshots.get(storage, "person:alice"), [merged]);
+});
+
 test("isolates anchor snapshot failures per storage", async () => {
   const snapshots = new ExtractionAnchorSnapshot();
   const failedStorage = {

package/src/orchestration/extraction-anchor-snapshot.ts

@@ -62,7 +62,12 @@ export class ExtractionAnchorSnapshot {
       if (!cached) return;
       const snapshot = await cached;
       const relativePath = resolvePersistedMemoryRelativePath({ memoryId, pathById, category });
-      const memory = await storage.readMemoryByPath(path.join(storage.dir, relativePath));
+      let memory = await storage.readMemoryByPath(path.join(storage.dir, relativePath));
+      // Final round (B): a pre-existing target (e.g. cold-tier) has no
+      // pathById entry, so the derived hot path misses and the read returns
+      // null — leaving the cached pre-merge body in place. Fall back to the
+      // same cold-aware id lookup the merge itself uses.
+      if (!memory) memory = await storage.getMemoryByIdIncludingArchived(memoryId);
       if (!memory) return;
       const existingIndex = snapshot.findIndex((entry) => entry.frontmatter.id === memoryId);
       if (existingIndex >= 0) snapshot.splice(existingIndex, 1);

package/src/orchestration/extraction-persist-deps.ts

@@ -1,4 +1,5 @@
 import type { ContradictionResolveOutcome } from "./contradiction-linking-coordinator.js";
+import type { GraphEdge } from "../graph.js";
 import type { GraphConstructionCapabilitySet } from "../capabilities.js";
 import type { SemanticDedupHit } from "../dedup/semantic.js";
 import type { EmbeddingFallback } from "../embedding-fallback.js";
@@ -94,6 +95,6 @@ export interface ExtractionPersistDeps {
     threadEpisodeIdsForGraph: string[] | undefined,
     fallbackCausalPredecessor: string | undefined,
     graphCaps?: GraphConstructionCapabilitySet
-  ) => Promise<void>;
+  ) => Promise<GraphEdge[] | void>;
   updateTemporalTagIndexes: (storage: StorageManager, persistedIds: string[]) => Promise<void>;
 }