@remnic/core 10.0.7 → 10.0.8

package/dist/who-knows-cli.js

@@ -4,14 +4,15 @@ import {
   renderWhoKnows,
   renderWhoKnowsJson,
   renderWhoKnowsText
-} from "./chunk-JFGX2DKT.js";
-import "./chunk-Z4CETAL7.js";
-import "./chunk-OX5LMCEQ.js";
-import "./chunk-LZKOVXMX.js";
+} from "./chunk-KRIEQCKE.js";
+import "./chunk-3ENX2RB4.js";
+import "./chunk-WJLGUY27.js";
 import "./chunk-UHVXE24Y.js";
+import "./chunk-LZKOVXMX.js";
 import "./chunk-V4JZCTMK.js";
-import "./chunk-YV54LYEB.js";
-import "./chunk-J5QL66XK.js";
+import "./chunk-7UX44C4N.js";
+import "./chunk-MB5EJ2CT.js";
+import "./chunk-CYEPCZN5.js";
 import "./chunk-T3FMRLWQ.js";
 import "./chunk-7VO6E5UD.js";
 import "./chunk-5BUCKFRE.js";
@@ -19,7 +20,6 @@ import "./chunk-S7LWX2PQ.js";
 import "./chunk-T2YX56QI.js";
 import "./chunk-4O6WRBGE.js";
 import "./chunk-GUMZC2BO.js";
-import "./chunk-CYEPCZN5.js";
 import "./chunk-TFA6HPOA.js";
 import "./chunk-F4TWWUMP.js";
 import "./chunk-72A4L5JJ.js";
@@ -28,8 +28,8 @@ import "./chunk-S2V7RUCL.js";
 import "./chunk-X3724WL4.js";
 import "./chunk-MRPOZBJC.js";
 import "./chunk-S2HLHAZ4.js";
-import "./chunk-DM2T26WE.js";
 import "./chunk-LDXUBPMO.js";
+import "./chunk-DM2T26WE.js";
 import "./chunk-FF6N7BXC.js";
 import "./chunk-2DT7PIDZ.js";
 import "./chunk-AAD2ZS6P.js";
@@ -49,12 +49,12 @@ import "./chunk-5WITETWU.js";
 import "./chunk-6CIAGZ6X.js";
 import "./chunk-7CT3AI52.js";
 import "./chunk-G7D6GZ5J.js";
-import "./chunk-JALYQUYO.js";
-import "./chunk-IUM3VSHI.js";
+import "./chunk-DGRMWDQY.js";
 import "./chunk-G26YNEOC.js";
+import "./chunk-SIGAGKNE.js";
+import "./chunk-IUM3VSHI.js";
 import "./chunk-WVHRNAXL.js";
 import "./chunk-TPSLVZHS.js";
-import "./chunk-SIGAGKNE.js";
 import "./chunk-23G5P7TA.js";
 import "./chunk-C64XATK7.js";
 import "./chunk-42JKGUFJ.js";

package/dist/who-knows.js

@@ -9,13 +9,14 @@ import {
   loadWhoKnowsEntities,
   tokenizeTopic,
   validateWhoKnowsInput
-} from "./chunk-Z4CETAL7.js";
-import "./chunk-OX5LMCEQ.js";
-import "./chunk-LZKOVXMX.js";
+} from "./chunk-3ENX2RB4.js";
+import "./chunk-WJLGUY27.js";
 import "./chunk-UHVXE24Y.js";
+import "./chunk-LZKOVXMX.js";
 import "./chunk-V4JZCTMK.js";
-import "./chunk-YV54LYEB.js";
-import "./chunk-J5QL66XK.js";
+import "./chunk-7UX44C4N.js";
+import "./chunk-MB5EJ2CT.js";
+import "./chunk-CYEPCZN5.js";
 import "./chunk-T3FMRLWQ.js";
 import "./chunk-7VO6E5UD.js";
 import "./chunk-5BUCKFRE.js";
@@ -23,7 +24,6 @@ import "./chunk-S7LWX2PQ.js";
 import "./chunk-T2YX56QI.js";
 import "./chunk-4O6WRBGE.js";
 import "./chunk-GUMZC2BO.js";
