@remnic/core 9.7.14 → 9.8.0

package/dist/{chunk-NKCPUHCI.js → chunk-WZFAPHIK.js}

@@ -1,15 +1,12 @@
 import {
   topicOverlapScore
-} from "./chunk-2A3OXAP2.js";
+} from "./chunk-B7RWBZXW.js";
 import {
   resolveCausalTrajectoryStoreDir
-} from "./chunk-7XGSIUP5.js";
+} from "./chunk-W4FBGYGK.js";
 import {
   normalizeRecallTokens
 } from "./chunk-ZBJMUXZH.js";
-import {
-  log
-} from "./chunk-37CTGERM.js";
 import {
   assertIsoRecordedAt,
   assertString,
@@ -20,6 +17,9 @@ import {
   listJsonFiles,
   readJsonFile
 } from "./chunk-LPSF4OQH.js";
+import {
+  log
+} from "./chunk-3WCASNQZ.js";
 
 // src/causal-chain.ts
 import { createHash } from "crypto";
@@ -339,4 +339,4 @@ export {
   scoreStitchCandidate,
   stitchCausalChain
 };
-//# sourceMappingURL=chunk-NKCPUHCI.js.map
+//# sourceMappingURL=chunk-WZFAPHIK.js.map

package/dist/{chunk-KQPJLK3X.js → chunk-XL24QQ63.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-U3PN77QT.js";
 import {
   log
-} from "./chunk-37CTGERM.js";
+} from "./chunk-3WCASNQZ.js";
 
 // src/routing/store.ts
 import { lstat, mkdir, readFile, realpath, rename, rm, rmdir, stat, writeFile } from "fs/promises";
@@ -306,4 +306,4 @@ var RoutingRulesStore = class {
 export {
   RoutingRulesStore
 };
-//# sourceMappingURL=chunk-KQPJLK3X.js.map
+//# sourceMappingURL=chunk-XL24QQ63.js.map

package/dist/{chunk-X47LWMKA.js → chunk-XMMESCPD.js}

@@ -145,6 +145,7 @@ var ALL_CACHE_LAYERS = [
   {
     name: "hot-memories",
     scope: "dir",
+    evictOn: { "memory-create": true, "memory-mutate": true, "secure-key-change": true },
     invalidateForDir: (baseDir) => void hotCacheByDir.delete(baseDir),
     clearAll: () => hotCacheByDir.clear(),
     hasEntriesFor: (baseDir) => hotCacheByDir.has(baseDir)
@@ -152,6 +153,7 @@ var ALL_CACHE_LAYERS = [
   {
     name: "archive-memories",
     scope: "dir",
+    evictOn: { "memory-mutate": true, "secure-key-change": true },
     invalidateForDir: (baseDir) => void archiveCacheByDir.delete(baseDir),
     clearAll: () => archiveCacheByDir.clear(),
     hasEntriesFor: (baseDir) => archiveCacheByDir.has(baseDir)
@@ -159,6 +161,7 @@ var ALL_CACHE_LAYERS = [
   {
     name: "entities",
     scope: "dir",
+    evictOn: { "entity-write": true, "secure-key-change": true },
     invalidateForDir: (baseDir) => invalidateCachedEntities(baseDir),
     clearAll: () => entityCacheByDir.clear(),
     hasEntriesFor: (baseDir) => {
@@ -172,6 +175,7 @@ var ALL_CACHE_LAYERS = [
   {
     name: "derived-episode-map",
     scope: "dir",
+    evictOn: { "memory-create": true, "memory-mutate": true, "secure-key-change": true },
     invalidateForDir: (baseDir) => void episodeMapByDir.delete(baseDir),
     clearAll: () => episodeMapByDir.clear(),
     hasEntriesFor: (baseDir) => episodeMapByDir.has(baseDir)
@@ -179,6 +183,7 @@ var ALL_CACHE_LAYERS = [
   {
     name: "derived-rule-memories",
     scope: "dir",
+    evictOn: { "memory-create": true, "memory-mutate": true, "secure-key-change": true },
     invalidateForDir: (baseDir) => void ruleMemoriesByDir.delete(baseDir),
     clearAll: () => ruleMemoriesByDir.clear(),
     hasEntriesFor: (baseDir) => ruleMemoriesByDir.has(baseDir)
@@ -186,6 +191,7 @@ var ALL_CACHE_LAYERS = [
   {
     name: "qmd-search",
     scope: "global",
+    evictOn: { "memory-mutate": true, "entity-write": true, "secure-key-change": true },
     invalidateForDir: () => qmdSearchCache.clear(),
     clearAll: () => qmdSearchCache.clear(),
     hasEntriesFor: () => qmdSearchCache.size > 0
@@ -193,6 +199,7 @@ var ALL_CACHE_LAYERS = [
   {
     name: "qmd-recall",
     scope: "global",
+    evictOn: { "memory-mutate": true, "entity-write": true, "secure-key-change": true },
     invalidateForDir: () => clearQmdRecallCache(),
     clearAll: () => clearQmdRecallCache(),
     hasEntriesFor: () => qmdRecallCacheSize() > 0
@@ -203,6 +210,17 @@ function invalidateAllForDir(baseDir) {
     layer.invalidateForDir(baseDir);
   }
 }
+function invalidateForScope(baseDir, scope) {
+  for (const layer of ALL_CACHE_LAYERS) {
+    if (layer.evictOn[scope]) layer.invalidateForDir(baseDir);
+  }
+}
+function invalidateForScopeExceptHot(baseDir, scope) {
+  for (const layer of ALL_CACHE_LAYERS) {
+    if (layer.name === "hot-memories") continue;
+    if (layer.evictOn[scope]) layer.invalidateForDir(baseDir);
+  }
+}
 function invalidateDerivedAndGlobalForDir(baseDir) {
   for (const layer of ALL_CACHE_LAYERS) {
     if (layer.name === "hot-memories" || layer.name === "entities" || layer.name === "archive-memories") {
@@ -220,6 +238,10 @@ function clearMemoryCache(baseDir) {
     layer.clearAll();
   }
 }
+function clearQmdResultCaches() {
+  qmdSearchCache.clear();
+  clearQmdRecallCache();
+}
 function getMemoryCacheStats(baseDir) {
   const hot = hotCacheByDir.get(baseDir);
   const archive = archiveCacheByDir.get(baseDir);
@@ -249,8 +271,11 @@ export {
   setCachedQmdSearch,
   ALL_CACHE_LAYERS,
   invalidateAllForDir,
+  invalidateForScope,
+  invalidateForScopeExceptHot,
   invalidateDerivedAndGlobalForDir,
   clearMemoryCache,
+  clearQmdResultCaches,
   getMemoryCacheStats
 };
-//# sourceMappingURL=chunk-X47LWMKA.js.map
+//# sourceMappingURL=chunk-XMMESCPD.js.map

package/dist/chunk-XMMESCPD.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/memory-cache.ts"],"sourcesContent":["import type { EntityFile, MemoryFile } from \"./types.js\";\nimport { clearQmdRecallCache, qmdRecallCacheSize } from \"./qmd-recall-cache.js\";\n\ninterface CacheEntry {\n  memories: Map<string, MemoryFile>; // keyed by file path\n  version: number;\n  loadedAt: number;\n  // Secure-store key identity that decrypted these memories (issue #1902, Codex\n  // P1). \"\" for plaintext/locked stores. A manager only reads an entry whose\n  // keyId matches its own, so a locked/unkeyed instance never sees content\n  // another instance decrypted under a key for the same baseDir.\n  keyId: string;\n  // Effective TTL (ms) this entry was stored under (issue #1902, Codex Medium),\n  // so the opportunistic sweep can evict abandoned corpora that are never\n  // revisited. 0 = no TTL (never swept by age).\n  ttlMs: number;\n}\n\n// Module-level singleton — shared across all StorageManager instances and sessions\nconst hotCacheByDir = new Map<string, CacheEntry>();\nconst archiveCacheByDir = new Map<string, CacheEntry>();\n\n/**\n * Evict every hot entry whose own TTL has elapsed (issue #1902, Codex Medium).\n * Called opportunistically on each set so a long-running process that reads many\n * namespace/temporary roots and never revisits some of them still releases their\n * (potentially hundreds-of-MB) corpora within the TTL, instead of holding them\n * resident until an explicit global clear. O(entries) over a small map.\n */\nfunction sweepExpiredHotEntries(now: number): void {\n  for (const [dir, entry] of hotCacheByDir) {\n    if (entry.ttlMs > 0 && now - entry.loadedAt > entry.ttlMs) hotCacheByDir.delete(dir);\n  }\n}\n\nexport function getCachedMemories(\n  baseDir: string,\n  currentVersion: number,\n  keyId = \"\",\n  ttlMs = 0,\n): MemoryFile[] | null {\n  // Don't serve from cache when version tracking is unavailable (version=0).\n  // This ensures tests and fresh installs without a version file always read disk.\n  if (currentVersion === 0) return null;\n  const entry = hotCacheByDir.get(baseDir);\n  if (!entry || entry.version !== currentVersion || entry.keyId !== keyId) return null;\n  // TTL safety net (issue #1902): bound staleness from external filesystem edits\n  // that bypass the version sentinel. ttlMs <= 0 disables the check. On expiry\n  // evict the entry (not just return null) so a revisited-but-stale dir releases\n  // its resident corpus instead of lingering until an explicit clear.\n  if (ttlMs > 0 && Date.now() - entry.loadedAt > ttlMs) {\n    hotCacheByDir.delete(baseDir);\n    return null;\n  }\n  return [...entry.memories.values()];\n}\n\nexport function setCachedMemories(\n  baseDir: string,\n  memories: MemoryFile[],\n  version: number,\n  keyId = \"\",\n  ttlMs = 0,\n): void {\n  const map = new Map<string, MemoryFile>();\n  for (const m of memories) map.set(m.path, m);\n  const now = Date.now();\n  hotCacheByDir.set(baseDir, { memories: map, version, loadedAt: now, keyId, ttlMs });\n  // Release abandoned corpora that expired but were never revisited (Codex Medium).\n  sweepExpiredHotEntries(now);\n}\n\nexport function updateCacheOnWrite(baseDir: string, memory: MemoryFile, keyId = \"\"): void {\n  const entry = hotCacheByDir.get(baseDir);\n  // Only mutate an entry that belongs to THIS key identity (issue #1902, Codex\n  // Medium). A concurrent differently-keyed manager may have replaced the\n  // single hotCacheByDir slot during an awaited parse; inserting our decrypted\n  // MemoryFile into its entry would leak plaintext across the key boundary.\n  if (entry && entry.keyId === keyId) entry.memories.set(memory.path, memory);\n}\n\nexport function updateCacheOnDelete(baseDir: string, filePath: string, keyId = \"\"): void {\n  const entry = hotCacheByDir.get(baseDir);\n  if (entry && entry.keyId === keyId) entry.memories.delete(filePath);\n}\n// Archive cache — same pattern, separate store\nexport function getCachedArchivedMemories(\n  baseDir: string,\n  currentVersion: number,\n  keyId = \"\",\n): MemoryFile[] | null {\n  if (currentVersion === 0) return null;\n  const entry = archiveCacheByDir.get(baseDir);\n  if (!entry || entry.version !== currentVersion || entry.keyId !== keyId) return null;\n  return [...entry.memories.values()];\n}\n\nexport function setCachedArchivedMemories(\n  baseDir: string,\n  memories: MemoryFile[],\n  version: number,\n  keyId = \"\",\n): void {\n  const map = new Map<string, MemoryFile>();\n  for (const m of memories) map.set(m.path, m);\n  // ttlMs: 0 — the archive cache has no age TTL; it is version-keyed and cleared\n  // via invalidation. The field satisfies the shared CacheEntry shape (#1902).\n  archiveCacheByDir.set(baseDir, { memories: map, version, loadedAt: Date.now(), keyId, ttlMs: 0 });\n}\n\n// Entity cache — same pattern as memory cache, but keyed by schema-aware parse inputs.\nconst entityCacheByDir = new Map<string, { entities: EntityFile[]; version: number; loadedAt: number }>();\n\n/**\n * Single normalization point for the entity-cache schema key (issue #1535).\n * BOTH the set/get key builder and the prefix invalidation derive from here so\n * `undefined` vs `\"\"` (or any future normalization rule) can never diverge\n * between the write path and the invalidate path (rule 38 cousin).\n */\nfunction normalizeEntitySchemaKey(schemaKey: string | undefined): string {\n  return schemaKey ?? \"\";\n}\n\n/** Prefix shared by every entity-cache key for a dir, regardless of schemaKey. */\nfunction entityCacheKeyPrefix(baseDir: string): string {\n  return `${baseDir}\\u0000`;\n}\n\nfunction buildEntityCacheKey(baseDir: string, schemaKey?: string): string {\n  return `${entityCacheKeyPrefix(baseDir)}${normalizeEntitySchemaKey(schemaKey)}`;\n}\n\nexport function getCachedEntities(\n  baseDir: string,\n  currentVersion: number,\n  schemaKey: string = \"\",\n): EntityFile[] | null {\n  if (currentVersion === 0) return null;\n  const entry = entityCacheByDir.get(buildEntityCacheKey(baseDir, schemaKey));\n  if (!entry || entry.version !== currentVersion) return null;\n  return entry.entities;\n}\n\nexport function setCachedEntities(\n  baseDir: string,\n  entities: EntityFile[],\n  version: number,\n  schemaKey: string = \"\",\n): void {\n  entityCacheByDir.set(buildEntityCacheKey(baseDir, schemaKey), {\n    entities,\n    version,\n    loadedAt: Date.now(),\n  });\n}\n\nexport function invalidateCachedEntities(baseDir: string): void {\n  const prefix = entityCacheKeyPrefix(baseDir);\n  for (const key of entityCacheByDir.keys()) {\n    if (key.startsWith(prefix)) entityCacheByDir.delete(key);\n  }\n}\n\n// Derived caches — pre-filtered views invalidated alongside the main cache.\n// These avoid O(146K) filter+map on every verified recall/rules call.\ninterface DerivedCacheEntry<T> {\n  data: T;\n  sourceVersion: number; // matches the hot cache version it was derived from\n  keyId: string; // secure-store key identity of the corpus it was derived from (#1902)\n  loadedAt: number; // build time — bounds staleness from external edits via ttlMs (#1902)\n}\n\nconst episodeMapByDir = new Map<string, DerivedCacheEntry<Map<string, MemoryFile>>>();\nconst ruleMemoriesByDir = new Map<string, DerivedCacheEntry<{ all: MemoryFile[]; byId: Map<string, MemoryFile> }>>();\n\nexport function getCachedEpisodeMap(\n  baseDir: string,\n  currentVersion: number,\n  keyId = \"\",\n  ttlMs = 0,\n): Map<string, MemoryFile> | null {\n  if (currentVersion === 0) return null;\n  const entry = episodeMapByDir.get(baseDir);\n  if (!entry || entry.sourceVersion !== currentVersion || entry.keyId !== keyId) return null;\n  // TTL safety net (issue #1902): the version sentinel doesn't move on a direct\n  // external edit, so bound how long a derived view is served before a rebuild\n  // (which re-reads via readAllMemories, itself TTL-bounded). ttlMs <= 0 disables.\n  if (ttlMs > 0 && Date.now() - entry.loadedAt > ttlMs) {\n    episodeMapByDir.delete(baseDir);\n    return null;\n  }\n  return entry.data;\n}\n\n/** Build and cache the episode memory map from the full memory list. */\nexport function setCachedEpisodeMap(\n  baseDir: string,\n  memories: MemoryFile[],\n  version: number,\n  cache = true,\n  keyId = \"\",\n): Map<string, MemoryFile> {\n  const map = new Map<string, MemoryFile>();\n  for (const m of memories) {\n    if (m.frontmatter.status === \"archived\" || m.frontmatter.status === \"forgotten\") continue;\n    if (m.frontmatter.memoryKind !== \"episode\") continue;\n    map.set(m.frontmatter.id, m);\n  }\n  if (cache) episodeMapByDir.set(baseDir, { data: map, sourceVersion: version, keyId, loadedAt: Date.now() });\n  return map;\n}\n\n/** Get pre-filtered rule memories. Derived from hot cache. */\nexport function getCachedRuleMemories(\n  baseDir: string,\n  currentVersion: number,\n  keyId = \"\",\n  ttlMs = 0,\n): { all: MemoryFile[]; byId: Map<string, MemoryFile> } | null {\n  if (currentVersion === 0) return null;\n  const entry = ruleMemoriesByDir.get(baseDir);\n  if (!entry || entry.sourceVersion !== currentVersion || entry.keyId !== keyId) return null;\n  // TTL safety net (issue #1902): bound staleness from direct external edits\n  // that don't move the version sentinel. ttlMs <= 0 disables.\n  if (ttlMs > 0 && Date.now() - entry.loadedAt > ttlMs) {\n    ruleMemoriesByDir.delete(baseDir);\n    return null;\n  }\n  return entry.data;\n}\n\n/** Build and cache the rule memories from the full memory list. */\nexport function setCachedRuleMemories(\n  baseDir: string,\n  memories: MemoryFile[],\n  version: number,\n  cache = true,\n  keyId = \"\",\n): { all: MemoryFile[]; byId: Map<string, MemoryFile> } {\n  const byId = new Map<string, MemoryFile>();\n  const all: MemoryFile[] = [];\n  for (const m of memories) {\n    byId.set(m.frontmatter.id, m);\n    if (\n      m.frontmatter.category === \"rule\" &&\n      m.frontmatter.status !== \"archived\" &&\n      m.frontmatter.status !== \"forgotten\"\n    ) {\n      all.push(m);\n    }\n  }\n  const result = { all, byId };\n  if (cache) ruleMemoriesByDir.set(baseDir, { data: result, sourceVersion: version, keyId, loadedAt: Date.now() });\n  return result;\n}\n\n// QMD search result cache — short-lived (60s TTL) to avoid stale results\n// while reducing redundant daemon calls for repeated/similar queries.\ninterface QmdCacheEntry {\n  results: unknown[];\n  cachedAt: number;\n}\nconst QMD_CACHE_TTL_MS = 60_000;\nconst qmdSearchCache = new Map<string, QmdCacheEntry>();\n\nexport function getCachedQmdSearch(cacheKey: string): unknown[] | null {\n  const entry = qmdSearchCache.get(cacheKey);\n  if (!entry) return null;\n  if (Date.now() - entry.cachedAt > QMD_CACHE_TTL_MS) {\n    qmdSearchCache.delete(cacheKey);\n    return null;\n  }\n  return entry.results;\n}\n\nexport function setCachedQmdSearch(cacheKey: string, results: unknown[]): void {\n  qmdSearchCache.set(cacheKey, { results, cachedAt: Date.now() });\n  // Evict old entries to prevent unbounded growth\n  if (qmdSearchCache.size > 200) {\n    const now = Date.now();\n    for (const [key, entry] of qmdSearchCache) {\n      if (now - entry.cachedAt > QMD_CACHE_TTL_MS) qmdSearchCache.delete(key);\n    }\n  }\n}\n\n/**\n * Mutation scopes (issue #1904). A cache layer declares (via `evictOn`) which\n * of these mutation kinds evict it, so the invalidation chokepoint can clear\n * only the layers a given write actually affects instead of nuking every\n * layer on every write (the permanently-cold-cache regression #1904 fixes).\n */\nexport type MemoryMutationScope =\n  | \"memory-create\" // a new memory doc added; no existing doc's recall-visibility changes\n  | \"memory-mutate\" // existing doc changed/moved/removed/status-changed (update, supersede,\n  //   archive, invalidate, frontmatter, cold-tier change, bulk delete)\n  | \"entity-write\" // an entity file changed\n  | \"secure-key-change\"; // encryption key rotated; everything is now unreadable → evict all\n\n/**\n * Cache-layer registry (issue #1535).\n *\n * EVERY process-level cache that can serve memory-derived content is\n * enumerated here, and the single invalidation chokepoint\n * (`invalidateAllForDir`) iterates this list. Adding a new cache layer to\n * this module (or qmd-recall-cache.ts) REQUIRES registering it here —\n * otherwise mutations will never invalidate it (the exact bug this registry\n * exists to prevent) and the enumerate-all-layers fitness test in\n * tests/cache-invalidation-coherence.test.ts fails.\n */\nexport interface MemoryCacheLayer {\n  /** Stable identifier used by tests and diagnostics. */\n  readonly name: string;\n  /** \"dir\" layers evict only entries for the given baseDir. \"global\" layers\n   *  are fully cleared on any mutation: their keys embed queries, namespaces,\n   *  and strategies rather than a storage dir, so a per-dir selective clear\n   *  is not possible without recording the dir in each entry. Full clear is\n   *  the simple-and-correct choice — these caches are re-warmable\n   *  (issue #1535, implementation guide option (b)). */\n  readonly scope: \"dir\" | \"global\";\n  /** Which mutation scopes evict this layer (issue #1904). A `memory-create`\n   *  only refreshes the full-memory-list views (hot + derived episode/rule); a\n   *  `memory-mutate`/`entity-write`/`secure-key-change` evicts every layer whose\n   *  content it can affect. Adding a layer REQUIRES declaring this. */\n  readonly evictOn: Partial<Record<MemoryMutationScope, true>>;\n  /** Evict entries for baseDir (\"dir\" scope) or everything (\"global\" scope). */\n  readonly invalidateForDir: (baseDir: string) => void;\n  /** Evict every entry across all dirs. */\n  readonly clearAll: () => void;\n  /** True when the layer still holds entries for baseDir (\"dir\" scope) or\n   *  any entries at all (\"global\" scope). */\n  readonly hasEntriesFor: (baseDir: string) => boolean;\n}\n\nexport const ALL_CACHE_LAYERS: readonly MemoryCacheLayer[] = [\n  {\n    name: \"hot-memories\",\n    scope: \"dir\",\n    evictOn: { \"memory-create\": true, \"memory-mutate\": true, \"secure-key-change\": true },\n    invalidateForDir: (baseDir) => void hotCacheByDir.delete(baseDir),\n    clearAll: () => hotCacheByDir.clear(),\n    hasEntriesFor: (baseDir) => hotCacheByDir.has(baseDir),\n  },\n  {\n    name: \"archive-memories\",\n    scope: \"dir\",\n    evictOn: { \"memory-mutate\": true, \"secure-key-change\": true },\n    invalidateForDir: (baseDir) => void archiveCacheByDir.delete(baseDir),\n    clearAll: () => archiveCacheByDir.clear(),\n    hasEntriesFor: (baseDir) => archiveCacheByDir.has(baseDir),\n  },\n  {\n    name: \"entities\",\n    scope: \"dir\",\n    evictOn: { \"entity-write\": true, \"secure-key-change\": true },\n    invalidateForDir: (baseDir) => invalidateCachedEntities(baseDir),\n    clearAll: () => entityCacheByDir.clear(),\n    hasEntriesFor: (baseDir) => {\n      const prefix = entityCacheKeyPrefix(baseDir);\n      for (const key of entityCacheByDir.keys()) {\n        if (key.startsWith(prefix)) return true;\n      }\n      return false;\n    },\n  },\n  {\n    name: \"derived-episode-map\",\n    scope: \"dir\",\n    evictOn: { \"memory-create\": true, \"memory-mutate\": true, \"secure-key-change\": true },\n    invalidateForDir: (baseDir) => void episodeMapByDir.delete(baseDir),\n    clearAll: () => episodeMapByDir.clear(),\n    hasEntriesFor: (baseDir) => episodeMapByDir.has(baseDir),\n  },\n  {\n    name: \"derived-rule-memories\",\n    scope: \"dir\",\n    evictOn: { \"memory-create\": true, \"memory-mutate\": true, \"secure-key-change\": true },\n    invalidateForDir: (baseDir) => void ruleMemoriesByDir.delete(baseDir),\n    clearAll: () => ruleMemoriesByDir.clear(),\n    hasEntriesFor: (baseDir) => ruleMemoriesByDir.has(baseDir),\n  },\n  {\n    name: \"qmd-search\",\n    scope: \"global\",\n    evictOn: { \"memory-mutate\": true, \"entity-write\": true, \"secure-key-change\": true },\n    invalidateForDir: () => qmdSearchCache.clear(),\n    clearAll: () => qmdSearchCache.clear(),\n    hasEntriesFor: () => qmdSearchCache.size > 0,\n  },\n  {\n    name: \"qmd-recall\",\n    scope: \"global\",\n    evictOn: { \"memory-mutate\": true, \"entity-write\": true, \"secure-key-change\": true },\n    invalidateForDir: () => clearQmdRecallCache(),\n    clearAll: () => clearQmdRecallCache(),\n    hasEntriesFor: () => qmdRecallCacheSize() > 0,\n  },\n];\n\n/**\n * The single invalidation chokepoint (issue #1535, rule 37).\n *\n * Every memory/entity mutation path must route through this function —\n * storage.ts calls it from its internal invalidation funnels\n * (invalidateAllMemoriesCache / invalidateColdMemoriesCache /\n * bumpMemoryStatusVersion / setSecureStoreKey). Nothing may clear an\n * individual layer ad hoc: partial clears are how the stale-recall bug\n * happened (qmdRecallCache was never invalidated on mutations, so recall\n * served pre-edit bundles for the remainder of its fresh/stale TTL window).\n */\nexport function invalidateAllForDir(baseDir: string): void {\n  for (const layer of ALL_CACHE_LAYERS) {\n    layer.invalidateForDir(baseDir);\n  }\n}\n\n/**\n * Scope-aware invalidation chokepoint (issue #1904). Evicts only the layers\n * whose `evictOn` includes `scope`, so the highest-frequency write\n * (`memory-create`, fired continuously by extraction) stops nuking the QMD\n * result caches and the version-keyed entity cache it cannot affect. This is\n * the single scoped entry point — like `invalidateAllForDir`, it iterates the\n * `ALL_CACHE_LAYERS` registry rather than clearing any layer ad hoc, so the\n * single-chokepoint invariant (#1535) holds: a new layer only participates by\n * declaring `evictOn`.\n */\nexport function invalidateForScope(baseDir: string, scope: MemoryMutationScope): void {\n  for (const layer of ALL_CACHE_LAYERS) {\n    if (layer.evictOn[scope]) layer.invalidateForDir(baseDir);\n  }\n}\n\n/**\n * Companion to {@link invalidateForScope} for the single-file write fast path\n * (issue #1902 + #1904): it patches the hot-memories entry in place and\n * re-keys it, so this evicts every OTHER layer the scope would clear but leaves\n * hot-memories alone. A `memory-create` thus evicts only the derived\n * episode/rule views (hot patched, QMD/entities/archive kept warm), which is\n * the whole point of #1904 — a create must not evict the QMD result caches.\n */\nexport function invalidateForScopeExceptHot(baseDir: string, scope: MemoryMutationScope): void {\n  for (const layer of ALL_CACHE_LAYERS) {\n    if (layer.name === \"hot-memories\") continue;\n    if (layer.evictOn[scope]) layer.invalidateForDir(baseDir);\n  }\n}\n\n/**\n * Invalidate every cache layer for `baseDir` EXCEPT the hot-memories layer\n * (issue #1902). Single-file write paths use this instead of\n * `invalidateAllForDir` because they patch the hot-memories entry in place\n * (via `updateCacheOnWrite`/`updateCacheOnDelete`) and re-key it to the bumped\n * version — so dropping it here would defeat the whole warm-cache fast path.\n * The derived episode/rule views and the global QMD caches are cheap to\n * rebuild and are not patched, so they are still evicted here. Every other\n * layer remains reachable for the wholesale `invalidateAllForDir` /\n * `clearMemoryCache` chokepoint used by bulk/ambiguous mutations.\n */\nexport function invalidateDerivedAndGlobalForDir(baseDir: string): void {\n  // Preserve the layers a single-file write intentionally keeps warm (issue\n  // #1902, Codex Medium): hot-memories is patched + re-keyed in place; the\n  // entities layer is keyed on memory-status, which plain create/content writes\n  // deliberately do NOT bump (so entity retrieval stays warm); and the\n  // archive-memories layer is version-keyed on the archive tier, untouched by a\n  // hot-tier write. Evict ONLY the derived (episode/rule) and global (QMD) views.\n  for (const layer of ALL_CACHE_LAYERS) {\n    if (\n      layer.name === \"hot-memories\" ||\n      layer.name === \"entities\" ||\n      layer.name === \"archive-memories\"\n    ) {\n      continue;\n    }\n    layer.invalidateForDir(baseDir);\n  }\n}\n\nexport function clearMemoryCache(baseDir?: string): void {\n  if (baseDir) {\n    invalidateAllForDir(baseDir);\n    return;\n  }\n  for (const layer of ALL_CACHE_LAYERS) {\n    layer.clearAll();\n  }\n}\n\n/**\n * Clear ONLY the two global QMD result caches (qmd-search + qmd-recall), leaving\n * every dir-scoped layer (hot/archive/entities/derived) untouched. Called after\n * a successful QMD maintenance update+embed (#1904, Codex): a newly-persisted\n * fact becomes searchable at that moment, so any cached pre-index recall/search\n * bundle is now stale and must not be served. This lets the create path keep the\n * QMD caches warm during index lag (perf win) while guaranteeing invalidation\n * the moment the fact is actually indexed — no extended stale window.\n */\nexport function clearQmdResultCaches(): void {\n  qmdSearchCache.clear();\n  clearQmdRecallCache();\n}\n\nexport function getMemoryCacheStats(baseDir: string): {\n  hotSize: number;\n  archiveSize: number;\n  hotVersion: number | null;\n  archiveVersion: number | null;\n} {\n  const hot = hotCacheByDir.get(baseDir);\n  const archive = archiveCacheByDir.get(baseDir);\n  return {\n    hotSize: hot?.memories.size ?? 0,\n    archiveSize: archive?.memories.size ?? 0,\n    hotVersion: hot?.version ?? null,\n    archiveVersion: archive?.version ?? null,\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-4B4MUS5D.js → chunk-YROFNEG5.js}

@@ -1,20 +1,20 @@
 import {
   collectNativeKnowledgeChunks
-} from "./chunk-MRHFJV44.js";
+} from "./chunk-2DQ2XREU.js";
 import {
   compareEntityTimestamps,
   normalizeEntityName
-} from "./chunk-7ICYQUOL.js";
+} from "./chunk-4BJQODZF.js";
 import {
-  resolveNamespaceCapabilities
-} from "./chunk-BFPETA3S.js";
+  sanitizeMemoryContent
+} from "./chunk-5GKPFL3S.js";
 import {
   normalizeEntityText,
   resolveRequestedEntitySectionKeys
 } from "./chunk-4DJQYKMN.js";
 import {
-  sanitizeMemoryContent
-} from "./chunk-5GKPFL3S.js";
+  resolveNamespaceCapabilities
+} from "./chunk-SCCO46KZ.js";
 
 // src/entity-retrieval.ts
 import { createHash } from "crypto";
@@ -682,4 +682,4 @@ export {
   entityIndexVersion,
   entityRecentTranscriptLookbackHours
 };
-//# sourceMappingURL=chunk-4B4MUS5D.js.map
+//# sourceMappingURL=chunk-YROFNEG5.js.map

package/dist/{chunk-WU46YPY6.js → chunk-YV32N67O.js}

@@ -16,4 +16,4 @@ export {
   reportSearchDegradation,
   resolveEnsureCollectionArgs
 };
-//# sourceMappingURL=chunk-WU46YPY6.js.map
+//# sourceMappingURL=chunk-YV32N67O.js.map

package/dist/chunk-YV32N67O.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/search/port.ts"],"sourcesContent":["import type { QmdSearchResult } from \"../types.js\";\n\n/** Alias so consumers don't need to reference \"Qmd\" in a backend-agnostic context. */\nexport type SearchResult = QmdSearchResult;\n\nexport interface SearchQueryOptions {\n  intent?: string;\n  explain?: boolean;\n  candidateLimit?: number;\n  rerank?: boolean;\n  chunkStrategy?: \"auto\" | \"regex\";\n  structuredSearches?: Array<{ type: \"lex\" | \"vec\" | \"hyde\"; query: string }>;\n}\n\n/**\n * A search that returned empty (or partial) results because the backend was\n * unavailable, still loading, or timed out — cases that are otherwise\n * indistinguishable from a genuine \"no matches\" (issue #1536, CLAUDE.md\n * rule 34).\n */\nexport interface SearchDegradation {\n  backend: \"qmd\" | \"remote\" | \"meilisearch\" | \"orama\" | \"lancedb\";\n  code:\n    | \"backend_unavailable\"\n    | \"backend_error\"\n    | \"daemon_timeout\"\n    | \"daemon_loading\"\n    | \"subprocess_error\"\n    | \"deadline_exceeded\"\n    | \"remote_error\";\n  detail?: string;\n}\n\nexport interface SearchExecutionOptions {\n  signal?: AbortSignal;\n  /**\n   * Observer invoked when the backend degrades during this call (#1536).\n   * Callers that need to distinguish empty-because-degraded from\n   * empty-because-no-matches (recall x-ray, fallback decisions) pass a\n   * collector here. Observer failures are swallowed by the notifier —\n   * observability must never break search.\n   */\n  onDegradation?: (degradation: SearchDegradation) => void;\n}\n\nexport function reportSearchDegradation(\n  execution: SearchExecutionOptions | undefined,\n  degradation: SearchDegradation,\n): void {\n  try {\n    execution?.onDegradation?.(degradation);\n  } catch {\n    // Observability must never break search.\n  }\n}\n\nexport function resolveEnsureCollectionArgs(\n  collectionOrExecution?: string | SearchExecutionOptions,\n  execution?: SearchExecutionOptions,\n): { collection?: string; execution?: SearchExecutionOptions } {\n  if (typeof collectionOrExecution === \"string\") {\n    return { collection: collectionOrExecution, execution };\n  }\n  return { collection: undefined, execution: collectionOrExecution ?? execution };\n}\n\n/**\n * Optional status report for search backends that track embedding backlog.\n * Backends without embedding pipelines return null from status().\n */\nexport interface SearchBackendStatus {\n  pendingEmbeddings: number | null;\n  oldestPendingAgeMs: number | null;\n  totalFiles: number | null;\n  embeddedFiles: number | null;\n}\n\n/**\n * Abstract search backend interface.\n *\n * Implementations:\n * - QmdClient (default, local hybrid BM25+vector+reranking)\n * - OramaBackend (embedded, pure JS, hybrid FTS+vector)\n * - LanceDbBackend (embedded, native Arrow bindings, RRF reranking)\n * - MeilisearchBackend (server-based SDK, hybrid search)\n * - RemoteSearchBackend (HTTP REST adapter)\n * - NoopSearchBackend (graceful degradation)\n *\n * See docs/writing-a-search-backend.md for the implementation guide.\n */\nexport interface SearchBackend {\n  // ── Lifecycle ──\n  probe(): Promise<boolean>;\n  /**\n   * Optional non-mutating availability probe for health/readiness checks.\n   * Implementations must avoid auto-upgrades, collection creation, daemon\n   * startup, or any other runtime-modifying side effects.\n   */\n  checkAvailability?(execution?: SearchExecutionOptions): Promise<boolean>;\n  isAvailable(): boolean;\n  debugStatus(): string;\n  /** Optional embedding backlog status for health surfaces. */\n  status?(): Promise<SearchBackendStatus>;\n\n  // ── Search ──\n  search(\n    query: string,\n    collection?: string,\n    maxResults?: number,\n    options?: SearchQueryOptions,\n    execution?: SearchExecutionOptions,\n  ): Promise<SearchResult[]>;\n  searchGlobal(query: string, maxResults?: number, execution?: SearchExecutionOptions): Promise<SearchResult[]>;\n  bm25Search(\n    query: string,\n    collection?: string,\n    maxResults?: number,\n    execution?: SearchExecutionOptions,\n  ): Promise<SearchResult[]>;\n  vectorSearch(\n    query: string,\n    collection?: string,\n    maxResults?: number,\n    execution?: SearchExecutionOptions,\n  ): Promise<SearchResult[]>;\n  hybridSearch(\n    query: string,\n    collection?: string,\n    maxResults?: number,\n    execution?: SearchExecutionOptions,\n  ): Promise<SearchResult[]>;\n\n  // ── Maintenance ──\n  update(execution?: SearchExecutionOptions): Promise<void>;\n  /**\n   * Wall-clock ms of the most recent SUCCESSFUL index refresh, or null when the\n   * backend has never run one. Ordinary update() is fail-open: it returns\n   * silently (without throwing or advancing this timestamp) when the backend is\n   * unavailable or the call is suppressed by a min-interval / failure backoff.\n   * Callers that must know whether update() actually indexed — so they can\n   * invalidate dependent caches only on a real refresh — snapshot this before\n   * the call and treat the backend as refreshed iff the value advanced. Optional\n   * because not every backend tracks it; absent means \"assume refreshed\".\n   */\n  readonly lastUpdateRanAtMs?: number | null;\n  /**\n   * Optional strict refresh used by callers that must know whether the backend\n   * was actually refreshed before writing success markers. Ordinary update\n   * calls remain fail-open for migration/maintenance resilience.\n   */\n  updateStrict?(execution?: SearchExecutionOptions): Promise<void>;\n  updateCollection(collection: string, execution?: SearchExecutionOptions): Promise<void>;\n  updateCollectionFromDir?(collection: string, memoryDir: string, execution?: SearchExecutionOptions): Promise<void>;\n  /**\n   * True when update() refreshes every indexed collection, not just this\n   * backend's configured collection. Namespace routers use this to avoid\n   * repeating the same expensive global update once per namespace.\n   */\n  updatesAllCollections?(): boolean;\n  /**\n   * Optional strict refresh used by callers that must know whether a collection\n   * was actually refreshed before writing success markers. Ordinary update\n   * calls remain fail-open for migration/maintenance resilience.\n   */\n  updateCollectionStrict?(collection: string, execution?: SearchExecutionOptions): Promise<void>;\n  embed(): Promise<void>;\n  /**\n   * Optional strict embed used by callers that must know vectors were actually\n   * refreshed before writing success markers.\n   */\n  embedStrict?(): Promise<void>;\n  embedCollection(collection: string): Promise<void>;\n  /**\n   * Optional strict collection embed used by callers that must know vectors were\n   * actually refreshed before writing success markers.\n   */\n  embedCollectionStrict?(collection: string): Promise<void>;\n\n  // ── Collection management ──\n  /**\n   * Optional non-mutating collection probe. Backends that can distinguish a\n   * missing collection from a transient probe failure should implement this so\n   * callers can avoid auto-creating collections in unsafe layouts.\n   */\n  checkCollection?(\n    collectionOrExecution?: string | SearchExecutionOptions,\n    execution?: SearchExecutionOptions,\n  ): Promise<\"present\" | \"missing\" | \"unknown\" | \"skipped\">;\n  ensureCollection(\n    memoryDir: string,\n    execution?: SearchExecutionOptions,\n  ): Promise<\"present\" | \"missing\" | \"unknown\" | \"skipped\">;\n  ensureCollection(\n    memoryDir: string,\n    collection?: string,\n    execution?: SearchExecutionOptions,\n  ): Promise<\"present\" | \"missing\" | \"unknown\" | \"skipped\">;\n}\n"],"mappings":";AA6CO,SAAS,wBACd,WACA,aACM;AACN,MAAI;AACF,eAAW,gBAAgB,WAAW;AAAA,EACxC,QAAQ;AAAA,EAER;AACF;AAEO,SAAS,4BACd,uBACA,WAC6D;AAC7D,MAAI,OAAO,0BAA0B,UAAU;AAC7C,WAAO,EAAE,YAAY,uBAAuB,UAAU;AAAA,EACxD;AACA,SAAO,EAAE,YAAY,QAAW,WAAW,yBAAyB,UAAU;AAChF;","names":[]}

package/dist/{chunk-B3F4CWQR.js → chunk-YVKF3HEW.js}

@@ -23,4 +23,4 @@ export {
   confidenceTier,
   SPECULATIVE_TTL_DAYS
 };
-//# sourceMappingURL=chunk-B3F4CWQR.js.map
+//# sourceMappingURL=chunk-YVKF3HEW.js.map