@remnic/core 10.0.17 → 10.0.19

package/src/reasoning-trace-recall.ts

@@ -88,6 +88,8 @@ export interface BoostableResult {
   path: string;
   score: number;
   docid?: string;
+  /** Effective relevance carried forward by an upstream rerank stage. */
+  effectiveScore?: number;
 }
 
 /**
@@ -118,6 +120,17 @@ export interface ApplyReasoningTraceBoostOptions {
   boost?: number;
 }
 
+/**
+ * The relevance a row is compared on: its effective relevance when a rerank
+ * stage left one (MMR ranks on the same basis), else the raw retrieval score.
+ */
+function comparisonRelevance(row: BoostableResult): number {
+  if (typeof row.effectiveScore === "number" && Number.isFinite(row.effectiveScore)) {
+    return row.effectiveScore;
+  }
+  return typeof row.score === "number" && Number.isFinite(row.score) ? row.score : 0;
+}
+
 /**
  * Apply a score boost to results whose path sits under reasoning-traces/
  * when the query looks like a problem-solving ask. Returns a new array;
@@ -167,7 +180,18 @@ export function applyReasoningTraceBoost<R extends BoostableResult>(
     if (isReasoningTracePath(r.path)) {
       changed = true;
       const baseScore = typeof r.score === "number" && Number.isFinite(r.score) ? r.score : 0;
-      boosted.push({ ...r, score: baseScore + boostAmount } as R);
+      // Compose the boost into the effective relevance too: a downstream MMR
+      // pass prefers it over the raw score, so a stale value would drop the
+      // boost.
+      const effective =
+        typeof r.effectiveScore === "number" && Number.isFinite(r.effectiveScore)
+          ? r.effectiveScore + boostAmount
+          : undefined;
+      boosted.push(
+        effective === undefined
+          ? ({ ...r, score: baseScore + boostAmount } as R)
+          : ({ ...r, score: baseScore + boostAmount, effectiveScore: effective } as R),
+      );
     } else {
       boosted.push(r);
     }
@@ -175,21 +199,22 @@ export function applyReasoningTraceBoost<R extends BoostableResult>(
   if (!changed) return boosted;
 
   // Step 2: promote each boosted trace upward past any non-trace neighbor
-  // whose score is strictly lower than the boosted score. Non-trace items
-  // never move past each other, so reranker-driven ordering on non-trace
-  // items is preserved.
+  // whose relevance is strictly lower than the boosted trace's. The
+  // comparison uses the SAME basis MMR ranks on — the effective relevance a
+  // rerank stage left behind, else the raw score — so the boost cannot
+  // promote a trace the pipeline deliberately demoted. Non-trace items never
+  // move past each other, so reranker-driven ordering on non-trace items is
+  // preserved.
   const out = boosted.slice();
   for (let i = 0; i < out.length; i++) {
     if (!isReasoningTracePath(out[i].path)) continue;
     const trace = out[i];
-    const traceScore =
-      typeof trace.score === "number" && Number.isFinite(trace.score) ? trace.score : 0;
+    const traceScore = comparisonRelevance(trace);
     let j = i;
     while (j > 0) {
       const prev = out[j - 1];
       if (isReasoningTracePath(prev.path)) break; // don't reorder traces vs each other
-      const prevScore =
-        typeof prev.score === "number" && Number.isFinite(prev.score) ? prev.score : 0;
+      const prevScore = comparisonRelevance(prev);
       if (prevScore >= traceScore) break;
       out[j] = prev;
       j -= 1;

package/src/recall-mmr.ts

@@ -459,6 +459,11 @@ export interface MmrRecallResult {
   readonly path?: string;
   readonly snippet?: string;
   readonly score?: number;
+  /**
+   * Effective relevance carried forward by the rerank stage that last
+   * adjusted the result. Preferred over `score` for MMR's relevance term.
+   */
+  readonly effectiveScore?: number;
 }
 
 export interface ReorderRecallResultsOptions {
@@ -545,7 +550,7 @@ export function reorderRecallResultsWithMmr<R extends MmrRecallResult>(
   const candidates: MmrCandidate[] = results.map((r, index) => ({
     id: makeRecallKey(r, index),
     content: r.snippet ?? "",
-    score: typeof r.score === "number" ? r.score : 0,
+    score: effectiveRelevance(r),
     embedding: null,
   }));
   // Index lookup by id so we can map MMR-selected candidates back to their
@@ -601,6 +606,17 @@ export function reorderRecallResultsWithMmr<R extends MmrRecallResult>(
   return { reordered, diversity, lambda };
 }
 
+/**
+ * Relevance for MMR's `sim(d, query)` term: the effective relevance an
+ * upstream rerank stage carried forward, else the raw retrieval score.
+ */
+function effectiveRelevance(r: MmrRecallResult): number {
+  if (typeof r.effectiveScore === "number" && Number.isFinite(r.effectiveScore)) {
+    return r.effectiveScore;
+  }
+  return typeof r.score === "number" ? r.score : 0;
+}
+
 function makeRecallKey(r: MmrRecallResult, index: number): string {
   const baseKey = r.path || r.docid || "";
   return `${baseKey}::${index}`;

package/src/recall-rerank-coordinator.test.ts

@@ -24,6 +24,8 @@ import test from "node:test";
 import { parseConfig } from "./config.js";
 import { resolveCapabilities } from "./capabilities.js";
 import { RecallRerankCoordinator } from "./orchestration/recall-rerank-coordinator.js";
+import { applyReasoningTraceBoost } from "./reasoning-trace-recall.js";
+import { DRIFT_DETECTION_DEFAULTS } from "./preferences/drift-config.js";
 import { Orchestrator } from "./orchestrator.js";
 import type { PluginConfig, QmdSearchResult, MemoryFile } from "./types.js";
 import type { StorageManager } from "./index.js";
@@ -720,3 +722,276 @@ test("#2859 linkless superseded status does not consume a packet slot", () => {
     "status-only superseded rows are rejected before the packet cap",
   );
 });
+
+
+// ─── #3226 — the rerank stages' relevance survives the MMR pass ───────────
+/**
+ * The rerank stages decide an order, but the MMR pass re-derived relevance
+ * from the RAW retrieval score and undid it. Each stage now carries its own
+ * relevance (`QmdSearchResult.effectiveScore`) forward and MMR ranks by that.
+ *
+ * The raw scores are WIDELY SEPARATED (100 vs 0.1) on purpose: a fix that
+ * approximates the stage's decision with `raw score × multiplier` still fails.
+ */
+
+/** Frontmatter double at an explicit path (the cast mirrors `mem` above). */
+function memAt(memPath: string, frontmatter: Record<string, unknown>): MemoryFile {
+  return { path: memPath, frontmatter: frontmatter as unknown as MemoryFile["frontmatter"], content: memPath };
+}
+
+/** `/facts/<id>.md` frontmatter map from `[id, mw_success?, mw_fail?]` rows. */
+function facts(rows: Array<[string, number?, number?]>): Map<string, MemoryFile> {
+  return new Map(rows.map(([id, ok, fail]) => [`/facts/${id}.md`, mem(id, ok, fail)]));
+}
+
+function coordinatorFor(config: PluginConfig): RecallRerankCoordinator {
+  const corpus = makeFakes([]);
+  return new RecallRerankCoordinator({
+    getConfig: () => config,
+    getStorage: corpus.getStorage,
+    readQmdResultMemory: async () => null,
+  });
+}
+
+const WORTH_RESULTS = [result("bad", 100), result("good", 0.1)];
+const WORTH_FM = facts([["bad", 0, 10], ["good", 10, 0]]);
+const TRUST_CONFIG = { recallMemoryWorthFilterEnabled: false, trustScoreEnabled: true, recallMmrEnabled: true, recallMmrLambda: 1 };
+
+for (const lambda of [1, 0.7]) {
+  test(`#3226: a Memory-Worth promotion survives MMR (lambda ${lambda})`, async () => {
+    const coord = coordinatorFor(await baseConfig({ recallMmrEnabled: true, recallMmrLambda: lambda }));
+    const before = WORTH_RESULTS.map((r) => ({ ...r }));
+    const staged = await coord.applyMemoryWorthRerank(WORTH_RESULTS, ["default"], WORTH_FM);
+    const applied = coord.diversifyAndLimitRecallResults("memories", staged, 1);
+    assert.deepEqual(applied.map((r) => r.path), ["/facts/good.md"], "MMR must not undo the promotion");
+    assert.deepEqual(WORTH_RESULTS, before, "the stage must not mutate its input");
+  });
+}
+
+type Scenario = {
+  name: string;
+  config: Partial<PluginConfig>;
+  stage: (c: RecallRerankCoordinator, r: QmdSearchResult[], p: Map<string, MemoryFile>) => Promise<QmdSearchResult[]>;
+  results: QmdSearchResult[];
+  preloaded: Map<string, MemoryFile>;
+  applied: string[];
+};
+
+const SCENARIOS: Scenario[] = [
+  {
+    name: "a TrustScore demotion survives MMR",
+    config: TRUST_CONFIG,
+    stage: async (c, r, p) => (await c.applyTrustScoreRerank(r, ["default"], p)).results,
+    results: [result("untrusted", 100), result("trusted", 1), result("plain", 0.1)],
+    preloaded: facts([["untrusted", 0, 10], ["trusted", 10, 0], ["plain"]]),
+    applied: ["/facts/trusted.md"],
+  },
+  {
+    name: "a quarantined memory is not resurrected by MMR",
+    config: TRUST_CONFIG,
+    stage: async (c, r, p) => (await c.applyTrustScoreRerank(r, ["default"], p)).results,
+    results: [result("contradicted", 100), result("kept", 0.1)],
+    preloaded: new Map([
+      ["/facts/contradicted.md", memAt("/facts/contradicted.md", { faithfulness: { verdict: "contradicted" } })],
+      ["/facts/kept.md", mem("kept")],
+    ]),
+    applied: ["/facts/kept.md"],
+  },
+  {
+    name: "preference-drift damping survives MMR",
+    config: { recallMmrEnabled: true, recallMmrLambda: 1, driftDetection: { ...DRIFT_DETECTION_DEFAULTS, recallDamping: true, stalePenalty: 0.25 } },
+    stage: (c, r, p) => c.applyPreferenceDriftStage(r, ["default"], p),
+    results: [result("stale", 100), result("fresh", 0.1)],
+    preloaded: new Map([
+      ["/facts/stale.md", memAt("/facts/stale.md", { category: "preference", driftState: "stale" })],
+      ["/facts/fresh.md", memAt("/facts/fresh.md", { category: "fact" })],
+    ]),
+    applied: ["/facts/fresh.md"],
+  },
+];
+
+for (const scenario of SCENARIOS) {
+  test(`#3226: ${scenario.name}`, async () => {
+    const coord = coordinatorFor(await baseConfig(scenario.config));
+    const before = scenario.results.map((r) => ({ ...r }));
+    const staged = await scenario.stage(coord, scenario.results, scenario.preloaded);
+    const applied = coord.diversifyAndLimitRecallResults("memories", staged, 1);
+    assert.deepEqual(applied.map((r) => r.path), scenario.applied, "MMR must not undo the stage");
+    assert.deepEqual(scenario.results, before, "the stage must not mutate its input");
+  });
+}
+
+test("#3226: MMR off leaves the branch order verbatim", async () => {
+  const coord = coordinatorFor(await baseConfig({ recallMmrEnabled: false }));
+  // Two near-duplicates plus one orthogonal candidate: with MMR on, lambda 0.3
+  // promotes the orthogonal candidate into slot 2 — this pins that MMR was off.
+  const branch: QmdSearchResult[] = [
+    { docid: "d1", path: "p/d1", snippet: "rocket thrust vectoring", score: 0.99 },
+    { docid: "d2", path: "p/d2", snippet: "rocket thrust vectoring", score: 0.98 },
+    { docid: "o1", path: "p/o1", snippet: "coffee brewing at high altitude", score: 0.4 },
+  ];
+  const applied = coord.diversifyAndLimitRecallResults("memories", branch, 2);
+  assert.deepEqual(applied.map((r) => r.docid), ["d1", "d2"], "MMR off: the branch order is the applied order");
+});
+
+test("#3226: without a rerank stage MMR keeps using the raw score", async () => {
+  const config = await baseConfig({ recallMemoryWorthFilterEnabled: false, trustScoreEnabled: false });
+  const coord = coordinatorFor(config);
+  const results = [result("a", 0.9), result("b", 0.8)];
+  const outcome = await coord.applyTrustScoreToBranch(results, ["default"], resolveCapabilities(config), "test");
+  assert.deepEqual(outcome.results, results, "no stage ran: the results come back untouched");
+  for (const r of outcome.results) assert.equal(r.effectiveScore, undefined, "no relevance is attached");
+});
+
+test("#3226: a no-op stage leaves the results byte-identical", async () => {
+  const coord = coordinatorFor(await baseConfig());
+  const results = [result("a", 0.9), result("b", 0.8)];
+  const staged = await coord.applyMemoryWorthRerank(results, ["default"], facts([["a"], ["b"]]));
+  assert.deepEqual(staged, results, "a neutral stage returns the input unchanged");
+  for (const r of staged) assert.equal(r.effectiveScore, undefined, "a no-op stage attaches no relevance");
+});
+
+test("#3226: an annotation-only drift stage keeps the upstream effective relevance", async () => {
+  const config = await baseConfig({ driftDetection: { ...DRIFT_DETECTION_DEFAULTS, annotateAfterDays: 30 } });
+  const coord = coordinatorFor(config);
+  const preloaded = new Map<string, MemoryFile>([
+    ["/facts/bad.md", memAt("/facts/bad.md", { mw_success: 0, mw_fail: 10 })],
+    ["/facts/good.md", memAt("/facts/good.md", { mw_success: 10, mw_fail: 0, category: "preference", lastCorroborated: "2020-01-01" })],
+  ]);
+  const staged = await coord.applyMemoryWorthRerank(WORTH_RESULTS, ["default"], preloaded);
+  const annotated = await coord.applyPreferenceDriftStage(staged, ["default"], preloaded);
+  assert.deepEqual(annotated.map((r) => r.path), ["/facts/good.md", "/facts/bad.md"], "the order is unchanged");
+  assert.ok(annotated[0]?.driftNote, "the age note is still attached");
+  assert.equal(typeof staged[0]?.effectiveScore, "number", "the stage attached a relevance");
+  assert.equal(annotated[0]?.effectiveScore, staged[0]?.effectiveScore, "the upstream relevance survives");
+});
+
+for (const boostCase of [
+  {
+    name: "a strongly demoted trace does not leapfrog a high-effective fact",
+    frontmatter: { mw_success: 0, mw_fail: 10 },
+    applied: "/facts/fact.md",
+  },
+  {
+    name: "a near-equal effective relevance lets the boost promote the trace",
+    frontmatter: { mw_success: 1000, mw_fail: 0 },
+    applied: "/reasoning-traces/trace.md",
+  },
+]) {
+  test(`#3226: the reasoning-trace boost — ${boostCase.name}`, async () => {
+    // The boost capability is off here: the boost is applied explicitly so the
+    // MMR pass sees exactly the boosted array.
+    const coord = coordinatorFor(await baseConfig({ recallMmrEnabled: true, recallMmrLambda: 1 }));
+    const staged = await coord.applyMemoryWorthRerank(
+      [
+        { ...result("fact", 0.9), path: "/facts/fact.md" },
+        { ...result("trace", 0.8), path: "/reasoning-traces/trace.md" },
+      ],
+      ["default"],
+      new Map([
+        ["/facts/fact.md", memAt("/facts/fact.md", {})],
+        ["/reasoning-traces/trace.md", memAt("/reasoning-traces/trace.md", boostCase.frontmatter)],
+      ]),
+    );
+    const trace = staged.find((r) => r.path === "/reasoning-traces/trace.md");
+    assert.ok(trace, "the trace is staged");
+    const boosted = applyReasoningTraceBoost(staged, { enabled: true, query: "how do I fix the build?" });
+    const boostedTrace = boosted.find((r) => r.path === "/reasoning-traces/trace.md");
+    assert.ok(boostedTrace, "the trace survives the boost");
+    assert.equal(boostedTrace.score, trace.score + 0.15, "the raw score keeps its boost");
+    assert.equal(
+      boostedTrace.effectiveScore,
+      trace.effectiveScore! + 0.15,
+      "the exact adjustment is attached to the effective relevance",
+    );
+    const applied = coord.diversifyAndLimitRecallResults("memories", boosted, 1);
+    assert.deepEqual(
+      applied.map((r) => r.path),
+      [boostCase.applied],
+      "the final order follows the effective relevance",
+    );
+  });
+}
+
+for (const poolSize of [10, 40]) {
+  test(`#3226: reasoning boost keeps its scale in a ${poolSize}-candidate adjusted pool`, async () => {
+    const coord = coordinatorFor(await baseConfig({ recallMmrEnabled: true, recallMmrLambda: 1 }));
+    const candidates = [
+      result("fact", 0.9),
+      { ...result("trace", 0.8), path: "/reasoning-traces/trace.md" },
+      ...Array.from({ length: poolSize - 3 }, (_, index) => result(`plain-${index}`, 0.7)),
+      result("bad", 0.1),
+    ];
+    const frontmatter = new Map(candidates.map((candidate) => [
+      candidate.path,
+      memAt(candidate.path, candidate.path === "/facts/bad.md" ? { mw_success: 0, mw_fail: 10 } : {}),
+    ]));
+    const staged = await coord.applyMemoryWorthRerank(candidates, ["default"], frontmatter);
+    const boosted = applyReasoningTraceBoost(staged, { enabled: true, query: "how do I fix this?" });
+    assert.equal(
+      coord.diversifyAndLimitRecallResults("memories", boosted, 1)[0]?.path,
+      "/reasoning-traces/trace.md",
+      "a neutral adjacent trace must retain a meaningful boost when another candidate is adjusted",
+    );
+  });
+}
+
+test("#3226: quarantined prefixes do not compress survivor relevance", async () => {
+  const coord = coordinatorFor(await baseConfig(TRUST_CONFIG));
+  const survivors = [result("trusted", 0.9), result("untrusted", 0.8)];
+  const quarantined = Array.from({ length: 20 }, (_, index) => result(`quarantined-${index}`, 1));
+  const frontmatter = new Map([
+    ...facts([["trusted", 10, 0], ["untrusted", 0, 10]]),
+    ...quarantined.map((candidate) => [
+      candidate.path,
+      memAt(candidate.path, { faithfulness: { verdict: "contradicted" } }),
+    ] as const),
+  ]);
+  const baseline = (await coord.applyTrustScoreRerank(survivors, ["default"], frontmatter)).results;
+  const prefixed = (await coord.applyTrustScoreRerank([...quarantined, ...survivors], ["default"], frontmatter)).results;
+  assert.deepEqual(
+    prefixed.map((candidate) => [candidate.path, candidate.effectiveScore]),
+    baseline.map((candidate) => [candidate.path, candidate.effectiveScore]),
+    "excluded candidates must not change the surviving pool's relevance scale",
+  );
+});
+
+test("#3226: quarantine placement does not change survivor relevance", async () => {
+  const coord = coordinatorFor(await baseConfig(TRUST_CONFIG));
+  const survivors = [result("trusted", 0.9), result("untrusted", 0.8), result("plain", 0.7)];
+  const excluded = Array.from({ length: 20 }, (_, index) => result(`excluded-${index}`, 1));
+  const frontmatter = new Map([
+    ...facts([["trusted", 10, 0], ["untrusted", 0, 10], ["plain"]]),
+    ...excluded.map((candidate) => [
+      candidate.path, memAt(candidate.path, { faithfulness: { verdict: "contradicted" } }),
+    ] as const),
+  ]);
+  const baseline = (await coord.applyTrustScoreRerank(survivors, ["default"], frontmatter)).results;
+  for (const split of [0, 1, 2, 3]) {
+    const input = [...survivors.slice(0, split), ...excluded, ...survivors.slice(split)];
+    const admitted = (await coord.applyTrustScoreRerank(input, ["default"], frontmatter)).results;
+    assert.deepEqual(
+      admitted.map((candidate) => [candidate.path, candidate.effectiveScore]),
+      baseline.map((candidate) => [candidate.path, candidate.effectiveScore]),
+      `excluded rows at position ${split} must not leave rank holes`,
+    );
+  }
+});
+
+test("#3226: active drift damping composes upstream effective relevance", async () => {
+  const coord = coordinatorFor(await baseConfig({
+    driftDetection: { ...DRIFT_DETECTION_DEFAULTS, recallDamping: true, stalePenalty: 0.25 },
+  }));
+  const candidates = [
+    { ...result("top", 0.1), effectiveScore: 0.95 },
+    { ...result("stale", 100), effectiveScore: 0.9 },
+    { ...result("tail", 0.8), effectiveScore: 0.1 },
+  ];
+  const frontmatter = new Map(candidates.map((candidate) => [
+    candidate.path,
+    memAt(candidate.path, candidate.path === "/facts/stale.md" ? { category: "preference", driftState: "stale" } : {}),
+  ]));
+  const damped = await coord.applyPreferenceDriftStage(candidates, ["default"], frontmatter);
+  assert.deepEqual(damped.map((candidate) => candidate.effectiveScore), [0.95, 0.9 * 0.25, 0.1]);
+  assert.deepEqual(candidates.map((candidate) => candidate.effectiveScore), [0.95, 0.9, 0.1], "inputs remain unmodified");
+});

package/src/types.ts

@@ -3460,6 +3460,11 @@ export interface QmdSearchResult extends OriginMetadata, RecallDriftAnnotation,
   path: string;
   snippet: string;
   score: number;
+  /**
+   * Pool-normalized rank × multiplier from the last adjusted rerank stage.
+   * MMR prefers it over `score`; additive boosts compose on this scale.
+   */
+  effectiveScore?: number;
   line?: number;
   explain?: QmdSearchExplain;
   transport?: "daemon" | "subprocess" | "hybrid" | "scoped_prefilter";