@remnic/core 10.0.101 → 10.0.102

package/dist/harmonic-retrieval.d.ts

@@ -25,13 +25,20 @@ export interface ProjectedHarmonicGraph {
     nodes: AbstractionNode[];
     anchors: CueAnchor[];
 }
-/** Counters for tests and diagnostics. `shared` counts reads that joined a build already running. */
+/** Counters for tests and diagnostics. `stale` hits also count as `hits`. */
 export declare const harmonicGraphCacheStats: {
     hits: number;
     misses: number;
+    stale: number;
     shared: number;
 };
 export declare function clearHarmonicGraphCache(): void;
+/**
+ * Resolves once every build running now has settled, and after the failure bookkeeping of a background
+ * refresh (that handler was attached when the refresh started, so it runs first). For tests: a time-based
+ * wait races a slow build.
+ */
+export declare function settleHarmonicGraphBuilds(): Promise<void>;
 /**
  * `readProjectedHarmonicGraph` with an opt-in in-memory cache. Every recall used
  * to re-read all nodes, anchors and source memories from disk (about 4.7 s on a
@@ -40,9 +47,12 @@ export declare function clearHarmonicGraphCache(): void;
  * cold-write version sentinels (bumped by every memory write, in any process) and
  * the graph version sentinel (bumped by node and anchor writes). A stamp read is
  * four stats, not a scan of the memories. The TTL bounds the one input a sentinel
- * cannot see, which is wall-clock validity expiry. Concurrent misses share one
- * build. An explicit `nowMs` bypasses the cache so tests stay deterministic. The
- * cached arrays are frozen: callers must not mutate them.
+ * cannot see, which is wall-clock validity expiry; past it the stale graph is served
+ * while one refresh runs (up to GRAPH_CACHE_MAX_STALE_MS). A changed stamp always
+ * waits for a fresh build, because a stale graph could carry governed metadata of a
+ * memory that left the active set. Concurrent misses share one build. An explicit
+ * `nowMs` bypasses the cache so tests stay deterministic. The cached arrays are
+ * frozen: callers must not mutate them.
  */
 export declare function readProjectedHarmonicGraph(options: {
     memoryDir: string;

package/dist/harmonic-retrieval.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"harmonic-retrieval.d.ts","sourceRoot":"","sources":["../src/harmonic-retrieval.ts"],"names":[],"mappings":"AAMC,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,wBAAwB,CAAC;AACjC,OAAO,EAA+C,KAAK,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAsPnH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,aAAa,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,eAAe,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,EAAE,qBAAqB,EAAE,CAAC;CACzC;AA+ED,wBAAsB,oBAAoB,CAAC,OAAO,EAAE;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAY7B;AAED,wBAAsB,cAAc,CAAC,OAAO,EAAE;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAavB;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,OAAO,EAAE,SAAS,EAAE,CAAC;CACtB;AAiGD,qGAAqG;AACrG,eAAO,MAAM,uBAAuB;;;;CAAoC,CAAC;AAWzE,wBAAgB,uBAAuB,IAAI,IAAI,CAG9C;AAuDD;;;;;;;;;;;GAWG;AACH,wBAAsB,0BAA0B,CAAC,OAAO,EAAE;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,cAAc,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CA4BlC;AAED,wBAAsB,uBAAuB,CAAC,OAAO,EAAE;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,yHAAyH;IACzH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,GAAG,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAoFrC"}
+{"version":3,"file":"harmonic-retrieval.d.ts","sourceRoot":"","sources":["../src/harmonic-retrieval.ts"],"names":[],"mappings":"AAOC,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,wBAAwB,CAAC;AACjC,OAAO,EAA+C,KAAK,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AA+PnH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,aAAa,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,eAAe,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,EAAE,qBAAqB,EAAE,CAAC;CACzC;AA+ED,wBAAsB,oBAAoB,CAAC,OAAO,EAAE;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAY7B;AAED,wBAAsB,cAAc,CAAC,OAAO,EAAE;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAavB;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,OAAO,EAAE,SAAS,EAAE,CAAC;CACtB;AAqKD,6EAA6E;AAC7E,eAAO,MAAM,uBAAuB;;;;;CAA8C,CAAC;AAWnF,wBAAgB,uBAAuB,IAAI,IAAI,CAI9C;AAED;;;;GAIG;AACH,wBAAsB,yBAAyB,IAAI,OAAO,CAAC,IAAI,CAAC,CAE/D;AAiDD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,0BAA0B,CAAC,OAAO,EAAE;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,cAAc,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAyClC;AAED,wBAAsB,uBAAuB,CAAC,OAAO,EAAE;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,yHAAyH;IACzH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,GAAG,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAoFrC"}

package/dist/harmonic-retrieval.js

@@ -4,8 +4,9 @@ import {
   readAbstractionNodes,
   readCueAnchors,
   readProjectedHarmonicGraph,
-  searchHarmonicRetrieval
-} from "./chunk-PL36IQPL.js";
+  searchHarmonicRetrieval,
+  settleHarmonicGraphBuilds
+} from "./chunk-KCRHFW3N.js";
 import "./chunk-HUDPXTXW.js";
 import "./chunk-AZEZSQ5R.js";
 import "./chunk-FL3O34XF.js";
