@remnic/core 9.69.37 → 9.69.39

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

@@ -567,3 +567,156 @@ test("trust rerank preserves duplicate paths owned by different namespaces (#202
   );
   assert.equal(outcome.trustByPath?.size, 2, "trust metadata must have one entry per namespaced result");
 });
+
+test("#2859 state-view cap: pairs reconcile before cap/MMR and count as one evidence packet", () => {
+  // MMR off so the ordered pool equals the input order — the packet
+  // semantics under test are then fully deterministic.
+  const config = parseConfig({ recallMmrEnabled: false });
+  const corpus = makeFakes([]);
+  const coordinator = new RecallRerankCoordinator({
+    getConfig: () => config,
+    getStorage: corpus.getStorage,
+    readQmdResultMemory: async () => null,
+  });
+  const sv = (
+    id: string,
+    score: number,
+    chain: Partial<QmdSearchResult> = {},
+  ): QmdSearchResult => ({ ...result(id, score), id, status: "active", ...chain });
+  const rows: QmdSearchResult[] = [
+    sv("p1", 0.95, { status: "superseded", supersededBy: "s1" }),
+    sv("orphan", 0.9, { status: "superseded", supersededBy: "absent" }),
+    sv("s1", 0.85),
+    sv("f1", 0.8),
+    sv("f2", 0.75),
+  ];
+  const caps = resolveCapabilities(config);
+
+  // Packet view: [p1+s1], [f1], [f2] — the orphan is reconciled away
+  // BEFORE the cap, and the admitted pair consumes a single slot.
+  const partition = coordinator.diversifyRecallResultsWithHeadroom(
+    "memories",
+    rows,
+    2,
+    undefined,
+    caps,
+    true,
+  );
+  assert.deepEqual(
+    partition.appliedResults.map((r) => r.id),
+    ["p1", "s1", "f1"],
+    "a complete pair is one packet: pred+succ plus one filler for limit 2",
+  );
+  assert.deepEqual(
+    partition.headroomResults.map((r) => r.id),
+    ["f2"],
+    "headroom is the remainder of the reconciled pool",
+  );
+
+  // The slice never splits a packet at the boundary: even with the
+  // successor ranked LAST, the pair is admitted together.
+  const splitRisk: QmdSearchResult[] = [
+    sv("p1", 0.95, { status: "superseded", supersededBy: "s1" }),
+    sv("f1", 0.9),
+    sv("f2", 0.85),
+    sv("s1", 0.8),
+  ];
+  const applied = coordinator.diversifyAndLimitRecallResults(
+    "memories",
+    splitRisk,
+    2,
+    undefined,
+    caps,
+    true,
+  );
+  assert.deepEqual(
+    applied.map((r) => r.id),
+    ["p1", "f1", "s1"],
+    "no underfill: the boundary keeps the evidence packet complete",
+  );
+
+  // Flag absent → the legacy row slice, byte-identical (zero-diff default).
+  const legacy = coordinator.diversifyAndLimitRecallResults(
+    "memories",
+    rows,
+    2,
+    undefined,
+    caps,
+  );
+  assert.deepEqual(
+    legacy.map((r) => r.id),
+    ["p1", "orphan"],
+    "without the state view the cap stays the plain top-N row slice",
+  );
+});
+
+test("#2859 packet cap after filter: a quarantined successor does not consume budget", () => {
+  const config = parseConfig({ recallMmrEnabled: false });
+  const corpus = makeFakes([]);
+  const coordinator = new RecallRerankCoordinator({
+    getConfig: () => config,
+    getStorage: corpus.getStorage,
+    readQmdResultMemory: async () => null,
+  });
+  const sv = (
+    id: string,
+    score: number,
+    chain: Partial<QmdSearchResult> = {},
+  ): QmdSearchResult => ({ ...result(id, score), id, status: "active", ...chain });
+  // Trust already removed s1. Cap-after-filter must drop the orphaned
+  // predecessor and promote the next live packet instead of returning empty.
+  const afterTrust: QmdSearchResult[] = [
+    sv("p1", 0.95, { status: "superseded", supersededBy: "s1" }),
+    sv("f1", 0.8),
+    sv("f2", 0.75),
+  ];
+  const partition = coordinator.diversifyRecallResultsWithHeadroom(
+    "memories",
+    afterTrust,
+    1,
+    undefined,
+    resolveCapabilities(config),
+    true,
+  );
+  assert.deepEqual(
+    partition.appliedResults.map((row) => row.id),
+    ["f1"],
+    "disallowed pair must not occupy the only packet slot",
+  );
+  assert.deepEqual(
+    partition.headroomResults.map((row) => row.id),
+    ["f2"],
+  );
+});
+
+test("#2859 linkless superseded status does not consume a packet slot", () => {
+  const config = parseConfig({ recallMmrEnabled: false });
+  const corpus = makeFakes([]);
+  const coordinator = new RecallRerankCoordinator({
+    getConfig: () => config,
+    getStorage: corpus.getStorage,
+    readQmdResultMemory: async () => null,
+  });
+  const sv = (
+    id: string,
+    score: number,
+    chain: Partial<QmdSearchResult> = {},
+  ): QmdSearchResult => ({ ...result(id, score), id, status: "active", ...chain });
+  const rows: QmdSearchResult[] = [
+    sv("legacy", 0.99, { status: "superseded" }),
+    sv("live", 0.5),
+  ];
+  const applied = coordinator.diversifyAndLimitRecallResults(
+    "memories",
+    rows,
+    1,
+    undefined,
+    resolveCapabilities(config),
+    true,
+  );
+  assert.deepEqual(
+    applied.map((row) => row.id),
+    ["live"],
+    "status-only superseded rows are rejected before the packet cap",
+  );
+});

