@remnic/core 10.0.100 → 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.100",
+  "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.100"
+    "@remnic/coding-graph": "^10.0.102"
   },
   "peerDependenciesMeta": {
     "@remnic/coding-graph": {

package/src/entity-lazy-compatibility.test.ts

@@ -6,6 +6,26 @@ import test from "node:test";
 import { StorageManager, parseEntityFile } from "./storage.js";
 import { sleep } from "./utils/sleep.js";
 
+const deferredStores: StorageManager[] = [];
+
+// Opens a store the way the daemon does: the canonical-id migration starts in
+// the background. Registered so teardown can wait for it.
+async function deferStore(dir: string): Promise<StorageManager> {
+  const store = new StorageManager(dir);
+  deferredStores.push(store);
+  await store.ensureDirectories({ waitForEntityMigration: false });
+  return store;
+}
+
+// The deferred migration keeps writing under dir until it settles. Release any
+// lock the test holds, wait for every registered migration, then remove dir.
+async function disposeStore(dir: string): Promise<void> {
+  await rm(path.join(dir, "state", "entity-canonical-id-migration.lock"), { force: true });
+  await Promise.all(deferredStores.splice(0).map((store) => store.drainEntityCanonicalIdMigration()));
+  StorageManager.clearAllStaticCaches();
+  await rm(dir, { recursive: true, force: true });
+}
+
 async function legacyStore() {
   const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-lazy-compat-"));
   const seed = new StorageManager(dir);
@@ -15,8 +35,7 @@ async function legacyStore() {
   await rm(journal, { force: true });
   const lock = path.join(dir, "state", "entity-canonical-id-migration.lock");
   await writeFile(lock, `${process.pid} test-holder ${new Date().toISOString()}\n`);
-  const storage = new StorageManager(dir);
-  await storage.ensureDirectories({ waitForEntityMigration: false });
+  const storage = await deferStore(dir);
   return { dir, id, journal, lock, storage };
 }
 
@@ -27,8 +46,7 @@ test("canonical reads find a legacy file without a journal or migration", async
     await assert.rejects(() => readFile(fixture.journal), { code: "ENOENT" });
     assert.ok(await readFile(fixture.lock));
   } finally {
-    StorageManager.clearAllStaticCaches();
-    await rm(fixture.dir, { recursive: true, force: true });
+    await disposeStore(fixture.dir);
   }
 });
 
@@ -39,8 +57,7 @@ test("ambiguous legacy canonical matches are refused rather than picking a claim
     await writeFile(path.join(fixture.dir, "entities", "other-legacy-person.md"), raw);
     await assert.rejects(() => fixture.storage.readEntity(fixture.id), /ambiguous/i);
   } finally {
-    StorageManager.clearAllStaticCaches();
-    await rm(fixture.dir, { recursive: true, force: true });
+    await disposeStore(fixture.dir);
   }
 });
 
@@ -50,8 +67,9 @@ test("completed migration skips corpus reads on repeated misses in a fresh read-
     const seed = new StorageManager(dir);
     await seed.writeEntity("Existing Person", "person", ["Synthetic fact."]);
     await seed.ensureDirectories();
-    const reader = new StorageManager(dir);
-    await reader.ensureDirectories({ waitForEntityMigration: false });
+    const reader = await deferStore(dir);
+    // Let the startup migration finish so only the readEntity calls below are counted.
+    await reader.drainEntityCanonicalIdMigration();
     // Bracket access is TypeScript's typed escape hatch for the private reader.
     const originalRead = reader["readStorageSecureFile"].bind(reader);
     const reads: string[] = [];
@@ -63,8 +81,7 @@ test("completed migration skips corpus reads on repeated misses in a fresh read-
     assert.equal(await reader.readEntity("person-missing"), "");
     assert.deepEqual(reads, ["person-missing.md", "person-missing.md"], "completed-store misses must not scan entity contents");
   } finally {
-    StorageManager.clearAllStaticCaches();
-    await rm(dir, { recursive: true, force: true });
+    await disposeStore(dir);
   }
 });
 
@@ -74,8 +91,7 @@ test("an external entities change invalidates the amortized completion verdict o
     const seed = new StorageManager(dir);
     const id = await seed.writeEntity("Café", "project", ["Synthetic legacy fact."]);
     await seed.ensureDirectories();
-    const reader = new StorageManager(dir);
-    await reader.ensureDirectories({ waitForEntityMigration: false });
+    const reader = await deferStore(dir);
     const canonical = reader.normalizeEntityName("Café", "project");
     // First miss computes and caches the completion verdict.
     assert.equal(await reader.readEntity("project-missing"), "");
@@ -84,8 +100,7 @@ test("an external entities change invalidates the amortized completion verdict o
     await rename(path.join(dir, "entities", `${id}.md`), path.join(dir, "entities", "legacy-cafe.md"));
     assert.match(await reader.readEntity(canonical), /Synthetic legacy fact/);
   } finally {
-    StorageManager.clearAllStaticCaches();
-    await rm(dir, { recursive: true, force: true });
+    await disposeStore(dir);
   }
 });
 
@@ -99,8 +114,7 @@ test("an external aliases change invalidates the amortized completion verdict on
     const journal = await readFile(journalPath, "utf8");
     assert.equal(JSON.parse(journal).complete, true);
 
-    const reader = new StorageManager(dir);
-    await reader.ensureDirectories({ waitForEntityMigration: false });
+    const reader = await deferStore(dir);
     // Warm amortized completion (and any same-reader completion memo) on a miss.
     assert.equal(await reader.readEntity("project-missing"), "");
 
@@ -121,8 +135,7 @@ test("an external aliases change invalidates the amortized completion verdict on
     assert.equal(await readFile(journalPath, "utf8"), journal, "read compatibility must not replay migration");
     assert.ok(await readFile(lock));
   } finally {
-    StorageManager.clearAllStaticCaches();
-    await rm(dir, { recursive: true, force: true });
+    await disposeStore(dir);
   }
 });
 
@@ -146,16 +159,14 @@ for (const change of ["aliases", "raw legacy write"]) {
       }
       const lock = path.join(dir, "state", "entity-canonical-id-migration.lock");
       await writeFile(lock, `${process.pid} test-holder ${new Date().toISOString()}\n`);
-      const reader = new StorageManager(dir);
-      await reader.ensureDirectories({ waitForEntityMigration: false });
+      const reader = await deferStore(dir);
       const canonical = reader.normalizeEntityName("Café", "project");
       if (change === "aliases") assert.notEqual(canonical, previousId);
       assert.match(await reader.readEntity(canonical), /Synthetic legacy fact/);
       assert.equal(await readFile(journalPath, "utf8"), journal, "read compatibility must not replay migration");
       assert.ok(await readFile(lock));
     } finally {
-      StorageManager.clearAllStaticCaches();
-      await rm(dir, { recursive: true, force: true });
+      await disposeStore(dir);
     }
   });
 }
@@ -221,8 +232,7 @@ for (const mutation of mutations) {
       const journal = JSON.parse(await readFile(fixture.journal, "utf8"));
       assert.equal(journal.complete, true);
     } finally {
-      StorageManager.clearAllStaticCaches();
-      await rm(fixture.dir, { recursive: true, force: true });
+      await disposeStore(fixture.dir);
     }
   });
 }

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);
+    }
   });
 });