@remnic/core 9.66.0 → 9.66.2

package/src/recall-navigate.ts

@@ -0,0 +1,100 @@
+/**
+ * Recall navigation helpers (issue #1956 first slice).
+ *
+ * Pure expand/traverse over disclosure levels and typed links. No LLM, no IO.
+ * Surfaces (MCP/HTTP/CLI) and parseConfig wiring wait for a later PR —
+ * config.ts is at its fileSizeGrandfather ceiling.
+ *
+ * Budget 0 is off (unavailable). Empty means the step ran and found nothing.
+ */
+import {
+  RECALL_DISCLOSURE_LEVELS,
+  type RecallDisclosure,
+} from "./types.js";
+
+export const RECALL_NAV_LINK_TYPES = [
+  "supports",
+  "contradicts",
+  "elaborates",
+  "supersedes",
+  "causes",
+] as const;
+
+export type RecallNavLinkType = (typeof RECALL_NAV_LINK_TYPES)[number];
+
+export interface RecallNavBudget {
+  budget: number;
+}
+
+export interface RecallNavEdge {
+  targetId: string;
+  linkType: string;
+  preview?: string;
+}
+
+export interface RecallNavNode {
+  id: string;
+  disclosure: RecallDisclosure;
+  payloads?: Partial<Record<RecallDisclosure, string>>;
+  links?: readonly RecallNavEdge[];
+}
+
+export interface RecallNavNeighbor {
+  id: string;
+  linkType: RecallNavLinkType;
+  preview?: string;
+}
+
+export type RecallNavExpandResult =
+  | { status: "ok"; node: { id: string; disclosure: RecallDisclosure; text: string } }
+  | { status: "empty" }
+  | { status: "unavailable"; reason: "budget_off" };
+
+export type RecallNavTraverseResult =
+  | { status: "ok"; neighbors: readonly RecallNavNeighbor[] }
+  | { status: "empty" }
+  | { status: "unavailable"; reason: "budget_off" };
+
+export function isRecallNavLinkType(value: unknown): value is RecallNavLinkType {
+  return typeof value === "string" && (RECALL_NAV_LINK_TYPES as readonly string[]).includes(value);
+}
+
+export function expandRecallNode(
+  node: RecallNavNode,
+  options: RecallNavBudget,
+): RecallNavExpandResult {
+  if (!Number.isFinite(options.budget) || options.budget <= 0) {
+    return { status: "unavailable", reason: "budget_off" };
+  }
+  const current = RECALL_DISCLOSURE_LEVELS.indexOf(node.disclosure);
+  const next = current >= 0 ? RECALL_DISCLOSURE_LEVELS[current + 1] : undefined;
+  if (next === undefined) return { status: "empty" };
+  const text = node.payloads?.[next];
+  if (typeof text !== "string") return { status: "empty" };
+  return { status: "ok", node: { id: node.id, disclosure: next, text } };
+}
+
+export function traverseRecallLink(
+  from: RecallNavNode,
+  linkType: string,
+  options: RecallNavBudget,
+): RecallNavTraverseResult {
+  if (!isRecallNavLinkType(linkType)) {
+    throw new Error(
+      `unknown recall nav linkType: ${JSON.stringify(linkType)}. Valid: ${RECALL_NAV_LINK_TYPES.join(", ")}`,
+    );
+  }
+  if (!Number.isFinite(options.budget) || options.budget <= 0) {
+    return { status: "unavailable", reason: "budget_off" };
+  }
+  const neighbors = (from.links ?? [])
+    .filter((link) => link.linkType === linkType)
+    .map((link) => {
+      const neighbor: RecallNavNeighbor = { id: link.targetId, linkType };
+      if (link.preview !== undefined) neighbor.preview = link.preview;
+      return neighbor;
+    })
+    .sort((a, b) => a.id.localeCompare(b.id, "en"));
+  if (neighbors.length === 0) return { status: "empty" };
+  return { status: "ok", neighbors };
+}

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