@@ -132,6 +133,7 @@ export {
   readAbstractionNodes,
   readCueAnchors,
   readProjectedHarmonicGraph,
-  searchHarmonicRetrieval
+  searchHarmonicRetrieval,
+  settleHarmonicGraphBuilds
 };
 //# sourceMappingURL=harmonic-retrieval.js.map

package/dist/index.js

@@ -259,7 +259,7 @@ import {
   writeManifest,
   writeMeetingEpisodeMemory,
   writeTimelineState
-} from "./chunk-MMOXCCHF.js";
+} from "./chunk-T3X4CCHC.js";
 import "./chunk-6P7U3HWG.js";
 import "./chunk-PQM3B54K.js";
 import {
@@ -717,7 +717,7 @@ import {
 import "./chunk-UOBPK2OS.js";
 import "./chunk-2YA5N2BY.js";
 import "./chunk-3HSRWJTC.js";
-import "./chunk-PL36IQPL.js";
+import "./chunk-KCRHFW3N.js";
 import "./chunk-HUDPXTXW.js";
 import "./chunk-AZEZSQ5R.js";
 import "./chunk-YAZNBMNF.js";

package/dist/orchestration/backlog-scheduler.js

@@ -1,7 +1,7 @@
 import {
   BufferDrainRunner
-} from "../chunk-QIPDTAWZ.js";
-import "../chunk-MMOXCCHF.js";
+} from "../chunk-D77I4MD4.js";
+import "../chunk-T3X4CCHC.js";
 import "../chunk-6P7U3HWG.js";
 import "../chunk-PQM3B54K.js";
 import "../chunk-B3DR2JBZ.js";
@@ -174,7 +174,7 @@ import "../chunk-MDPT6QFK.js";
 import "../chunk-UOBPK2OS.js";
 import "../chunk-2YA5N2BY.js";
 import "../chunk-3HSRWJTC.js";
-import "../chunk-PL36IQPL.js";
+import "../chunk-KCRHFW3N.js";
 import "../chunk-HUDPXTXW.js";
 import "../chunk-AZEZSQ5R.js";
 import "../chunk-YAZNBMNF.js";

package/dist/orchestration/buffer-drain-runner.js

@@ -1,8 +1,8 @@
 import {
   BufferDrainRunner,
   ClaimBufferStorage
-} from "../chunk-QIPDTAWZ.js";
-import "../chunk-MMOXCCHF.js";
+} from "../chunk-D77I4MD4.js";
+import "../chunk-T3X4CCHC.js";
 import "../chunk-6P7U3HWG.js";
 import "../chunk-PQM3B54K.js";
 import "../chunk-B3DR2JBZ.js";
@@ -175,7 +175,7 @@ import "../chunk-MDPT6QFK.js";
 import "../chunk-UOBPK2OS.js";
 import "../chunk-2YA5N2BY.js";
 import "../chunk-3HSRWJTC.js";
-import "../chunk-PL36IQPL.js";
+import "../chunk-KCRHFW3N.js";
 import "../chunk-HUDPXTXW.js";
 import "../chunk-AZEZSQ5R.js";
 import "../chunk-YAZNBMNF.js";

package/dist/orchestrator.js

@@ -6,7 +6,7 @@ import {
   mergeGraphExpandedResults,
   qmdStartupCollectionChecksWithTimeout,
   resolveEffectiveIdentityInjectionMode
-} from "./chunk-MMOXCCHF.js";
+} from "./chunk-T3X4CCHC.js";
 import "./chunk-6P7U3HWG.js";
 import "./chunk-PQM3B54K.js";
 import "./chunk-B3DR2JBZ.js";
