@remnic/core 10.0.94 → 10.0.96

package/dist/transfer/export-okf.js

@@ -4,20 +4,20 @@ import {
   exportOkfBundle,
   firstHeading,
   parseIncludeStatus
-} from "../chunk-SUTEBYGI.js";
+} from "../chunk-V7T45MI6.js";
 import {
   OKF_EXPORT_VERSION
 } from "../chunk-I7TR2OCU.js";
 import "../chunk-D24OXEPB.js";
 import "../chunk-3UXOZBHV.js";
-import "../chunk-FWRXW7CZ.js";
+import "../chunk-4CXK3GT3.js";
 import "../chunk-QGVCFVX6.js";
 import "../chunk-UHVXE24Y.js";
-import "../chunk-IGOW4TJE.js";
-import "../chunk-RFUL2ZIQ.js";
+import "../chunk-O3JG4PD3.js";
 import "../chunk-G6OFEGUR.js";
-import "../chunk-A4F7OIC5.js";
-import "../chunk-XPXHQI6N.js";
+import "../chunk-RFUL2ZIQ.js";
+import "../chunk-WVIWDMFB.js";
+import "../chunk-FVMEZ57K.js";
 import "../chunk-DOJBV6WR.js";
 import "../chunk-PFUXPTBT.js";
 import "../chunk-CYEPCZN5.js";
@@ -49,25 +49,20 @@ import "../chunk-3WU7XOFN.js";
 import "../chunk-P4GUQSK3.js";
 import "../chunk-4LZ7SVKM.js";
 import "../chunk-YHTG64XV.js";
-import "../chunk-SQ3GEIEL.js";
-import "../chunk-IAYUTGF2.js";
+import "../chunk-KUQLUYIR.js";
+import "../chunk-O3GZPLVY.js";
 import "../chunk-5WITETWU.js";
-import "../chunk-M5GVCJSJ.js";
-import "../chunk-RBOJCG4T.js";
 import "../chunk-6CIAGZ6X.js";
-import "../chunk-7CT3AI52.js";
 import "../chunk-G7D6GZ5J.js";
 import "../chunk-7VLBZKNB.js";
 import "../chunk-Y33KJ556.js";
-import "../chunk-R23JWJD3.js";
+import "../chunk-J426U7XK.js";
 import "../chunk-NWA6IXR3.js";
+import "../chunk-AF2XMJKD.js";
 import "../chunk-OR42ZI54.js";
 import "../chunk-IUM3VSHI.js";
 import "../chunk-EZ47HOJ6.js";
-import "../chunk-AF2XMJKD.js";
 import "../chunk-23G5P7TA.js";
-import "../chunk-C64XATK7.js";
-import "../chunk-42JKGUFJ.js";
 import "../chunk-MMRTPH3J.js";
 import "../chunk-I55KAVET.js";
 import "../chunk-L2EXJQJP.js";
@@ -111,6 +106,11 @@ import "../chunk-P7FMDTKL.js";
 import "../chunk-X4OZMANG.js";
 import "../chunk-ZEFVK7XC.js";
 import "../chunk-R2MBW2S4.js";
+import "../chunk-M5GVCJSJ.js";
+import "../chunk-RBOJCG4T.js";
+import "../chunk-7CT3AI52.js";
+import "../chunk-C64XATK7.js";
+import "../chunk-42JKGUFJ.js";
 import "../chunk-QUIRIG2P.js";
 import "../chunk-6KH5NLQS.js";
 import "../chunk-P2QRMMVQ.js";

package/dist/verified-recall.js

@@ -1,16 +1,16 @@
 import {
   compareVerifiedEpisodeResults,
   searchVerifiedEpisodes
-} from "./chunk-ILY5SSOM.js";
+} from "./chunk-53ZVHXVZ.js";
 import "./chunk-B7RWBZXW.js";
-import "./chunk-FWRXW7CZ.js";
+import "./chunk-4CXK3GT3.js";
 import "./chunk-QGVCFVX6.js";
 import "./chunk-UHVXE24Y.js";
