@remnic/core 9.69.38 → 9.69.39

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"],
+  );
+});

package/src/recall-state-view.ts

@@ -8,6 +8,13 @@
  *
  * Change-intent morphology lives here (do not grow intent.ts). A superseded
  * memory is admitted only when its successor is also in the candidate set.
+ *
+ * #2859 — chain identities are namespace-qualified (`namespace\0id`): the
+ * same id in two namespaces never cross-anchors. The reverse chain derives
+ * from the successor's `supersedes` back-pointer when a predecessor lacks
+ * `supersededBy`, and asOf snapshot labels use the temporal validity
+ * boundary (predecessor `invalidAt` / successor `validAt`), not the
+ * `supersededAt` write time.
  */
 import { coerceBooleanLike } from "./connectors/coerce.js";
 
@@ -17,14 +24,24 @@ export interface StateViewChain {
   predecessorId: string;
   successorId: string;
   supersededAt?: string;
+  /** #2859 — namespace scope; a chain link never crosses namespaces. */
+  namespace?: string;
 }
 
 export interface StateViewResult {
   id?: string;
   docid?: string;
   status?: string;
+  /** #2859 — namespace that owns this row; qualifies every chain identity. */
+  namespace?: string;
+  /** #2859 — back-pointer: id of the row this one replaced. */
+  supersedes?: string;
   supersededBy?: string;
   supersededAt?: string;
+  /** #2859 — fact validity start (frontmatter `valid_at`). */
+  validAt?: string;
+  /** #2859 — fact validity end (frontmatter `invalid_at`). */
+  invalidAt?: string;
   stateLabel?: StateLabel;
 }
 
@@ -66,32 +83,94 @@ export function resultStateViewId(result: StateViewResult): string {
   return result.id ?? result.docid ?? "";
 }
 
