@remnic/core 9.3.659 → 9.3.661

package/src/recall-state.ts

@@ -3,6 +3,7 @@ import path from "node:path";
 import { createHash, randomUUID } from "node:crypto";
 import { log } from "./logger.js";
 import { writeFileAtomically } from "./maintenance/atomic-file.js";
+import type { SearchDegradation } from "./search/port.js";
 import type {
   IdentityInjectionMode,
   RecallPlanMode,
@@ -59,6 +60,14 @@ export interface LastRecallSnapshot {
    * graph-path `recallExplain` operation.
    */
   tierExplain?: RecallTierExplain;
+  /**
+   * Backend degradations observed while serving this recall (issue #1536).
+   * Present only when a search backend reported unavailable/loading/timeout
+   * during the recall — distinguishing "no matches" from "backend could not
+   * answer" (CLAUDE.md rule 34). Deliberately independent of `tierExplain`,
+   * which is gated behind `recallDirectAnswerEnabled`.
+   */
+  backendDegradations?: SearchDegradation[];
 }
 
 export interface GraphRecallExpandedEntry {
@@ -136,6 +145,31 @@ type StateFileWriter = (filePath: string, content: string) => Promise<void>;
  * qmd-recall-cache.ts).  The payload is pure JSON-shaped data, so
  * structuredClone is both safe and complete here.
  */
+/**
+ * Stale-snapshot identity guard shared by the annotate methods (issue #518):
+ * a writeNonce match wins outright; otherwise traceId (when expected) and
+ * recordedAt are compared. Extracted so every annotation surface applies
+ * identical guards (CLAUDE.md rule 22).
+ */
+function snapshotMatchesExpectedIdentity(
+  current: LastRecallSnapshot,
+  expected?: { writeNonce?: string; traceId?: string; recordedAt?: string },
+): boolean {
+  if (!expected) return true;
+  if (typeof expected.writeNonce === "string" && expected.writeNonce.length > 0) {
+    return current.writeNonce === expected.writeNonce;
+  }
+  const hasExpectedTraceId =
+    typeof expected.traceId === "string" && expected.traceId.length > 0;
+  if (hasExpectedTraceId) {
+    return current.traceId === expected.traceId;
+  }
+  if (expected.recordedAt !== undefined) {
+    return current.recordedAt === expected.recordedAt;
+  }
+  return true;
+}
+
 function cloneTierExplain(
   tierExplain: RecallTierExplain | undefined,
 ): RecallTierExplain | undefined {
@@ -271,6 +305,13 @@ export class LastRecallStore {
      * can render which retrieval tier served the query.
      */
     tierExplain?: RecallTierExplain;
+    /**
+     * Backend degradations observed while serving this recall (issue #1536).
+     * Passed at record time so the published snapshot is born annotated —
+     * a post-record annotation would leave a window where readers see the
+     * snapshot without them (codex review on #1544).
+     */
+    backendDegradations?: SearchDegradation[];
   }): Promise<void> {
     const now = new Date().toISOString();
     const queryHash = createHash("sha256").update(opts.query).digest("hex");
@@ -302,6 +343,10 @@ export class LastRecallStore {
       identityInjectedChars: opts.identityInjection?.injectedChars,
       identityInjectionTruncated: opts.identityInjection?.truncated,
       tierExplain: opts.tierExplain,
+      backendDegradations:
+        opts.backendDegradations && opts.backendDegradations.length > 0
+          ? opts.backendDegradations
+          : undefined,
     };
     // `cloneLastRecallSnapshot` handles `null` but that never applies
     // at this call site — the non-null assertion keeps the type
@@ -355,27 +400,7 @@ export class LastRecallStore {
   ): Promise<void> {
     const current = this.state[sessionKey];
     if (!current) return;
-    if (expected) {
-      if (
-        typeof expected.writeNonce === "string" &&
-        expected.writeNonce.length > 0
-      ) {
-        if (current.writeNonce !== expected.writeNonce) return;
-      } else {
-        const hasExpectedTraceId =
-          typeof expected.traceId === "string" && expected.traceId.length > 0;
-        const traceIdMatches =
-          hasExpectedTraceId && current.traceId === expected.traceId;
-        const recordedAtMatches =
-          expected.recordedAt !== undefined &&
-          current.recordedAt === expected.recordedAt;
-        if (hasExpectedTraceId) {
-          if (!traceIdMatches) return;
-        } else if (expected.recordedAt !== undefined && !recordedAtMatches) {
-          return;
-        }
-      }
-    }
+    if (!snapshotMatchesExpectedIdentity(current, expected)) return;
     this.state[sessionKey] = {
       ...current,
       tierExplain: cloneTierExplain(tierExplain),
@@ -387,6 +412,7 @@ export class LastRecallStore {
     }
   }
 
+
   private flushState(): Promise<void> {
     const run = this.stateWriteChain.catch(() => undefined).then(async () => {
       await mkdir(path.dirname(this.statePath), { recursive: true });

package/src/search/port.ts

@@ -12,8 +12,33 @@ export interface SearchQueryOptions {
   structuredSearches?: Array<{ type: "lex" | "vec" | "hyde"; query: string }>;
 }
 
+/**
+ * A search that returned empty (or partial) results because the backend was
+ * unavailable, still loading, or timed out — cases that are otherwise
+ * indistinguishable from a genuine "no matches" (issue #1536, CLAUDE.md
+ * rule 34).
+ */
+export interface SearchDegradation {
+  backend: "qmd";
+  code:
+    | "backend_unavailable"
+    | "daemon_timeout"
+    | "daemon_loading"
+    | "subprocess_error"
+    | "deadline_exceeded";
+  detail?: string;
+}
+
 export interface SearchExecutionOptions {
   signal?: AbortSignal;
+  /**
+   * Observer invoked when the backend degrades during this call (#1536).
+   * Callers that need to distinguish empty-because-degraded from
+   * empty-because-no-matches (recall x-ray, fallback decisions) pass a
+   * collector here. Observer failures are swallowed by the notifier —
+   * observability must never break search.
+   */
+  onDegradation?: (degradation: SearchDegradation) => void;
 }
 
 export function resolveEnsureCollectionArgs(

package/src/storage.ts

@@ -5,7 +5,7 @@ import path from "node:path";
 import { log } from "./logger.js";
 import { isErrnoCode } from "./utils/errno.js";
 import { RECALL_FALLBACK_DIRS } from "./utils/category-dir.js";
-import { getCachedEntities, invalidateCachedEntities, setCachedEntities } from "./memory-cache.js";
+import { getCachedEntities, invalidateAllForDir, setCachedEntities } from "./memory-cache.js";
 import { rotateMarkdownFileToArchive } from "./hygiene.js";
 import { sanitizeMemoryContent } from "./sanitize.js";
 import { createVersion as createPageVersion, type VersioningConfig, type VersionTrigger } from "./page-versioning.js";
@@ -2335,7 +2335,10 @@ export class StorageManager {
   setSecureStoreKey(key: Buffer | null, encryptOnWrite = true): void {
     this._secureStoreKey = key;
     this._secureStoreEncryptOnWrite = encryptOnWrite;
-    invalidateCachedEntities(this.baseDir);
+    // Route through the invalidation chokepoint (issue #1535): a key change
+    // (or store lock) must evict every cache layer that may hold content
+    // decrypted under the previous key, not just the entity layer.
+    invalidateAllForDir(this.baseDir);
     this.invalidateKnowledgeIndexCache();
   }
 
@@ -2511,6 +2514,13 @@ export class StorageManager {
 
   private bumpMemoryStatusVersion(): void {
     this.bumpSharedVersion("memory-status", StorageManager.memoryStatusVersionByDir);
+    // Invalidation chokepoint (issue #1535): status/entity mutations funnel
+    // through this bump — several of them (supersedeMemory, archiveMemories,
+    // writeEntity, cleanExpiredCommitments) do NOT call
+    // invalidateAllMemoriesCache(), so the chokepoint must fire here as well.
+    // Version bumps only invalidate the version-checked layers lazily; the
+    // TTL-based QMD caches need this eager clear.
+    invalidateAllForDir(this.baseDir);
   }
 
   getMemoryStatusVersion(): number {
@@ -2943,8 +2953,9 @@ export class StorageManager {
   }
 
   private async invalidateAfterOfflineSyncMutation(filePath: string): Promise<void> {
+    // invalidateAllMemoriesCache() routes through the invalidateAllForDir()
+    // chokepoint, which also covers the entity cache (issue #1535).
     this.invalidateAllMemoriesCache();
-    invalidateCachedEntities(this.baseDir);
     this.invalidateKnowledgeIndexCache();
     this.factHashIndexAuthoritative = false;
     await unlink(this.factHashIndexReadyPath).catch((error: unknown) => {
@@ -4002,6 +4013,13 @@ export class StorageManager {
    *  inside cold/, archiveMemory, etc.). */
   private invalidateAllMemoriesCache(): void {
     StorageManager.allMemoriesInFlight.delete(this.baseDir);
+    // Invalidation chokepoint (issue #1535): eagerly evict EVERY process-level
+    // cache layer that can serve memory-derived content for this dir — hot,
+    // archive, entity, derived episode/rule views, and both QMD result caches
+    // (qmdSearchCache and qmdRecallCache). Before this call was added, the QMD
+    // recall cache was never invalidated on mutations, so recall served
+    // pre-edit bundles for the remainder of its fresh/stale TTL window.
+    invalidateAllForDir(this.baseDir);
   }
 
   /**
@@ -4020,6 +4038,12 @@ export class StorageManager {
     const coldRoot = path.join(this.baseDir, "cold");
     StorageManager.coldMemoriesCache.delete(coldRoot);
     this.bumpColdWriteVersion();
+    // Invalidation chokepoint (issue #1535): cold-tier mutations can reach
+    // this funnel without invalidateAllMemoriesCache() (e.g. the cold-only
+    // branch of invalidateMemoryCachesForTiers used by maintenance/purge), so
+    // the chokepoint must fire here too — cold memories are recallable and a
+    // cold delete must not leave stale QMD recall bundles behind.
+    invalidateAllForDir(this.baseDir);
   }
 
   /** Return the current cold-write version counter for this storage root.