-import "./chunk-IGOW4TJE.js";
-import "./chunk-RFUL2ZIQ.js";
+import "./chunk-O3JG4PD3.js";
 import "./chunk-G6OFEGUR.js";
-import "./chunk-A4F7OIC5.js";
-import "./chunk-XPXHQI6N.js";
+import "./chunk-RFUL2ZIQ.js";
+import "./chunk-WVIWDMFB.js";
+import "./chunk-FVMEZ57K.js";
 import "./chunk-DOJBV6WR.js";
 import "./chunk-PFUXPTBT.js";
 import "./chunk-CYEPCZN5.js";
@@ -42,25 +42,20 @@ import "./chunk-3WU7XOFN.js";
 import "./chunk-P4GUQSK3.js";
 import "./chunk-4LZ7SVKM.js";
 import "./chunk-YHTG64XV.js";
-import "./chunk-SQ3GEIEL.js";
-import "./chunk-IAYUTGF2.js";
+import "./chunk-KUQLUYIR.js";
+import "./chunk-O3GZPLVY.js";
 import "./chunk-5WITETWU.js";
-import "./chunk-M5GVCJSJ.js";
-import "./chunk-RBOJCG4T.js";
 import "./chunk-6CIAGZ6X.js";
-import "./chunk-7CT3AI52.js";
 import "./chunk-G7D6GZ5J.js";
 import "./chunk-7VLBZKNB.js";
 import "./chunk-Y33KJ556.js";
-import "./chunk-R23JWJD3.js";
+import "./chunk-J426U7XK.js";
 import "./chunk-NWA6IXR3.js";
+import "./chunk-AF2XMJKD.js";
 import "./chunk-OR42ZI54.js";
 import "./chunk-IUM3VSHI.js";
 import "./chunk-EZ47HOJ6.js";
-import "./chunk-AF2XMJKD.js";
 import "./chunk-23G5P7TA.js";
-import "./chunk-C64XATK7.js";
-import "./chunk-42JKGUFJ.js";
 import "./chunk-MMRTPH3J.js";
 import "./chunk-I55KAVET.js";
 import "./chunk-L2EXJQJP.js";
@@ -104,6 +99,11 @@ import "./chunk-P7FMDTKL.js";
 import "./chunk-X4OZMANG.js";
 import "./chunk-ZEFVK7XC.js";
 import "./chunk-R2MBW2S4.js";
+import "./chunk-M5GVCJSJ.js";
+import "./chunk-RBOJCG4T.js";
+import "./chunk-7CT3AI52.js";
+import "./chunk-C64XATK7.js";
+import "./chunk-42JKGUFJ.js";
 import "./chunk-QUIRIG2P.js";
 import "./chunk-6KH5NLQS.js";
 import "./chunk-P2QRMMVQ.js";

package/dist/who-knows-cli.js

@@ -4,16 +4,16 @@ import {
   renderWhoKnows,
   renderWhoKnowsJson,
   renderWhoKnowsText
-} from "./chunk-J7BIFOYP.js";
-import "./chunk-IQ55QGY5.js";
-import "./chunk-FWRXW7CZ.js";
+} from "./chunk-U6TC6Z5B.js";
+import "./chunk-R4JYSBZE.js";
+import "./chunk-4CXK3GT3.js";
 import "./chunk-QGVCFVX6.js";
 import "./chunk-UHVXE24Y.js";
-import "./chunk-IGOW4TJE.js";
-import "./chunk-RFUL2ZIQ.js";
+import "./chunk-O3JG4PD3.js";
 import "./chunk-G6OFEGUR.js";
-import "./chunk-A4F7OIC5.js";
-import "./chunk-XPXHQI6N.js";
+import "./chunk-RFUL2ZIQ.js";
+import "./chunk-WVIWDMFB.js";
+import "./chunk-FVMEZ57K.js";
 import "./chunk-DOJBV6WR.js";
 import "./chunk-PFUXPTBT.js";
 import "./chunk-CYEPCZN5.js";