@@ -0,0 +1,94 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { renderStateViewLine } from "./recall-state-view-render.js";
+
+const TEXT = "Was a baker";
+const DATE = "2026-03-01";
+const SUCCESSOR = "new-job";
+
+test("historical line gets the superseded prefix", () => {
+  const line = renderStateViewLine(
+    {
+      id: "old-job",
+      text: TEXT,
+      stateLabel: "historical",
+      supersededAt: DATE,
+      supersededBy: SUCCESSOR,
+    },
+    { enabled: true },
+  );
+  assert.equal(line, `[superseded ${DATE} by ${SUCCESSOR}] ${TEXT}`);
+});
+
+test("transition line gets the superseded prefix", () => {
+  const line = renderStateViewLine(
+    {
+      id: "mid-job",
+      text: TEXT,
+      stateLabel: "transition",
+      supersededAt: DATE,
+      supersededBy: SUCCESSOR,
+    },
+    { enabled: true },
+  );
+  assert.equal(line, `[superseded ${DATE} by ${SUCCESSOR}] ${TEXT}`);
+});
+
+test("current line is identity text", () => {
+  assert.equal(
+    renderStateViewLine(
+      {
+        id: "new-job",
+        text: TEXT,
+        stateLabel: "current",
+        supersededAt: DATE,
+        supersededBy: SUCCESSOR,
+      },
+      { enabled: true },
+    ),
+    TEXT,
+  );
+});
+
+test("missing date is identity text", () => {
+  assert.equal(
+    renderStateViewLine(
+      {
+        id: "old-job",
+        text: TEXT,
+        stateLabel: "historical",
+        supersededBy: SUCCESSOR,
+      },
+      { enabled: true },
+    ),
+    TEXT,
+  );
+});
+
+test("missing successor is identity text", () => {
+  assert.equal(
+    renderStateViewLine(
+      {
+        id: "old-job",
+        text: TEXT,
+        stateLabel: "historical",
+        supersededAt: DATE,
+      },
+      { enabled: true },
+    ),
+    TEXT,
+  );
+});
+
+test("enabled false is identity text", () => {
+  const historical = {
+    id: "old-job",
+    text: TEXT,
+    stateLabel: "historical" as const,
+    supersededAt: DATE,
+    supersededBy: SUCCESSOR,
+  };
+  assert.equal(renderStateViewLine(historical), TEXT);
+  assert.equal(renderStateViewLine(historical, { enabled: false }), TEXT);
+});

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

@@ -0,0 +1,24 @@
+/**
+ * Recall inject-line renderer for state views (issue #1952).
+ *
+ * Historical and transition rows get `[superseded <date> by <id>]` when both
+ * supersededAt and supersededBy are present. Current rows and a disabled
+ * flag are identity.
+ */
+import { formatSupersededPrefix, type StateViewResult } from "./recall-state-view.js";
+
+export type StateViewLineResult = StateViewResult & { text?: string };
+
+export function renderStateViewLine(
+  result: StateViewLineResult,
+  options: { enabled?: boolean } = {},
+): string {
+  const text = typeof result.text === "string" ? result.text : "";
+  if (options.enabled !== true) return text;
+  const label = result.stateLabel;
+  if (label !== "historical" && label !== "transition") return text;
+  const date = result.supersededAt;
+  const successor = result.supersededBy;
+  if (!date || !successor) return text;
+  return `${formatSupersededPrefix(date, successor)} ${text}`;
+}

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

