@remnic/core 9.7.8 → 9.7.10

package/src/page-versioning.ts

@@ -25,7 +25,8 @@ import {
   writeFile,
   unlink,
 } from "node:fs/promises";
-import { ALL_CATEGORY_DIRS } from "./utils/category-dir.js";
+import { ALL_CATEGORY_DIRS, RECALL_FALLBACK_DIRS } from "./utils/category-dir.js";
+import { bumpMemoryCorpusVersionForDir } from "./memory-corpus-version.js";
 
 // ---------------------------------------------------------------------------
 // Public interfaces
@@ -332,6 +333,18 @@ export async function revertToVersion(
 
   // Write the reverted content to the actual page
   await writeFile(pagePath, targetContent, "utf-8");
+  // A revert overwrites a memory file out-of-band (not via a StorageManager
+  // mutation), so bump the corpus sentinel when the reverted page lives under a
+  // recall category dir — forcing a warm hot-memories cache to rescan on its
+  // next read (issue #1902, Codex P1). Non-recall pages (entities/artifacts/
+  // profiles) are not in the corpus scan, so they need no bump.
+  // The hot-memories corpus covers the RECALL corpus, which excludes the
+  // non-memory queue dirs (questions/). Use RECALL_FALLBACK_DIRS — a revert of a
+  // questions/ page must NOT bump the recall corpus sentinel and force a rescan.
+  const revertedTop = relPath(pagePath, resolvedMemoryDir).split(path.sep)[0];
+  if ((RECALL_FALLBACK_DIRS as readonly string[]).includes(revertedTop)) {
+    bumpMemoryCorpusVersionForDir(resolvedMemoryDir);
+  }
   log.debug(`page-versioning: reverted ${pagePath} to version ${versionId}`);
 
   return version;

package/src/provenance-frontmatter.test.ts

@@ -5,6 +5,7 @@ import path from "node:path";
 import { mkdtemp, mkdir, rm, writeFile, readFile } from "node:fs/promises";
 
 import { StorageManager } from "./storage.js";
+import { clearMemoryCache } from "./memory-cache.js";
 import type { ProvenanceSource } from "./types.js";
 
 /**
@@ -64,6 +65,11 @@ async function writeFactFile(
   const factsDir = path.join((storage as unknown as { baseDir: string }).baseDir, "facts", today);
   await mkdir(factsDir, { recursive: true });
   await writeFile(path.join(factsDir, `${id}.md`), `${lines.join("\n")}\n\n${body}\n`, "utf-8");
+  // This is an out-of-band write (bypasses StorageManager.writeMemory), so it
+  // must invalidate the version-keyed hot-memories cache (issue #1902) — drop
+  // every cache layer for this dir via the exported chokepoint so the next
+  // readAllMemories() rescans disk and sees this file (matches the harness seam).
+  clearMemoryCache(storage.dir);
   return id;
 }
 

package/src/review/index.ts

@@ -8,6 +8,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { getCategoryDir, ALL_CATEGORY_DIRS } from "../utils/category-dir.js";
+import { bumpMemoryCorpusVersionForDir } from "../memory-corpus-version.js";
 
 // ── Types ────────────────────────────────────────────────────────────────────
 
@@ -259,14 +260,21 @@ export function performReview(
   action: ReviewAction,
   options: ReviewActionOptions = {},
 ): ReviewResult {
-  switch (action) {
-    case "approve":
-      return approveItem(memoryDir, itemId, options);
-    case "dismiss":
-      return dismissItem(memoryDir, itemId, options);
-    case "flag":
-      return flagItem(memoryDir, itemId, options);
-  }
+  const result =
+    action === "approve"
+      ? approveItem(memoryDir, itemId, options)
+      : action === "dismiss"
+        ? dismissItem(memoryDir, itemId, options)
+        : flagItem(memoryDir, itemId, options);
+  // Review approval/dismissal/flagging edits, moves, or removes memory files
+  // directly (out-of-band — it does not go through a StorageManager mutation
+  // method), so bump the corpus sentinel to force the version-keyed hot cache
+  // to rescan on its next read (issue #1902). Only bump when a file was
+  // actually modified/moved (updatedPath set) — no-op early returns (item not
+  // found, unparsable frontmatter) must not advance the sentinel or needlessly
+  // clear caches (Cursor Medium).
+  if (result.updatedPath !== undefined) bumpMemoryCorpusVersionForDir(memoryDir);
+  return result;
 }
 
 // ── Actions ──────────────────────────────────────────────────────────────────

package/src/semantic-rule-promotion.ts

@@ -498,7 +498,15 @@ function normalizeRuleWhitespace(value: string): string {
 }
 
 function stripTrailingClausePunctuation(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 canonicalizeRuleContent(value: string): string {

package/src/semantic-rule-verifier.ts

@@ -116,18 +116,31 @@ export async function searchVerifiedSemanticRules(options: {
   query: string;
   maxResults: number;
   minEffectiveConfidence?: number;
+  /** Hot-memories cache gate (issue #1902, Codex P2). Threaded from the caller
+   *  so a named-namespace root (never registered in the per-dir default map)
+   *  honors the owning daemon's config instead of the process-wide default. */
+  hotMemoriesCacheEnabled?: boolean;
 }): Promise<VerifiedSemanticRuleResult[]> {
   const queryTokens = new Set(normalizeRecallTokens(options.query, ["what", "which"]));
   if (queryTokens.size === 0 || options.maxResults <= 0) return [];
 
-  const storage = new StorageManager(options.memoryDir);
-  const version = storage.getMemoryStatusVersion();
-
-  // Use derived rule cache to avoid O(146K) iteration on every call.
-  let cachedRules = getCachedRuleMemories(storage.dir, version);
+  const storage = new StorageManager(options.memoryDir, undefined, options.hotMemoriesCacheEnabled);
+  // Key the derived rule cache on the CORPUS version, not memory-status (Codex
+  // P1, #1902): rule memories are derived from the full corpus, and plain
+  // creates/writeChunk bump only the corpus sentinel. Keying on memory-status
+  // would let a peer process serve a stale rule set that omits newly created
+  // rule memories.
+  const version = storage.getMemoryCorpusVersion();
+
+  // Use derived rule cache to avoid O(146K) iteration on every call — but honor
+  // the hotMemoriesCacheEnabled opt-out (Codex P2): when disabled, never read or
+  // retain the derived cache, always rebuild from a fresh scan.
+  const cacheEnabled = storage.isHotCacheEnabled();
+  const keyId = storage.hotCacheKeyId();
+  let cachedRules = cacheEnabled ? getCachedRuleMemories(storage.dir, version, keyId, storage.hotCacheTtlMs()) : null;
   if (!cachedRules) {
     const allMems = await storage.readAllMemories();
-    cachedRules = setCachedRuleMemories(storage.dir, allMems, version);
+    cachedRules = setCachedRuleMemories(storage.dir, allMems, version, cacheEnabled, keyId);
   }
   const { all: ruleMemories, byId: memoryById } = cachedRules;
   const minEffectiveConfidence = options.minEffectiveConfidence ?? DEFAULT_MIN_EFFECTIVE_CONFIDENCE;

package/src/spaces/index.ts

@@ -13,6 +13,7 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { readEnvVar, resolveHomeDir } from "../runtime/env.js";
+import { bumpMemoryCorpusVersionForDir } from "../memory-corpus-version.js";
 
 // ── Types ────────────────────────────────────────────────────────────────────
 
@@ -935,6 +936,15 @@ function copyMemories(
     }
     fs.writeFileSync(targetPath, content);
     merged++;
+    // Bump the target's corpus sentinel per write (out-of-band — not through a
+    // StorageManager mutation), on the CANONICAL root (targetRoot), matching
+    // where files were written and where a StorageManager resolves its
+    // version/cache keys. Per-write (not once after the loop) so a warm
+    // hot-memories cache for the target rescans MID-batch and never serves the
+    // pre-copy corpus while copies are still landing (#1902; a symlinked target
+    // would otherwise diverge, and a once-after bump leaves in-batch reads
+    // stale).
+    bumpMemoryCorpusVersionForDir(targetRoot);
   }
 
   return { merged, conflicts, skipped };

