@remnic/core 9.25.5 → 9.25.7

package/src/recall-cold-deadline.test.ts

@@ -4,7 +4,7 @@
  * Pins the task-level cancellation contract of runColdStepWithinDeadline
  * inside RecallSearchPipelineCoordinator.applyColdFallbackPipeline:
  *   - when the per-step deadline wins, the losing cold task's INJECTED signal
- *     is aborted (so an orphaned archive scan stops cooperatively) and the
+ *     is aborted so an orphaned query-aware fallback stops cooperatively; the
  *     step returns its fallback (fail-open);
  *   - a task-level deadline must NOT abort the request-level signal;
  *   - a task that completes normally (no deadline) never aborts the injected
@@ -37,24 +37,22 @@ async function coldConfig() {
 }
 
 /**
- * Minimal deps for the archive-scan branch. qmd.isAvailable() === false forces
- * the cold-qmd block to be skipped, so control reaches the archive-scan step;
- * an empty archive result returns [] before any namespace/storage-router work,
- * keeping the stub surface tight. The cast is a deliberate test double.
+ * Minimal dependencies for the query-aware fallback. QMD is unavailable, so
+ * the cold-QMD branch is skipped and the injected fallback step is observed.
  */
 function coldDeps(
   config: PluginConfig,
-  searchLongTermArchiveFallback: RecallSearchPipelineDeps["searchLongTermArchiveFallback"],
+  searchQueryAwareFallback: RecallSearchPipelineDeps["searchQueryAwareFallback"],
 ): RecallSearchPipelineDeps {
   return {
     config,
     qmd: { isAvailable: () => false },
     namespaceFromPath: () => "default",
-    searchLongTermArchiveFallback,
+    searchQueryAwareFallback,
   } as unknown as RecallSearchPipelineDeps;
 }
 