package/src/recall-state-view-anchors.ts

@@ -0,0 +1,163 @@
+import { isChangeOrientedQuery, stateViewKey } from "./recall-state-view.js";
+/**
+ * State-view anchor admission (#2859).
+ *
+ * Shared namespace-qualified admission tracker for the recall safety
+ * filter (QMD/embedding/cold paths) and the recent-scan path. A deferred
+ * superseded row is admitted only when an in-set successor anchors it —
+ * through the row's own `supersededBy` or through an admitted successor's
+ * `supersedes` back-pointer. Identities are `namespace\0id`, so identical
+ * ids across namespace fanout never cross-anchor.
+ */
+import { shouldFilterSupersededFromRecall } from "./temporal-supersession.js";
+import type { MemoryFile } from "./types.js";
+
+export interface StateViewAnchorFrontmatter {
+  id?: string;
+  supersedes?: string;
+  supersededBy?: string;
+}
+
+/**
+ * #2859 — pair reconciliation and packet-counting caps apply only WITHOUT
+ * a historical pin: under asOf the validity filter legitimately orphans
+ * predecessors (see annotateStateView's asOf mode).
+ */
+export function stateViewPacketActive(stateViewActive: boolean | undefined, asOfMs: number | undefined): boolean {
+  return stateViewActive === true && !(typeof asOfMs === "number" && Number.isFinite(asOfMs));
+}
+
+/**
+ * #1952/#2859 — config flag OR per-call override, gated on change intent.
+ * Packet semantics are off under a historical asOf pin (see stateViewPacketActive).
+ */
+export function resolveRecallStateViewFlags(
+  optionFlag: boolean | undefined,
+  configFlag: boolean | undefined,
+  retrievalQuery: string,
+  asOfMs: number | undefined,
+): { stateViewActive: boolean; stateViewPacketActive: boolean } {
+  const stateViewActive =
+    (optionFlag === true || configFlag === true) && isChangeOrientedQuery(retrievalQuery);
+  return { stateViewActive, stateViewPacketActive: stateViewPacketActive(stateViewActive, asOfMs) };
+}
+
+export class StateViewAnchorTracker {
+  private readonly admitted = new Set<string>();
+  private readonly supersedesAnchors = new Set<string>();
+
+  has(namespace: string | undefined, frontmatter: StateViewAnchorFrontmatter): boolean {
+    const id = frontmatter.id;
+    return typeof id === "string" && id.length > 0 ? this.admitted.has(stateViewKey(namespace, id)) : false;
+  }
+
+  /**
+   * Register a row as admitted (a survivor of every gate, or a deferred
+   * row whose successor anchored it). The row's `supersedes` back-pointer
+   * then anchors its own predecessor.
+   */
+  admit(namespace: string | undefined, frontmatter: StateViewAnchorFrontmatter): void {
+    const id = frontmatter.id;
+    if (typeof id !== "string" || id.length === 0) return;
+    this.admitted.add(stateViewKey(namespace, id));
+    if (frontmatter.supersedes) {
+      this.supersedesAnchors.add(stateViewKey(namespace, frontmatter.supersedes));
+    }
+  }
+
+  /** True when an admitted successor anchors this superseded row. */
+  anchored(namespace: string | undefined, frontmatter: StateViewAnchorFrontmatter): boolean {
+    const id = frontmatter.id;
+    if (typeof id !== "string" || id.length === 0) return false;
+    const successorId = frontmatter.supersededBy;
+    return (
+      (typeof successorId === "string" && this.admitted.has(stateViewKey(namespace, successorId))) ||
+      this.supersedesAnchors.has(stateViewKey(namespace, id))
+    );
+  }
+}
+
+export interface StateViewRecentAdmissionDeps {
+  namespaceOf: (path: string) => string;
+  isExcluded: (path: string) => boolean;
+  supersessionOptions: { enabled: boolean; includeInRecall: boolean };
+}
+
+/**
+ * #2859 — recent-scan admission: seed the tracker with every memory that
+ * survives the supersession gate, then admit superseded rows anchored by
+ * an in-set successor (fixpoint — an admitted link anchors the next).
+ */
+export function admitStateViewRecentMemories(
+  memories: readonly MemoryFile[],
+  deps: StateViewRecentAdmissionDeps
+): StateViewAnchorTracker {
+  const tracker = new StateViewAnchorTracker();
+  for (const m of memories) {
+    if (deps.isExcluded(m.path)) continue;
+    if (m.frontmatter.status === "superseded") continue;
+    if (shouldFilterSupersededFromRecall(m.frontmatter, deps.supersessionOptions)) continue;
+    tracker.admit(deps.namespaceOf(m.path), m.frontmatter);
+  }
+  for (let progress = true; progress; ) {
+    progress = false;
+    for (const m of memories) {
+      const namespace = deps.namespaceOf(m.path);
+      if (tracker.has(namespace, m.frontmatter)) continue;
+      if (deps.isExcluded(m.path)) continue;
+      if (m.frontmatter.status !== "superseded") continue;
+      if (!shouldFilterSupersededFromRecall(m.frontmatter, deps.supersessionOptions)) continue;
+      if (tracker.anchored(namespace, m.frontmatter)) {
+        tracker.admit(namespace, m.frontmatter);
+        progress = true;
+      }
+    }
+  }
+  return tracker;
+}
+
+export interface RecentScanMemoryFilterDeps extends StateViewRecentAdmissionDeps {
+  stateViewActive: boolean;
+  asOfMs: number | undefined;
+}
+
+/**
+ * Recent-scan admission for the fallback path.
+ *
+ * Superseded-status filtering delegates to
+ * shouldFilterSupersededFromRecall so recent-scan and the QMD
+ * safety filter share semantics (kill switch, audit mode, PR #402).
+ * #1952: an active state view admits a superseded memory whose
+ * successor ALSO survives this admission filter (fixpoint below).
+ * PR #713: when `as_of` is active, pass superseded candidates
+ * through here — boostSearchResults's `[valid_at, invalid_at)`
+ * evaluation is the authoritative historical gate. Other
+ * non-active statuses stay excluded.
+ * #2859: namespace-qualified anchors with the supersedes
+ * back-pointer — mirrors the safety-filter fixpoint.
+ */
+export function filterRecentScanMemories(
+  memories: readonly MemoryFile[],
+  deps: RecentScanMemoryFilterDeps,
+): MemoryFile[] {
+  const asOfActive = typeof deps.asOfMs === "number" && Number.isFinite(deps.asOfMs);
+  const stateViewAnchors =
+    deps.stateViewActive && !asOfActive ? admitStateViewRecentMemories(memories, deps) : null;
+  return memories.filter((m) => {
+    if (deps.isExcluded(m.path)) return false;
+    const status = m.frontmatter.status;
+    if (!status || status === "active") return true;
+    if (status === "superseded") {
+      if (asOfActive) return true;
+      if (stateViewAnchors?.has(deps.namespaceOf(m.path), m.frontmatter)) {
+        return true;
+      }
+      // Include superseded memory only if the canonical gate says
+      // NOT to filter it (kill switch off or audit mode on).
+      return !shouldFilterSupersededFromRecall(m.frontmatter, deps.supersessionOptions);
+    }
+    // Other non-active statuses (archived, retired, etc.) are
+    // excluded from the recent-scan path by default.
+    return false;
+  });
+}