@@ -0,0 +1,66 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { applyRecallStateViews } from "./recall-state-view-wire.js";
+import { widenRecallStateViews } from "./recall-state-view-widen.js";
+import type { StateViewResult } from "./recall-state-view.js";
+
+function fact(id: string, extra: Partial<StateViewResult> = {}): StateViewResult {
+  return { id, ...extra };
+}
+
+const CURRENT = fact("new-job", { status: "active" });
+const HISTORICAL = fact("old-job", {
+  status: "superseded",
+  supersededBy: "new-job",
+  supersededAt: "2026-03-01",
+});
+const ORPHAN = fact("orphan-job", {
+  status: "superseded",
+  supersededBy: "missing-job",
+});
+const ON = { recallStateViews: true } as const;
+const CHANGE = "when did the job title change";
+const NON_CHANGE = "what is the current job title";
+
+test("change-intent query labels both facts when successor is in the set", () => {
+  const labeled = widenRecallStateViews([CURRENT], CHANGE, ON, [HISTORICAL]);
+  assert.equal(labeled.length, 2);
+  assert.equal(labeled[0]?.id, "new-job");
+  assert.equal(labeled[0]?.stateLabel, "current");
+  assert.equal(labeled[1]?.id, "old-job");
+  assert.equal(labeled[1]?.stateLabel, "historical");
+  assert.deepEqual(
+    applyRecallStateViews([CURRENT, HISTORICAL], CHANGE, ON).map((row) => [
+      row.id,
+      row.stateLabel,
+    ]),
+    [
+      ["new-job", "current"],
+      ["old-job", "historical"],
+    ],
+  );
+});
+
+test("non-change query is identical (same array reference)", () => {
+  const input = [CURRENT, HISTORICAL];
+  assert.equal(widenRecallStateViews(input, NON_CHANGE, ON, [ORPHAN]), input);
+  assert.equal(applyRecallStateViews(input, NON_CHANGE, ON), input);
+  assert.equal(input[0]?.stateLabel, undefined);
+});
+
+test("recallStateViews false is identity (same array reference)", () => {
+  const input = [CURRENT];
+  assert.equal(widenRecallStateViews(input, CHANGE, {}, [HISTORICAL]), input);
+  assert.equal(widenRecallStateViews(input, CHANGE, { recallStateViews: false }, [HISTORICAL]), input);
+  assert.equal(applyRecallStateViews(input, CHANGE, { recallStateViews: false }), input);
+  assert.equal(input[0]?.stateLabel, undefined);
+});
+
+test("superseded without successor is dropped", () => {
+  assert.deepEqual(widenRecallStateViews([ORPHAN], CHANGE, ON), []);
+  assert.deepEqual(widenRecallStateViews([CURRENT], CHANGE, ON, [ORPHAN]), [
+    { ...CURRENT, stateLabel: "current" },
+  ]);
+  assert.deepEqual(applyRecallStateViews([ORPHAN], CHANGE, ON), []);
+});

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

@@ -0,0 +1,49 @@
+/**
+ * Recall state-view widening (issue #1952).
+ *
+ * When recallStateViews is on and the query is change-oriented, admit a
+ * superseded memory only if its successor is already in the candidate set.
+ * Flag off / non-change queries are identity.
+ */
+import {
+  annotateStateView,
+  isChangeOrientedQuery,
+  parseRecallStateViews,
+  resultStateViewId,
+  shouldWidenSuperseded,
+  type StateViewResult,
+} from "./recall-state-view.js";
+
+export function widenRecallStateViews<T extends StateViewResult>(
+  results: T[],
+  query: string,
+  config: unknown,
+  pool: readonly T[] = [],
+): T[] {
+  const raw =
+    typeof config === "object" && config !== null && "recallStateViews" in config
+      ? config.recallStateViews
+      : undefined;
+  const enabled = parseRecallStateViews(raw);
+  if (!enabled || !isChangeOrientedQuery(query)) return results;
+
+  const candidateIds = new Set<string>();
+  for (const result of results) {
+    const id = resultStateViewId(result);
+    if (id) candidateIds.add(id);
+  }
+
+  const seen = new Set(candidateIds);
+  const extra: T[] = [];
+  for (const item of pool) {
+    const id = resultStateViewId(item);
+    if (!id || seen.has(id)) continue;
+    if (!shouldWidenSuperseded(item.supersededBy, candidateIds)) continue;
+    extra.push(item);
+    seen.add(id);
+  }
+
+  return annotateStateView(extra.length > 0 ? results.concat(extra) : results, query, [], {
+    enabled: true,
+  });
+}

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

