@remnic/core 9.3.714 → 9.3.716

package/src/orchestrator.ts

@@ -1396,12 +1396,11 @@ export async function resolveRecallModeDecisionAsync(
   options: RecallModeGraphOptions & {
     config: PluginConfig;
     /**
-     * Recall-operation capability gates (issue #1523). OPTIONAL and additive:
-     * the recall orchestrator passes a resolved set, but existing callers that
-     * only pass `config` + planner flags stay backward-compatible — the LLM
-     * planner gate falls back to `config.recallPlannerLlmEnabled` when omitted.
+     * Recall-operation capability gates (issue #1523). REQUIRED: the recall
+     * orchestrator always passes a resolved set — the LLM planner gate reads
+     * `caps.recallPlannerLlm`, never re-derives from config.
      */
-    caps?: CapabilitySet;
+    caps: CapabilitySet;
     hints?: string[];
     llm?: FallbackLlmClient;
     signal?: AbortSignal;
@@ -1410,10 +1409,8 @@ export async function resolveRecallModeDecisionAsync(
   const heuristicDecision = resolveRecallModeDecision(options);
 
   // Planner globally off, or LLM planning not opted into → heuristic only.
-  // Prefer the resolved capability when supplied; otherwise fall back to the
-  // config flag so callers on the old option shape get identical gating.
-  const plannerLlmEnabled =
-    options.caps?.recallPlannerLlm ?? options.config.recallPlannerLlmEnabled;
+  // Read the resolved capability (issue #1523) — never re-derive from config.
+  const plannerLlmEnabled = options.caps.recallPlannerLlm;
   if (!options.plannerEnabled || !plannerLlmEnabled) {
     return heuristicDecision;
   }
@@ -1423,9 +1420,9 @@ export async function resolveRecallModeDecisionAsync(
     options.prompt,
     options.hints,
     options.config,
+    options.caps,
     options.llm,
     options.signal,
-    options.caps,
   );
 
   // Shadow mode: record what the LLM would have chosen but keep the heuristic
@@ -1731,8 +1728,16 @@ export function resolveRecentThreadMemoryPaths(options: {
     buildMemoryPathById(options.allMemsForGraph, options.storageDir);
   if (pathById.size === 0) return [];
 
+  // #1635 (defensive): skip pending_review ids from legacy episode sets.
+  const pendingReviewIds = new Set<string>(
+    (options.allMemsForGraph ?? [])
+      .filter((m) => m.frontmatter.status === "pending_review" && m.frontmatter.id)
+      .map((m) => m.frontmatter.id as string),
+  );
+
   return options.threadEpisodeIds
     .filter((id) => id !== options.currentMemoryId)
+    .filter((id) => !pendingReviewIds.has(id))
     .slice(-maxRecent)
     .map((id) => pathById.get(id))
     .filter((p): p is string => typeof p === "string" && p.length > 0);
@@ -1858,6 +1863,11 @@ export class Orchestrator {
    * callers already destructure `persistedIds` by position.
    */
   private lastPersistExtractionDeferredCount: number = 0;
+  /**
+   * Side-channel (#1635): pending_review persisted ids from the last
+   * persistExtraction; runExtraction excludes them from the thread episode set.
+   */
+  private lastPersistExtractionPendingReviewIds: string[] = [];
   private readonly _fastGatewayLlm: FallbackLlmClient | null;
 
   get fastGatewayLlm(): FallbackLlmClient | null {
@@ -13461,23 +13471,16 @@ export class Orchestrator {
     }
 
     // Batch-append persisted IDs so non-fact memories (entities/questions) are
-    // always attached to the thread.
+    // always attached to the thread. The helper excludes pending_review ids (#1635).
     if (
       this.config.threadingEnabled &&
       threadIdForExtraction &&
       persistedIds.length > 0
     ) {
-      try {
-        await this.threading.appendEpisodeIds(
-          threadIdForExtraction,
-          persistedIds,
-        );
-      } catch (err) {
-        log.warn(
-          "[threading] appendEpisodeIds failed after persistence (non-fatal)",
-          err,
-        );
-      }
+      await this.appendPersistedThreadEpisodes(
+        threadIdForExtraction,
+        persistedIds,
+      );
     }
 
     // Thread title update for the already-established thread context.
@@ -13831,9 +13834,11 @@ export class Orchestrator {
       // to avoid a maintenance hazard where the two guard paths could diverge.
       return attachCitation(content, citationContext, citationTemplate);
     };
+    const persistedIds: string[] = [];
     const supersessionOrderingAt = (validAt?: string): string =>
       validAt && validAt.length > 0 ? validAt : new Date().toISOString();
-    const persistedIds: string[] = [];
+    // #1635: pending_review persisted ids, excluded from the thread episode set below.
+    const pendingReviewPersistedIds: string[] = [];
     const persistedIdsByStorage = new Map<
       string,
       { storage: StorageManager; ids: string[] }
@@ -13841,11 +13846,18 @@ export class Orchestrator {
     const trackPersistedId = (
       targetStorage: StorageManager,
       id: string,
-      options: { includeReturnedIds?: boolean } = {},
+      options: {
+        includeReturnedIds?: boolean;
+        /** #1635: keep this id out of the persisted thread episode set. */
+        pendingReview?: boolean;
+      } = {},
     ): void => {
       if (options.includeReturnedIds !== false) {
         persistedIds.push(id);
       }
+      if (options.pendingReview) {
+        pendingReviewPersistedIds.push(id);
+      }
       const key = targetStorage.dir;
       const existing = persistedIdsByStorage.get(key);
       if (existing) {
@@ -15347,7 +15359,9 @@ export class Orchestrator {
           log.debug(
             `chunked memory ${parentId} into ${chunkResult.chunks.length} chunks`,
           );
-          trackPersistedId(targetStorage, parentId);
+          trackPersistedId(targetStorage, parentId, {
+            pendingReview: faithfulnessEnforceStatus === "pending_review",
+          });
           // #1576 (cursor Medium): keep pending_review ids out of threadEpisodeIdsForGraph — else later active facts build thread-predecessor edges to an unfaithful memory.
           if (
             faithfulnessEnforceStatus !== "pending_review" &&
@@ -15633,8 +15647,9 @@ export class Orchestrator {
             source: "extraction",
           }),
         );
-        trackPersistedId(targetStorage, memoryId);
-        // #1576 (cursor Medium): same thread-episode guard on the non-chunked path.
+        trackPersistedId(targetStorage, memoryId, {
+          pendingReview: faithfulnessEnforceStatus === "pending_review",
+        });
         if (
           faithfulnessEnforceStatus !== "pending_review" &&
           threadEpisodeIdsForGraph &&
@@ -15944,9 +15959,35 @@ export class Orchestrator {
       log.debug(`temporal-index update error (non-fatal): ${err}`),
     );
 
+    // #1635: surface pending_review ids so the thread episode set excludes them.
+    this.lastPersistExtractionPendingReviewIds = pendingReviewPersistedIds;
     // Return the persisted fact IDs for threading
     return persistedIds;
   }
+  /**
+   * Append persisted ids to the thread episode set, excluding pending_review
+   * fact ids (#1635) so they don't re-seed predecessor edges. Fail-open like
+   * the raw appendEpisodeIds call it replaces.
+   */
+  private async appendPersistedThreadEpisodes(
+    threadId: string,
+    persistedIds: string[],
+  ): Promise<void> {
+    const pendingReviewIds = this.lastPersistExtractionPendingReviewIds ?? [];
+    const episodeIds =
+      pendingReviewIds.length > 0
+        ? persistedIds.filter((id) => !pendingReviewIds.includes(id))
+        : persistedIds;
+    if (episodeIds.length === 0) return;
+    try {
+      await this.threading.appendEpisodeIds(threadId, episodeIds);
+    } catch (err) {
+      log.warn(
+        "[threading] appendEpisodeIds failed after persistence (non-fatal)",
+        err,
+      );
+    }
+  }
 
   private async indexPersistedMemory(
     storage: StorageManager,

package/src/recall-planner-llm.test.ts

@@ -41,7 +41,7 @@ test("returns heuristic without calling the LLM when recallPlannerLlmEnabled is
   const captured: Array<Record<string, unknown>> = [];
   const llm = stubLlm({ capturedOptions: captured, result: { mode: "no_recall" } });
 
-  const result = await planRecallModeLLM("what did we decide about auth?", undefined, config, llm, undefined, resolveCapabilities(config));
+  const result = await planRecallModeLLM("what did we decide about auth?", undefined, config, resolveCapabilities(config), llm, undefined);
 
   assert.equal(captured.length, 0, "LLM must not be contacted when disabled");
   assert.equal(result.source, "heuristic");
@@ -55,7 +55,7 @@ test("uses the LLM classification when enabled", async () => {
   const config = parseConfig({ recallPlannerLlmEnabled: true });
   const llm = stubLlm({ result: { mode: "graph_mode", reason: "asks for root cause" }, modelUsed: "anthropic/claude" });
 
-  const result = await planRecallModeLLM("restart the gateway", undefined, config, llm, undefined, resolveCapabilities(config));
+  const result = await planRecallModeLLM("restart the gateway", undefined, config, resolveCapabilities(config), llm, undefined);
 
   assert.equal(result.source, "llm");
   assert.equal(result.mode, "graph_mode");
@@ -75,7 +75,7 @@ test("forwards taskModelChain AND recallPlannerModel in gateway mode (provider-a
   const captured: Array<Record<string, unknown>> = [];
   const llm = stubLlm({ capturedOptions: captured, result: { mode: "minimal" } });
 
-  await planRecallModeLLM("check status", undefined, config, llm, undefined, resolveCapabilities(config));
+  await planRecallModeLLM("check status", undefined, config, resolveCapabilities(config), llm, undefined);
 
   assert.equal(captured.length, 1);
   // recallPlannerModel is tried first (prepended), taskModelChain is the fallback chain.
@@ -98,7 +98,7 @@ test("plugin mode passes only the explicit model, no gateway chain", async () =>
   const captured: Array<Record<string, unknown>> = [];
   const llm = stubLlm({ capturedOptions: captured, result: { mode: "full" } });
 
-  await planRecallModeLLM("summarize the project", undefined, config, llm, undefined, resolveCapabilities(config));
+  await planRecallModeLLM("summarize the project", undefined, config, resolveCapabilities(config), llm, undefined);
 
   assert.equal(captured.length, 1);
   assert.equal(captured[0]?.model, "openai/gpt-5.5");
@@ -110,7 +110,7 @@ test("falls back to heuristic when the LLM throws", async () => {
   const config = parseConfig({ recallPlannerLlmEnabled: true });
   const llm = stubLlm({ throwError: "boom" });
 
-  const result = await planRecallModeLLM("what happened during the outage?", undefined, config, llm, undefined, resolveCapabilities(config));
+  const result = await planRecallModeLLM("what happened during the outage?", undefined, config, resolveCapabilities(config), llm, undefined);
 
   assert.equal(result.source, "heuristic-fallback");
   assert.equal(result.fallbackUsed, true);
@@ -124,7 +124,7 @@ test("falls back to heuristic when the LLM returns no parseable result", async (
   const config = parseConfig({ recallPlannerLlmEnabled: true });
   const llm = stubLlm({ result: null });
 
-  const result = await planRecallModeLLM("how did we get here?", undefined, config, llm, undefined, resolveCapabilities(config));
+  const result = await planRecallModeLLM("how did we get here?", undefined, config, resolveCapabilities(config), llm, undefined);
 
   assert.equal(result.source, "heuristic-fallback");
   assert.equal(result.fallbackUsed, true);
@@ -140,7 +140,7 @@ test("falls back without a network attempt when the chain is empty and the model
   const captured: Array<Record<string, unknown>> = [];
   const llm = stubLlm({ available: false, capturedOptions: captured, result: { mode: "full" } });
 
-  const result = await planRecallModeLLM("anything", undefined, config, llm, undefined, resolveCapabilities(config));
+  const result = await planRecallModeLLM("anything", undefined, config, resolveCapabilities(config), llm, undefined);
 
   assert.equal(captured.length, 0, "no network attempt when nothing is routable");
   assert.equal(result.source, "heuristic-fallback");
@@ -156,7 +156,7 @@ test("attempts the call (and falls back) when a provider-qualified model overrid
   const captured: Array<Record<string, unknown>> = [];
   const llm = stubLlm({ available: false, capturedOptions: captured, result: null });
 
-  const result = await planRecallModeLLM("anything", undefined, config, llm, undefined, resolveCapabilities(config));
+  const result = await planRecallModeLLM("anything", undefined, config, resolveCapabilities(config), llm, undefined);
 
   assert.equal(captured.length, 1, "qualified model override → still attempt the call");
   assert.equal(captured[0]?.model, "openai/gpt-5.5");
@@ -171,7 +171,7 @@ test("an already-aborted recall short-circuits to the heuristic without an LLM c
   const ac = new AbortController();
   ac.abort();
 
-  const result = await planRecallModeLLM("what did we decide?", undefined, config, llm, ac.signal, resolveCapabilities(config));
+  const result = await planRecallModeLLM("what did we decide?", undefined, config, resolveCapabilities(config), llm, ac.signal);
 
   assert.equal(captured.length, 0, "no LLM call when the recall is already aborted");
   assert.equal(result.source, "heuristic-fallback");
@@ -185,7 +185,7 @@ test("forwards the abort signal into the LLM call (cancellation contract)", asyn
   const llm = stubLlm({ capturedOptions: captured, result: { mode: "minimal" } });
   const ac = new AbortController();
 
-  await planRecallModeLLM("check status", undefined, config, llm, ac.signal, resolveCapabilities(config));
+  await planRecallModeLLM("check status", undefined, config, resolveCapabilities(config), llm, ac.signal);
 
   assert.equal(captured.length, 1);
   assert.equal(captured[0]?.signal, ac.signal, "recall abort signal must reach FallbackLlmClient");
@@ -196,7 +196,7 @@ test("empty prompts skip the LLM entirely", async () => {
   const captured: Array<Record<string, unknown>> = [];
   const llm = stubLlm({ capturedOptions: captured, result: { mode: "full" } });
 
-  const result = await planRecallModeLLM("   ", undefined, config, llm, undefined, resolveCapabilities(config));
+  const result = await planRecallModeLLM("   ", undefined, config, resolveCapabilities(config), llm, undefined);
 
   assert.equal(captured.length, 0);
   assert.equal(result.mode, "no_recall"); // heuristic returns no_recall for empty
@@ -223,3 +223,22 @@ test("resolveRecallPlannerLlmOptions drops bare model names but keeps provider-q
   );
   assert.equal(qualified.model, "anthropic/claude-haiku-4-5");
 });
+
+test("caps.recallPlannerLlm is authoritative — disabled caps wins over enabled config flag (one-resolution-per-op #1523)", async () => {
+  // Issue #1523 contract: the capability resolved at the operation entry is
+  // THE gate. Construct a deliberate mismatch: config says enabled, but the
+  // resolved CapabilitySet says disabled. The function must NOT call the LLM.
+  const config = parseConfig({ recallPlannerLlmEnabled: true });
+  const captured: Array<Record<string, unknown>> = [];
+  const llm = stubLlm({ capturedOptions: captured, result: { mode: "full" } });
+
+  // Manually construct caps with recallPlannerLlm: false (simulating a
+  // resolution that disagrees with the raw config — e.g. session toggle off).
+  const caps = { ...resolveCapabilities(config), recallPlannerLlm: false } as any;
+
+  const result = await planRecallModeLLM("what did we decide?", undefined, config, caps, llm, undefined);
+
+  assert.equal(captured.length, 0, "LLM must not be contacted when caps says disabled, even if config says enabled");
+  assert.equal(result.source, "heuristic");
+  assert.equal(result.reason, "llm-disabled");
+});

package/src/recall-planner-llm.ts

@@ -188,16 +188,15 @@ export async function planRecallModeLLM(
   prompt: string,
   hints: string[] | undefined,
   config: PluginConfig,
+  caps: CapabilitySet,
   llm?: FallbackLlmClient,
   signal?: AbortSignal,
-  caps?: CapabilitySet,
 ): Promise<RecallPlannerLlmResult> {
   const heuristicMode = planRecallMode(prompt);
 
-  // `caps` is OPTIONAL and additive (issue #1523). Prefer the resolved
-  // capability when supplied; fall back to the config flag so existing callers
-  // that pass only `config` keep identical gating.
-  const plannerLlmEnabled = caps?.recallPlannerLlm ?? config.recallPlannerLlmEnabled;
+  // The recall-operation entry resolved this gate once (issue #1523); read the
+  // capability, never re-derive it from raw config here.
+  const plannerLlmEnabled = caps.recallPlannerLlm;
   if (!plannerLlmEnabled) {
     return heuristicResult(heuristicMode, "heuristic", "llm-disabled", 0, false);
   }