@remnic/core 9.7.8 → 9.7.9

package/dist/verified-recall.js

@@ -1,38 +1,40 @@
 import {
   compareVerifiedEpisodeResults,
   searchVerifiedEpisodes
-} from "./chunk-R2SJDIPO.js";
+} from "./chunk-KPXAJ77O.js";
 import "./chunk-2A3OXAP2.js";
 import "./chunk-ZBJMUXZH.js";
-import "./chunk-KTOH7EJE.js";
+import "./chunk-PV7E2FGY.js";
 import "./chunk-B3ABVQ36.js";
 import "./chunk-L2B3EE7B.js";
 import "./chunk-5UZXUTVO.js";
 import "./chunk-VSMRDBFT.js";
+import "./chunk-LTJAMRGI.js";
 import "./chunk-EHK6KZHK.js";
 import "./chunk-6CIAGZ6X.js";
 import "./chunk-J6A3CX5N.js";
 import "./chunk-4KJLYTLS.js";
 import "./chunk-SVOZFLIQ.js";
-import "./chunk-LTJAMRGI.js";
-import "./chunk-JO5AT6QT.js";
-import "./chunk-RHOZ5LLO.js";
-import "./chunk-RL6NEVXT.js";
-import "./chunk-AWJ2FHCF.js";
-import "./chunk-42JKGUFJ.js";
+import "./chunk-3ZVFLMFQ.js";
 import "./chunk-RULE4VG5.js";
 import "./chunk-SCU65EZI.js";
+import "./chunk-RHOZ5LLO.js";
+import "./chunk-RL6NEVXT.js";
 import "./chunk-DM2T26WE.js";
 import "./chunk-LDXUBPMO.js";
-import "./chunk-LKT755LP.js";
+import "./chunk-VA4WSW54.js";
 import "./chunk-AAD2ZS6P.js";
 import "./chunk-G7D6GZ5J.js";
-import "./chunk-VF4XKTX3.js";
+import "./chunk-VZ5OJE4X.js";
+import "./chunk-OKUEZOGW.js";
+import "./chunk-X47LWMKA.js";
+import "./chunk-42JKGUFJ.js";
+import "./chunk-PDJTHRAW.js";
 import "./chunk-W5H6ZRPT.js";
-import "./chunk-GKCCHHZK.js";
+import "./chunk-UXKMMNJD.js";
 import "./chunk-K2ZLHESQ.js";
-import "./chunk-L2EXJQJP.js";
 import "./chunk-VFSP73LP.js";
+import "./chunk-L2EXJQJP.js";
 import "./chunk-RGMVMVMF.js";
 import "./chunk-N7RWREIQ.js";
 import "./chunk-OEHCMALU.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/core",
-  "version": "9.7.8",
+  "version": "9.7.9",
   "description": "Framework-agnostic Remnic memory engine — orchestrator, storage, extraction, search, trust zones",
   "type": "module",
   "main": "dist/index.js",
@@ -1090,6 +1090,16 @@
       "remnic-source": "./src/importance.ts",
       "import": "./dist/importance.js"
     },