@@ -0,0 +1,35 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { applyRecallStateViews } from "./recall-state-view-wire.js";
+import type { StateViewResult } from "./recall-state-view.js";
+
+function fact(id: string, extra: Partial<StateViewResult> = {}): StateViewResult {
+  return { id, ...extra };
+}
+
+const PAIR: StateViewResult[] = [
+  fact("new-job", { status: "active" }),
+  fact("old-job", { status: "superseded", supersededBy: "new-job", supersededAt: "2026-03-01" }),
+];
+
+test("recallStateViews false is identity (same array reference)", () => {
+  const input = PAIR.map((row) => ({ ...row }));
+  assert.equal(applyRecallStateViews(input, "when did the job title change", {}), input);
+  assert.equal(
+    applyRecallStateViews(input, "when did the job title change", { recallStateViews: false }),
+    input,
+  );
+  assert.equal(input[0]?.stateLabel, undefined);
+});
+
+test("change-intent query labels a synthetic superseded pair when recallStateViews is on", () => {
+  const labeled = applyRecallStateViews(PAIR, "when did the job title change", {
+    recallStateViews: true,
+  });
+  assert.equal(labeled.length, 2);
+  assert.equal(labeled[0]?.id, "new-job");
+  assert.equal(labeled[0]?.stateLabel, "current");
+  assert.equal(labeled[1]?.id, "old-job");
+  assert.equal(labeled[1]?.stateLabel, "historical");
+});

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

@@ -0,0 +1,18 @@
+/**
+ * Recall inject seam for state views (issue #1952).
+ *
+ * Widening lives in recall-state-view-widen.ts. parseConfig cannot grow.
+ * Operators set `recallStateViews` on the live PluginConfig extra field.
+ * Default false is identity.
+ */
+
+import { widenRecallStateViews } from "./recall-state-view-widen.js";
+import type { StateViewResult } from "./recall-state-view.js";
+
+export function applyRecallStateViews<T extends StateViewResult>(
+  results: T[],
+  query: string,
+  config: unknown,
+): T[] {
+  return widenRecallStateViews(results, query, config);
+}

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