-import "./chunk-CYEPCZN5.js";
 import "./chunk-TFA6HPOA.js";
 import "./chunk-F4TWWUMP.js";
 import "./chunk-72A4L5JJ.js";
@@ -32,8 +32,8 @@ import "./chunk-S2V7RUCL.js";
 import "./chunk-X3724WL4.js";
 import "./chunk-MRPOZBJC.js";
 import "./chunk-S2HLHAZ4.js";
-import "./chunk-DM2T26WE.js";
 import "./chunk-LDXUBPMO.js";
+import "./chunk-DM2T26WE.js";
 import "./chunk-FF6N7BXC.js";
 import "./chunk-2DT7PIDZ.js";
 import "./chunk-AAD2ZS6P.js";
@@ -53,12 +53,12 @@ import "./chunk-5WITETWU.js";
 import "./chunk-6CIAGZ6X.js";
 import "./chunk-7CT3AI52.js";
 import "./chunk-G7D6GZ5J.js";
-import "./chunk-JALYQUYO.js";
-import "./chunk-IUM3VSHI.js";
+import "./chunk-DGRMWDQY.js";
 import "./chunk-G26YNEOC.js";
+import "./chunk-SIGAGKNE.js";
+import "./chunk-IUM3VSHI.js";
 import "./chunk-WVHRNAXL.js";
 import "./chunk-TPSLVZHS.js";
-import "./chunk-SIGAGKNE.js";
 import "./chunk-23G5P7TA.js";
 import "./chunk-C64XATK7.js";
 import "./chunk-42JKGUFJ.js";

package/package.json

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

package/src/harmonic-retrieval.ts

@@ -1,5 +1,4 @@
 import path from "node:path";
-import { existsSync } from "node:fs";
 import { realpath } from "node:fs/promises";
 import { listJsonFilesStrict, readJsonFile } from "./json-store.js";
 import { throwIfAborted } from "./abort-error.js";
@@ -22,31 +21,11 @@ import { readProjectedMemoryStates } from "./memory-projection-batch.js";
 import { SecureStoreLockedError } from "./secure-store/secure-fs.js";
 import { StorageManager } from "./storage.js";
 import { RECALL_FALLBACK_DIRS } from "./utils/category-dir.js";
-import { isPathInsideStorageRoot } from "./storage-paths.js";
+import { readHarmonicSourceMemory, readUnresolvedHarmonicSources } from "./harmonic-source-lookup.js";
 
 
 type SourceMemoryMap = Map<string, MemoryFile>;
 
-// `rootReal` set: a direct probe, which skips the corpus walk's symlink
-// hardening, so the resolved file must stay inside the memory root. Null: the
-// path came from the contained corpus walk and is already trusted.
-async function readMemoryFile(
-  storage: StorageManager,
-  rootReal: string | null,
-  filePath: string,
-  abortSignal?: AbortSignal,
-): Promise<MemoryFile | null> {
-  throwIfAborted(abortSignal, "harmonic retrieval aborted");
-  if (!existsSync(filePath)) return null;
-  try {
-    if (rootReal !== null && !isPathInsideStorageRoot(rootReal, await realpath(filePath))) return null;
-    return await storage.readMemoryByPath(filePath);
-  } catch (err) {
-    throwIfAborted(abortSignal, "harmonic retrieval aborted");
-    if (err instanceof SecureStoreLockedError) throw err;
-    return null;
-  }
-}
 
 // An index older than this is treated as unusable: the date window needed to
 // cover "created since the last rebuild" would stop being cheap.
@@ -61,13 +40,6 @@ function utcDaysSince(rebuiltMs: number, nowMs: number): string[] {
   return days;
 }
 
-// Source ids confirmed absent by a corpus path walk. A node only references a
-// source after the source file exists, so a confirmed absence stays true unless
-// the file is restored later; the short TTL bounds that. Without this, one
-// dangling id (a hard-deleted fact) would force a walk on every recall.
-const ABSENT_SOURCE_TTL_MS = 10 * 60_000;
-const ABSENT_SOURCE_MAX_ENTRIES = 4096;
-const absentSourceIds = new Map<string, number>(); // `${memoryDir}\0${id}` -> expiry ms
 
 // Memories the projection has no row for were written after its last rebuild, so
 // their dated directory is normally one of `days`. Hot and cold tiers are probed