@@ -183,7 +183,7 @@ import "./chunk-MDPT6QFK.js";
 import "./chunk-UOBPK2OS.js";
 import "./chunk-2YA5N2BY.js";
 import "./chunk-3HSRWJTC.js";
-import "./chunk-PL36IQPL.js";
+import "./chunk-KCRHFW3N.js";
 import "./chunk-HUDPXTXW.js";
 import "./chunk-AZEZSQ5R.js";
 import "./chunk-YAZNBMNF.js";

package/dist/recall-navigation.js

@@ -1,6 +1,6 @@
 import {
   runRecallNavigation
-} from "./chunk-MMOXCCHF.js";
+} from "./chunk-T3X4CCHC.js";
 import "./chunk-6P7U3HWG.js";
 import "./chunk-PQM3B54K.js";
 import "./chunk-B3DR2JBZ.js";
@@ -173,7 +173,7 @@ import "./chunk-MDPT6QFK.js";
 import "./chunk-UOBPK2OS.js";
 import "./chunk-2YA5N2BY.js";
 import "./chunk-3HSRWJTC.js";
-import "./chunk-PL36IQPL.js";
+import "./chunk-KCRHFW3N.js";
 import "./chunk-HUDPXTXW.js";
 import "./chunk-AZEZSQ5R.js";
 import "./chunk-YAZNBMNF.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/core",
-  "version": "10.0.101",
+  "version": "10.0.102",
   "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.101"
