@remnic/core 9.65.1 → 9.65.3

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

@@ -24,6 +24,11 @@ import {
   buildMemoryWorthCounterMap,
   type MemoryWorthCounters,
 } from "../memory-worth-filter.js";
+import {
+  applyPreferenceDriftRanking,
+  isPreferenceDriftStageActive,
+  type DriftRecallFrontmatter,
+} from "../preferences/drift-recall.js";
 import {
   applyTrustScoreStage,
   buildTrustSignalsForRerank,
@@ -470,9 +475,16 @@ export class RecallRerankCoordinator {
     results: QmdSearchResult[];
     trustByPath: Map<string, TrustStageResultItem> | null;
   }> {
+    // The trust stage and the Memory Worth multiplier are mutually exclusive
+    // (rule 39); the preference-drift stage runs AFTER whichever one applied,
+    // on every branch, so its gate is uniform across recall paths (§27).
+    let staged = results;
+    let trustByPath: Map<string, TrustStageResultItem> | null = null;
     if (caps.recallTrustScore && results.length > 0) {
       try {
-        return await this.applyTrustScoreRerank(results, namespaces, preloadedFrontmatter, abortSignal);
+        const outcome = await this.applyTrustScoreRerank(results, namespaces, preloadedFrontmatter, abortSignal);
+        staged = outcome.results;
+        trustByPath = outcome.trustByPath;
       } catch (err) {
         log.debug(`trust-score stage (${label}) failed open`, {
           error: (err as Error).message,
@@ -480,20 +492,127 @@ export class RecallRerankCoordinator {
       }
     } else if (caps.recallMemoryWorthFilter && results.length > 0) {
       try {
-        const filtered = await this.applyMemoryWorthRerank(
+        staged = await this.applyMemoryWorthRerank(
           results,
           namespaces,
           preloadedFrontmatter,
           abortSignal,
         );
-        return { results: filtered, trustByPath: null };
       } catch (err) {
         log.debug(`memory-worth filter (${label}) failed open`, {
           error: (err as Error).message,
         });
       }
     }
-    return { results, trustByPath: null };
+    const damped = await this.applyPreferenceDriftStage(
+      staged,
+      namespaces,
+      preloadedFrontmatter,
+      abortSignal,
+    );
+    return { results: damped, trustByPath };
+  }
+
+  /**
+   * Issue #2371 — stale-preference damping + injection annotation.
+   *
+   * Runs immediately after the trust/Memory-Worth stage on EVERY recall branch
+   * (hot QMD, embedding fallback, recent scan, cold fallback), so the feature
+   * gate applies uniformly and fallback parity holds (§27, AGENTS.md retrieval
+   * guardrails). Fully inert on the default config: when neither damping nor
+   * annotation is active the input array is returned untouched and NO
+   * frontmatter is read, so recall ordering and injected text stay
+   * byte-identical to pre-#2371.
+   *
+   * Fail-open: any lookup error leaves the branch's results unchanged.
+   */
+  async applyPreferenceDriftStage(
+    results: QmdSearchResult[],
+    namespaces: string[],
+    preloadedFrontmatter?: ReadonlyMap<string, MemoryFile>,
+    abortSignal?: AbortSignal,
+  ): Promise<QmdSearchResult[]> {
+    const config = this.getConfig();
+    if (!isPreferenceDriftStageActive(config.driftDetection)) return results;
+    if (results.length === 0) return results;
+
+    try {
+      const frontmatterByKey = new Map<string, DriftRecallFrontmatter>();
+      const missing: QmdSearchResult[] = [];
+      for (const r of results) {
+        const key = memoryMapKey(r);
+        const preloaded = preloadedFrontmatter?.get(key) ?? preloadedFrontmatter?.get(r.path);
+        if (preloaded) {
+          frontmatterByKey.set(key, preloaded.frontmatter);
+        } else {
+          missing.push(r);
+        }
+      }
+
+      // Branches without a preloaded map (embedding fallback) read the
+      // candidates directly. Bounded-parallel at the same batch size the
+      // Memory Worth stage uses, and only for the handful of candidates the
+      // branch actually returned — never a corpus scan.
+      if (missing.length > 0) {
+        let reader: StorageManager | null = null;
+        for (const ns of namespaces) {
+          try {
+            reader = await this.getStorage(ns);
+            break;
+          } catch {
+            // try next namespace
+          }
+        }
+        if (reader) {
+          const readerNn = reader;
+          const BATCH = 16;
+          for (let off = 0; off < missing.length; off += BATCH) {
+            if (abortSignal?.aborted) break;
+            await Promise.all(
+              missing.slice(off, off + BATCH).map(async (r) => {
+                try {
+                  const memory = await this.readQmdResultMemory(r.path, readerNn, namespaces, r.namespace);
+                  if (memory) frontmatterByKey.set(memoryMapKey(r), memory.frontmatter);
+                } catch (err) {
+                  log.debug("preference-drift: direct path lookup failed", {
+                    path: r.path,
+                    error: (err as Error).message,
+                  });
+                }
+              }),
+            );
+          }
+        }
+      }
+
+      // Synthetic monotone-decreasing rank score so neutral candidates keep
+      // their upstream order and only the damped ones move — same technique the
+      // Memory Worth stage uses, for the same reason.
+      const ranked = results.map((r, i) => ({
+        key: memoryMapKey(r),
+        rank: results.length - i,
+        frontmatter: frontmatterByKey.get(memoryMapKey(r)),
+      }));
+      const ordered = applyPreferenceDriftRanking(ranked, {
+        config: config.driftDetection,
+        now: new Date(),
+      });
+
+      const byKey = new Map(results.map((r) => [memoryMapKey(r), r]));
+      const reordered: QmdSearchResult[] = [];
+      for (const item of ordered) {
+        const original = byKey.get(item.key);
+        if (!original) continue;
+        // `driftNote` is copied onto a NEW result object — never mutated in
+        // place — so a shared upstream result can't leak an annotation into an
+        // unrelated branch.
+        reordered.push(item.note ? { ...original, driftNote: item.note } : original);
+      }
+      return reordered;
+    } catch (err) {
+      log.debug("preference-drift stage failed open", { error: (err as Error).message });
+      return results;
+    }
   }
 
   diversifyRecallResultsWithHeadroom(

package/src/orchestration/recall-result-formatter.ts

@@ -230,14 +230,18 @@ export class RecallResultFormatter {
       const withHandle = handle ? `${head.trimEnd()} ${handle}` : head.trimEnd();
       const connectorLabel = renderConnectorLabel(r.sourceConnector);
       const withConnector = connectorLabel ? `${withHandle} [agent: ${connectorLabel}]` : withHandle;
+      // Preference age note (issue #2371). Set only when
+      // `driftDetection.annotateAfterDays` is on, so this suffix is absent —
+      // and the rendered line byte-identical to pre-#2371 — by default.
+      const withDrift = r.driftNote ? `${withConnector} ${r.driftNote}` : withConnector;
       if (hedgeMap) {
         const item = trustResultFor(hedgeMap, r);
         if (item) {
           const hedge = renderEpistemicHedge(item.trust);
-          if (hedge.length > 0) return `${withConnector} ${hedge}`;
+          if (hedge.length > 0) return `${withDrift} ${hedge}`;
         }
       }
-      return withConnector;
+      return withDrift;
     });
     return { heading: `## ${title}`, entries };
   }

package/src/orchestration/recall-search-pipeline.ts

@@ -113,7 +113,10 @@ export interface RecallSearchPipelineDeps {
     recallNamespaces: string[],
   ): Promise<QueryAwarePrefilter>;
   readonly config: PluginConfig;
-  readonly recallRerankCoordinator: Pick<RecallRerankCoordinator, "diversifyRecallResultsWithHeadroom">;
+  readonly recallRerankCoordinator: Pick<
+    RecallRerankCoordinator,
+    "diversifyRecallResultsWithHeadroom" | "applyPreferenceDriftStage"
+  >;
   diversifyAndLimitRecallResults(
     sectionId: string,
     results: QmdSearchResult[],
@@ -954,6 +957,16 @@ export class RecallSearchPipelineCoordinator {
         });
       }
     }
+    // Cold fallback boosts inline rather than through applyTrustScoreToBranch,
+    // so the preference-drift stage is applied here explicitly — otherwise
+    // damping would silently not apply to this branch (§27 fallback parity).
+    if (results.length > 0) {
+      results = await this.deps.recallRerankCoordinator.applyPreferenceDriftStage(
+        results,
+        options.recallNamespaces,
+        boostInput.memoryByPath,
+      );
+    }
 
     if (options.xrayPoolSizeSink) {
       options.xrayPoolSizeSink.size = Math.max(

package/src/preferences/drift-config.ts

@@ -0,0 +1,118 @@
+/**
+ * Preference drift detection config (issue #2371).
+ *
+ * Standalone top-level block, parsed the same way `contradictionScan` and
+ * `procedural.maintenance` are: shape-validated, string-coercion safe (§24),
+ * and honoring documented zero/no-op values (§33) rather than clamping them
+ * to something non-zero.
+ */
+
+import { coerceBool, coerceNumber } from "../connectors/coerce.js";
+
+export interface DriftDetectionConfig {
+  /** Master switch for drift classification and its apply mode. Default false. */
+  enabled: boolean;
+  /** A preference younger than this is never a scan candidate. Default 60. */
+  minAgeDays: number;
+  /** Evidence-gathering window, in days back from the run instant. Default 45. */
+  lookbackDays: number;
+  /** Cap on preferences classified per run. `0` disables the scan entirely. Default 25. */
+  maxCandidatesPerRun: number;
+  /** When true, recall damps `driftState: stale` preferences. Default false. */
+  recallDamping: boolean;
+  /** Multiplier applied to stale preferences in (0, 1]; `1` is a documented no-op. Default 0.8. */
+  stalePenalty: number;
+  /** Annotate injected preferences uncorroborated for this many days. `0` = off. Default 0. */
+  annotateAfterDays: number;
+}
+
+export const DRIFT_DETECTION_DEFAULTS: DriftDetectionConfig = {
+  enabled: false,
+  minAgeDays: 60,
+  lookbackDays: 45,
+  maxCandidatesPerRun: 25,
+  recallDamping: false,
+  stalePenalty: 0.8,
+  annotateAfterDays: 0,
+};
+
+function parseFlag(src: Record<string, unknown>, key: string, fallback: boolean): boolean {
+  const value = src[key];
+  if (value === undefined || value === null) return fallback;
+  const coerced = coerceBool(value);
+  if (coerced === undefined) {
+    throw new Error(
+      `driftDetection.${key} must be a boolean or one of "true"/"false"/"1"/"0"/"yes"/"no"/"on"/"off" (got ${JSON.stringify(value)}).`,
+    );
+  }
+  return coerced;
+}
+
+function parseDayCount(src: Record<string, unknown>, key: string, fallback: number): number {
+  const value = src[key];
+  if (value === undefined || value === null) return fallback;
+  const coerced = coerceNumber(value);
+  if (coerced === undefined || !Number.isFinite(coerced)) {
+    throw new Error(`driftDetection.${key} must be a finite number (got ${JSON.stringify(value)}).`);
+  }
+  if (!Number.isInteger(coerced)) {
+    throw new Error(`driftDetection.${key} must be an integer (got ${JSON.stringify(value)}).`);
+  }
+  if (coerced < 0 || coerced > 36_500) {
+    throw new Error(`driftDetection.${key} must be between 0 and 36500 (got ${JSON.stringify(value)}).`);
+  }
+  return coerced;
+}
+
+export function parseDriftDetectionConfig(raw: unknown): DriftDetectionConfig {
+  if (raw === undefined || raw === null) return { ...DRIFT_DETECTION_DEFAULTS };
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(
+      `driftDetection must be an object (got ${JSON.stringify(raw)}). Omit the key to keep drift detection disabled (issue #2371).`,
+    );
+  }
+  const src = raw as Record<string, unknown>;
+
+  // `0` disables the scan and MUST survive as zero — the documented disable
+  // value, never coerced up to a minimum (§33).
+  const rawMax = src.maxCandidatesPerRun;
+  let maxCandidatesPerRun = DRIFT_DETECTION_DEFAULTS.maxCandidatesPerRun;
+  if (rawMax !== undefined && rawMax !== null) {
+    const coerced = coerceNumber(rawMax);
+    if (coerced === undefined || !Number.isInteger(coerced) || coerced < 0) {
+      throw new Error(
+        `driftDetection.maxCandidatesPerRun must be an integer >= 0 (got ${JSON.stringify(rawMax)}). Use 0 to disable the scan.`,
+      );
+    }
+    maxCandidatesPerRun = coerced;
+  }
+
+  // stalePenalty is a multiplier in (0, 1]. `1` is the documented no-op; `0`
+  // would erase a memory's rank entirely and is rejected rather than accepted
+  // as a silent "delete from recall".
+  const rawPenalty = src.stalePenalty;
+  let stalePenalty = DRIFT_DETECTION_DEFAULTS.stalePenalty;
+  if (rawPenalty !== undefined && rawPenalty !== null) {
+    const coerced = coerceNumber(rawPenalty);
+    if (coerced === undefined || !Number.isFinite(coerced) || coerced <= 0 || coerced > 1) {
+      throw new Error(
+        `driftDetection.stalePenalty must be a number in (0, 1] (got ${JSON.stringify(rawPenalty)}). Use 1 to disable damping without changing the flag.`,
+      );
+    }
+    stalePenalty = coerced;
+  }
+
+  return {
+    enabled: parseFlag(src, "enabled", DRIFT_DETECTION_DEFAULTS.enabled),
+    minAgeDays: parseDayCount(src, "minAgeDays", DRIFT_DETECTION_DEFAULTS.minAgeDays),
+    lookbackDays: parseDayCount(src, "lookbackDays", DRIFT_DETECTION_DEFAULTS.lookbackDays),
+    maxCandidatesPerRun,
+    recallDamping: parseFlag(src, "recallDamping", DRIFT_DETECTION_DEFAULTS.recallDamping),
+    stalePenalty,
+    annotateAfterDays: parseDayCount(
+      src,
+      "annotateAfterDays",
+      DRIFT_DETECTION_DEFAULTS.annotateAfterDays,
+    ),
+  };
+}

package/src/preferences/drift-recall.ts

@@ -0,0 +1,133 @@
+/**
+ * Stale-preference recall stage (issue #2371).
+ *
+ * Pure ranking + annotation helpers, deliberately free of storage, LLM, and
+ * config-loading imports so the recall hot path can import them without
+ * pulling in the drift scan's dependency graph.
+ *
+ * Two independent, independently-gated effects:
+ *
+ *   1. `driftDetection.recallDamping` multiplies the rank score of a
+ *      `category: preference` memory carrying `driftState: stale` by
+ *      `stalePenalty`, so a stale preference sinks below an otherwise-equal
+ *      fresh memory. Applied in the same boost stage as the Memory Worth
+ *      multiplier, so the pipeline-order contract (retrieve → filter →
+ *      rerank/boost → cap → format) is untouched.
+ *   2. `driftDetection.annotateAfterDays` emits a compact age note for a
+ *      preference whose last corroboration is older than the configured
+ *      window. Formatting-stage only — it never mutates the stored memory.
+ *
+ * Both are off by default, and with both off this module returns the input
+ * order and no notes, so recall output is byte-identical to pre-#2371.
+ */
+
+import type { DriftDetectionConfig } from "./drift-config.js";
+import type { MemoryDriftState } from "./drift-types.js";
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/** The only frontmatter fields this stage reads. */
+export interface DriftRecallFrontmatter {
+  category?: string;
+  driftState?: MemoryDriftState;
+  lastCorroborated?: string;
+  created?: string;
+}
+
+export interface DriftRankInput {
+  /** Opaque candidate identity — the caller's composite (namespace, path) key. */
+  key: string;
+  /** Monotone-decreasing rank score preserving upstream order. */
+  rank: number;
+  frontmatter?: DriftRecallFrontmatter;
+}
+
+export interface DriftRankOutput {
+  key: string;
+  /** `1` when untouched, `stalePenalty` when damped. */
+  multiplier: number;
+  /** Injection annotation, when the age gate fired. */
+  note?: string;
+}
+
+/**
+ * True when this stage would change nothing. Callers use it to skip the
+ * frontmatter lookups entirely on the default (all-off) configuration.
+ *
+ * `stalePenalty === 1` is the documented no-op (§33): damping stays "enabled"
+ * but multiplies by one, so it must not by itself activate the stage.
+ */
+export function isPreferenceDriftStageActive(config: DriftDetectionConfig | undefined): boolean {
+  if (!config) return false;
+  // `recallDamping` is a real boolean here: parseDriftDetectionConfig already
+  // coerced the string forms and threw on anything unrecognized, so no further
+  // coercion is needed at this boundary.
+  const damping = config.recallDamping && config.stalePenalty < 1;
+  return damping || config.annotateAfterDays > 0;
+}
+
+/**
+ * Render the age note for an uncorroborated preference, or `undefined` when
+ * the gate is off or the preference is inside the window.
+ *
+ * `lastCorroborated` absent falls back to `created`: a preference the scan has
+ * never corroborated is measured from when it was stated, which is exactly the
+ * "stated 2026-01; not corroborated since" case the survey describes.
+ */
+export function driftAgeNote(
+  frontmatter: DriftRecallFrontmatter | undefined,
+  config: DriftDetectionConfig,
+  now: Date,
+): string | undefined {
+  if (config.annotateAfterDays <= 0) return undefined;
+  if (!frontmatter || frontmatter.category !== "preference") return undefined;
+  const anchor = frontmatter.lastCorroborated ?? frontmatter.created;
+  if (typeof anchor !== "string") return undefined;
+  const anchorMs = Date.parse(anchor);
+  if (!Number.isFinite(anchorMs)) return undefined;
+  const ageDays = Math.floor((now.getTime() - anchorMs) / DAY_MS);
+  if (ageDays < config.annotateAfterDays) return undefined;
+  const stated = new Date(anchorMs).toISOString().slice(0, 7);
+  return frontmatter.lastCorroborated
+    ? `(corroborated ${stated}; not since)`
+    : `(stated ${stated}; not corroborated since)`;
+}
+
+/**
+ * Rank and annotate one recall branch's candidates.
+ *
+ * Returns one output per input, ordered by damped rank descending with a
+ * stable key tiebreak so the comparator is total and the ordering is identical
+ * across runs (§12).
+ */
+export function applyPreferenceDriftRanking(
+  inputs: readonly DriftRankInput[],
+  options: { config: DriftDetectionConfig; now: Date },
+): DriftRankOutput[] {
+  const { config, now } = options;
+  const damping = config.recallDamping && config.stalePenalty < 1;
+
+  const scored = inputs.map((input, index) => {
+    const fm = input.frontmatter;
+    const isStalePreference = fm?.category === "preference" && fm.driftState === "stale";
+    const multiplier = damping && isStalePreference ? config.stalePenalty : 1;
+    return {
+      key: input.key,
+      index,
+      multiplier,
+      damped: input.rank * multiplier,
+      note: driftAgeNote(fm, config, now),
+    };
+  });
+
+  scored.sort((a, b) => {
+    if (a.damped !== b.damped) return a.damped > b.damped ? -1 : 1;
+    // Equal damped score → preserve upstream order, then key, so the
+    // comparator returns 0 only for genuinely identical entries.
+    if (a.index !== b.index) return a.index < b.index ? -1 : 1;
+    if (a.key !== b.key) return a.key < b.key ? -1 : 1;
+    return 0;
+  });
+
+  return scored.map((s) => (s.note ? { key: s.key, multiplier: s.multiplier, note: s.note } : { key: s.key, multiplier: s.multiplier }));
+}

package/src/preferences/drift-types.ts

@@ -0,0 +1,87 @@
+/**
+ * Shared preference-drift type surfaces (issue #2371).
+ *
+ * These live in the preferences module rather than in `types.ts` so the
+ * cross-cutting fields drift detection introduces are declared next to the
+ * subsystem that owns them, and `types.ts` composes them through `extends`
+ * instead of growing another inline block.
+ */
+
+import type { DriftDetectionConfig } from "./drift-config.js";
+
+/**
+ * Drift verdict persisted on `preference` memories. `corroborated` is
+ * deliberately NOT a member: a corroborated preference clears `driftState` and
+ * stamps `lastCorroborated`, so the stored enum only carries a negative
+ * verdict.
+ */
+export type MemoryDriftState = "stale" | "drifted";
+
+/**
+ * Derived drift provenance stamped by the scan AFTER a memory exists — never
+ * supplied at compose time, which is why these fields stay outside the sealed
+ * write envelope for exactly the reason `mw_success` / `mw_fail` do.
+ *
+ * Mixed into `MemoryFrontmatter`.
+ */
+export interface MemoryDriftProvenance {
+  /**
+   * `stale` means the lookback window held no corroborating evidence either
+   * way; `drifted` means recent evidence pointed away from the preference and
+   * a review item was opened. Absent means "not classified".
+   */
+  driftState?: MemoryDriftState;
+  /** ISO 8601 timestamp of the last run that found corroborating evidence. */
+  lastCorroborated?: string;
+}
+
+/**
+ * Per-recall render hint, mixed into `QmdSearchResult`. Set by the
+ * preference-drift recall stage when `driftDetection.annotateAfterDays` is on
+ * and absent otherwise. Never persisted — this annotates one injection, it is
+ * not memory state.
+ */
+export interface RecallDriftAnnotation {
+  driftNote?: string;
+}
+
+/** Mixed into `PluginConfig`. */
+export interface DriftDetectionSettings {
+  driftDetection: DriftDetectionConfig;
+}
+
+/**
+ * Frontmatter codec for the drift stamps. Lives here, beside the interface it
+ * serializes, so `storage.ts` stays a caller rather than growing another
+ * field-specific block.
+ */
+export function serializeDriftProvenance(fm: MemoryDriftProvenance): string[] {
+  const lines: string[] = [];
+  if (fm.driftState !== undefined) {
+    // An unrecognized verdict on write is a caller bug that must surface, not
+    // something to persist silently.
+    if (fm.driftState !== "stale" && fm.driftState !== "drifted") {
+      throw new Error(
+        `serializeFrontmatter: invalid driftState ${JSON.stringify(fm.driftState)} — expected "stale" | "drifted"`,
+      );
+    }
+    lines.push(`driftState: ${fm.driftState}`);
+  }
+  if (fm.lastCorroborated) lines.push(`lastCorroborated: ${fm.lastCorroborated}`);
+  return lines;
+}
+
+/**
+ * Read the drift stamps back. A hand-edited or unrecognized stored verdict
+ * round-trips to `undefined` rather than poisoning recall damping — the same
+ * policy the Memory Worth counters use for corrupt values.
+ */
+export function parseDriftProvenance(
+  fm: Record<string, string | undefined>,
+): MemoryDriftProvenance {
+  return {
+    driftState:
+      fm.driftState === "stale" || fm.driftState === "drifted" ? fm.driftState : undefined,
+    lastCorroborated: fm.lastCorroborated || undefined,
+  };
+}

package/src/preferences/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Preference drift detection (issue #2371) — public barrel.
+ *
+ * Ordered leaf-first (types → config → pure recall stage → scan/resolution) so
+ * the scan module, which is the only member with storage and contradiction
+ * imports, initializes last.
+ */
+
+export * from "./drift-types.js";
+export * from "./drift-config.js";
+export * from "./drift-recall.js";
+export * from "./preference-drift.js";