package/src/recall-state-view-widen.ts

@@ -9,8 +9,9 @@ import {
   annotateStateView,
   isChangeOrientedQuery,
   parseRecallStateViews,
-  resultStateViewId,
+  resultStateViewKey,
   shouldWidenSuperseded,
+  stateViewKey,
   type StateViewResult,
 } from "./recall-state-view.js";
 
@@ -45,21 +46,34 @@ export function widenRecallStateViews<T extends StateViewResult>(
   if (!enabled || !isChangeOrientedQuery(query)) return results;
   const asOfActive = typeof asOfMs === "number" && Number.isFinite(asOfMs);
 
+  // #2859: matches are namespace-qualified, and a successor's `supersedes`
+  // back-pointer anchors its predecessor even when the predecessor's own
+  // `supersededBy` is absent.
   const candidateIds = new Set<string>();
+  const supersedesAnchors = new Set<string>();
   for (const result of results) {
-    const id = resultStateViewId(result);
-    if (id) candidateIds.add(id);
+    const key = resultStateViewKey(result);
+    if (!key) continue;
+    candidateIds.add(key);
+    if (result.supersedes) {
+      supersedesAnchors.add(stateViewKey(result.namespace, result.supersedes));
+    }
   }
 
   const seen = new Set(candidateIds);
   const extra: T[] = [];
   if (!asOfActive) {
     for (const item of pool) {
-      const id = resultStateViewId(item);
-      if (!id || seen.has(id)) continue;
-      if (!shouldWidenSuperseded(item.supersededBy, candidateIds)) continue;
+      const key = resultStateViewKey(item);
+      if (!key || seen.has(key)) continue;
+      const successorKey = item.supersededBy
+        ? stateViewKey(item.namespace, item.supersededBy)
+        : undefined;
+      if (!shouldWidenSuperseded(successorKey, candidateIds) && !supersedesAnchors.has(key)) {
+        continue;
+      }
       extra.push(item);
-      seen.add(id);
+      seen.add(key);
     }
   }
 

package/src/recall-state-view-zero-diff.test.ts

@@ -143,6 +143,7 @@ type LiveFixtureRow = StateViewLine & {
   score: number;
   supersededAt?: string;
   supersededBy?: string;
+  supersedes?: string;
 };
 
 // Review round 2: the earlier follow-up ran `injectStateViewLines`, which has
@@ -176,6 +177,7 @@ function liveEntries(
     stateLabel: result.stateLabel,
     ...(result.supersededAt ? { supersededAt: result.supersededAt } : {}),
     ...(result.supersededBy ? { supersededBy: result.supersededBy } : {}),
+    ...(result.supersedes ? { supersedes: result.supersedes } : {}),
   }));
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- test fixture
   const widened = applyRecallStateViews(qmdResults as any[], query, config);