+    "@remnic/coding-graph": "^10.0.102"
   },
   "peerDependenciesMeta": {
     "@remnic/coding-graph": {

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

@@ -11,6 +11,7 @@ import {
   type ProjectedHarmonicGraph,
   readProjectedHarmonicGraph,
   searchHarmonicRetrieval,
+  settleHarmonicGraphBuilds,
 } from "./harmonic-retrieval.js";
 import { bumpMemoryCorpusVersionForDir } from "./memory-corpus-version.js";
 import { StorageManager } from "./storage.js";
@@ -232,6 +233,14 @@ test("pruneOrphanCueAnchors alone invalidates the cached graph", async () => {
 // Recall waits for the graph build, so a cache miss costs every recall that lands on it. Production: a
 // 2106 node, 9174 anchor graph rebuilt in 5 s standalone, 7 s inside the daemon, and 17 to 32 s when two
 // recalls overlapped and each ran its own build.
+async function until(condition: () => Promise<boolean>) {
+  for (let i = 0; i < 400; i += 1) {
+    if (await condition()) return;
+    await new Promise((resolve) => setTimeout(resolve, 5));
+  }
+  assert.fail("condition not reached in 2 s");
+}
+
 test("concurrent reads on a cold cache share one build", async () => {
   await withDir(async (memoryDir, storage) => {
     const memory = await storage.writeMemory("fact", "theta shared fact", { source: "test" });
@@ -257,6 +266,73 @@ test("a caller that aborts leaves the shared build for the others", async () =>
   });
 });
 
+test("a read past the TTL answers from the stale graph and refreshes behind it", 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");
+    const missesBefore = harmonicGraphCacheStats.misses;
+    clock.mock.mockImplementation(() => start + 31_000);
+    assert.equal((await read(memoryDir)).nodes.length, 1, "past the TTL the caller does not wait for a rebuild");
+    assert.equal(harmonicGraphCacheStats.misses, missesBefore + 1, "a refresh was started");
+    await until(async () => (await read(memoryDir)).nodes.length === 0);
+  });
+});
+
+test("a graph past the stale limit is rebuilt before it is served", async (t) => {
+  await withDir(async (memoryDir, storage) => {
+    const memory = await storage.writeMemory("fact", "kappa limit fact", { source: "test" });
+    const nodeFile = await recordAbstractionNode({ memoryDir, node: node("n1", "kappa limit 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 + 330_000);
+    assert.equal((await read(memoryDir)).nodes.length, 0, "the stale window ends 300 s after the TTL, at 330 s");
+  });
+});
+
+test("a graph is still served stale one millisecond before the stale window ends", async (t) => {
+  await withDir(async (memoryDir, storage) => {
+    const memory = await storage.writeMemory("fact", "kappa edge fact", { source: "test" });
+    const nodeFile = await recordAbstractionNode({ memoryDir, node: node("n1", "kappa edge 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 + 329_999);
+    assert.equal((await read(memoryDir)).nodes.length, 1, "up to 300 s past the TTL the stale graph is served");
+    await settleHarmonicGraphBuilds();
+  });
+});
+
+test("an ineligible source's invalid_at does not end the cache entry", async (t) => {
+  await withDir(async (memoryDir, storage) => {
+    const start = Date.now();
+    const clock = t.mock.method(Date, "now", () => start);
+    const live = await storage.writeMemory("fact", "pi eligible fact", { source: "test" });
+    const gone = await storage.writeMemory("fact", "pi quarantined fact", {
+      source: "test",
+      invalidAt: new Date(start + 10_000).toISOString(),
+    });
+    const gonePath = (await storage.getMemoryById(gone.id))!.path;
+    await writeFile(gonePath, (await readFile(gonePath, "utf8")).replace("category: fact", "category: fact\nstatus: quarantined"));
+    bumpMemoryCorpusVersionForDir(memoryDir); // the out-of-band status edit needs the documented bump, as in the status test above
+    await recordAbstractionNode({ memoryDir, node: node("n1", "pi mixed fact", [live.id, gone.id]) });
+    assert.equal((await read(memoryDir)).nodes.length, 1);
+    const before = { ...harmonicGraphCacheStats };
+    clock.mock.mockImplementation(() => start + 20_000);
+    assert.equal((await read(memoryDir)).nodes.length, 1);
+    assert.equal(harmonicGraphCacheStats.misses, before.misses, "the quarantined source's invalid_at passing starts no rebuild");
+    assert.equal(harmonicGraphCacheStats.hits, before.hits + 1);
+  });
+});
+
 // Unreadable node store: a file where the nodes directory belongs is not ENOENT, so the strict listing throws
 // (a corrupt node file would not: readAbstractionNodes skips those on purpose).
 async function breakNodeStore(memoryDir: string) {
@@ -270,6 +346,24 @@ async function breakNodeStore(memoryDir: string) {
   };
 }
 
+test("a source whose invalid_at passes inside the stale window is never served", async (t) => {
+  await withDir(async (memoryDir, storage) => {
+    const start = Date.now();
+    const clock = t.mock.method(Date, "now", () => start);
+    const memory = await storage.writeMemory("fact", "lambda expiry fact", {
+      source: "test",
+      invalidAt: new Date(start + 60_000).toISOString(),
+    });
+    await recordAbstractionNode({ memoryDir, node: node("n1", "lambda expiry fact", [memory.id]) });
+    assert.equal((await read(memoryDir)).nodes.length, 1);
+    clock.mock.mockImplementation(() => start + 31_000);
+    assert.equal((await read(memoryDir)).nodes.length, 1, "past the TTL but before the invalid_at: stale is fine");
+    await until(async () => harmonicGraphCacheStats.stale >= 1);
+    clock.mock.mockImplementation(() => start + 61_000);
+    assert.equal((await read(memoryDir)).nodes.length, 0, "after the invalid_at the graph is rebuilt before it is served");
+  });
+});
+
 test("callers that joined a failing build all reject, and the next read retries and succeeds", async () => {
   await withDir(async (memoryDir, storage) => {
     const memory = await storage.writeMemory("fact", "mu retry fact", { source: "test" });
@@ -284,18 +378,69 @@ test("callers that joined a failing build all reject, and the next read retries
   });
 });
 
-test("an entry older than the TTL is rebuilt", async (t) => {
+test("a failing refresh is retried at most once per TTL, not on every stale read", 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 memory = await storage.writeMemory("fact", "nu backoff fact", { source: "test" });
+    await recordAbstractionNode({ memoryDir, node: node("n1", "nu backoff 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");
+    const restore = await breakNodeStore(memoryDir);
     clock.mock.mockImplementation(() => start + 31_000);
-    assert.equal((await read(memoryDir)).nodes.length, 0, "rebuilt past the TTL");
+    const missesBefore = harmonicGraphCacheStats.misses;
+    assert.equal((await read(memoryDir)).nodes.length, 1, "the stale graph is still served");
+    // The failing build bumps `misses` before it reads the broken store: wait for it to settle, not for a time.
+    await settleHarmonicGraphBuilds();
+    assert.equal(harmonicGraphCacheStats.misses, missesBefore + 1, "one refresh was started");
+    clock.mock.mockImplementation(() => start + 40_000);
+    for (let i = 0; i < 5; i += 1) await read(memoryDir);
+    await settleHarmonicGraphBuilds();
+    assert.equal(harmonicGraphCacheStats.misses, missesBefore + 1, "no new build inside the backoff");
+    await restore();
+    clock.mock.mockImplementation(() => start + 62_000);
+    await read(memoryDir);
+    await until(async () => harmonicGraphCacheStats.misses === missesBefore + 2);
+  });
+});
+
+// The build's own clock reading is taken before it reads the anchors, so an invalid_at can pass while a
+// build is still running. Every caller that joined that build must still get an unexpired graph.
+test("a source that expires while the build is running is not served from that build", async () => {
+  await withDir(async (memoryDir, storage) => {
+    const sources: Array<{ id: string; path: string }> = [];
+    for (let i = 0; i < 120; i += 1) {
+      const memory = await storage.writeMemory("fact", `xi race fact ${i}`, { source: "test" });
+      await recordAbstractionNode({ memoryDir, node: node(`n${i}`, `xi race fact ${i}`, [memory.id]) });
+      sources.push({ id: memory.id, path: (await storage.getMemoryById(memory.id))!.path });
+    }
+    // Anchors are read after the sources are projected, so many of them make the tail the deadline falls in.
+    await upsertCueAnchors({
+      memoryDir,
+      anchors: Array.from({ length: 1500 }, (_, i) => anchor(`xi-a${i}`, `n${i % 120}`, sources[i % 120]!.id)),
+    });
+    // Calibrate: how long one cold build takes on this machine.
+    const calibrationStart = Date.now();
+    await read(memoryDir);
+    const buildMs = Date.now() - calibrationStart;
+    clearHarmonicGraphCache();
+    // n0's source expires near the end of the next build, which started before the deadline.
+    const first = sources[0]!;
+    const deadlineMs = Date.now() + Math.max(2, Math.floor(buildMs * 0.85));
+    await writeFile(
+      first.path,
+      (await readFile(first.path, "utf8")).replace("category: fact", `category: fact\ninvalidAt: ${new Date(deadlineMs).toISOString()}`),
+    );
+    // The storage layer caches parsed memories by corpus version, so an out-of-band edit needs the documented bump.
+    bumpMemoryCorpusVersionForDir(memoryDir);
+    const graph = await read(memoryDir);
+    const returnedAtMs = Date.now();
+    const served = graph.nodes.some((candidate) => candidate.nodeId === "n0");
+    // A build that finished before the deadline may legitimately include n0 (a 25 ms margin covers the
+    // hand-off); one that returned after it must not.
+    if (returnedAtMs >= deadlineMs + 25) {
+      assert.equal(served, false, `expired source served; build took about ${buildMs} ms`);
+      assert.equal(graph.nodes.length, 119);
+    }
   });
 });
 

package/src/harmonic-retrieval.ts

@@ -2,6 +2,7 @@ import path from "node:path";
 import { realpath } from "node:fs/promises";
 import { listJsonFilesStrict, readJsonFile } from "./json-store.js";
 import { raceAbort, throwIfAborted } from "./abort-error.js";
+import { log } from "./logger.js";
 import { readHarmonicGraphStamp } from "./harmonic-graph-version.js";
 import { inferMemoryStatus, toMemoryPathRel } from "./memory-lifecycle-ledger-utils.js";
  import {
@@ -170,6 +171,20 @@ function parseSourceMemoryInsertedAt(node: AbstractionNode): Map<string, string>
   return insertedAtById;
 }
 
+/**
+ * Whether a source memory can back a projected node at all. Shared with `earliestInvalidAtMs`, so the cache
+ * deadline only follows a source that the projection would use.
+ * #2332: a private support-passport record leaves the eligible set the same way a rejected one does — a node
+ * title or anchor attribution rebuilt from it would leak governed metadata into the deep-recall frontier (and
+ * every other graph reader) before any content check runs.
+ */
+function isEligibleSourceMemory(memory: MemoryFile, memoryDir: string): boolean {
+  return (
+    !isSupportPassportPrivateMemory(memory) &&
+    inferMemoryStatus(memory.frontmatter, toMemoryPathRel(memoryDir, memory.path)) === "active"
+  );
+}
+
 function projectSourceBackedNode(
   node: AbstractionNode,
   sourceMemories: SourceMemoryMap,
@@ -184,12 +199,7 @@ function projectSourceBackedNode(
     const memory = sourceMemories.get(memoryId);
     return (
       memory !== undefined &&
-      // #2332: a private support-passport record leaves the eligible set the
-      // same way a rejected one does — a node title or anchor attribution
-      // rebuilt from it would leak governed metadata into the deep-recall
-      // frontier (and every other graph reader) before any content check runs.
-      !isSupportPassportPrivateMemory(memory) &&
-      inferMemoryStatus(memory.frontmatter, toMemoryPathRel(memoryDir, memory.path)) === "active" &&
+      isEligibleSourceMemory(memory, memoryDir) &&
       (temporalExpiredInInjection || !isValidityExpiredNow(memory.frontmatter, nowMs))
     );
   });
@@ -404,6 +414,22 @@ export interface ProjectedHarmonicGraph {
  *   one of that node's surviving active sources, and is dropped once no
  *   reference survives.
  */
+interface ExpiringHarmonicGraph extends ProjectedHarmonicGraph {
+  /** First instant a source memory's `invalid_at` passes: from then on the graph is wrong without any write. */
+  validUntilMs: number;
+}
+
+function earliestInvalidAtMs(sourceMemories: SourceMemoryMap, memoryDir: string, nowMs: number): number {
+  let earliest = Number.POSITIVE_INFINITY;
+  for (const memory of sourceMemories.values()) {
+    // An ineligible source drops out of the projection whatever its `invalid_at`, so its deadline changes nothing.
+    if (!isEligibleSourceMemory(memory, memoryDir)) continue;
+    const invalidAtMs = Date.parse(memory.frontmatter.invalid_at?.trim() ?? "");
+    if (Number.isFinite(invalidAtMs) && invalidAtMs > nowMs && invalidAtMs < earliest) earliest = invalidAtMs;
+  }
+  return earliest;
+}
+
 async function buildProjectedHarmonicGraph(options: {
   memoryDir: string;
   abstractionNodeStoreDir?: string;
@@ -412,6 +438,18 @@ async function buildProjectedHarmonicGraph(options: {
   temporalExpiredInInjection?: boolean;
   nowMs?: number;
 }): Promise<ProjectedHarmonicGraph> {
+  const { nodes, anchors } = await buildExpiringHarmonicGraph(options);
+  return { nodes, anchors };
+}
+
+async function buildExpiringHarmonicGraph(options: {
+  memoryDir: string;
+  abstractionNodeStoreDir?: string;
+  anchorsEnabled: boolean;
+  abortSignal?: AbortSignal;
+  temporalExpiredInInjection?: boolean;
+  nowMs?: number;
+}): Promise<ExpiringHarmonicGraph> {
   throwIfAborted(options.abortSignal, "harmonic retrieval aborted");
   const nodes = await readAbstractionNodes(options);
   const sourceMemoryIds = [...new Set(nodes.flatMap((node) => node.sourceMemoryIds ?? []))];
@@ -424,6 +462,10 @@ async function buildProjectedHarmonicGraph(options: {
       })
     : new Map();
   const nowMs = options.nowMs ?? Date.now();
+  // With temporalExpiredInInjection the validity filter is off, so no `invalid_at` can age the graph.
+  const validUntilMs = options.temporalExpiredInInjection === true
+    ? Number.POSITIVE_INFINITY
+    : earliestInvalidAtMs(sourceMemories, options.memoryDir, nowMs);
   // A node whose full stored source set survived projection keeps legacy
   // anchor attribution (an anchor written before per-node source ids existed).
   const legacyCompatibleNodeRefs = new Set<string>();
@@ -444,7 +486,7 @@ async function buildProjectedHarmonicGraph(options: {
     }
     return projected ? [projected] : [];
   });
-  if (!options.anchorsEnabled) return { nodes: projectedNodes, anchors: [] };
+  if (!options.anchorsEnabled) return { nodes: projectedNodes, anchors: [], validUntilMs };
   throwIfAborted(options.abortSignal, "harmonic retrieval aborted");
   const nodeIndex = new Map(projectedNodes.map((node) => [node.nodeId, node]));
   const anchors = (await readCueAnchors(options)).flatMap((anchor) => {
@@ -458,20 +500,25 @@ async function buildProjectedHarmonicGraph(options: {
     });
     return nodeRefs.length > 0 ? [{ ...anchor, nodeRefs }] : [];
   });
-  return { nodes: projectedNodes, anchors };
+  return { nodes: projectedNodes, anchors, validUntilMs };
 }
 
 const GRAPH_CACHE_TTL_MS = 30_000;
+/**
+ * Past the TTL a graph whose stamp is unchanged is still served while a refresh runs behind it, so no
+ * recall waits for a rebuild just because the TTL lapsed. This is how long past the TTL; after it the graph is rebuilt first.
+ */
+const GRAPH_CACHE_MAX_STALE_MS = 300_000;
 const GRAPH_CACHE_MAX_ENTRIES = 8;
 
 interface GraphCacheEntry {
   stamp: string;
-  startedAtMs: number;
+  /** When the build finished, so the TTL measures how long the graph has been available. */
+  builtAtMs: number;
+  validUntilMs: number;
   graph: ProjectedHarmonicGraph;
 }
 
-const graphCache = new Map<string, GraphCacheEntry>();
-
 interface GraphBuild {
   stamp: string;
   promise: Promise<ProjectedHarmonicGraph>;
@@ -481,10 +528,41 @@ interface GraphBuild {
   waiting: number;
 }
 
+const graphCache = new Map<string, GraphCacheEntry>();
 /** One build per cache key at a time: every recall that lands on a miss waits for the same build. */
 const graphBuilds = new Map<string, GraphBuild>();
-/** Counters for tests and diagnostics. `shared` counts reads that joined a build already running. */
-export const harmonicGraphCacheStats = { hits: 0, misses: 0, shared: 0 };
+/** When a background refresh last failed, per key: stale reads retry at most once per TTL. Capped like the cache. */
+const refreshFailedAtMs = new Map<string, number>();
+
+function rememberRefreshFailure(key: string): void {
+  refreshFailedAtMs.delete(key);
+  refreshFailedAtMs.set(key, Date.now());
+  while (refreshFailedAtMs.size > GRAPH_CACHE_MAX_ENTRIES) {
+    const oldest = refreshFailedAtMs.keys().next().value;
+    if (oldest === undefined) break;
+    refreshFailedAtMs.delete(oldest);
+  }
+}
+
+/**
+ * A source's `invalid_at` can pass while the build is still reading anchors, which would hand every caller
+ * that joined this build a graph that is already expired. Rebuild until the graph is unexpired at completion.
+ * Each round drops the sources that expired, so the set of future deadlines shrinks and the loop ends.
+ */
+async function buildUnexpiredHarmonicGraph(options: GraphReadOptions, abortSignal: AbortSignal): Promise<ExpiringHarmonicGraph> {
+  for (;;) {
+    const built = await buildExpiringHarmonicGraph({
+      memoryDir: options.memoryDir,
+      abstractionNodeStoreDir: options.abstractionNodeStoreDir,
+      anchorsEnabled: options.anchorsEnabled,
+      temporalExpiredInInjection: options.temporalExpiredInInjection,
+      abortSignal,
+    });
+    if (Date.now() < built.validUntilMs) return built;
+  }
+}
+/** Counters for tests and diagnostics. `stale` hits also count as `hits`. */
+export const harmonicGraphCacheStats = { hits: 0, misses: 0, stale: 0, shared: 0 };
 
 /** Freeze records and their nested arrays/objects so a caller cannot corrupt the shared cache. */
 function deepFreeze<T extends object>(value: T): T {
@@ -498,6 +576,16 @@ function deepFreeze<T extends object>(value: T): T {
 export function clearHarmonicGraphCache(): void {
   graphCache.clear();
   graphBuilds.clear();
+  refreshFailedAtMs.clear();
+}
+
+/**
+ * Resolves once every build running now has settled, and after the failure bookkeeping of a background
+ * refresh (that handler was attached when the refresh started, so it runs first). For tests: a time-based
+ * wait races a slow build.
+ */
+export async function settleHarmonicGraphBuilds(): Promise<void> {
+  await Promise.allSettled([...graphBuilds.values()].map((build) => build.promise));
 }
 
 type GraphReadOptions = Parameters<typeof buildProjectedHarmonicGraph>[0];
@@ -508,21 +596,15 @@ type GraphReadOptions = Parameters<typeof buildProjectedHarmonicGraph>[0];
  */
 function startGraphBuild(key: string, stamp: string, options: GraphReadOptions): GraphBuild {
   harmonicGraphCacheStats.misses++;
-  const startedAtMs = Date.now();
   const controller = new AbortController();
-  const promise: Promise<ProjectedHarmonicGraph> = buildProjectedHarmonicGraph({
-    memoryDir: options.memoryDir,
-    abstractionNodeStoreDir: options.abstractionNodeStoreDir,
-    anchorsEnabled: options.anchorsEnabled,
-    temporalExpiredInInjection: options.temporalExpiredInInjection,
-    abortSignal: controller.signal,
-  })
+  const promise: Promise<ProjectedHarmonicGraph> = buildUnexpiredHarmonicGraph(options, controller.signal)
     .then((built) => {
       const graph = { nodes: deepFreeze(built.nodes), anchors: deepFreeze(built.anchors) };
       // A cleared cache or a newer build for this key has replaced this one: do not store a stale graph.
       if (graphBuilds.get(key)?.promise !== promise) return graph;
+      refreshFailedAtMs.delete(key);
       graphCache.delete(key);
-      graphCache.set(key, { stamp, startedAtMs, graph });
+      graphCache.set(key, { stamp, builtAtMs: Date.now(), validUntilMs: built.validUntilMs, graph });
       while (graphCache.size > GRAPH_CACHE_MAX_ENTRIES) {
         const oldest = graphCache.keys().next().value;
         if (oldest === undefined) break;
@@ -561,9 +643,12 @@ function joinGraphBuild(key: string, build: GraphBuild, signal: AbortSignal | un
  * cold-write version sentinels (bumped by every memory write, in any process) and
  * the graph version sentinel (bumped by node and anchor writes). A stamp read is
  * four stats, not a scan of the memories. The TTL bounds the one input a sentinel
- * cannot see, which is wall-clock validity expiry. Concurrent misses share one
- * build. An explicit `nowMs` bypasses the cache so tests stay deterministic. The
- * cached arrays are frozen: callers must not mutate them.
+ * cannot see, which is wall-clock validity expiry; past it the stale graph is served
+ * while one refresh runs (up to GRAPH_CACHE_MAX_STALE_MS). A changed stamp always
+ * waits for a fresh build, because a stale graph could carry governed metadata of a
+ * memory that left the active set. Concurrent misses share one build. An explicit
+ * `nowMs` bypasses the cache so tests stay deterministic. The cached arrays are
+ * frozen: callers must not mutate them.
  */
 export async function readProjectedHarmonicGraph(options: {
   memoryDir: string;
@@ -587,12 +672,25 @@ export async function readProjectedHarmonicGraph(options: {
   // The stamp is read BEFORE the build, so a write that lands mid-build leaves the
   // entry stale and the next call rebuilds.
   const stamp = readHarmonicGraphStamp(options.memoryDir, nodeStoreDir);
-  const startedAtMs = Date.now();
+  const nowMs = Date.now();
   const hit = graphCache.get(key);
-  if (hit && hit.stamp === stamp && startedAtMs - hit.startedAtMs < GRAPH_CACHE_TTL_MS) {
+  // A source's `invalid_at` passing changes the projection without bumping the stamp, so it ends the entry
+  // at the exact instant, however fresh the entry is.
+  if (hit && hit.stamp === stamp && nowMs < hit.validUntilMs && nowMs - hit.builtAtMs < GRAPH_CACHE_TTL_MS + GRAPH_CACHE_MAX_STALE_MS) {
     harmonicGraphCacheStats.hits++;
     graphCache.delete(key);
     graphCache.set(key, hit);
+    if (nowMs - hit.builtAtMs >= GRAPH_CACHE_TTL_MS) {
+      harmonicGraphCacheStats.stale++;
+      const failedAtMs = refreshFailedAtMs.get(key);
+      const backingOff = failedAtMs !== undefined && nowMs - failedAtMs < GRAPH_CACHE_TTL_MS;
+      if (graphBuilds.get(key)?.stamp !== stamp && !backingOff) {
+        startGraphBuild(key, stamp, options).promise.catch((err) => {
+          rememberRefreshFailure(key);
+          log.debug(`harmonic graph refresh failed: ${err}`);
+        });
+      }
+    }
     return hit.graph;
   }
   const running = graphBuilds.get(key);