@@ -45,25 +45,20 @@ import "./chunk-3WU7XOFN.js";
 import "./chunk-P4GUQSK3.js";
 import "./chunk-4LZ7SVKM.js";
 import "./chunk-YHTG64XV.js";
-import "./chunk-SQ3GEIEL.js";
-import "./chunk-IAYUTGF2.js";
+import "./chunk-KUQLUYIR.js";
+import "./chunk-O3GZPLVY.js";
 import "./chunk-5WITETWU.js";
-import "./chunk-M5GVCJSJ.js";
-import "./chunk-RBOJCG4T.js";
 import "./chunk-6CIAGZ6X.js";
-import "./chunk-7CT3AI52.js";
 import "./chunk-G7D6GZ5J.js";
 import "./chunk-7VLBZKNB.js";
 import "./chunk-Y33KJ556.js";
-import "./chunk-R23JWJD3.js";
+import "./chunk-J426U7XK.js";
 import "./chunk-NWA6IXR3.js";
+import "./chunk-AF2XMJKD.js";
 import "./chunk-OR42ZI54.js";
 import "./chunk-IUM3VSHI.js";
 import "./chunk-EZ47HOJ6.js";
-import "./chunk-AF2XMJKD.js";
 import "./chunk-23G5P7TA.js";
-import "./chunk-C64XATK7.js";
-import "./chunk-42JKGUFJ.js";
 import "./chunk-MMRTPH3J.js";
 import "./chunk-I55KAVET.js";
 import "./chunk-L2EXJQJP.js";
@@ -107,6 +102,11 @@ import "./chunk-P7FMDTKL.js";
 import "./chunk-X4OZMANG.js";
 import "./chunk-ZEFVK7XC.js";
 import "./chunk-R2MBW2S4.js";
+import "./chunk-M5GVCJSJ.js";
+import "./chunk-RBOJCG4T.js";
+import "./chunk-7CT3AI52.js";
+import "./chunk-C64XATK7.js";
+import "./chunk-42JKGUFJ.js";
 import "./chunk-QUIRIG2P.js";
 import "./chunk-6KH5NLQS.js";
 import "./chunk-P2QRMMVQ.js";

package/dist/who-knows.js

@@ -9,15 +9,15 @@ import {
   loadWhoKnowsEntities,
   tokenizeTopic,
   validateWhoKnowsInput
-} from "./chunk-IQ55QGY5.js";
-import "./chunk-FWRXW7CZ.js";
+} from "./chunk-R4JYSBZE.js";
+import "./chunk-4CXK3GT3.js";
 import "./chunk-QGVCFVX6.js";
 import "./chunk-UHVXE24Y.js";
-import "./chunk-IGOW4TJE.js";
-import "./chunk-RFUL2ZIQ.js";
+import "./chunk-O3JG4PD3.js";
 import "./chunk-G6OFEGUR.js";
-import "./chunk-A4F7OIC5.js";
-import "./chunk-XPXHQI6N.js";
+import "./chunk-RFUL2ZIQ.js";
+import "./chunk-WVIWDMFB.js";
+import "./chunk-FVMEZ57K.js";
 import "./chunk-DOJBV6WR.js";
 import "./chunk-PFUXPTBT.js";
 import "./chunk-CYEPCZN5.js";
@@ -49,25 +49,20 @@ import "./chunk-3WU7XOFN.js";
 import "./chunk-P4GUQSK3.js";
 import "./chunk-4LZ7SVKM.js";
 import "./chunk-YHTG64XV.js";
-import "./chunk-SQ3GEIEL.js";
-import "./chunk-IAYUTGF2.js";
+import "./chunk-KUQLUYIR.js";
+import "./chunk-O3GZPLVY.js";
 import "./chunk-5WITETWU.js";
-import "./chunk-M5GVCJSJ.js";
-import "./chunk-RBOJCG4T.js";
 import "./chunk-6CIAGZ6X.js";
-import "./chunk-7CT3AI52.js";
 import "./chunk-G7D6GZ5J.js";
 import "./chunk-7VLBZKNB.js";
 import "./chunk-Y33KJ556.js";
