@remnic/core 9.66.1 → 9.66.2

package/src/extraction-span.ts

@@ -0,0 +1,39 @@
+/**
+ * Isolated span-offset parser (issue #2333 first slice).
+ *
+ * Default off. Extraction wiring waits on the Phase A bench gate.
+ */
+
+export interface SpanOffsets {
+  start: number;
+  end: number;
+}
+
+export interface ParsedSpan {
+  text: string;
+  start?: number;
+  end?: number;
+}
+
+export function parseSpanOffsets(
+  text: string,
+  offsets: SpanOffsets,
+  spanModeEnabled: boolean | 0 | 1 = false,
+): ParsedSpan {
+  if (spanModeEnabled !== true && spanModeEnabled !== 1) {
+    return { text };
+  }
+
+  const { start, end } = offsets;
+  if (!Number.isInteger(start) || !Number.isInteger(end)) {
+    throw new RangeError("invalid span: out of range");
+  }
+  if (start > end) {
+    throw new RangeError("invalid span: reversed");
+  }
+  if (start < 0 || end > text.length) {
+    throw new RangeError("invalid span: out of range");
+  }
+
+  return { text: text.slice(start, end), start, end };
+}

package/src/index.ts

@@ -1458,3 +1458,4 @@ export * from "./maintenance/atomic-file.js";
 export * from "./eval-trajectory.js";
 export { MemoryControllerCoordinator, chooseAction, computeEvidenceReportHash, controllerConfigHash, evaluateActiveGates, hashControllerState, verifyEvidenceReport } from "./memory-controller.js";
 export type { ActiveContextAdapter, ActiveContextMessage, ActiveContextPlan, MemoryControllerActionFamily, MemoryControllerChoice, MemoryControllerConfig, MemoryControllerDeps, MemoryControllerEvent, MemoryControllerEvidence, MemoryControllerEvidenceReport, MemoryControllerExecutors, MemoryControllerMode, MemoryControllerPairedSeedEvidence, MemoryControllerReceipt, MemoryControllerRecorder, MemoryControllerReportReader, MemoryControllerRunResult, MemoryControllerState } from "./memory-controller.js";
+export * from "./recall-navigate.js";

package/src/recall-deep-access.test.ts

@@ -0,0 +1,58 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { runDeepRecallAccess } from "./recall-deep-access.js";
+
+const QUERY = "who met at the cafe";
+
+test("budget 0 stops immediately with a tagged refusal", () => {
+  const result = runDeepRecallAccess({ query: QUERY, budget: 0, policyName: "expand-once" });
+  assert.equal(result.ok, false);
+  assert.deepEqual(result.refusal, { tag: "budget_exhausted" });
+  assert.equal(result.trace.length, 1);
+  assert.equal(result.trace[0]?.action, "stop");
+  assert.equal(result.state.budget, 0);
+  assert.equal(result.state.query, QUERY);
+  assert.deepEqual(result.state.workingSet, []);
+  assert.deepEqual(result.state.frontier, []);
+  assert.equal(result.traceJson, JSON.stringify(result.trace));
+});
+
+test("unknown policyName is rejected", () => {
+  assert.throws(
+    () => runDeepRecallAccess({ query: QUERY, budget: 2, policyName: "refine-twice" }),
+    /unknown deep recall access policy/,
+  );
+  assert.throws(
+    () => runDeepRecallAccess({ query: QUERY, budget: 2, policyName: "refine-twice" }),
+    /stop, expand-once/,
+  );
+});
+
+test("stop policy ends without expanding", () => {
+  const result = runDeepRecallAccess({ query: QUERY, budget: 3, policyName: "stop" });
+  assert.equal(result.ok, true);
+  assert.equal(result.refusal, undefined);
+  assert.equal(result.trace.length, 1);
+  assert.equal(result.trace[0]?.action, "stop");
+  assert.equal(result.state.budget, 3);
+  assert.deepEqual(result.state.workingSet, []);
+});
+
+test("expand-once expands once then stops", () => {
+  const result = runDeepRecallAccess({ query: QUERY, budget: 3, policyName: "expand-once" });
+  assert.equal(result.ok, true);
+  assert.deepEqual(
+    result.trace.map((step) => step.action),
+    ["expand", "stop"],
+  );
+  assert.equal(result.state.budget, 2);
+});
+
+test("same input produces the same trace JSON", () => {
+  const input = { query: QUERY, budget: 4, policyName: "expand-once" as const };
+  const first = runDeepRecallAccess(input);
+  const second = runDeepRecallAccess(input);
+  assert.equal(first.traceJson, second.traceJson);
+  assert.equal(first.traceJson, JSON.stringify(first.trace));
+});

package/src/recall-deep-access.ts