@@ -84,16 +56,7 @@ function unprojectedCandidatePaths(memoryDir: string, id: string, days: string[]
   return paths;
 }
 
-/**
- * Resolve only the source ids the abstraction nodes reference. Returns null when
- * the projection is absent, unreadable, too old, or not known to cover every
- * active memory (a scoped or pre-`complete` rebuild), so the caller keeps the
- * full-corpus scan. Every file is read from disk, so status, tags and validity
- * are current; the index only says where to look. An id the cheap probes cannot
- * place (an import filed under an old date, a tier root outside the memory dir)
- * is looked up by one contained path-only walk, never a frontmatter parse of the
- * corpus.
- */
+/** Resolve indexed sources first, then use the durable unresolved-id path cache. */
 async function readIndexedSourceMemories(options: {
   memoryDir: string;
   abortSignal?: AbortSignal;
@@ -103,7 +66,7 @@ async function readIndexedSourceMemories(options: {
   // The ids go to SQL as bound parameters, so any id the projection holds is safe to look up.
   const batch = readProjectedMemoryStates(options.memoryDir, options.sourceMemoryIds);
   const rebuiltMs = Date.parse(batch?.rebuiltAt ?? "");
-  if (!batch?.complete || !Number.isFinite(rebuiltMs) || options.nowMs - rebuiltMs > INDEX_MAX_AGE_MS) return null;
+  if (!batch?.complete || !batch.rebuiltAt || !Number.isFinite(rebuiltMs) || options.nowMs - rebuiltMs > INDEX_MAX_AGE_MS) return null;
   const rootReal = await realpath(options.memoryDir).catch(() => null);
   if (rootReal === null) return null;
 
@@ -120,42 +83,27 @@ async function readIndexedSourceMemories(options: {
     } catch {
       safeId = false;
     }
-    // An unprojected id that is not a single path segment cannot be probed or
-    // matched by filename, and the scan keys sources by frontmatter id, so only
-    // the scan can place it. Rare (legacy/imported ids); worst case is the old cost.
-    if (!state && !safeId) return null;
     // state.path was containment-checked by the projection reader.
     const candidates = state
       ? [state.path, path.join(options.memoryDir, "cold", state.pathRel)]
-      : unprojectedCandidatePaths(options.memoryDir, id, days);
+      : safeId ? unprojectedCandidatePaths(options.memoryDir, id, days) : [];
     let found = false;
     for (const candidate of candidates) {
-      const memory = await readMemoryFile(storage, rootReal, candidate, options.abortSignal);
+      const memory = await readHarmonicSourceMemory(storage, rootReal, candidate, options.abortSignal);
       if (memory?.frontmatter.id !== id) continue;
       sourceMemories.set(id, memory);
       found = true;
       break;
     }
-    const absentKey = `${options.memoryDir}\0${id}`;
-    if (!found && safeId && (absentSourceIds.get(absentKey) ?? 0) <= options.nowMs) pending.push(id);
+    if (!found) pending.push(id);
   }
   if (pending.length === 0) return sourceMemories;
 
-  const wanted = new Set(pending);
-  const walked = [
-    ...(await storage.collectActiveMemoryPaths({ abortSignal: options.abortSignal })),
-    ...(await storage.collectColdMemoryPaths({ abortSignal: options.abortSignal })),
-  ];
-  for (const filePath of walked) {
-    throwIfAborted(options.abortSignal, "harmonic retrieval aborted");
-    if (!wanted.has(path.basename(filePath, ".md"))) continue;
-    const memory = await readMemoryFile(storage, null, filePath, options.abortSignal);
-    if (memory && wanted.has(memory.frontmatter.id)) sourceMemories.set(memory.frontmatter.id, memory);
-  }
-  if (absentSourceIds.size > ABSENT_SOURCE_MAX_ENTRIES) absentSourceIds.clear();
-  for (const id of pending) {
-    if (!sourceMemories.has(id)) absentSourceIds.set(`${options.memoryDir}\0${id}`, options.nowMs + ABSENT_SOURCE_TTL_MS);
-  }
+  const unresolved = await readUnresolvedHarmonicSources({
+    storage, rootReal, rebuiltAt: batch.rebuiltAt, sourceMemoryIds: pending,
+    nowMs: options.nowMs, abortSignal: options.abortSignal,
+  });
+  for (const [id, memory] of unresolved) sourceMemories.set(id, memory);
   return sourceMemories;
 }
 
@@ -168,7 +116,7 @@ async function readCorpusSourceMemories(options: {
     const storage = new StorageManager(options.memoryDir);
     const [hotMemories, coldMemories] = await Promise.all([
       storage.readAllMemories({ abortSignal: options.abortSignal }),
-      storage.readAllColdMemories(),
+      storage.readAllColdMemories({ abortSignal: options.abortSignal }),
     ]);
     for (const memory of [...hotMemories, ...coldMemories]) {
       throwIfAborted(options.abortSignal, "harmonic retrieval aborted");

package/src/harmonic-source-lookup.test.ts

@@ -0,0 +1,178 @@
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { mkdir, mkdtemp, readFile, realpath, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import test from "node:test";
+import { recordAbstractionNode } from "./abstraction-nodes.js";
+import { readProjectedHarmonicGraph } from "./harmonic-retrieval.js";
+import { rebuildMemoryProjection } from "./maintenance/rebuild-memory-projection.js";
+import { StorageManager } from "./storage.js";
+import { readUnresolvedHarmonicSources } from "./harmonic-source-lookup.js";
+import { bumpMemoryCorpusVersionForDir } from "./memory-corpus-version.js";
+
+async function seed(memoryDir: string) {
+  const storage = new StorageManager(memoryDir);
+  await storage.ensureDirectories();
+  const real = await storage.writeMemory("fact", "real harmonic source", { source: "test" });
+  await recordAbstractionNode({ memoryDir, node: {
+    schemaVersion: 1, nodeId: "source-lookup", recordedAt: new Date().toISOString(),
+    sessionKey: "agent:test", kind: "topic", abstractionLevel: "meso",
+    title: "source lookup", summary: "source lookup",
+    sourceMemoryIds: [real.id, "missing-source", "hot-import", "cold/import"],
+  } });
+  await rebuildMemoryProjection({ memoryDir, storage, dryRun: false });
+  return { storage, real };
+}
+
+async function importFile(memoryDir: string, tier: string, name: string, id: string) {
+  const dir = path.join(memoryDir, tier, "facts", "2000-01-01");
+  await mkdir(dir, { recursive: true });
+  await writeFile(path.join(dir, name),
+    `---\nid: ${id}\ncategory: fact\ncreated: 2000-01-01T00:00:00.000Z\nupdated: 2000-01-01T00:00:00.000Z\nsource: test\nconfidence: 0.8\nconfidenceTier: implied\ntags: []\n---\n\nImported ${id} body.\n`);
+}
+
+test("old-dated imports with non-id filenames resolve in both tiers without a corpus parse (#3188)", async (t) => {
+  const memoryDir = await mkdtemp(path.join(tmpdir(), "remnic-harmonic-lookup-"));
+  try {
+    const { real } = await seed(memoryDir);
+    await importFile(memoryDir, "", "unrelated-hot-name.md", "hot-import");
+    await importFile(memoryDir, "cold", "unrelated-cold-name.md", "cold/import");
+    let scans = 0;
+    t.mock.method(StorageManager.prototype, "readAllMemories", async () => { scans += 1; return []; });
+    const graph = await readProjectedHarmonicGraph({ memoryDir, anchorsEnabled: false });
+    assert.deepEqual(graph.nodes[0]?.sourceMemoryIds?.slice().sort(), [real.id, "hot-import", "cold/import"].sort());
+    assert.equal(scans, 0, "unprojected legacy ids must not force the full frontmatter corpus scan");
+  } finally {
+    t.mock.restoreAll();
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("confirmed missing sources survive a fresh process without another path walk (#3188)", async () => {
+  const memoryDir = await mkdtemp(path.join(tmpdir(), "remnic-harmonic-durable-"));
+  try {
+    const { real } = await seed(memoryDir);
+    const graph = await readProjectedHarmonicGraph({ memoryDir, anchorsEnabled: false });
+    assert.deepEqual(graph.nodes[0]?.sourceMemoryIds, [real.id]);
+    const script = `
+      import { StorageManager } from ${JSON.stringify(new URL("./storage.ts", import.meta.url).href)};
+      import { readProjectedHarmonicGraph } from ${JSON.stringify(new URL("./harmonic-retrieval.ts", import.meta.url).href)};
+      StorageManager.prototype.collectActiveMemoryPaths = async () => { throw new Error("unexpected hot walk after restart"); };
+      StorageManager.prototype.collectColdMemoryPaths = async () => { throw new Error("unexpected cold walk after restart"); };
+      StorageManager.prototype.readAllMemories = async () => { throw new Error("unexpected corpus scan after restart"); };
+      const graph = await readProjectedHarmonicGraph({ memoryDir: ${JSON.stringify(memoryDir)}, anchorsEnabled: false });
+      if (graph.nodes[0]?.sourceMemoryIds?.join() !== ${JSON.stringify(real.id)}) throw new Error("source lost after restart");
+    `;
+    await promisify(execFile)(process.execPath, ["--import", "tsx", "--input-type=module", "-e", script]);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+for (const invalidation of ["ttl", "rebuiltAt", "corpusVersion"]) {
+  test(`durable misses invalidate on ${invalidation} without losing an imported source (#3188)`, async () => {
+    const memoryDir = await mkdtemp(path.join(tmpdir(), "remnic-harmonic-epoch-"));
+    try {
+      const { storage } = await seed(memoryDir);
+      const nowMs = Date.now();
+      const options = {
+        storage, rootReal: await realpath(memoryDir), rebuiltAt: new Date(nowMs).toISOString(),
+        nowMs, sourceMemoryIds: ["restored-id"],
+      };
+      assert.equal((await readUnresolvedHarmonicSources(options)).size, 0);
+      await importFile(memoryDir, "", "not-the-source-id.md", "restored-id");
+      assert.equal((await readUnresolvedHarmonicSources(options)).size, 0, "the existing ten-minute miss window is preserved");
+      if (invalidation === "ttl") options.nowMs += 10 * 60_000;
+      if (invalidation === "rebuiltAt") options.rebuiltAt = new Date(nowMs + 1).toISOString();
+      if (invalidation === "corpusVersion") bumpMemoryCorpusVersionForDir(memoryDir);
+      const restored = await readUnresolvedHarmonicSources(options);
+      assert.equal(restored.get("restored-id")?.content.trim(), "Imported restored-id body.");
+    } finally {
+      await rm(memoryDir, { recursive: true, force: true });
+    }
+  });
+}
+
+test("harmonic cold walk receives cancellation and cannot publish a partial absence cache (#3188)", async (t) => {
+  const memoryDir = await mkdtemp(path.join(tmpdir(), "remnic-harmonic-cancel-"));
+  try {
+    await seed(memoryDir);
+    await importFile(memoryDir, "cold", "cold-import.md", "cold/import");
+    const controller = new AbortController();
+    const original = StorageManager.prototype.collectColdMemoryPaths;
+    t.mock.method(StorageManager.prototype, "collectColdMemoryPaths", function (
+      this: StorageManager, options?: Parameters<StorageManager["collectColdMemoryPaths"]>[0],
+    ) {
+      assert.equal(options?.abortSignal, controller.signal);
+      controller.abort();
+      return original.call(this, options);
+    });
+    await assert.rejects(
+      () => readProjectedHarmonicGraph({ memoryDir, anchorsEnabled: false, abortSignal: controller.signal }),
+      { name: "AbortError" },
+    );
+    await assert.rejects(() => readFile(path.join(memoryDir, "state/harmonic-source-paths.json")), { code: "ENOENT" });
+    t.mock.restoreAll();
+    const graph = await readProjectedHarmonicGraph({ memoryDir, anchorsEnabled: false });
+    assert.equal(graph.nodes[0]?.sourceMemoryIds?.includes("cold/import"), true);
+  } finally {
+    t.mock.restoreAll();
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("an unreadable/unwritable path cache never suppresses an imported source (#3188)", async () => {
+  const memoryDir = await mkdtemp(path.join(tmpdir(), "remnic-harmonic-cache-errors-"));
+  try {
+    await seed(memoryDir);
+    await importFile(memoryDir, "", "not-id.md", "hot-import");
+    const cachePath = path.join(memoryDir, "state/harmonic-source-paths.json");
+    await mkdir(cachePath);
+    const graph = await readProjectedHarmonicGraph({ memoryDir, anchorsEnabled: false });
+    assert.equal(graph.nodes[0]?.sourceMemoryIds?.includes("hot-import"), true);
+    await rm(cachePath, { recursive: true });
+    await writeFile(cachePath, "{broken");
+    const recovered = await readProjectedHarmonicGraph({ memoryDir, anchorsEnabled: false });
+    assert.equal(recovered.nodes[0]?.sourceMemoryIds?.includes("hot-import"), true);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("an unresolved opaque id keeps the old scan candidate set for an edited projected file (#3188)", async () => {
+  const memoryDir = await mkdtemp(path.join(tmpdir(), "remnic-harmonic-opaque-"));
+  try {
+    const { storage, real } = await seed(memoryDir);
+    const memory = await storage.getMemoryById(real.id);
+    assert.ok(memory);
+    await writeFile(memory.path,
+      `---\nid: cold/import\ncategory: fact\ncreated: 2000-01-01T00:00:00.000Z\nupdated: 2000-01-01T00:00:00.000Z\nsource: test\nconfidence: 0.8\nconfidenceTier: implied\ntags: []\n---\n\nEdited projected legacy source.\n`);
+    const graph = await readProjectedHarmonicGraph({ memoryDir, anchorsEnabled: false });
+    assert.deepEqual(graph.nodes[0]?.sourceMemoryIds, ["cold/import"]);
+    assert.equal(graph.nodes[0]?.summary, "Edited projected legacy source.");
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("cached import paths reread source status without another walk (#3188)", async (t) => {
+  const memoryDir = await mkdtemp(path.join(tmpdir(), "remnic-harmonic-fresh-status-"));
+  try {
+    const { real } = await seed(memoryDir);
+    await importFile(memoryDir, "", "not-id.md", "hot-import");
+    const first = await readProjectedHarmonicGraph({ memoryDir, anchorsEnabled: false });
+    assert.equal(first.nodes[0]?.sourceMemoryIds?.includes("hot-import"), true);
+    const filePath = path.join(memoryDir, "facts/2000-01-01/not-id.md");
+    await writeFile(filePath, (await readFile(filePath, "utf8")).replace("category: fact", "category: fact\nstatus: quarantined"));
+    t.mock.method(StorageManager.prototype, "collectActiveMemoryPaths", async () => { throw new Error("unexpected hot walk"); });
+    t.mock.method(StorageManager.prototype, "collectColdMemoryPaths", async () => { throw new Error("unexpected cold walk"); });
+    t.mock.method(StorageManager.prototype, "readAllMemories", async () => { throw new Error("unexpected corpus parse"); });
+    const second = await readProjectedHarmonicGraph({ memoryDir, anchorsEnabled: false });
+    assert.deepEqual(second.nodes[0]?.sourceMemoryIds, [real.id]);
+  } finally {
+    t.mock.restoreAll();
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});

package/src/harmonic-source-lookup.ts

@@ -0,0 +1,142 @@
+import path from "node:path";
+import { existsSync } from "node:fs";
+import { mkdir, realpath } from "node:fs/promises";
+import { throwIfAborted } from "./abort-error.js";
+import { readJsonFile, writeJsonFileAtomic } from "./json-store.js";
+import { readProjectedMemoryPaths } from "./memory-projection-batch.js";
+import { SecureStoreLockedError } from "./secure-store/secure-fs.js";
+import { isPathInsideStorageRoot, isSafeLegacyPathSegment } from "./storage-paths.js";
+import { isRecord } from "./store-contract.js";
+import type { StorageManager } from "./storage.js";
+import type { MemoryFile } from "./types.js";
+import { RECALL_FALLBACK_DIRS } from "./utils/category-dir.js";
+
+const LOOKUP_TTL_MS = 10 * 60_000;
+const MAX_CACHE_ENTRIES = 4096;
+type PathEntry = { path: string | null; expiresAt: number };
+
+/** Direct and cached probes must retain the walk's realpath containment check. */
+export async function readHarmonicSourceMemory(
+  storage: StorageManager,
+  rootReal: string,
+  filePath: string,
+  abortSignal?: AbortSignal,
+): Promise<MemoryFile | null> {
+  throwIfAborted(abortSignal, "harmonic retrieval aborted");
+  if (!existsSync(filePath)) return null;
+  try {
+    if (!isPathInsideStorageRoot(rootReal, await realpath(filePath))) return null;
+    return await storage.readMemoryByPath(filePath);
+  } catch (err) {
+    throwIfAborted(abortSignal, "harmonic retrieval aborted");
+    if (err instanceof SecureStoreLockedError) throw err;
+    return null;
+  }
+}
+
+function isCorpusPath(memoryDir: string, filePath: string): boolean {
+  if (!isPathInsideStorageRoot(memoryDir, filePath)) return false;
+  const [dir] = path.relative(memoryDir, filePath).split(path.sep);
+  return dir === "cold" || RECALL_FALLBACK_DIRS.includes(dir);
+}
+
+/** A cache miss is not authoritative: unreadable/invalid cache state keeps the walk. */
+async function readPathCache(
+  filePath: string, rebuiltAt: string, corpusVersion: string, nowMs: number,
+): Promise<Map<string, PathEntry>> {
+  try {
+    const raw = await readJsonFile(filePath);
+    if (!isRecord(raw) || raw.rebuiltAt !== rebuiltAt || raw.corpusVersion !== corpusVersion || !Array.isArray(raw.entries)) return new Map();
+    const entries = new Map<string, PathEntry>();
+    for (const row of raw.entries) {
+      if (!Array.isArray(row) || row.length !== 3) continue;
+      const [id, storedPath, expiresAt] = row;
+      if (typeof id !== "string" || (storedPath !== null && typeof storedPath !== "string")) continue;
+      if (typeof expiresAt !== "number" || !Number.isFinite(expiresAt) || expiresAt <= nowMs || expiresAt > nowMs + LOOKUP_TTL_MS) continue;
+      entries.set(id, { path: storedPath, expiresAt });
+    }
+    return entries;
+  } catch {
+    return new Map();
+  }
+}
+
+/** Resolve only unresolved ids; persist paths/absence, never memory content. */
+export async function readUnresolvedHarmonicSources(options: {
+  storage: StorageManager;
+  rootReal: string;
+  rebuiltAt: string;
+  sourceMemoryIds: string[];
+  nowMs: number;
+  abortSignal?: AbortSignal;
+}): Promise<Map<string, MemoryFile>> {
+  const { storage, rootReal, rebuiltAt, nowMs, abortSignal } = options;
+  throwIfAborted(abortSignal, "harmonic retrieval aborted");
+  const corpusVersion = storage.getCorpusScanVersion();
+  const stateDir = path.join(storage.dir, "state");
+  const cachePath = path.join(stateDir, "harmonic-source-paths.json");
+  const stateReal = await realpath(stateDir).catch(() => null);
+  const safeCache = stateReal !== null && isPathInsideStorageRoot(rootReal, stateReal);
+  const cache = safeCache ? await readPathCache(cachePath, rebuiltAt, corpusVersion, nowMs) : new Map<string, PathEntry>();
+  const found = new Map<string, MemoryFile>();
+  const pending = new Set<string>();
+  for (const id of options.sourceMemoryIds) {
+    throwIfAborted(abortSignal, "harmonic retrieval aborted");
+    const entry = cache.get(id);
+    if (entry?.path === null) continue;
+    if (entry?.path) {
+      const candidate = path.resolve(storage.dir, entry.path);
+      const memory = isCorpusPath(storage.dir, candidate)
+        ? await readHarmonicSourceMemory(storage, rootReal, candidate, abortSignal) : null;
+      if (memory?.frontmatter.id === id) {
+        found.set(id, memory);
+        continue;
+      }
+    }
+    pending.add(id);
+  }
+  if (pending.size === 0) return found;
+
+  // Opaque legacy ids previously used the full scan, including edited projected files.
+  const inspectProjected = [...pending].some((id) => !isSafeLegacyPathSegment(id));
+  const projectedPaths = readProjectedMemoryPaths(storage.dir);
+  const walked = [
+    ...(await storage.collectActiveMemoryPaths({ abortSignal, propagateReadErrors: true })),
+    ...(await storage.collectColdMemoryPaths({ abortSignal, propagateReadErrors: true })),
+  ];
+  for (const filePath of walked) {
+    throwIfAborted(abortSignal, "harmonic retrieval aborted");
+    // Existing projected files need no parse unless their filename names a wanted id.
+    // New/imported files must be keyed by frontmatter id, not their basename (#3188).
+    if (!inspectProjected && !pending.has(path.basename(filePath, ".md")) && projectedPaths?.has(filePath)) continue;
+    const memory = await readHarmonicSourceMemory(storage, rootReal, filePath, abortSignal);
+    if (!memory) continue;
+    const id = memory.frontmatter.id;
+    if (pending.has(id)) {
+      found.set(id, memory);
+      cache.set(id, { path: path.relative(storage.dir, filePath), expiresAt: nowMs + LOOKUP_TTL_MS });
+    }
+  }
+  for (const id of pending) {
+    if (!found.has(id)) cache.set(id, { path: null, expiresAt: nowMs + LOOKUP_TTL_MS });
+  }
+  throwIfAborted(abortSignal, "harmonic retrieval aborted");
+  // A concurrent mutation must not publish absence for a different corpus epoch.
+  if (storage.getCorpusScanVersion() === corpusVersion) {
+    try {
+      await mkdir(stateDir, { recursive: true });
+      if (isPathInsideStorageRoot(rootReal, await realpath(stateDir))) {
+        throwIfAborted(abortSignal, "harmonic retrieval aborted");
+        // ponytail: atomic last-writer-wins cache; contention can repeat a walk, not lose sources.
+        await writeJsonFileAtomic(cachePath, {
+          rebuiltAt, corpusVersion,
+          entries: [...cache].slice(-MAX_CACHE_ENTRIES).map(([id, entry]) => [id, entry.path, entry.expiresAt]),
+        });
+      }
+    } catch {
+      throwIfAborted(abortSignal, "harmonic retrieval aborted");
+      // Cache publication is optional; resolved memories remain usable on a read-only store.
+    }
+  }
+  return found;
+}

package/src/memory-projection-batch.ts

@@ -1,4 +1,6 @@
+import path from "node:path";
 import type { MemoryProjectionCurrentState } from "./types.js";
+import { isRecord } from "./store-contract.js";
 import {
   memoryCurrentSelectExpressions,
   openProjectionReadonly,
@@ -80,3 +82,21 @@ export function readProjectedMemoryStates(
     db.close();
   }
 }
+
+/** Path-only census used to avoid parsing already-projected files during a fallback lookup. */
+export function readProjectedMemoryPaths(memoryDir: string): Set<string> | null {
+  const db = openProjectionReadonly(memoryDir);
+  if (!db) return null;
+  try {
+    const paths = new Set<string>();
+    for (const row of db.prepare("SELECT path_rel FROM memory_current").iterate()) {
+      const relative = isRecord(row) ? row.path_rel : undefined;
+      if (typeof relative === "string") paths.add(path.resolve(memoryDir, relative));
+    }
+    return paths;
+  } catch {
+    return null;
+  } finally {
+    db.close();
+  }
+}

package/src/orchestration/recall-internal.ts

@@ -3648,18 +3648,6 @@ export class RecallInternalCoordinator {
       this.deps.appendRecallSection(sectionBuckets, "trust-zones", trustZoneSection);
     }
 
-    const harmonicRetrievalSection = await awaitEnrichmentSection(
-      "harmonic",
-      harmonicRetrievalPromise,
-    );
-    if (harmonicRetrievalSection) {
-      this.deps.appendRecallSection(
-        sectionBuckets,
-        "harmonic-retrieval",
-        harmonicRetrievalSection,
-      );
-    }
-
     if (verifiedRecallSection) {
       this.deps.appendRecallSection(
         sectionBuckets,
@@ -4780,6 +4768,18 @@ export class RecallInternalCoordinator {
       }
     }
     const phase2AfterQmdMs = Date.now() - recallStart;
+
+    const harmonicRetrievalSection = await awaitEnrichmentSection(
+      "harmonic",
+      harmonicRetrievalPromise,
+    );
+    if (harmonicRetrievalSection) {
+      this.deps.appendRecallSection(
+        sectionBuckets,
+        "harmonic-retrieval",
+        harmonicRetrievalSection,
+      );
+    }
     if (shouldPersistGraphSnapshot) {
       if (!graphSnapshotStatus) {
         graphSnapshotStatus = "skipped";