+    "./in-flight-reads": {
+      "types": "./dist/in-flight-reads.d.ts",
+      "remnic-source": "./src/in-flight-reads.ts",
+      "import": "./dist/in-flight-reads.js"
+    },
+    "./in-flight-reads.js": {
+      "types": "./dist/in-flight-reads.d.ts",
+      "remnic-source": "./src/in-flight-reads.ts",
+      "import": "./dist/in-flight-reads.js"
+    },
     "./index": {
       "types": "./dist/index.d.ts",
       "remnic-source": "./src/index.ts",
@@ -3000,7 +3010,7 @@
     "core"
   ],
   "peerDependencies": {
-    "@remnic/coding-graph": "^9.7.8"
+    "@remnic/coding-graph": "^9.7.9"
   },
   "peerDependenciesMeta": {
     "@remnic/coding-graph": {

package/src/binary-lifecycle/pipeline.ts

@@ -18,6 +18,21 @@ import type {
 import type { BinaryStorageBackend } from "./backend.js";
 import { readManifest, writeManifest } from "./manifest.js";
 import { scanForBinaries } from "./scanner.js";
+import { bumpMemoryCorpusVersionForDir } from "../memory-corpus-version.js";
+import { RECALL_FALLBACK_DIRS } from "../utils/category-dir.js";
+
+/**
+ * True when `mdPath` is an active recall-corpus memory file under `memoryDir`
+ * (a top-level RECALL_FALLBACK_DIRS category), so a redirect rewrite of it must
+ * bump the corpus sentinel to self-heal a warm hot-memories cache (#1902).
+ * entities/, artifacts/, and other non-recall paths need no bump.
+ */
+function isRecallCorpusMarkdown(mdPath: string, memoryDir: string): boolean {
+  const rel = path.relative(memoryDir, mdPath);
+  if (rel.startsWith("..") || path.isAbsolute(rel)) return false;
+  const top = rel.split(path.sep)[0];
+  return (RECALL_FALLBACK_DIRS as readonly string[]).includes(top);
+}
 
 /** Minimal logger interface so we don't depend on the full logger module. */
 interface PipelineLogger {
@@ -305,6 +320,13 @@ async function stageRedirect(
     for (const update of updates) {
       try {
         await writeMarkdownFile(update.mdPath, update.content);
+        // The redirect rewrote an on-disk memory file out-of-band (not through a
+        // StorageManager mutation). Bump the corpus sentinel per write so a warm
+        // hot-memories cache rescans — mid-batch too, never serving pre-redirect
+        // content (#1902). Only recall-corpus files affect that cache.
+        if (isRecallCorpusMarkdown(update.mdPath, memoryDir)) {
+          bumpMemoryCorpusVersionForDir(memoryDir);
+        }
       } catch (err) {
         writeFailCount++;
         const msg = `redirect write failed for ${update.mdPath}: ${err instanceof Error ? err.message : String(err)}`;

package/src/cli.ts

@@ -10,6 +10,7 @@ import { resolveNamespaceCapabilities,
   resolveIdentityContinuityCapabilities,
   resolveSecurityCapabilities, resolveEvalCapabilities, resolveConsolidationCapabilities, resolveRecallAuxiliaryCapabilities } from "./capabilities.js";
 import { ThreadingManager } from "./threading.js";
+import { bumpMemoryCorpusVersionForDir } from "./memory-corpus-version.js";
 import { utcDayRange } from "./transcript.js";
 import { runWearablesCliCommand } from "./wearables/cli.js";
 import { registerResearchStatusCommands } from "./cli/research-status-commands.js";
@@ -7495,6 +7496,11 @@ export function registerCli(
             try {
               await unlink(filePath);
               deleted += 1;
+              // Per-delete corpus bump (Cursor Medium, #1902): dedupe removes
+              // active memory files directly (bypassing StorageManager), so bump
+              // each delete to keep a same-process or peer readAllMemories from
+              // recalling a duplicate that was already removed mid-batch.
+              bumpMemoryCorpusVersionForDir(memoryDir);
             } catch (err) {
               console.log(`  failed to delete ${filePath}: ${String(err)}`);
             }
@@ -7556,6 +7562,8 @@ export function registerCli(
             try {
               await unlink(filePath);
               deleted += 1;
+              // Per-delete corpus bump (Cursor Medium, #1902) — see dedupe-exact.
+              bumpMemoryCorpusVersionForDir(memoryDir);
             } catch (err) {
               console.log(`  failed to delete ${filePath}: ${String(err)}`);
             }

package/src/compounding/engine.ts

@@ -321,7 +321,15 @@ function normalizePromotionWhitespace(value: string): string {
 }
 
 function stripTrailingPromotionPunctuation(value: string): string {
-  return value.replace(/[,:;]+$/g, "").trim();
+  // Linear trailing-punctuation strip (no `/[,:;]+$/` — CodeQL flags that as a
+  // polynomial-backtracking ReDoS on long runs of ',;:'). Walk back once, O(n).
+  let end = value.length;
+  while (end > 0) {
+    const ch = value[end - 1];
+    if (ch === "," || ch === ":" || ch === ";") end--;
+    else break;
+  }
+  return value.slice(0, end).trim();
 }
 
 function extractExplicitIfThenRule(value: string): string | null {

package/src/config.ts

@@ -2106,6 +2106,20 @@ export function parseConfig(
     // opt out with recallMemoryWorthFilterEnabled=false.
     recallMemoryWorthFilterEnabled:
       coerceBool(cfg.recallMemoryWorthFilterEnabled) ?? true,
+    // Hot-memories result cache (issue #1902). Default on: readAllMemories()
+    // serves from the version-keyed in-process corpus cache. coerceBool
+    // handles "false"/"0" string forms; set false to force disk scans.
+    hotMemoriesCacheEnabled: coerceBool(cfg.hotMemoriesCacheEnabled) ?? true,
+    // External-edit safety net (issue #1902): the version sentinel gives
+    // immediate coherence for cooperating writers, but direct user/git/editor
+    // writes to memory files (which the project supports) don't bump it. Bound
+    // the hot cache's staleness with a TTL so such edits self-heal. Default 60s;
+    // 0 disables the TTL (version invalidation only — max perf for pure-daemon
+    // deployments with no external edits). coerceNumber handles string forms.
+    hotMemoriesCacheTtlMs: (() => {
+      const n = coerceNumber(cfg.hotMemoriesCacheTtlMs);
+      return n !== undefined && n >= 0 ? n : 60_000;
+    })(),
     recallMemoryWorthHalfLifeMs: (() => {
       const n = coerceNumber(cfg.recallMemoryWorthHalfLifeMs);
       return n !== undefined && n >= 0 ? n : 0;

package/src/consolidation-undo.ts

@@ -25,6 +25,7 @@ import { mkdir, writeFile, access, realpath, lstat } from "node:fs/promises";
 import { constants as fsConstants } from "node:fs";
 import type { StorageManager } from "./storage.js";
 import type { VersioningConfig } from "./page-versioning.js";
+import { bumpMemoryCorpusVersionForDir } from "./memory-corpus-version.js";
 import { getVersion } from "./page-versioning.js";
 
 /**
@@ -646,6 +647,13 @@ export async function runConsolidationUndo(options: {
         // write fails with EEXIST instead of silently overwriting the new
         // file (PR #637 round-11 review, codex P1).
         await writeFile(p.sourcePath, p.content, { encoding: "utf-8", flag: "wx" });
+        // Restore writes an active memory file back out-of-band (direct wx write,
+        // not a StorageManager mutation). Bump the corpus sentinel per successful
+        // restore so a warm hot-memories cache rescans — a later restore failure
+        // returns before archiveMemory() runs, so without this the already-written
+        // restores would stay invisible to recall until an unrelated mutation or
+        // restart (esp. with hotMemoriesCacheTtlMs: 0). Issue #1902, Codex Medium.
+        bumpMemoryCorpusVersionForDir(memoryDir);
         result.restores.push({
           entry: p.entry,
           sourcePath: p.sourcePath,

package/src/curation/index.ts

@@ -9,6 +9,7 @@ import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
 import { getCategoryDir, ALL_CATEGORY_DIRS } from "../utils/category-dir.js";
+import { bumpMemoryCorpusVersionForDir } from "../memory-corpus-version.js";
 
 // ── Types ────────────────────────────────────────────────────────────────────
 
@@ -202,6 +203,10 @@ export async function curate(options: CurateOptions): Promise<CurateResult> {
     }
   }
 
+  // Per-statement corpus bumps happen in writeStatement (below) so a
+  // same-process readAllMemories mid-batch never serves a stale/partial corpus
+  // (Cursor Medium, #1902); no after-loop bump needed here.
+
   return {
     statements,
     filesProcessed,
@@ -471,6 +476,10 @@ function writeStatement(stmt: CuratedStatement, memoryDir: string): string {
   const body = `${frontmatter}\n\n${stmt.content}\n`;
 
   fs.writeFileSync(filePath, body);
+  // Bump the corpus sentinel per write (out-of-band create) so a concurrent
+  // same-process readAllMemories rescans and sees this statement immediately,
+  // never a stale/partial corpus mid-batch (Cursor Medium, #1902).
+  bumpMemoryCorpusVersionForDir(memoryDir);
   return filePath;
 }
 

package/src/in-flight-reads.ts

@@ -0,0 +1,63 @@
+import type { MemoryFile } from "./types.js";
+
+/**
+ * In-flight readAllMemories() dedup registry (issue #1902).
+ *
+ * NOT a cache layer — it holds transient per-(directory, secure-store key) scan
+ * promises so temporally-overlapping reads collapse onto ONE disk scan; the slot
+ * is deleted when the promise settles. It lives in its own module (not
+ * memory-cache.ts) so it is not swept by the ALL_CACHE_LAYERS invalidation
+ * contract, yet remains importable by both StorageManager and the out-of-band
+ * corpus-bump helper (memory-corpus-version.ts).
+ *
+ * Keyed by baseDir AND secure-store key identity (Codex P1 / Cursor Medium):
+ * an unlocked manager's decrypted scan must NOT be handed to a locked or
+ * differently-keyed manager for the same dir — that would bypass the keyId
+ * isolation getCachedMemories enforces. Locked/plaintext stores use keyId "".
+ */
+const inFlightReadsByKey = new Map<string, Promise<MemoryFile[]>>();
+
+const DIR_SEP = "\u0000";
+
+function composeKey(baseDir: string, keyId: string): string {
+  return `${baseDir}${DIR_SEP}${keyId}`;
+}
+
+export function getInFlightRead(baseDir: string, keyId = ""): Promise<MemoryFile[]> | undefined {
+  return inFlightReadsByKey.get(composeKey(baseDir, keyId));
+}
+
+export function setInFlightRead(baseDir: string, keyId: string, read: Promise<MemoryFile[]>): void {
+  inFlightReadsByKey.set(composeKey(baseDir, keyId), read);
+}
+
+/**
+ * Delete the in-flight slot for one (baseDir, keyId). When `expected` is given,
+ * only deletes if the slot still holds that exact promise (owner-only clear).
+ */
+export function deleteInFlightRead(
+  baseDir: string,
+  keyId = "",
+  expected?: Promise<MemoryFile[]>,
+): void {
+  const key = composeKey(baseDir, keyId);
+  if (expected === undefined || inFlightReadsByKey.get(key) === expected) {
+    inFlightReadsByKey.delete(key);
+  }
+}
+
+/**
+ * Drop EVERY in-flight slot for `baseDir` across all secure-store identities.
+ * Used by mutations / invalidation / out-of-band corpus bumps: after the corpus
+ * changes, no reader of any key identity may attach to a pre-mutation scan.
+ */
+export function deleteInFlightReadsForDir(baseDir: string): void {
+  const prefix = `${baseDir}${DIR_SEP}`;
+  for (const key of inFlightReadsByKey.keys()) {
+    if (key.startsWith(prefix)) inFlightReadsByKey.delete(key);
+  }
+}
+
+export function clearInFlightReads(): void {
+  inFlightReadsByKey.clear();
+}

package/src/maintenance/memory-governance.ts

@@ -4,6 +4,7 @@ import { StorageManager } from "../storage.js";
 import { decideLifecycleTransition } from "../lifecycle.js";
 import type { MemoryFile, MemoryStatus } from "../types.js";
 import { RECALL_FALLBACK_DIRS } from "../utils/category-dir.js";
+import { bumpMemoryCorpusVersionForDir } from "../memory-corpus-version.js";
 import { assertPathInsideRoot } from "../utils/path-containment.js";
 
 export type MemoryGovernanceMode = "shadow" | "apply";
@@ -1015,6 +1016,11 @@ export async function restoreMemoryGovernanceRun(
     await mkdir(path.dirname(entry.originalPath), { recursive: true });
     await writeFile(entry.originalPath, entry.beforeRaw, "utf-8");
     restoredActions += 1;
+    // Restore writes/removes memory files directly (out-of-band — not through a
+    // StorageManager mutation). Bump the corpus sentinel PER entry so a
+    // same-process or peer readAllMemories rescans mid-batch and never serves a
+    // partially-restored corpus (Cursor Medium, #1902).
+    bumpMemoryCorpusVersionForDir(options.memoryDir);
   }
 
   return {

package/src/memory-cache-hot.test.ts

@@ -0,0 +1,131 @@
+/**
+ * Issue #1902 — unit tests for the hot-memories result cache layer.
+ *
+ * These pin the low-level cache contract that StorageManager.readAllMemories()
+ * relies on: version-keyed round-trip, the version-0 and version-mismatch null
+ * guards, in-place patch-on-write / patch-on-delete, and the two invalidation
+ * shapes (wholesale drop vs derived/global-only keep).
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  clearMemoryCache,
+  getCachedMemories,
+  invalidateAllForDir,
+  invalidateDerivedAndGlobalForDir,
+  setCachedMemories,
+  updateCacheOnDelete,
+  updateCacheOnWrite,
+} from "./memory-cache.js";
+import type { MemoryFile } from "./types.js";
+
+function mem(p: string, content = "x"): MemoryFile {
+  return {
+    path: p,
+    frontmatter: { id: p, category: "fact" },
+    content,
+  } as unknown as MemoryFile;
+}
+
+test("hot cache: round-trips at a matching version", () => {
+  const dir = "/tmp/remnic-hot-unit-a";
+  clearMemoryCache();
+  setCachedMemories(dir, [mem("a.md"), mem("b.md")], 3);
+  const got = getCachedMemories(dir, 3);
+  assert.ok(got, "expected a cache hit at the matching version");
+  assert.deepEqual(got!.map((m) => m.path).sort(), ["a.md", "b.md"]);
+  clearMemoryCache();
+});
+
+test("hot cache: version 0 always misses (fresh/test dirs)", () => {
+  const dir = "/tmp/remnic-hot-unit-b";
+  clearMemoryCache();
+  setCachedMemories(dir, [mem("a.md")], 0);
+  assert.equal(getCachedMemories(dir, 0), null, "version 0 must never serve a cache hit");
+  clearMemoryCache();
+});
+
+test("hot cache: version mismatch misses (never serves stale)", () => {
+  const dir = "/tmp/remnic-hot-unit-c";
+  clearMemoryCache();
+  setCachedMemories(dir, [mem("a.md")], 5);
+  assert.ok(getCachedMemories(dir, 5), "same version hits");
+  assert.equal(getCachedMemories(dir, 6), null, "a bumped version must miss");
+  clearMemoryCache();
+});
+
+test("hot cache: updateCacheOnWrite / updateCacheOnDelete mutate the entry in place", () => {
+  const dir = "/tmp/remnic-hot-unit-d";
+  clearMemoryCache();
+  setCachedMemories(dir, [mem("a.md")], 2);
+  updateCacheOnWrite(dir, mem("b.md", "new"));
+  const afterWrite = getCachedMemories(dir, 2);
+  assert.deepEqual(afterWrite!.map((m) => m.path).sort(), ["a.md", "b.md"], "write adds in place");
+  updateCacheOnWrite(dir, mem("a.md", "updated"));
+  assert.equal(
+    getCachedMemories(dir, 2)!.find((m) => m.path === "a.md")!.content,
+    "updated",
+    "write to an existing path replaces in place",
+  );
+  updateCacheOnDelete(dir, "a.md");
+  assert.deepEqual(getCachedMemories(dir, 2)!.map((m) => m.path), ["b.md"], "delete removes in place");
+  clearMemoryCache();
+});
+
+test("hot cache: wholesale invalidateAllForDir drops the hot layer; invalidateDerivedAndGlobalForDir keeps it", () => {
+  const dir = "/tmp/remnic-hot-unit-e";
+  clearMemoryCache();
+  setCachedMemories(dir, [mem("a.md")], 4);
+  invalidateDerivedAndGlobalForDir(dir);
+  assert.ok(
+    getCachedMemories(dir, 4),
+    "invalidateDerivedAndGlobalForDir must NOT drop the hot layer (patch-on-write keeps it warm)",
+  );
+  invalidateAllForDir(dir);
+  assert.equal(getCachedMemories(dir, 4), null, "invalidateAllForDir must drop the hot layer");
+  clearMemoryCache();
+});
+
+test("hot cache: keyId scopes entries — a mismatched secure-store key misses (#1902 Codex P1)", () => {
+  const dir = "/tmp/remnic-hot-unit-keyid";
+  clearMemoryCache();
+  // A keyed (unlocked encrypted) manager warms the cache with decrypted content.
+  setCachedMemories(dir, [mem("secret.md", "decrypted")], 5, "secure-store:key:1");
+  // A locked/unkeyed manager for the SAME dir must NOT read the decrypted entry.
+  assert.equal(
+    getCachedMemories(dir, 5, ""),
+    null,
+    "a manager without the matching key must miss the decrypted cache entry",
+  );
+  // A different key id also misses.
+  assert.equal(getCachedMemories(dir, 5, "secure-store:key:2"), null, "a different key id misses");
+  // The matching key id hits.
+  const got = getCachedMemories(dir, 5, "secure-store:key:1");
+  assert.ok(got, "the matching key id serves the cached corpus");
+  assert.deepEqual(got!.map((m) => m.path), ["secret.md"]);
+  clearMemoryCache();
+});
+
+test("hot cache: TTL expires an entry so external edits self-heal (#1902 Codex P1)", (t) => {
+  const dir = "/tmp/remnic-hot-unit-ttl";
+  clearMemoryCache();
+  // Deterministic time control (no real timers): the entry's loadedAt is stamped
+  // from the mocked clock at set time; advancing it past the TTL forces a miss.
+  t.mock.timers.enable({ apis: ["Date"] });
+  try {
+    setCachedMemories(dir, [mem("a.md")], 9, "");
+    // ttl=0 disables the TTL: always a hit at the matching version.
+    assert.ok(getCachedMemories(dir, 9, "", 0), "ttl=0 disables expiry");
+    // Fresh entry within a generous TTL still hits.
+    assert.ok(getCachedMemories(dir, 9, "", 60_000), "fresh entry within TTL hits");
+    // Advance past the TTL: the entry is now a miss, forcing a rescan that would
+    // pick up any external filesystem edit that bypassed the version sentinel.
+    t.mock.timers.tick(120_000);
+    assert.equal(getCachedMemories(dir, 9, "", 60_000), null, "entry older than ttl is a miss");
+  } finally {
+    t.mock.timers.reset();
+    clearMemoryCache();
+  }
+});