-import "./chunk-R23JWJD3.js";
+import "./chunk-J426U7XK.js";
 import "./chunk-NWA6IXR3.js";
+import "./chunk-AF2XMJKD.js";
 import "./chunk-OR42ZI54.js";
 import "./chunk-IUM3VSHI.js";
 import "./chunk-EZ47HOJ6.js";
-import "./chunk-AF2XMJKD.js";
 import "./chunk-23G5P7TA.js";
-import "./chunk-C64XATK7.js";
-import "./chunk-42JKGUFJ.js";
 import "./chunk-MMRTPH3J.js";
 import "./chunk-I55KAVET.js";
 import "./chunk-L2EXJQJP.js";
@@ -111,6 +106,11 @@ import "./chunk-P7FMDTKL.js";
 import "./chunk-X4OZMANG.js";
 import "./chunk-ZEFVK7XC.js";
 import "./chunk-R2MBW2S4.js";
+import "./chunk-M5GVCJSJ.js";
+import "./chunk-RBOJCG4T.js";
+import "./chunk-7CT3AI52.js";
+import "./chunk-C64XATK7.js";
+import "./chunk-42JKGUFJ.js";
 import "./chunk-QUIRIG2P.js";
 import "./chunk-6KH5NLQS.js";
 import "./chunk-P2QRMMVQ.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/core",
-  "version": "10.0.94",
+  "version": "10.0.96",
   "description": "Framework-agnostic Remnic memory engine — orchestrator, storage, extraction, search, trust zones",
   "type": "module",
   "main": "dist/index.js",