@@ -289,3 +291,31 @@ test("the live route still renders every current entry it was given", () => {
   assert.match(entries[0]!, /the API limit is 100\/min/);
   assert.match(entries[1]!, /we chose SQLite/);
 });
+
+test("the enabled route renders history for a supersedes-only pair", () => {
+  const results = [
+    {
+      memoryId: "m-1",
+      text: "we use PostgreSQL",
+      stateLabel: "current" as const,
+      score: 0.9,
+      supersedes: "m-0",
+    },
+    {
+      memoryId: "m-0",
+      text: "we use SQLite",
+      stateLabel: "current" as const,
+      supersededAt: "2026-08-01",
+      score: 0.7,
+    },
+  ];
+  const query = "what changed about the database?";
+  const enabled = liveEntries(results, query, true);
+  const old = enabled.entries.find((entry) => entry.includes("we use SQLite"));
+  assert.equal(
+    enabled.widened.find((row) => row.id === "m-0")?.stateLabel,
+    "historical",
+  );
+  assert.ok(old, "enabled render includes the predecessor");
+  assert.match(old!, /\[superseded 2026-08-01 by m-1\] we use SQLite/);
+});

package/src/recall-state-view.test.ts

@@ -3,9 +3,11 @@ import test from "node:test";
 
 import {
   annotateStateView,
+  capStateViewPackets,
   formatSupersededPrefix,
   isChangeOrientedQuery,
   parseRecallStateViews,
+  reconcileStateViewPairs,
   shouldWidenSuperseded,
   type StateViewChain,
   type StateViewResult,
@@ -271,3 +273,162 @@ test("transitive orphan chains collapse: A→B→(C absent) drops both A and B",
     "the fixpoint must drop A once B is dropped, not render a dangling historical",
   );
 });