package/src/storage/memory-read-store.ts

@@ -60,6 +60,8 @@ export interface MemoryReadStoreDeps {
   readonly proceduresDir: string;
   readonly questionsDir: string;
   readColdWriteVersion(): number;
+  /** Secure-store key identity for keying decrypted-corpus caches (#1902). */
+  hotCacheKeyId(): string;
   readMemoryByPath(filePath: string): Promise<MemoryFile | null>;
   readParsedMemoriesFromPaths(
     filePaths: string[],
@@ -365,10 +367,15 @@ export class MemoryReadStore {
     // stale data for up to 30s when another process wrote a new cold memory.
     const currentColdVersion = this.deps.readColdWriteVersion();
 
-    // Return cached result if still valid by both TTL and sentinel version.
+    // Return cached result if still valid by TTL, sentinel version, AND the
+    // secure-store key identity (issue #1902). readParsedMemoriesFromPaths
+    // decrypts per this manager's key, so a differently-keyed manager must not
+    // read a cold corpus another instance decrypted for the same coldRoot.
+    const keyId = this.deps.hotCacheKeyId();
     const cached = this.deps.storageManagerClass.coldMemoriesCache.get(coldRoot);
     if (
       cached &&
+      cached.keyId === keyId &&
       Date.now() - cached.loadedAt < this.deps.storageManagerClass.COLD_SCAN_CACHE_TTL_MS &&
       cached.coldVersion === currentColdVersion
     ) {
@@ -407,7 +414,7 @@ export class MemoryReadStore {
 
     // Store in cache with the sentinel version captured above so that any
     // subsequent cold-version bump (by this or another process) invalidates it.
-    this.deps.storageManagerClass.coldMemoriesCache.set(coldRoot, { memories, loadedAt: Date.now(), coldVersion: currentColdVersion });
+    this.deps.storageManagerClass.coldMemoriesCache.set(coldRoot, { memories, loadedAt: Date.now(), coldVersion: currentColdVersion, keyId });
     return memories;
   }
 

package/src/storage-contract/cache-coherence.test.ts

@@ -10,6 +10,9 @@
 
 import assert from "node:assert/strict";
 import test from "node:test";
+import { appendFile, mkdtemp, rm, mkdir, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
 
 import { StorageManager } from "../storage.js";
 import { resetStaticCaches } from "./harness.js";
@@ -98,3 +101,242 @@ test("cache-coherence: readAllMemories reflects writes across instances after in
     await rm(dir, { recursive: true, force: true });
   }
 });
+
+type ScanSpy = { _readAllMemoriesFromDisk: () => Promise<unknown> };
+
+function installScanSpy(sm: StorageManager): { scans: () => number } {
+  const spy = sm as unknown as ScanSpy;
+  const orig = spy._readAllMemoriesFromDisk.bind(sm);
+  let count = 0;
+  spy._readAllMemoriesFromDisk = async () => {
+    count += 1;
+    return orig();
+  };
+  return { scans: () => count };
+}
+
+test("hot cache (#1902): a warm readAllMemories() serves without re-scanning disk", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-hot-warm-"));
+  try {
+    resetStaticCaches();
+    const sm = new StorageManager(dir);
+    await sm.ensureDirectories();
+    await sm.writeMemory("fact", "A");
+    await sm.readAllMemories(); // warming scan populates the hot cache
+    const spy = installScanSpy(sm);
+    const warm = await sm.readAllMemories();
+    assert.equal(spy.scans(), 0, "a warm read must not touch disk");
+    assert.ok(warm.some((m) => m.content === "A"));
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("hot cache (#1902): a single-file write patches the cache in place — next read stays warm", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-hot-patch-"));
+  try {
+    resetStaticCaches();
+    const sm = new StorageManager(dir);
+    await sm.ensureDirectories();
+    await sm.writeMemory("fact", "A");
+    await sm.readAllMemories(); // warm
+    const spy = installScanSpy(sm);
+    await sm.writeMemory("fact", "B"); // patch-on-write keeps the entry warm
+    const after = await sm.readAllMemories();
+    assert.equal(spy.scans(), 0, "patch-on-write must keep the cache warm (no rescan)");
+    assert.ok(after.some((m) => m.content === "B"), "the newly written fact is present");
+    assert.ok(after.some((m) => m.content === "A"), "the prior fact survives the patch");
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("hot cache (#1902): a peer corpus-version bump forces exactly one rescan (cross-process coherence)", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-hot-peer-"));
+  try {
+    resetStaticCaches();
+    const sm = new StorageManager(dir);
+    await sm.ensureDirectories();
+    await sm.writeMemory("fact", "A");
+    await sm.readAllMemories(); // warm
+    const spy = installScanSpy(sm);
+    // Simulate a peer process advancing the on-disk corpus sentinel (its byte
+    // size IS the version). This instance's warm entry is now stale-versioned.
+    await appendFile(path.join(dir, "state", ".memory-corpus-version.log"), "x");
+    const afterPeer = await sm.readAllMemories();
+    assert.equal(spy.scans(), 1, "a peer sentinel bump must force exactly one rescan");
+    assert.ok(afterPeer.some((m) => m.content === "A"));
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("hot cache (#1902): a delete rescans and drops the removed memory", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-hot-del-"));
+  try {
+    resetStaticCaches();
+    const sm = new StorageManager(dir);
+    await sm.ensureDirectories();
+    const { id } = await sm.writeMemory("fact", "A");
+    await sm.writeMemory("fact", "B");
+    await sm.readAllMemories(); // warm
+    await sm.invalidateMemory(id); // delete drops the hot layer wholesale
+    const after = await sm.readAllMemories();
+    assert.ok(after.some((m) => m.content === "B"), "surviving memory remains");
+    assert.ok(!after.some((m) => m.content === "A"), "the deleted memory is gone");
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("hot cache (#1902/#1904 compat): a plain fact create does NOT bump memory-status (entity cache stays warm)", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-hot-status-"));
+  try {
+    resetStaticCaches();
+    const sm = new StorageManager(dir);
+    await sm.ensureDirectories();
+    await sm.writeMemory("fact", "seed"); // establish the state dir + baseline
+    const before = sm.getMemoryStatusVersion();
+    await sm.writeMemory("fact", "another create");
+    assert.equal(
+      sm.getMemoryStatusVersion(),
+      before,
+      "a plain fact create must not bump memory-status (the entity cache keys on it)",
+    );
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("hot cache (#1902): hotMemoriesCacheEnabled=false forces every read to rescan", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-hot-off-"));
+  try {
+    resetStaticCaches();
+    const sm = new StorageManager(dir, undefined, false); // gate off
+    await sm.ensureDirectories();
+    await sm.writeMemory("fact", "A");
+    const spy = installScanSpy(sm);
+    await sm.readAllMemories();
+    await sm.readAllMemories();
+    assert.equal(spy.scans(), 2, "with the cache disabled, each sequential read scans disk");
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("hot cache (#1902): the gate default is isolated per memory dir (Codex P2)", async () => {
+  const dirOff = await mkdtemp(path.join(os.tmpdir(), "remnic-hot-perdir-off-"));
+  const dirOn = await mkdtemp(path.join(os.tmpdir(), "remnic-hot-perdir-on-"));
+  try {
+    resetStaticCaches();
+    // Register divergent per-dir settings; a later registration must NOT flip
+    // an earlier dir's behavior (the "last orchestrator wins" bug).
+    StorageManager.setHotMemoriesCacheDefault(dirOff, false);
+    StorageManager.setHotMemoriesCacheDefault(dirOn, true);
+    // Constructed WITHOUT a per-instance override, so each resolves its own
+    // dir's registered default.
+    const smOff = new StorageManager(dirOff);
+    const smOn = new StorageManager(dirOn);
+    await smOff.ensureDirectories();
+    await smOff.writeMemory("fact", "A");
+    await smOn.ensureDirectories();
+    await smOn.writeMemory("fact", "B");
+    const spyOff = installScanSpy(smOff);
+    const spyOn = installScanSpy(smOn);
+    await smOff.readAllMemories();
+    await smOff.readAllMemories();
+    await smOn.readAllMemories();
+    await smOn.readAllMemories();
+    assert.equal(spyOff.scans(), 2, "dir registered false rescans on every read");
+    assert.equal(spyOn.scans(), 1, "dir registered true serves the second read from cache");
+  } finally {
+    resetStaticCaches();
+    await rm(dirOff, { recursive: true, force: true });
+    await rm(dirOn, { recursive: true, force: true });
+  }
+});
+
+test("hot cache (#1902): flushAccessTracking patches locally + bumps for cross-process coherence", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-hot-access-"));
+  try {
+    resetStaticCaches();
+    const sm = new StorageManager(dir);
+    await sm.ensureDirectories();
+    const { id } = await sm.writeMemory("fact", "trackable");
+    // Warm the cache.
+    const warm = await sm.readAllMemories();
+    assert.equal(warm.length, 1);
+    const versionBefore = sm.getMemoryCorpusVersion();
+    const spy = installScanSpy(sm);
+    await sm.flushAccessTracking([
+      { memoryId: id, newCount: 7, lastAccessed: "2026-07-16T00:00:00.000Z" },
+    ]);
+    const after = await sm.readAllMemories();
+    // Local process: patched in place + re-keyed, so no rescan and fresh counts.
+    assert.equal(spy.scans(), 0, "access-tracking flush must not rescan the corpus locally");
+    const m = after.find((x) => x.frontmatter.id === id);
+    assert.equal(m?.frontmatter.accessCount, 7, "hot cache reflects the flushed access count");
+    assert.equal(m?.frontmatter.lastAccessed, "2026-07-16T00:00:00.000Z");
+    // Cross-process: the shared sentinel advanced so peer processes rescan and
+    // never overwrite this process's increment (Codex P2).
+    assert.ok(
+      sm.getMemoryCorpusVersion() > versionBefore,
+      "access-tracking flush advances the corpus sentinel for peer coherence",
+    );
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("hot cache (#1902): ensureDirectories activates a version-0 corpus so reads cache (Cursor Medium)", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-hot-zero-"));
+  try {
+    resetStaticCaches();
+    // Simulate an existing corpus with NO sentinel yet: write a fact file
+    // directly to disk (bypassing StorageManager, so nothing bumps the sentinel).
+    await mkdir(path.join(dir, "facts"), { recursive: true });
+    await writeFile(path.join(dir, "facts", "a.md"), "---\nid: fact-a\n---\nA");
+    const sm = new StorageManager(dir);
+    assert.equal(sm.getMemoryCorpusVersion(), 0, "precondition: sentinel starts at 0");
+    // The daemon calls ensureDirectories() at startup (before serving reads); it
+    // seeds a nonzero sentinel so the hot path engages on a read-heavy workload.
+    await sm.ensureDirectories();
+    assert.ok(sm.getMemoryCorpusVersion() > 0, "ensureDirectories activates the sentinel");
+    const spy = installScanSpy(sm);
+    const first = await sm.readAllMemories();
+    assert.equal(first.length, 1);
+    await sm.readAllMemories();
+    assert.equal(spy.scans(), 1, "second read is served from cache — activation worked");
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("hot cache (#1902): an empty corpus is served from cache, not rescanned (kilo null-check)", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-hot-empty-"));
+  try {
+    resetStaticCaches();
+    const sm = new StorageManager(dir);
+    // ensureDirectories activates the sentinel (version > 0); the corpus is empty.
+    await sm.ensureDirectories();
+    const first = await sm.readAllMemories();
+    assert.equal(first.length, 0, "corpus is empty");
+    const spy = installScanSpy(sm);
+    await sm.readAllMemories();
+    await sm.readAllMemories();
+    // getCachedMemories returns [] (falsy) for an empty corpus; the read guard
+    // must null-check, not truthiness-check, or every read rescans.
+    assert.equal(spy.scans(), 0, "empty corpus is served from cache on repeat reads");
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});

package/src/storage-contract/namespace-routing.test.ts

@@ -18,9 +18,10 @@ import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import test from "node:test";
 
-import { makeStorage, makeNamespaceRouter } from "./harness.js";
+import { makeStorage, makeNamespaceRouter, resetStaticCaches } from "./harness.js";
 import { resolveNamespaceStorageRoot } from "../namespaces/storage.js";
 import { namespaceIdentityToken } from "../namespaces/identity.js";
+import { getCachedMemories } from "../memory-cache.js";
 
 test("namespace-routing: default namespace resolves to the legacy memoryDir root", async () => {
   const { router, memoryDir, config, cleanup } = await makeNamespaceRouter();
@@ -133,3 +134,27 @@ test("namespace-routing: router caches StorageManager per namespace (same instan
     await cleanup();
   }
 });
+
+test("namespace-routing: hotMemoriesCacheEnabled=false propagates to namespace child storages (#1902 Codex P2)", async () => {
+  const { router, config, cleanup } = await makeNamespaceRouter({ hotMemoriesCacheEnabled: false });
+  try {
+    resetStaticCaches();
+    const sm = await router.storageFor("team-alpha");
+    await sm.ensureDirectories();
+    await sm.writeMemory("fact", "A");
+    await sm.readAllMemories();
+    await sm.readAllMemories();
+    const root = await resolveNamespaceStorageRoot(config, "team-alpha");
+    // Gate propagated to the child: with caching disabled the child storage
+    // never populates the module-level hot cache, so getCachedMemories stays
+    // null even after reads. Before the fix the child fell back to the
+    // process-wide default (true) and would have cached the corpus.
+    assert.equal(
+      getCachedMemories(root, sm.getMemoryCorpusVersion()),
+      null,
+      "namespace child honors the disabled gate and never caches the corpus",
+    );
+  } finally {
+    await cleanup();
+  }
+});