@@ -3386,7 +3386,7 @@
     "core"
   ],
   "peerDependencies": {
-    "@remnic/coding-graph": "^10.0.94"
+    "@remnic/coding-graph": "^10.0.96"
   },
   "peerDependenciesMeta": {
     "@remnic/coding-graph": {

package/src/abstraction-nodes.ts

@@ -1,6 +1,7 @@
 import { mkdir, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { listJsonFilesStrict, readJsonFile, withJsonStoreMutationLock, writeJsonFileAtomic } from "./json-store.js";
+import { bumpHarmonicGraphVersion } from "./harmonic-graph-version.js";
 import { compareDeterministicStrings, mergeSortedUniqueStrings } from "./deterministic-order.js";
 import { isNotFoundError } from "./utils/errno.js";
 import {
@@ -107,7 +108,11 @@ export async function recordAbstractionNode(options: {
   const nodesDir = path.join(rootDir, "nodes", day);
   const filePath = path.join(nodesDir, `${validated.nodeId}.json`);
   await mkdir(nodesDir, { recursive: true });
-  await writeFile(filePath, JSON.stringify(validated, null, 2), "utf8");
+  try {
+    await writeFile(filePath, JSON.stringify(validated, null, 2), "utf8");
+  } finally {
+    bumpHarmonicGraphVersion(rootDir);
+  }
   return filePath;
 }
 
@@ -269,7 +274,7 @@ export async function upsertAbstractionNodes(options: {
       filePaths.push(filePath);
     }
     return filePaths;
-  });
+  }).finally(() => bumpHarmonicGraphVersion(rootDir));
 }
 
 export async function upsertAbstractionNode(options: {

package/src/cue-anchors.ts

@@ -1,6 +1,7 @@
 import { mkdir, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { resolveAbstractionNodeStoreDir, validateAbstractionNode, type AbstractionNode } from "./abstraction-nodes.js";
+import { bumpHarmonicGraphVersion } from "./harmonic-graph-version.js";
 import { listJsonFilesStrict, readJsonFile, withJsonStoreMutationLock, writeJsonFileAtomic } from "./json-store.js";
 import { compareDeterministicStrings, mergeSortedUniqueStrings } from "./deterministic-order.js";
 import { isNotFoundError } from "./utils/errno.js";
@@ -163,7 +164,11 @@ export async function recordCueAnchor(options: {
   const anchorDir = path.join(rootDir, bounded.anchorType);
   const filePath = path.join(anchorDir, `${bounded.anchorId}.json`);
   await mkdir(anchorDir, { recursive: true });
-  await writeFile(filePath, JSON.stringify(bounded, null, 2), "utf8");
+  try {
+    await writeFile(filePath, JSON.stringify(bounded, null, 2), "utf8");
+  } finally {
+    bumpHarmonicGraphVersion(abstractionNodeStoreDir);
+  }
   return filePath;
 }
 
@@ -247,7 +252,7 @@ export async function upsertCueAnchors(options: {
       filePaths.push(filePath);
     }
     return filePaths;
-  });
+  }).finally(() => bumpHarmonicGraphVersion(abstractionNodeStoreDir));
 }
 
 function compareIncomingCueAnchors(left: CueAnchor, right: CueAnchor): number {
@@ -351,7 +356,7 @@ export async function pruneOrphanCueAnchors(options: {
       }
     }
     return removed;
-  });
+  }).finally(() => bumpHarmonicGraphVersion(abstractionNodeStoreDir));
 }
 
 export async function getCueAnchorStoreStatus(options: {

package/src/harmonic-graph-cache.test.ts

@@ -0,0 +1,244 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { recordAbstractionNode, upsertAbstractionNodes, type AbstractionNode } from "./abstraction-nodes.js";
+import { pruneOrphanCueAnchors, recordCueAnchor, upsertCueAnchors, type CueAnchor } from "./cue-anchors.js";
+import {
+  clearHarmonicGraphCache,
+  harmonicGraphCacheStats,
+  readProjectedHarmonicGraph,
+  searchHarmonicRetrieval,
+} from "./harmonic-retrieval.js";
+import { bumpMemoryCorpusVersionForDir } from "./memory-corpus-version.js";
+import { StorageManager } from "./storage.js";
+
+function node(nodeId: string, title: string, sourceMemoryIds: string[]): AbstractionNode {
+  return {
+    schemaVersion: 1,
+    nodeId,
+    recordedAt: new Date().toISOString(),
+    sessionKey: "agent:test",
+    kind: "topic",
+    abstractionLevel: "meso",
+    title,
+    summary: title,
+    sourceMemoryIds,
+  };
+}
+
+async function withDir(run: (memoryDir: string, storage: StorageManager) => Promise<void>) {
+  const memoryDir = await mkdtemp(path.join(tmpdir(), "remnic-harmonic-cache-"));
+  clearHarmonicGraphCache();
+  try {
+    const storage = new StorageManager(memoryDir);
+    await storage.ensureDirectories();
+    await run(memoryDir, storage);
+  } finally {
+    clearHarmonicGraphCache();
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+}
+
+const read = (memoryDir: string, extra: { nowMs?: number } = {}) =>
+  readProjectedHarmonicGraph({ memoryDir, anchorsEnabled: true, useCache: true, ...extra });
+
+test("a second cached read does no file reads", async () => {
+  await withDir(async (memoryDir, storage) => {
+    const first = await storage.writeMemory("fact", "cache source one", { source: "test" });
+    const nodeFile = await recordAbstractionNode({ memoryDir, node: node("n1", "cache source one", [first.id]) });
+    const before = { ...harmonicGraphCacheStats };
+    const a = await read(memoryDir);
+    assert.equal(a.nodes.length, 1);
+    assert.equal(harmonicGraphCacheStats.misses, before.misses + 1);
+    // Remove every file the projection reads. A real read would now return nothing.
+    await rm(nodeFile, { force: true });
+    await rm((await storage.getMemoryById(first.id))!.path, { force: true });
+    const b = await read(memoryDir);
+    assert.equal(harmonicGraphCacheStats.hits, before.hits + 1);
+    assert.equal(b, a);
+    assert.equal(b.nodes.length, 1);
+  });
+});
+
+test("a recall after a new memory is saved sees it", async () => {
+  await withDir(async (memoryDir, storage) => {
+    const first = await storage.writeMemory("fact", "alpha harmonic", { source: "test" });
+    await recordAbstractionNode({ memoryDir, node: node("n1", "alpha harmonic", [first.id]) });
+    const hits = () => harmonicGraphCacheStats.hits;
+    const query = { memoryDir, query: "bravo cache", maxResults: 3, anchorsEnabled: true, useGraphCache: true };
+    assert.equal((await searchHarmonicRetrieval(query)).length, 0);
+    const h = hits();
+    assert.equal((await searchHarmonicRetrieval(query)).length, 0);
+    assert.equal(hits(), h + 1);
+
+    const second = await storage.writeMemory("fact", "bravo cache", { source: "test" });
+    await recordAbstractionNode({ memoryDir, node: node("n2", "bravo cache", [second.id]) });
+    const results = await searchHarmonicRetrieval(query);
+    assert.deepEqual(results.map((result) => result.node.nodeId), ["n2"]);
+  });
+});
+
+test("an out-of-band corpus bump invalidates, so a source that leaves the active set drops out", async () => {
+  await withDir(async (memoryDir, storage) => {
+    const memory = await storage.writeMemory("fact", "gamma status fact", { source: "test" });
+    await recordAbstractionNode({ memoryDir, node: node("n1", "gamma status fact", [memory.id]) });
+    assert.equal((await read(memoryDir)).nodes.length, 1);
+    const memoryPath = (await storage.getMemoryById(memory.id))!.path;
+    await writeFile(
+      memoryPath,
+      (await readFile(memoryPath, "utf8")).replace("category: fact", "category: fact\nstatus: quarantined"),
+    );
+    // The documented out-of-band bump: the same call review and governance writers make.
+    bumpMemoryCorpusVersionForDir(memoryDir);
+    assert.equal((await read(memoryDir)).nodes.length, 0);
+  });
+});
+
+test("an explicit nowMs bypasses the cache", async () => {
+  await withDir(async (memoryDir, storage) => {
+    const memory = await storage.writeMemory("fact", "delta bypass fact", { source: "test" });
+    const nodeFile = await recordAbstractionNode({ memoryDir, node: node("n1", "delta bypass fact", [memory.id]) });
+    assert.equal((await read(memoryDir)).nodes.length, 1);
+    await rm(nodeFile, { force: true });
+    assert.equal((await read(memoryDir, { nowMs: Date.now() })).nodes.length, 0);
+  });
+});
+
+test("cached arrays are frozen", async () => {
+  await withDir(async (memoryDir, storage) => {
+    const memory = await storage.writeMemory("fact", "epsilon frozen fact", { source: "test" });
+    await recordAbstractionNode({ memoryDir, node: node("n1", "epsilon frozen fact", [memory.id]) });
+    const graph = await read(memoryDir);
+    assert.throws(() => graph.nodes.push(node("x", "x", [])), TypeError);
+  });
+});
+
+test("cached node records are deep frozen, so a caller cannot change later reads", async () => {
+  await withDir(async (memoryDir, storage) => {
+    const memory = await storage.writeMemory("fact", "zeta deep frozen fact", { source: "test" });
+    await recordAbstractionNode({ memoryDir, node: node("n1", "zeta deep frozen fact", [memory.id]) });
+    const graph = await read(memoryDir);
+    const cached = graph.nodes[0]!;
+    assert.throws(() => { cached.title = "changed"; }, TypeError);
+    assert.throws(() => cached.sourceMemoryIds?.push("x"), TypeError);
+    assert.equal((await read(memoryDir)).nodes[0]!.title, "zeta deep frozen fact");
+  });
+});
+
+test("an aborted signal rejects even when the graph is cached", async () => {
+  await withDir(async (memoryDir, storage) => {
+    const memory = await storage.writeMemory("fact", "eta abort fact", { source: "test" });
+    await recordAbstractionNode({ memoryDir, node: node("n1", "eta abort fact", [memory.id]) });
+    await read(memoryDir);
+    const controller = new AbortController();
+    controller.abort();
+    await assert.rejects(
+      readProjectedHarmonicGraph({ memoryDir, anchorsEnabled: true, useCache: true, abortSignal: controller.signal }),
+    );
+  });
+});
+
+function anchor(anchorId: string, nodeRef: string, memoryId: string): CueAnchor {
+  return {
+    schemaVersion: 1,
+    anchorId,
+    anchorType: "entity",
+    anchorValue: anchorId,
+    normalizedCue: anchorId,
+    recordedAt: new Date().toISOString(),
+    sessionKey: "agent:test",
+    nodeRefs: [nodeRef],
+    sourceMemoryIdsByNodeRef: { [nodeRef]: [memoryId] },
+  };
+}
+
+// Each case seeds node n1 (source m1) and, for the anchor cases, anchor a1, fills the cache, then runs ONE
+// store write with no memory write after it. The next read must miss and show the new count; with the
+// graph version bump removed these fail because the corpus sentinels never move.
+async function seedForWrite(memoryDir: string, storage: StorageManager) {
+  const m1 = await storage.writeMemory("fact", "seed one", { source: "test" });
+  const m2 = await storage.writeMemory("fact", "seed two", { source: "test" });
+  await recordAbstractionNode({ memoryDir, node: node("n1", "seed one", [m1.id]) });
+  await recordAbstractionNode({ memoryDir, node: node("n2", "seed two", [m2.id]) });
+  await recordCueAnchor({ memoryDir, anchor: anchor("a1", "n1", m1.id) });
+  return { m1, m2 };
+}
+
+async function counts(memoryDir: string) {
+  const graph = await read(memoryDir);
+  return { nodes: graph.nodes.length, anchors: graph.anchors.length };
+}
+
+const storeWrites: Array<{
+  name: string;
+  write: (memoryDir: string, ids: { m1: string; m2: string }) => Promise<void>;
+  expected: { nodes: number; anchors: number };
+}> = [
+  {
+    name: "recordAbstractionNode",
+    write: async (memoryDir, ids) => { await recordAbstractionNode({ memoryDir, node: node("n3", "seed three", [ids.m1]) }); },
+    expected: { nodes: 3, anchors: 1 },
+  },
+  {
+    name: "upsertAbstractionNodes",
+    write: async (memoryDir, ids) => { await upsertAbstractionNodes({ memoryDir, nodes: [node("n3", "seed three", [ids.m1])] }); },
+    expected: { nodes: 3, anchors: 1 },
+  },
+  {
+    name: "recordCueAnchor",
+    write: async (memoryDir, ids) => { await recordCueAnchor({ memoryDir, anchor: anchor("a2", "n2", ids.m2) }); },
+    expected: { nodes: 2, anchors: 2 },
+  },
+  {
+    name: "upsertCueAnchors",
+    write: async (memoryDir, ids) => { await upsertCueAnchors({ memoryDir, anchors: [anchor("a2", "n2", ids.m2)] }); },
+    expected: { nodes: 2, anchors: 2 },
+  },
+];
+
+for (const { name, write, expected } of storeWrites) {
+  test(`${name} alone invalidates the cached graph`, async () => {
+    await withDir(async (memoryDir, storage) => {
+      const { m1, m2 } = await seedForWrite(memoryDir, storage);
+      assert.deepEqual(await counts(memoryDir), { nodes: 2, anchors: 1 });
+      const hitsBefore = harmonicGraphCacheStats.hits;
+      assert.deepEqual(await counts(memoryDir), { nodes: 2, anchors: 1 });
+      assert.equal(harmonicGraphCacheStats.hits, hitsBefore + 1);
+
+      await write(memoryDir, { m1: m1.id, m2: m2.id });
+      const missesBefore = harmonicGraphCacheStats.misses;
+      assert.deepEqual(await counts(memoryDir), expected);
+      assert.equal(harmonicGraphCacheStats.misses, missesBefore + 1);
+    });
+  });
+}
+
+test("pruneOrphanCueAnchors alone invalidates the cached graph", async () => {
+  await withDir(async (memoryDir, storage) => {
+    const { m2 } = await seedForWrite(memoryDir, storage);
+    await recordCueAnchor({ memoryDir, anchor: anchor("a2", "n2", m2.id) });
+    assert.deepEqual(await counts(memoryDir), { nodes: 2, anchors: 2 });
+    // n2's file goes away behind the cache's back, which makes a2 an orphan. Only the prune below bumps.
+    await rm(path.join(memoryDir, "state", "abstraction-nodes", "nodes", new Date().toISOString().slice(0, 10), "n2.json"), { force: true });
+    assert.deepEqual(await counts(memoryDir), { nodes: 2, anchors: 2 });
+    assert.equal(await pruneOrphanCueAnchors({ memoryDir }), 1);
+    assert.deepEqual(await counts(memoryDir), { nodes: 1, anchors: 1 });
+  });
+});
+
+test("an entry older than the TTL is rebuilt", async (t) => {
+  await withDir(async (memoryDir, storage) => {
+    const memory = await storage.writeMemory("fact", "zeta ttl fact", { source: "test" });
+    const nodeFile = await recordAbstractionNode({ memoryDir, node: node("n1", "zeta ttl fact", [memory.id]) });
+    const start = Date.now();
+    const clock = t.mock.method(Date, "now", () => start);
+    assert.equal((await read(memoryDir)).nodes.length, 1);
+    await rm(nodeFile, { force: true });
+    clock.mock.mockImplementation(() => start + 29_000);
+    assert.equal((await read(memoryDir)).nodes.length, 1, "still cached inside the TTL");
+    clock.mock.mockImplementation(() => start + 31_000);
+    assert.equal((await read(memoryDir)).nodes.length, 0, "rebuilt past the TTL");
+  });
+});

package/src/harmonic-graph-version.ts

@@ -0,0 +1,46 @@
+import { appendFileSync, mkdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { MEMORY_CORPUS_VERSION_SENTINEL } from "./memory-corpus-version.js";
+
+/**
+ * Append-only sentinel in the abstraction node store root. The byte size is the
+ * version of the node and cue anchor stores, the same scheme the memory corpus
+ * sentinel uses, so a bump in one process is seen by every other process.
+ */
+export const HARMONIC_GRAPH_VERSION_SENTINEL = ".harmonic-graph-version.log";
+
+// Names must match StorageManager.versionFilePath("memory-status" | "cold-write").
+const MEMORY_STATUS_VERSION_SENTINEL = ".memory-status-version.log";
+const COLD_WRITE_VERSION_SENTINEL = ".cold-write-version.log";
+
+/**
+ * Record that a node or cue anchor was written. Fail-open: a failed bump must not
+ * fail the write; the harmonic graph cache TTL bounds the stale window.
+ */
+export function bumpHarmonicGraphVersion(abstractionNodeStoreDir: string): void {
+  try {
+    mkdirSync(abstractionNodeStoreDir, { recursive: true });
+    appendFileSync(path.join(abstractionNodeStoreDir, HARMONIC_GRAPH_VERSION_SENTINEL), "x");
+  } catch {
+    /* fail-open */
+  }
+}
+
+function sentinelSize(filePath: string): number {
+  try {
+    return statSync(filePath).size;
+  } catch {
+    return 0;
+  }
+}
+
+/** Four stats; changes whenever a memory, a node or a cue anchor is written. */
+export function readHarmonicGraphStamp(memoryDir: string, abstractionNodeStoreDir: string): string {
+  const stateDir = path.join(memoryDir, "state");
+  return [
+    sentinelSize(path.join(stateDir, MEMORY_CORPUS_VERSION_SENTINEL)),
+    sentinelSize(path.join(stateDir, MEMORY_STATUS_VERSION_SENTINEL)),
+    sentinelSize(path.join(stateDir, COLD_WRITE_VERSION_SENTINEL)),
+    sentinelSize(path.join(abstractionNodeStoreDir, HARMONIC_GRAPH_VERSION_SENTINEL)),
+  ].join(":");
+}