+
+test("#2859 reverse chain derives from the successor supersedes back-pointer when supersededBy is absent", () => {
+  const results = [
+    fact("new-job", { status: "active", supersedes: "old-job" }),
+    // Corrected row: no supersededBy, and even no "superseded" status —
+    // the ONLY link is the successor's back-pointer.
+    fact("old-job", {}),
+  ];
+  const labeled = annotateStateView(results, "when did the job title change", [], { enabled: true });
+  assert.deepEqual(
+    labeled.map((row) => [row.id, row.stateLabel, row.supersededBy]),
+    [
+      ["new-job", "current", undefined],
+      ["old-job", "historical", "new-job"],
+    ],
+    "the back-pointer must link the pair, admit the predecessor, and carry derived supersededBy",
+  );
+});
+
+test("#2859 back-pointer pair survives the orphan fixpoint in both directions", () => {
+  const results = [
+    fact("v3", { status: "active", supersedes: "v2" }),
+    fact("v2", { status: "superseded", supersedes: "v1" }),
+    fact("v1", {}),
+  ];
+  const labeled = annotateStateView(results, "what changed about the database", [], { enabled: true });
+  assert.deepEqual(
+    labeled.map((row) => [row.id, row.stateLabel]),
+    [
+      ["v3", "current"],
+      ["v2", "transition"],
+      ["v1", "historical"],
+    ],
+  );
+});
+
+test("#2859 asOf label uses the validity boundary, not the supersededAt write time", () => {
+  const pin = Date.parse("2026-08-05T00:00:00.000Z");
+  // Write time January, validity flip September: at an August pin the row
+  // was still the live fact even though supersededAt PREDATES the pin.
+  const predecessor = fact("old-job", {
+    status: "superseded",
+    supersededBy: "new-job",
+    supersededAt: "2026-01-01T00:00:00.000Z",
+    invalidAt: "2026-09-01T00:00:00.000Z",
+  });
+  const labeled = annotateStateView([predecessor], "when did the job title change", [], {
+    enabled: true,
+    asOfMs: pin,
+  });
+  assert.equal(
+    labeled[0]?.stateLabel,
+    "current",
+    "the boundary is invalidAt, so a pin before the flip labels the row current-at-snapshot",
+  );
+
+  // Past the boundary the same row labels historical (boundary <= pin).
+  const afterFlip = annotateStateView([predecessor], "when did the job title change", [], {
+    enabled: true,
+    asOfMs: Date.parse("2026-09-05T00:00:00.000Z"),
+  });
+  assert.equal(
+    afterFlip[0]?.stateLabel,
+    "historical",
+    "a pin past the validity flip labels the row historical",
+  );
+
+  // Legacy row without a validity window keeps the supersededAt fallback.
+  const legacy = fact("old-legacy", {
+    status: "superseded",
+    supersededBy: "new-legacy",
+    supersededAt: "2026-01-01T00:00:00.000Z",
+  });
+  const legacyLabel = annotateStateView([legacy], "when did the job title change", [], {
+    enabled: true,
+    asOfMs: pin,
+  });
+  assert.equal(
+    legacyLabel[0]?.stateLabel,
+    "historical",
+    "no invalidAt → the supersededAt write time is the only recorded boundary",
+  );
+});
+
+test("#2859 namespace-qualified identities: same id across namespaces never cross-anchors", () => {
+  // ns-a has the superseded predecessor; ns-b has an UNRELATED row that
+  // happens to reuse the successor id. Bare-id matching would admit the
+  // ns-a predecessor on the ns-b anchor.
+  const results = [
+    fact("m-1", { namespace: "ns-b", status: "active" }),
+    fact("m-0", { namespace: "ns-a", status: "superseded", supersededBy: "m-1" }),
+  ];
+  const labeled = annotateStateView(results, "when did this change", [], { enabled: true });
+  assert.deepEqual(
+    labeled.map((row) => row.id),
+    ["m-1"],
+    "a foreign-namespace successor must not anchor the superseded row",
+  );
+
+  // Positive control: the same-namespace successor anchors it.
+  const anchored = annotateStateView(
+    [
+      fact("m-1", { namespace: "ns-a", status: "active" }),
+      fact("m-0", { namespace: "ns-a", status: "superseded", supersededBy: "m-1" }),
+    ],
+    "when did this change",
+    [],
+    { enabled: true },
+  );
+  assert.deepEqual(
+    anchored.map((row) => [row.id, row.stateLabel]),
+    [
+      ["m-1", "current"],
+      ["m-0", "historical"],
+    ],
+  );
+});
+
+test("#2859 namespace-qualified chains: a chain link never crosses namespaces", () => {
+  const chains: StateViewChain[] = [
+    { predecessorId: "old", successorId: "new", namespace: "ns-a" },
+  ];
+  const results = [
+    fact("new", { namespace: "ns-b", status: "active" }),
+    fact("old", { namespace: "ns-a", status: "superseded", supersededAt: "2026-02-01" }),
+  ];
+  const labeled = annotateStateView(results, "before the correction what was it", chains, {
+    enabled: true,
+  });
+  assert.deepEqual(
+    labeled.map((row) => row.id),
+    ["new"],
+    "the ns-a chain link must not pair against the ns-b successor",
+  );
+});
+
+test("reconcile drops a linkless superseded row so it cannot consume a packet slot", () => {
+  const rows = [
+    fact("legacy", { status: "superseded", supersededAt: "2026-01-01" }),
+    fact("live", { status: "active" }),
+  ];
+  assert.deepEqual(
+    reconcileStateViewPairs(rows).map((row) => row.id),
+    ["live"],
+    "audit/kill-switch status-only rows have no successor and must leave before the cap",
+  );
+  assert.deepEqual(
+    capStateViewPackets(reconcileStateViewPairs(rows), 1).map((row) => row.id),
+    ["live"],
+  );
+});
+
+test("reconcile still keeps an unlinked active row", () => {
+  const rows = [fact("solo", { status: "active" })];
+  assert.deepEqual(
+    reconcileStateViewPairs(rows).map((row) => row.id),
+    ["solo"],
+  );
+});