@@ -0,0 +1,71 @@
+/**
+ * Named-policy access facade for the deep-recall stepper (issue #2332 leftover).
+ *
+ * Not the hot path. Surfaces and parseConfig wait. Policy names are
+ * allow-listed. Budget 0 returns a tagged refusal without a policy call.
+ */
+
+import { runDeepRecall, type DeepRecallResult, type DeepRecallState } from "./recall-deep.js";
+
+export const DEEP_RECALL_ACCESS_POLICIES = ["stop", "expand-once"] as const;
+
+export type DeepRecallAccessPolicyName = (typeof DEEP_RECALL_ACCESS_POLICIES)[number];
+
+export interface DeepRecallAccessInput {
+  query: string;
+  budget: number;
+  policyName: string;
+}
+
+export interface DeepRecallAccessRefusal {
+  tag: "budget_exhausted";
+}
+
+export interface DeepRecallAccessResult {
+  ok: boolean;
+  refusal?: DeepRecallAccessRefusal;
+  state: DeepRecallState;
+  trace: DeepRecallResult["trace"];
+  traceJson: string;
+}
+
+export function isDeepRecallAccessPolicyName(value: unknown): value is DeepRecallAccessPolicyName {
+  return typeof value === "string" && (DEEP_RECALL_ACCESS_POLICIES as readonly string[]).includes(value);
+}
+
+export function runDeepRecallAccess(input: DeepRecallAccessInput): DeepRecallAccessResult {
+  if (!isDeepRecallAccessPolicyName(input.policyName)) {
+    throw new Error(
+      `unknown deep recall access policy: ${JSON.stringify(input.policyName)}. Valid: ${DEEP_RECALL_ACCESS_POLICIES.join(", ")}`,
+    );
+  }
+
+  const start: DeepRecallState = { query: input.query, workingSet: [], frontier: [], budget: input.budget };
+  if (!Number.isFinite(input.budget) || input.budget <= 0) {
+    const result = runDeepRecall(start, () => {
+      throw new Error("policy must not run when budget is 0");
+    });
+    return {
+      ok: false,
+      refusal: { tag: "budget_exhausted" },
+      state: result.state,
+      trace: result.trace,
+      traceJson: JSON.stringify(result.trace),
+    };
+  }
+
+  let expanded = false;
+  const result = runDeepRecall(start, () => {
+    if (input.policyName === "expand-once" && !expanded) {
+      expanded = true;
+      return "expand";
+    }
+    return "stop";
+  });
+  return {
+    ok: true,
+    state: result.state,
+    trace: result.trace,
+    traceJson: JSON.stringify(result.trace),
+  };
+}

package/src/recall-deep-render.test.ts

@@ -0,0 +1,68 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  runDeepRecall,
+  type DeepRecallState,
+} from "./recall-deep.js";
+import { renderDeepRecallTrace } from "./recall-deep-render.js";
+
+function seed(extra: Partial<DeepRecallState> = {}): DeepRecallState {
+  return {
+    query: "who met at the cafe",
+    workingSet: [],
+    frontier: ["m-b", "m-c"],
+    budget: 2,
+    ...extra,
+  };
+}
+
+test("empty working set prints (empty)", () => {
+  const result = runDeepRecall(seed({ budget: 0 }), () => {
+    throw new Error("policy must not run when budget is 0");
+  });
+  assert.equal(
+    renderDeepRecallTrace(result),
+    [
+      "# Deep recall",
+      "",
+      "- query: who met at the cafe",
+      "- budget: 0",
+      "- stop: budget exhausted",
+      "",
+      "## Steps",
+      "",
+      "1. stop budget=0 workingSet=(empty) frontier=m-b, m-c",
+      "",
+    ].join("\n"),
+  );
+});
+
+test("expand then stop snapshot", () => {
+  const result = runDeepRecall(seed({ workingSet: ["m-seed"], budget: 2 }), (state) =>
+    state.workingSet.includes("m-b") ? "stop" : "expand",
+  );
+  assert.equal(
+    renderDeepRecallTrace(result),
+    [
+      "# Deep recall",
+      "",
+      "- query: who met at the cafe",
+      "- budget: 1",
+      "- stop: stop",
+      "",
+      "## Steps",
+      "",
+      "1. expand budget=1 workingSet=m-seed, m-b frontier=m-c",
+      "2. stop budget=1 workingSet=m-seed, m-b frontier=m-c",
+      "",
+    ].join("\n"),
+  );
+});
+
+test("same result renders the same bytes", () => {
+  const policy = () => "stop";
+  const first = renderDeepRecallTrace(runDeepRecall(seed({ budget: 3 }), policy));
+  const second = renderDeepRecallTrace(runDeepRecall(seed({ budget: 3 }), policy));
+  assert.equal(first, second);
+});

package/src/recall-deep-render.ts