-function buildSuccessorMap(results: readonly StateViewResult[], chains: readonly StateViewChain[]): Map<string, string> {
+/**
+ * #2859 — namespace-qualified chain identity. Namespace fanout can surface
+ * the same id from two namespaces; every successor/admission match runs on
+ * `namespace\0id` keys so a row in one namespace can never anchor (or be
+ * anchored by) an identically-named row in another.
+ */
+export function stateViewKey(namespace: string | undefined, id: string): string {
+  return `${typeof namespace === "string" ? namespace : ""}\u0000${id}`;
+}
+
+export function resultStateViewKey(result: StateViewResult): string {
+  const id = resultStateViewId(result);
+  return id ? stateViewKey(result.namespace, id) : "";
+}
+
+/** Inverse of {@link stateViewKey}: the id after the namespace separator. */
+function stateViewIdFromKey(key: string): string {
+  const sep = key.indexOf("\u0000");
+  return sep === -1 ? key : key.slice(sep + 1);
+}
+
+/**
+ * predecessorKey → successorKey, namespace-qualified. Precedence: explicit
+ * chains, then successor rows' `supersedes` back-pointers (#2859 — derives
+ * the reverse chain when the predecessor lacks `supersededBy`), then the
+ * predecessor's own `supersededBy` (authoritative when present).
+ */
+function buildSuccessorMap(
+  results: readonly StateViewResult[],
+  chains: readonly StateViewChain[],
+): Map<string, string> {
   const byPred = new Map<string, string>();
+  const link = (predKey: string, succKey: string, overwrite: boolean): void => {
+    if (!predKey || !succKey) return;
+    if (overwrite || !byPred.has(predKey)) byPred.set(predKey, succKey);
+  };
   for (const chain of chains) {
     if (chain.predecessorId && chain.successorId) {
-      byPred.set(chain.predecessorId, chain.successorId);
+      link(
+        stateViewKey(chain.namespace, chain.predecessorId),
+        stateViewKey(chain.namespace, chain.successorId),
+        false,
+      );
+    }
+  }
+  for (const result of results) {
+    const key = resultStateViewKey(result);
+    if (key && result.supersedes) {
+      link(stateViewKey(result.namespace, result.supersedes), key, false);
     }
   }
   for (const result of results) {
-    const id = resultStateViewId(result);
-    if (id && result.supersededBy) byPred.set(id, result.supersededBy);
+    const key = resultStateViewKey(result);
+    if (key && result.supersededBy) {
+      link(key, stateViewKey(result.namespace, result.supersededBy), true);
+    }
   }
   return byPred;
 }
 
+function successorLinkOf(
+  result: StateViewResult,
+  byPred: ReadonlyMap<string, string>,
+): { superseded: boolean; successorKey: string | undefined } {
+  const key = resultStateViewKey(result);
+  return {
+    superseded:
+      result.status === "superseded" ||
+      Boolean(result.supersededBy) ||
+      byPred.has(key),
+    successorKey: result.supersededBy
+      ? stateViewKey(result.namespace, result.supersededBy)
+      : byPred.get(key),
+  };
+}
+
 function labelFor(
-  id: string,
+  key: string,
   result: StateViewResult,
   byPred: Map<string, string>,
   admittedIds: ReadonlySet<string>,
   asOfMs: number | null,
 ): StateLabel {
-  const successorId = result.supersededBy ?? byPred.get(id);
-  const isPred = shouldWidenSuperseded(successorId, admittedIds);
+  const { successorKey } = successorLinkOf(result, byPred);
+  const isPred = shouldWidenSuperseded(successorKey, admittedIds);
   let isSucc = false;
   for (const [predId, succId] of byPred) {
-    if (succId === id && admittedIds.has(predId)) {
+    if (succId === key && admittedIds.has(predId)) {
       isSucc = true;
       break;
     }
@@ -101,19 +180,25 @@ function labelFor(
   if (isSucc) return "current";
   if (result.status === "superseded") {
     // #1952 asOf mode: the successor is legitimately absent under the
-    // historical pin. The row was the live fact at the snapshot when the
-    // recorded supersession postdates the pin ("current" relative to
-    // the snapshot); already replaced at the pin is "historical".
+    // historical pin (a linked successor takes the pair branches above).
+    // The row was the live fact at the snapshot when the temporal
+    // validity boundary postdates the pin ("current" relative to the
+    // snapshot); already replaced at the pin is "historical". #2859: the
+    // boundary is the fact's validity flip — `invalidAt` (the supersession
+    // pipeline sets it to the successor's valid_at) — not the
+    // `supersededAt` write time; legacy rows without a window fall back
+    // to supersededAt.
     return asOfMs === null ? "historical" : snapshotStateLabel(result, asOfMs);
   }
   return "current";
 }
 
 function snapshotStateLabel(result: StateViewResult, asOfMs: number): StateLabel {
-  const supersededAtMs = Date.parse(result.supersededAt ?? "");
-  return Number.isFinite(supersededAtMs) && supersededAtMs <= asOfMs
-    ? "historical"
-    : "current";
+  const invalidAtMs = Date.parse(result.invalidAt ?? "");
+  const boundaryMs = Number.isFinite(invalidAtMs)
+    ? invalidAtMs
+    : Date.parse(result.supersededAt ?? "");
+  return Number.isFinite(boundaryMs) && boundaryMs <= asOfMs ? "historical" : "current";
 }
 
 export function annotateStateView<T extends StateViewResult>(
@@ -136,26 +221,17 @@ export function annotateStateView<T extends StateViewResult>(
   const byPred = buildSuccessorMap(results, chains);
   const candidateIds = new Set<string>();
   for (const result of results) {
-    const id = resultStateViewId(result);
-    if (id) candidateIds.add(id);
+    const key = resultStateViewKey(result);
+    if (key) candidateIds.add(key);
   }
-
-  const isSupersededRow = (result: T): { superseded: boolean; successorId: string | undefined } => {
-    const id = resultStateViewId(result);
-    return {
-      superseded: result.status === "superseded" || Boolean(result.supersededBy) || byPred.has(id),
-      successorId: result.supersededBy ?? byPred.get(id),
-    };
-  };
-
   let admitted: T[];
   if (asOfMs !== null) {
     admitted = results.slice();
   } else {
     admitted = [];
     for (const result of results) {
-      const { superseded, successorId } = isSupersededRow(result);
-      if (!superseded || shouldWidenSuperseded(successorId, candidateIds)) {
+      const { superseded, successorKey } = successorLinkOf(result, byPred);
+      if (!superseded || shouldWidenSuperseded(successorKey, candidateIds)) {
         admitted.push(result);
       }
     }
@@ -163,24 +239,119 @@ export function annotateStateView<T extends StateViewResult>(
     // #1952 contract: superseded never appears without its successor. A
     // successor can itself be dropped (filtered elsewhere, or transitively
     // orphaned), so reconcile to a fixpoint instead of trusting the first pass.
-    let admittedIds = new Set(admitted.map(resultStateViewId).filter(Boolean));
+    let admittedIds = new Set(admitted.map(resultStateViewKey).filter(Boolean));
     for (let changed = true; changed; ) {
       changed = false;
       for (let i = admitted.length - 1; i >= 0; i -= 1) {
         const row = admitted[i]!;
-        const { superseded, successorId } = isSupersededRow(row);
-        if (superseded && !shouldWidenSuperseded(successorId, admittedIds)) {
+        const { superseded, successorKey } = successorLinkOf(row, byPred);
+        if (superseded && !shouldWidenSuperseded(successorKey, admittedIds)) {
           admitted.splice(i, 1);
           changed = true;
         }
       }
-      if (changed) admittedIds = new Set(admitted.map(resultStateViewId).filter(Boolean));
+      if (changed) admittedIds = new Set(admitted.map(resultStateViewKey).filter(Boolean));
     }
   }
 
-  const admittedIds = new Set(admitted.map(resultStateViewId).filter(Boolean));
+  const admittedIds = new Set(admitted.map(resultStateViewKey).filter(Boolean));
   return admitted.map((result) => {
-    const id = resultStateViewId(result);
-    return { ...result, stateLabel: labelFor(id, result, byPred, admittedIds, asOfMs) };
+    const key = resultStateViewKey(result);
+    const { successorKey } = successorLinkOf(result, byPred);
+    const stateLabel = labelFor(key, result, byPred, admittedIds, asOfMs);
+    if (result.supersededBy || !successorKey) return { ...result, stateLabel };
+    return { ...result, stateLabel, supersededBy: stateViewIdFromKey(successorKey) };
   });
 }
+
+/**
+ * #2859 — drop superseded rows whose successor is not in the pool BEFORE
+ * the user cap/MMR runs, so post-cap orphan removal can never underfill
+ * the result set. Reconciles to a fixpoint (a dropped successor orphans
+ * its own predecessors). Rows with no successor links pass through in
+ * order. ponytail: repeated full-pool passes are O(n²) on one long chain;
+ * recall pools stay small, memoize per-key if pools ever grow.
+ */
+export function reconcileStateViewPairs<T extends StateViewResult>(results: readonly T[]): T[] {
+  const byPred = buildSuccessorMap(results, []);
+  let kept = results.slice();
+  for (let changed = true; changed; ) {
+    changed = false;
+    const keptKeys = new Set(kept.map(resultStateViewKey).filter(Boolean));
+    const next: T[] = [];
+    for (const row of kept) {
+      const { superseded, successorKey } = successorLinkOf(row, byPred);
+      if (superseded && !shouldWidenSuperseded(successorKey, keptKeys)) {
+        changed = true;
+        continue;
+      }
+      next.push(row);
+    }
+    if (changed) kept = next;
+  }
+  return kept;
+}
+
+/**
+ * #2859 — packet-counting cap. A predecessor/successor chain admitted
+ * together is ONE complete evidence packet: it consumes a single slot of
+ * the user cap, and the slice never splits a packet at the boundary (no
+ * underfill from post-cap orphan removal). Rows keep their incoming
+ * (MMR) order; packets are ordered by first appearance. Call
+ * reconcileStateViewPairs first so orphans never consume a slot.
+ */
+export function capStateViewPackets<T extends StateViewResult>(
+  ordered: readonly T[],
+  limit: number,
+): T[] {
+  const safeLimit =
+    typeof limit === "number" && Number.isFinite(limit) ? Math.max(0, Math.floor(limit)) : 0;
+  if (safeLimit === 0) return [];
+  if (ordered.length === 0) return [];
+
+  const byPred = buildSuccessorMap(ordered, []);
+  // Union-find over row keys; blank-key rows become per-index singletons.
+  const parent = new Map<string, string>();
+  const root = (key: string): string => {
+    let current = key;
+    for (;;) {
+      const up = parent.get(current);
+      if (up === undefined || up === current) {
+        parent.set(current, current);
+        return current;
+      }
+      current = up;
+    }
+  };
+  const union = (a: string, b: string): void => {
+    const ra = root(a);
+    const rb = root(b);
+    if (ra !== rb) parent.set(ra, rb);
+  };
+  const keys: string[] = [];
+  const keyToIndex = new Map<string, number>();
+  for (let i = 0; i < ordered.length; i += 1) {
+    // ponytail: blank-key rows must stay distinct singletons; index-keyed.
+    const key = resultStateViewKey(ordered[i]!) || `#idx${i}`;
+    keys.push(key);
+    if (!parent.has(key)) parent.set(key, key);
+    const first = keyToIndex.get(key);
+    if (first !== undefined) union(keys[first]!, key);
+    else keyToIndex.set(key, i);
+  }
+  for (const [predKey, succKey] of byPred) {
+    const predIdx = keyToIndex.get(predKey);
+    const succIdx = keyToIndex.get(succKey);
+    if (predIdx !== undefined && succIdx !== undefined) union(keys[predIdx]!, keys[succIdx]!);
+  }
+  // Packets ordered by first appearance; admit whole packets until the cap.
+  const selectedRoots = new Set<string>();
+  for (let i = 0; i < ordered.length && selectedRoots.size < safeLimit; i += 1) {
+    selectedRoots.add(root(keys[i]!));
+  }
+  const selected: T[] = [];
+  for (let i = 0; i < ordered.length; i += 1) {
+    if (selectedRoots.has(root(keys[i]!))) selected.push(ordered[i]!);
+  }
+  return selected;
+}

package/src/trust-score-recall-paths.test.ts

@@ -175,7 +175,7 @@ test("TrustScore quarantine excludes a contradicted memory from injection but su
 
 test("X-ray capture preserves recent-scan serving while recording post-trust applied and pre-trust headroom", async () => {
   const { orchestrator, memoryDir } = await makeOrchestrator({
-    qmdMaxResults: 2,
+    qmdMaxResults: 1,
   });
   const now = Date.now();
   try {

package/dist/chunk-255PC37A.js

@@ -1,120 +0,0 @@
-import {
-  coerceBooleanLike
-} from "./chunk-PQVCH2AE.js";
-
-// src/recall-state-view.ts
-var DEFAULT_RECALL_STATE_VIEWS = false;
-var CHANGE_WORDS = ["switch", "switches", "switched", "switching", "change", "changes", "changed", "changing"];
-var CHANGE_PHRASE_RE = /\bwhen\s+did\b|\bused\s+to\b/;
-var CHANGE_WORD_RE = new RegExp(`\\b(?:${CHANGE_WORDS.join("|")})\\b`);
-var EVENT_POINTER_RE = /\b(?:before|after)\s+(?:the|a|an|this|that|these|those)\b/;
-function parseRecallStateViews(raw) {
-  return coerceBooleanLike(raw, "recallStateViews") === true;
-}
-function isChangeOrientedQuery(query) {
-  const lower = query.toLowerCase();
-  return CHANGE_PHRASE_RE.test(lower) || CHANGE_WORD_RE.test(lower) || EVENT_POINTER_RE.test(lower);
-}
-function shouldWidenSuperseded(successorId, candidateIds) {
-  return typeof successorId === "string" && successorId.length > 0 && candidateIds.has(successorId);
-}
-function formatSupersededPrefix(date, successorId) {
-  return `[superseded ${date} by ${successorId}]`;
-}
-function resultStateViewId(result) {
-  return result.id ?? result.docid ?? "";
-}
-function buildSuccessorMap(results, chains) {
-  const byPred = /* @__PURE__ */ new Map();
-  for (const chain of chains) {
-    if (chain.predecessorId && chain.successorId) {
-      byPred.set(chain.predecessorId, chain.successorId);
-    }
-  }
-  for (const result of results) {
-    const id = resultStateViewId(result);
-    if (id && result.supersededBy) byPred.set(id, result.supersededBy);
-  }
-  return byPred;
-}
-function labelFor(id, result, byPred, admittedIds, asOfMs) {
-  const successorId = result.supersededBy ?? byPred.get(id);
-  const isPred = shouldWidenSuperseded(successorId, admittedIds);
-  let isSucc = false;
-  for (const [predId, succId] of byPred) {
-    if (succId === id && admittedIds.has(predId)) {
-      isSucc = true;
-      break;
-    }
-  }
-  if (isPred && isSucc) return "transition";
-  if (isPred) return "historical";
-  if (isSucc) return "current";
-  if (result.status === "superseded") {
-    return asOfMs === null ? "historical" : snapshotStateLabel(result, asOfMs);
-  }
-  return "current";
-}
-function snapshotStateLabel(result, asOfMs) {
-  const supersededAtMs = Date.parse(result.supersededAt ?? "");
-  return Number.isFinite(supersededAtMs) && supersededAtMs <= asOfMs ? "historical" : "current";
-}
-function annotateStateView(results, query, chains, options = {}) {
-  const enabled = options.enabled === true;
-  if (!enabled || !isChangeOrientedQuery(query)) return results;
-  const asOfMs = typeof options.asOfMs === "number" && Number.isFinite(options.asOfMs) ? options.asOfMs : null;
-  const byPred = buildSuccessorMap(results, chains);
-  const candidateIds = /* @__PURE__ */ new Set();
-  for (const result of results) {
-    const id = resultStateViewId(result);
-    if (id) candidateIds.add(id);
-  }
-  const isSupersededRow = (result) => {
-    const id = resultStateViewId(result);
-    return {
-      superseded: result.status === "superseded" || Boolean(result.supersededBy) || byPred.has(id),
-      successorId: result.supersededBy ?? byPred.get(id)
-    };
-  };
-  let admitted;
-  if (asOfMs !== null) {
-    admitted = results.slice();
-  } else {
-    admitted = [];
-    for (const result of results) {
-      const { superseded, successorId } = isSupersededRow(result);
-      if (!superseded || shouldWidenSuperseded(successorId, candidateIds)) {
-        admitted.push(result);
-      }
-    }
-    let admittedIds2 = new Set(admitted.map(resultStateViewId).filter(Boolean));
-    for (let changed = true; changed; ) {
-      changed = false;
-      for (let i = admitted.length - 1; i >= 0; i -= 1) {
-        const row = admitted[i];
-        const { superseded, successorId } = isSupersededRow(row);
-        if (superseded && !shouldWidenSuperseded(successorId, admittedIds2)) {
-          admitted.splice(i, 1);
-          changed = true;
-        }
-      }
-      if (changed) admittedIds2 = new Set(admitted.map(resultStateViewId).filter(Boolean));
-    }
-  }
-  const admittedIds = new Set(admitted.map(resultStateViewId).filter(Boolean));
-  return admitted.map((result) => {
-    const id = resultStateViewId(result);
-    return { ...result, stateLabel: labelFor(id, result, byPred, admittedIds, asOfMs) };
-  });
-}
-
-export {
-  DEFAULT_RECALL_STATE_VIEWS,
-  parseRecallStateViews,
-  isChangeOrientedQuery,
-  shouldWidenSuperseded,
-  formatSupersededPrefix,
-  resultStateViewId,
-  annotateStateView
-};
-//# sourceMappingURL=chunk-255PC37A.js.map

package/dist/chunk-255PC37A.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/recall-state-view.ts"],"sourcesContent":["/**\n * Recall state views (issue #1952).\n *\n * Config key: `recallStateViews` (default false). When false, annotateStateView\n * is identity: same array reference, no `stateLabel`. config.ts is at its\n * fileSizeGrandfather ceiling, so parseConfig wiring waits for a later PR.\n * Call `parseRecallStateViews` at the recall seam when that lands.\n *\n * Change-intent morphology lives here (do not grow intent.ts). A superseded\n * memory is admitted only when its successor is also in the candidate set.\n */\nimport { coerceBooleanLike } from \"./connectors/coerce.js\";\n\nexport type StateLabel = \"current\" | \"historical\" | \"transition\";\n\nexport interface StateViewChain {\n  predecessorId: string;\n  successorId: string;\n  supersededAt?: string;\n}\n\nexport interface StateViewResult {\n  id?: string;\n  docid?: string;\n  status?: string;\n  supersededBy?: string;\n  supersededAt?: string;\n  stateLabel?: StateLabel;\n}\n\nexport const DEFAULT_RECALL_STATE_VIEWS = false;\n\nconst CHANGE_WORDS = [\"switch\", \"switches\", \"switched\", \"switching\", \"change\", \"changes\", \"changed\", \"changing\"];\n\n// Phrase matches are token-bounded: \"when Didi\" must not fire the\n// \"when did\" phrase, and \"confused to\" must not fire \"used to\".\nconst CHANGE_PHRASE_RE = /\\bwhen\\s+did\\b|\\bused\\s+to\\b/;\nconst CHANGE_WORD_RE = new RegExp(`\\\\b(?:${CHANGE_WORDS.join(\"|\")})\\\\b`);\n// Bare \"before\"/\"after\" are ordinary sequencing (\"before lunch\",\n// \"after install\"). They carry change intent only when they point at a\n// specific event through a determiner (\"before the move\", \"after the\n// cutover\").\nconst EVENT_POINTER_RE = /\\b(?:before|after)\\s+(?:the|a|an|this|that|these|those)\\b/;\n\nexport function parseRecallStateViews(raw: unknown): boolean {\n  return coerceBooleanLike(raw, \"recallStateViews\") === true;\n}\n\nexport function isChangeOrientedQuery(query: string): boolean {\n  const lower = query.toLowerCase();\n  return CHANGE_PHRASE_RE.test(lower) || CHANGE_WORD_RE.test(lower) || EVENT_POINTER_RE.test(lower);\n}\n\nexport function shouldWidenSuperseded(\n  successorId: string | undefined,\n  candidateIds: ReadonlySet<string>,\n): boolean {\n  return typeof successorId === \"string\" && successorId.length > 0 && candidateIds.has(successorId);\n}\n\nexport function formatSupersededPrefix(date: string, successorId: string): string {\n  return `[superseded ${date} by ${successorId}]`;\n}\n\nexport function resultStateViewId(result: StateViewResult): string {\n  return result.id ?? result.docid ?? \"\";\n}\n\nfunction buildSuccessorMap(results: readonly StateViewResult[], chains: readonly StateViewChain[]): Map<string, string> {\n  const byPred = new Map<string, string>();\n  for (const chain of chains) {\n    if (chain.predecessorId && chain.successorId) {\n      byPred.set(chain.predecessorId, chain.successorId);\n    }\n  }\n  for (const result of results) {\n    const id = resultStateViewId(result);\n    if (id && result.supersededBy) byPred.set(id, result.supersededBy);\n  }\n  return byPred;\n}\n\nfunction labelFor(\n  id: string,\n  result: StateViewResult,\n  byPred: Map<string, string>,\n  admittedIds: ReadonlySet<string>,\n  asOfMs: number | null,\n): StateLabel {\n  const successorId = result.supersededBy ?? byPred.get(id);\n  const isPred = shouldWidenSuperseded(successorId, admittedIds);\n  let isSucc = false;\n  for (const [predId, succId] of byPred) {\n    if (succId === id && admittedIds.has(predId)) {\n      isSucc = true;\n      break;\n    }\n  }\n  if (isPred && isSucc) return \"transition\";\n  if (isPred) return \"historical\";\n  if (isSucc) return \"current\";\n  if (result.status === \"superseded\") {\n    // #1952 asOf mode: the successor is legitimately absent under the\n    // historical pin. The row was the live fact at the snapshot when the\n    // recorded supersession postdates the pin (\"current\" relative to\n    // the snapshot); already replaced at the pin is \"historical\".\n    return asOfMs === null ? \"historical\" : snapshotStateLabel(result, asOfMs);\n  }\n  return \"current\";\n}\n\nfunction snapshotStateLabel(result: StateViewResult, asOfMs: number): StateLabel {\n  const supersededAtMs = Date.parse(result.supersededAt ?? \"\");\n  return Number.isFinite(supersededAtMs) && supersededAtMs <= asOfMs\n    ? \"historical\"\n    : \"current\";\n}\n\nexport function annotateStateView<T extends StateViewResult>(\n  results: T[],\n  query: string,\n  chains: readonly StateViewChain[],\n  options: { enabled?: boolean; asOfMs?: number } = {},\n): T[] {\n  const enabled = options.enabled === true;\n  if (!enabled || !isChangeOrientedQuery(query)) return results;\n  // #1952 asOf mode: under a historical pin the pipeline's isValidAsOf\n  // gate already decided validity at the pinned instant, so a predecessor\n  // must not be discarded merely because its successor is absent under\n  // the same filter. A valid asOf result is never emptied here.\n  const asOfMs =\n    typeof options.asOfMs === \"number\" && Number.isFinite(options.asOfMs)\n      ? options.asOfMs\n      : null;\n\n  const byPred = buildSuccessorMap(results, chains);\n  const candidateIds = new Set<string>();\n  for (const result of results) {\n    const id = resultStateViewId(result);\n    if (id) candidateIds.add(id);\n  }\n\n  const isSupersededRow = (result: T): { superseded: boolean; successorId: string | undefined } => {\n    const id = resultStateViewId(result);\n    return {\n      superseded: result.status === \"superseded\" || Boolean(result.supersededBy) || byPred.has(id),\n      successorId: result.supersededBy ?? byPred.get(id),\n    };\n  };\n\n  let admitted: T[];\n  if (asOfMs !== null) {\n    admitted = results.slice();\n  } else {\n    admitted = [];\n    for (const result of results) {\n      const { superseded, successorId } = isSupersededRow(result);\n      if (!superseded || shouldWidenSuperseded(successorId, candidateIds)) {\n        admitted.push(result);\n      }\n    }\n\n    // #1952 contract: superseded never appears without its successor. A\n    // successor can itself be dropped (filtered elsewhere, or transitively\n    // orphaned), so reconcile to a fixpoint instead of trusting the first pass.\n    let admittedIds = new Set(admitted.map(resultStateViewId).filter(Boolean));\n    for (let changed = true; changed; ) {\n      changed = false;\n      for (let i = admitted.length - 1; i >= 0; i -= 1) {\n        const row = admitted[i]!;\n        const { superseded, successorId } = isSupersededRow(row);\n        if (superseded && !shouldWidenSuperseded(successorId, admittedIds)) {\n          admitted.splice(i, 1);\n          changed = true;\n        }\n      }\n      if (changed) admittedIds = new Set(admitted.map(resultStateViewId).filter(Boolean));\n    }\n  }\n\n  const admittedIds = new Set(admitted.map(resultStateViewId).filter(Boolean));\n  return admitted.map((result) => {\n    const id = resultStateViewId(result);\n    return { ...result, stateLabel: labelFor(id, result, byPred, admittedIds, asOfMs) };\n  });\n}\n"],"mappings":"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","names":["admittedIds"]}