@@ -0,0 +1,131 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  annotateStateView,
+  formatSupersededPrefix,
+  isChangeOrientedQuery,
+  parseRecallStateViews,
+  shouldWidenSuperseded,
+  type StateViewChain,
+  type StateViewResult,
+} from "./recall-state-view.js";
+
+function fact(id: string, extra: Partial<StateViewResult> = {}): StateViewResult {
+  return { id, ...extra };
+}
+
+const PAIR: StateViewChain[] = [{ predecessorId: "old-job", successorId: "new-job", supersededAt: "2026-03-01" }];
+
+const PAIR_RESULTS: StateViewResult[] = [
+  fact("new-job", { status: "active" }),
+  fact("old-job", { status: "superseded", supersededBy: "new-job", supersededAt: "2026-03-01" }),
+];
+
+test("change-intent query labels both facts in a superseded pair", () => {
+  const labeled = annotateStateView(PAIR_RESULTS, "when did the job title change", PAIR, { enabled: true });
+  assert.equal(labeled.length, 2);
+  assert.equal(labeled[0]?.id, "new-job");
+  assert.equal(labeled[0]?.stateLabel, "current");
+  assert.equal(labeled[1]?.id, "old-job");
+  assert.equal(labeled[1]?.stateLabel, "historical");
+});
+
+test("change-intent conjugations fire the annotator", () => {
+  const phrases = [
+    "when did we switch",
+    "we used to",
+    "before the move",
+    "after the cutover",
+    "they switched vendors",
+    "she switches stacks",
+    "switching away from it",
+    "the title changed",
+    "it changes next week",
+    "they are changing providers",
+  ];
+  for (const query of phrases) {
+    assert.equal(isChangeOrientedQuery(query), true, query);
+    const labeled = annotateStateView(PAIR_RESULTS, query, PAIR, { enabled: true });
+    assert.equal(labeled[0]?.stateLabel, "current", query);
+    assert.equal(labeled[1]?.stateLabel, "historical", query);
+  }
+});
+
+test("non-change query is identical (same array reference, no labels)", () => {
+  const input = PAIR_RESULTS.map((row) => ({ ...row }));
+  const out = annotateStateView(input, "what is the current job title", PAIR, { enabled: true });
+  assert.equal(out, input);
+  assert.equal(out[0]?.stateLabel, undefined);
+  assert.equal(out[1]?.stateLabel, undefined);
+});
+
+test("recallStateViews false is identity (same array reference)", () => {
+  const input = PAIR_RESULTS.map((row) => ({ ...row }));
+  assert.equal(annotateStateView(input, "when did the job title change", PAIR), input);
+  assert.equal(annotateStateView(input, "when did the job title change", PAIR, { enabled: false }), input);
+  assert.equal(input[0]?.stateLabel, undefined);
+});
+
+test("superseded never appears without its successor", () => {
+  const orphan = [fact("old-job", { status: "superseded", supersededBy: "new-job" })];
+  const out = annotateStateView(orphan, "when did this change", PAIR, { enabled: true });
+  assert.deepEqual(out, []);
+  assert.equal(shouldWidenSuperseded("new-job", new Set(["old-job"])), false);
+  assert.equal(shouldWidenSuperseded("new-job", new Set(["old-job", "new-job"])), true);
+  assert.equal(shouldWidenSuperseded(undefined, new Set(["new-job"])), false);
+});
+
+test("annotateStateView is sort-stable", () => {
+  const reversed = [PAIR_RESULTS[1]!, PAIR_RESULTS[0]!];
+  const labeled = annotateStateView(reversed, "when did the title change", PAIR, { enabled: true });
+  assert.deepEqual(
+    labeled.map((row) => row.id),
+    ["old-job", "new-job"],
+  );
+  assert.equal(labeled[0]?.stateLabel, "historical");
+  assert.equal(labeled[1]?.stateLabel, "current");
+});
+
+test("middle hop of a three-node chain is transition", () => {
+  const chains: StateViewChain[] = [
+    { predecessorId: "v1", successorId: "v2" },
+    { predecessorId: "v2", successorId: "v3" },
+  ];
+  const results = [
+    fact("v1", { status: "superseded", supersededBy: "v2" }),
+    fact("v2", { status: "superseded", supersededBy: "v3" }),
+    fact("v3", { status: "active" }),
+  ];
+  const labeled = annotateStateView(results, "what changed", chains, { enabled: true });
+  assert.deepEqual(
+    labeled.map((row) => [row.id, row.stateLabel]),
+    [
+      ["v1", "historical"],
+      ["v2", "transition"],
+      ["v3", "current"],
+    ],
+  );
+});
+
+test("formatSupersededPrefix matches the injected-block contract", () => {
+  assert.equal(formatSupersededPrefix("2026-03-01", "new-job"), "[superseded 2026-03-01 by new-job]");
+});
+
+test("parseRecallStateViews honors 0/false and defaults off", () => {
+  assert.equal(parseRecallStateViews(undefined), false);
+  assert.equal(parseRecallStateViews(false), false);
+  assert.equal(parseRecallStateViews(0), false);
+  assert.equal(parseRecallStateViews("false"), false);
+  assert.equal(parseRecallStateViews("0"), false);
+  assert.equal(parseRecallStateViews(true), true);
+  assert.equal(parseRecallStateViews(1), true);
+  assert.equal(parseRecallStateViews("true"), true);
+});
+
+test("annotateStateView does not mutate input rows", () => {
+  const input = PAIR_RESULTS.map((row) => ({ ...row }));
+  annotateStateView(input, "when did this change", PAIR, { enabled: true });
+  assert.equal(input[0]?.stateLabel, undefined);
+  assert.equal(input[1]?.stateLabel, undefined);
+});