@@ -0,0 +1,32 @@
+/**
+ * Markdown renderer for a deep-recall trace (issue #2332 leftover).
+ *
+ * Deterministic. Surfaces wait. Empty working set prints (empty).
+ */
+
+import type { DeepRecallResult } from "./recall-deep.js";
+
+export function renderDeepRecallTrace(result: DeepRecallResult): string {
+  const last = result.trace[result.trace.length - 1];
+  const stop = !last ? "none" : last.budget <= 0 ? "budget exhausted" : last.action;
+  const steps =
+    result.trace.length === 0
+      ? ["(empty)"]
+      : result.trace.map((step, index) => {
+          const workingSet = step.workingSet.length === 0 ? "(empty)" : step.workingSet.join(", ");
+          const frontier = step.frontier.length === 0 ? "(empty)" : step.frontier.join(", ");
+          return `${index + 1}. ${step.action} budget=${step.budget} workingSet=${workingSet} frontier=${frontier}`;
+        });
+  return [
+    "# Deep recall",
+    "",
+    `- query: ${result.state.query}`,
+    `- budget: ${result.state.budget}`,
+    `- stop: ${stop}`,
+    "",
+    "## Steps",
+    "",
+    ...steps,
+    "",
+  ].join("\n");
+}

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.ts

@@ -1,28 +1,18 @@
 /**
  * Recall inject seam for state views (issue #1952).
  *
- * parseConfig cannot grow (fileSizeGrandfather). Operators set
- * `recallStateViews` on the live PluginConfig extra field. Default false
- * is identity. Use parseRecallStateViews — do not read a scattered
- * config flag property here.
+ * 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 {
-  annotateStateView,
-  parseRecallStateViews,
-  type StateViewResult,
-} from "./recall-state-view.js";
+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[] {
-  const raw =
-    typeof config === "object" && config !== null && "recallStateViews" in config
-      ? (config as { recallStateViews?: unknown }).recallStateViews
-      : undefined;
-  return annotateStateView(results, query, [], {
-    enabled: parseRecallStateViews(raw),
-  });
+  return widenRecallStateViews(results, query, config);
 }

package/src/shared-context/staleness.test.ts

@@ -0,0 +1,36 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import {
+  filterLiveEnvelopes,
+  markSupersededCirculation,
+  type SharedStalenessItem,
+} from "./staleness.js";
+
+test("filterLiveEnvelopes drops at the expiry instant (half-open)", () => {
+  const expiresAt = "2026-08-18T12:00:00.000Z";
+  const at = Date.parse(expiresAt);
+  const live: SharedStalenessItem = { id: "keep", expiresAt };
+  const forever: SharedStalenessItem = { id: "legacy" };
+  const items: SharedStalenessItem[] = [live, forever];
+
+  assert.deepEqual(filterLiveEnvelopes(items, at - 1), items);
+  assert.deepEqual(filterLiveEnvelopes(items, at), [forever]);
+  assert.deepEqual(filterLiveEnvelopes(items, at + 1), [forever]);
+  assert.equal(items.length, 2);
+});
+
+test("markSupersededCirculation flags targets that still circulate", () => {
+  const older: SharedStalenessItem = { id: "item-1", expiresAt: "2026-08-19T00:00:00.000Z" };
+  const newer: SharedStalenessItem = { id: "item-2", supersedes: "item-1" };
+  const other: SharedStalenessItem = { id: "item-3" };
+  const items: SharedStalenessItem[] = [older, newer, other];
+
+
+  const marked = markSupersededCirculation(items);
+  assert.equal(marked[0]?.circulating, true);
+  assert.equal(marked[1]?.circulating, undefined);
+  assert.equal(marked[2]?.circulating, undefined);
+  assert.equal(older.circulating, undefined);
+  assert.notEqual(marked[0], older);
+});

package/src/shared-context/staleness.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared-item staleness (issue #1957).
+ *
+ * Pure helpers. Expired items drop; superseded items that still circulate
+ * get a marker. Callers never `rm`.
+ */
+import { isExpired } from "./governance.js";
+
+export interface SharedStalenessItem {
+  id: string;
+  expiresAt?: string;
+  supersedes?: string;
+  circulating?: boolean;
+}
+
+/** Drop expired items. Half-open: `nowMs >= expiresAt` is expired. */
+export function filterLiveEnvelopes<T extends { expiresAt?: string }>(
+  items: readonly T[],
+  nowMs: number,
+): T[] {
+  return items.filter((item) => !isExpired(item, nowMs));
+}
+
+/**
+ * Mark items whose id appears in another item's `supersedes`.
+ * Returns a new array. Does not mutate input and does not delete files.
+ */
+export function markSupersededCirculation<T extends SharedStalenessItem>(
+  items: readonly T[],
+): T[] {
+  const supersededIds = new Set<string>();
+  for (const item of items) {
+    if (item.supersedes) supersededIds.add(item.supersedes);
+  }
+  return items.map((item) =>
+    supersededIds.has(item.id) ? { ...item, circulating: true } : item,
+  );
+}