-test("#1907: cold archive-scan deadline aborts the injected step signal, returns fallback, leaves the request signal intact", async () => {
+test("#1907: query-aware fallback deadline aborts the injected step signal, returns fallback, leaves the request signal intact", async () => {
   const { memoryDir, config } = await coldConfig();
   try {
     const stuck = Promise.withResolvers<QmdSearchResult[]>();
@@ -65,7 +63,7 @@ test("#1907: cold archive-scan deadline aborts the injected step signal, returns
     // so the late completion leaks "late" here and the assertion below fails.
     const lateWrites: string[] = [];
     const abandonedTaskSettled = Promise.withResolvers<void>();
-    const deps = coldDeps(config, async (_prompt, _ns, _limit, _prefilter, abortSignal) => {
+    const deps = coldDeps(config, async (_prompt, _limit, _prefilter, abortSignal) => {
       capturedStepSignal = abortSignal;
       const late = await stuck.promise; // does not settle before the deadline wins
       if (!abortSignal?.aborted) {
@@ -87,7 +85,7 @@ test("#1907: cold archive-scan deadline aborts the injected step signal, returns
     });
 
     assert.deepEqual(result, [], "the step returns its fallback when the deadline wins");
-    assert.ok(capturedStepSignal, "archive scan received an injected step signal");
+    assert.ok(capturedStepSignal, "query-aware fallback received an injected step signal");
     assert.equal(
       capturedStepSignal!.aborted,
       true,
@@ -119,7 +117,7 @@ test("#1907: a cold step that completes before its deadline never aborts the inj
   const { memoryDir, config } = await coldConfig();
   try {
     let capturedStepSignal: AbortSignal | undefined;
-    const deps = coldDeps(config, async (_prompt, _ns, _limit, _prefilter, abortSignal) => {
+    const deps = coldDeps(config, async (_prompt, _limit, _prefilter, abortSignal) => {
       capturedStepSignal = abortSignal;
       return []; // resolves immediately, well within the deadline
     });
@@ -135,8 +133,8 @@ test("#1907: a cold step that completes before its deadline never aborts the inj
       abortSignal: requestController.signal,
     });
 
-    assert.deepEqual(result, [], "empty archive returns []");
-    assert.ok(capturedStepSignal, "archive scan received an injected step signal");
+    assert.deepEqual(result, [], "empty query-aware fallback returns []");
+    assert.ok(capturedStepSignal, "query-aware fallback received an injected step signal");
     assert.equal(
       capturedStepSignal!.aborted,
       false,

package/src/testing/subjects/generic-recall-paths.test.ts

@@ -0,0 +1,157 @@
+import assert from "node:assert/strict";
+
+import { Orchestrator } from "../../orchestrator.js";
+import type { SearchBackend } from "../../search/port.js";
+import type { MemoryFile, PluginConfig, QmdSearchResult } from "../../types.js";
+import {
+  cleanupDir,
+  makeLifecycleConfig,
+  mkTempMemoryDir,
+  singleFactResult,
+  stubExtraction,
+} from "../orchestrator-lite.js";
+import {
+  type LifecycleSubject,
+  type MatrixRow,
+  runLifecycleMatrix,
+} from "../lifecycle-matrix.js";
+
+interface QmdSeam {
+  qmd: SearchBackend;
+}
+
+interface GenericRecallPathState {
+  readonly memoryDir: string;
+  orchestrator: Orchestrator;
+  readonly config: PluginConfig;
+  readonly archivePath: string;
+  readonly activePath: string;
+  readonly candidates: QmdSearchResult[];
+  recalled?: string;
+}
+
+function installQmd(orchestrator: Orchestrator, candidates: QmdSearchResult[]): void {
+  const seam = orchestrator as unknown as QmdSeam;
+  seam.qmd = {
+    isAvailable: () => true,
+    debugStatus: () => "lifecycle-test-qmd",
+    search: async () => candidates,
+    hybridSearch: async () => candidates,
+  } as unknown as SearchBackend;
+}
+
+function result(memory: MemoryFile, score: number): QmdSearchResult {
+  return {
+    docid: memory.frontmatter.id,
+    path: memory.path,
+    score,
+    snippet: memory.content,
+  };
+}
+
+const subject: LifecycleSubject<GenericRecallPathState> = {
+  async setup(row: MatrixRow): Promise<GenericRecallPathState> {
+    const memoryDir = await mkTempMemoryDir(`generic-recall-${row.id}`);
+    let orchestrator: Orchestrator | undefined;
+    try {
+      const config = makeLifecycleConfig(memoryDir, {
+        qmdEnabled: true,
+        qmdSearchStrategy: "lex",
+      });
+      orchestrator = new Orchestrator(config);
+      stubExtraction(orchestrator, () => singleFactResult(`replay-${row.id}`));
+      const storage = await orchestrator.getStorage();
+      const archivedWrite = await storage.writeMemory(
+        "fact",
+        `archived candidate for ${row.id}`,
+      );
+      const archivedMemory = await storage.getMemoryById(archivedWrite.id);
+      assert.ok(archivedMemory);
+      const archivePath = await storage.archiveMemory(archivedMemory);
+      assert.ok(archivePath);
+
+      const activeWrite = await storage.writeMemory(
+        "fact",
+        `active candidate for ${row.id}`,
+      );
+      const activeMemory = await storage.getMemoryById(activeWrite.id);
+      assert.ok(activeMemory);
+      const candidates = [
+        result({ ...archivedMemory, path: archivePath }, 1),
+        result(activeMemory, 0.9),
+      ];
+      installQmd(orchestrator, candidates);
+      return {
+        memoryDir,
+        orchestrator,
+        config,
+        archivePath,
+        activePath: activeMemory.path,
+        candidates,
+      };
+    } catch (error) {
+      await orchestrator?.destroy().catch(() => undefined);
+      await cleanupDir(memoryDir);
+      throw error;
+    }
+  },
+
+  async exercise(state, row): Promise<void> {
+    const sessionKey = `generic-recall-${row.id}`;
+    if (row.dimensions.flush !== "none") {
+      await state.orchestrator.flushSession(sessionKey, {
+        reason: row.dimensions.flush,
+      });
+    }
+    if (row.dimensions.restart) {
+      await state.orchestrator.destroy();
+      state.orchestrator = new Orchestrator(state.config);
+      installQmd(state.orchestrator, state.candidates);
+    }
+    if (
+      row.dimensions.providerIdentity === "explicit" ||
+      (row.dimensions.providerIdentity === "sparse" && row.dimensions.rememberedBinding)
+    ) {
+      state.orchestrator.setPeerIdForSession(sessionKey, "remembered-provider");
+    } else if (row.dimensions.providerIdentity === "rebound") {
+      state.orchestrator.setPeerIdForSession(sessionKey, "provider-a");
+      state.orchestrator.setPeerIdForSession(sessionKey, "provider-b");
+    }
+    if (row.dimensions.dedupeOrReplay) {
+      const replayTurn = {
+        source: "openclaw" as const,
+        sessionKey,
+        role: "user" as const,
+        content: "replayed candidate",
+        timestamp: "2026-07-25T00:00:00.000Z",
+      };
+      await state.orchestrator.ingestReplayBatch(
+        [replayTurn, { ...replayTurn }],
+        { archiveLcm: false },
+      );
+    }
+    state.recalled = await state.orchestrator.recall("candidate", sessionKey);
+  },
+
+  async invariants(state): Promise<void> {
+    assert.match(state.recalled ?? "", /active candidate/);
+    assert.doesNotMatch(state.recalled ?? "", /archived candidate/);
+    assert.equal(
+      state.candidates[0]?.path,
+      state.archivePath,
+      "the QMD fixture must put the archived memory ahead of the active hit",
+    );
+    assert.equal(
+      state.candidates[1]?.path,
+      state.activePath,
+      "the QMD fixture must include the persisted active memory",
+    );
+  },
+
+  async teardown(state): Promise<void> {
+    await state.orchestrator.destroy();
+    await cleanupDir(state.memoryDir);
+  },
+};
+
+runLifecycleMatrix("generic-recall-paths", subject);