package/src/recall-state-view.ts

@@ -0,0 +1,138 @@
+/**
+ * Recall state views (issue #1952).
+ *
+ * Config key: `recallStateViews` (default false). When false, annotateStateView
+ * is identity: same array reference, no `stateLabel`. config.ts is at its
+ * fileSizeGrandfather ceiling, so parseConfig wiring waits for a later PR.
+ * Call `parseRecallStateViews` at the recall seam when that lands.
+ *
+ * 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.
+ */
+import { coerceBooleanLike } from "./connectors/coerce.js";
+
+export type StateLabel = "current" | "historical" | "transition";
+
+export interface StateViewChain {
+  predecessorId: string;
+  successorId: string;
+  supersededAt?: string;
+}
+
+export interface StateViewResult {
+  id?: string;
+  docid?: string;
+  status?: string;
+  supersededBy?: string;
+  supersededAt?: string;
+  stateLabel?: StateLabel;
+}
+
+export const DEFAULT_RECALL_STATE_VIEWS = false;
+
+const CHANGE_WORDS = ["before", "after", "switch", "switches", "switched", "switching", "change", "changes", "changed", "changing"];
+
+export function parseRecallStateViews(raw: unknown): boolean {
+  return coerceBooleanLike(raw, "recallStateViews") === true;
+}
+
+export function isChangeOrientedQuery(query: string): boolean {
+  const lower = query.toLowerCase();
+  if (lower.includes("when did") || lower.includes("used to")) return true;
+  return CHANGE_WORDS.some((word) => {
+    const idx = lower.indexOf(word);
+    if (idx < 0) return false;
+    const before = idx === 0 || !/[a-z0-9]/.test(lower[idx - 1] ?? "");
+    const afterIdx = idx + word.length;
+    const after = afterIdx >= lower.length || !/[a-z0-9]/.test(lower[afterIdx] ?? "");
+    return before && after;
+  });
+}
+
+export function shouldWidenSuperseded(
+  successorId: string | undefined,
+  candidateIds: ReadonlySet<string>,
+): boolean {
+  return typeof successorId === "string" && successorId.length > 0 && candidateIds.has(successorId);
+}
+
+export function formatSupersededPrefix(date: string, successorId: string): string {
+  return `[superseded ${date} by ${successorId}]`;
+}
+
+export function resultStateViewId(result: StateViewResult): string {
+  return result.id ?? result.docid ?? "";
+}
+
+function buildSuccessorMap(results: readonly StateViewResult[], chains: readonly StateViewChain[]): Map<string, string> {
+  const byPred = new Map<string, string>();
+  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: string,
+  result: StateViewResult,
+  byPred: Map<string, string>,
+  admittedIds: ReadonlySet<string>,
+): StateLabel {
+  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";
+  return result.status === "superseded" ? "historical" : "current";
+}
+
+export function annotateStateView<T extends StateViewResult>(
+  results: T[],
+  query: string,
+  chains: readonly StateViewChain[],
+  options: { enabled?: boolean } = {},
+): T[] {
+  const enabled = options.enabled === true;
+  if (!enabled || !isChangeOrientedQuery(query)) return results;
+
+  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 admitted: T[] = [];
+  for (const result of results) {
+    const id = resultStateViewId(result);
+    const successorId = result.supersededBy ?? byPred.get(id);
+    const superseded = result.status === "superseded" || Boolean(result.supersededBy) || byPred.has(id);
+    if (!superseded || shouldWidenSuperseded(successorId, candidateIds)) {
+      admitted.push(result);
+    }
+  }
+
+  const admittedIds = new Set<string>();
+  for (const result of admitted) {
+    const id = resultStateViewId(result);
+    if (id) admittedIds.add(id);
+  }
+
+  return admitted.map((result) => {
+    const id = resultStateViewId(result);
+    return { ...result, stateLabel: labelFor(id, result, byPred, admittedIds) };
+  });
+}