@remnic/core 9.66.12 → 9.68.0

package/src/activity/timeline/recap-merge-edits.test.ts

@@ -0,0 +1,181 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  mergeRecapUserEdits,
+  type RecapSection,
+} from "./recap-merge-edits.js";
+
+test("edited section survives regeneration", () => {
+  const result = mergeRecapUserEdits({
+    generated: [{ key: "highlights", body: "new body" }],
+    edited: [{ key: "highlights", body: "hand edit" }],
+  });
+  assert.deepEqual(result.sections, [{ key: "highlights", body: "hand edit" }]);
+  assert.deepEqual(result.preserved, ["highlights"]);
+  assert.deepEqual(result.regenerated, []);
+});
+
+test("reset discards every edit", () => {
+  const result = mergeRecapUserEdits({
+    generated: [{ key: "highlights", body: "new body" }],
+    edited: [{ key: "highlights", body: "hand edit" }],
+    reset: true,
+  });
+  assert.deepEqual(result.sections, [{ key: "highlights", body: "new body" }]);
+  assert.deepEqual(result.preserved, []);
+  assert.deepEqual(result.regenerated, ["highlights"]);
+});
+
+test("edited-only section is kept and counted preserved", () => {
+  const result = mergeRecapUserEdits({
+    generated: [{ key: "highlights", body: "new body" }],
+    edited: [
+      { key: "highlights", body: "hand edit" },
+      { key: "zeta", body: "user section" },
+      { key: "alpha", body: "another user section" },
+    ],
+  });
+  assert.deepEqual(
+    result.sections.map((s) => s.key),
+    ["highlights", "alpha", "zeta"],
+  );
+  assert.deepEqual(result.preserved, ["highlights", "alpha", "zeta"]);
+  assert.deepEqual(result.regenerated, []);
+  const alpha = result.sections.find((s) => s.key === "alpha");
+  assert.equal(alpha?.body, "another user section");
+});
+
+test("edited-only section is dropped on reset", () => {
+  const result = mergeRecapUserEdits({
+    generated: [{ key: "highlights", body: "new body" }],
+    edited: [{ key: "zeta", body: "user section" }],
+    reset: true,
+  });
+  assert.deepEqual(
+    result.sections.map((s) => s.key),
+    ["highlights"],
+  );
+  assert.deepEqual(result.preserved, []);
+});
+
+test("generated-only section is included and counted regenerated", () => {
+  const result = mergeRecapUserEdits({
+    generated: [
+      { key: "highlights", body: "new body" },
+      { key: "notes", body: "generated notes" },
+    ],
+    edited: [{ key: "highlights", body: "hand edit" }],
+  });
+  const notes = result.sections.find((s) => s.key === "notes");
+  assert.equal(notes?.body, "generated notes");
+  assert.deepEqual(result.regenerated, ["notes"]);
+});
+
+test("whitespace-only edit falls back to generated body", () => {
+  const result = mergeRecapUserEdits({
+    generated: [{ key: "highlights", body: "new body" }],
+    edited: [{ key: "highlights", body: "  \n\t " }],
+  });
+  assert.deepEqual(result.sections, [{ key: "highlights", body: "new body" }]);
+  assert.deepEqual(result.preserved, []);
+  assert.deepEqual(result.regenerated, ["highlights"]);
+});
+
+test("whitespace-only edited-only key is dropped entirely", () => {
+  const result = mergeRecapUserEdits({
+    generated: [{ key: "highlights", body: "new body" }],
+    edited: [{ key: "zeta", body: "   " }],
+  });
+  assert.deepEqual(
+    result.sections.map((s) => s.key),
+    ["highlights"],
+  );
+  assert.deepEqual(result.preserved, []);
+});
+
+test("duplicate keys keep the first occurrence", () => {
+  const result = mergeRecapUserEdits({
+    generated: [
+      { key: "highlights", body: "first generated" },
+      { key: "highlights", body: "second generated" },
+    ],
+    edited: [
+      { key: "highlights", body: "first edit" },
+      { key: "highlights", body: "second edit" },
+    ],
+  });
+  assert.deepEqual(result.sections, [
+    { key: "highlights", body: "first edit" },
+  ]);
+});
+
+test("duplicate edited-only keys keep the first occurrence", () => {
+  const result = mergeRecapUserEdits({
+    generated: [{ key: "highlights", body: "gen" }],
+    edited: [
+      { key: "zeta", body: "first user section" },
+      { key: "zeta", body: "second user section" },
+    ],
+  });
+  const zeta = result.sections.find((s) => s.key === "zeta");
+  assert.equal(zeta?.body, "first user section");
+  assert.equal(result.sections.filter((s) => s.key === "zeta").length, 1);
+});
+
+test("output is deterministic across two calls on the same input", () => {
+  const input = {
+    generated: [
+      { key: "notes", body: "generated notes" },
+      { key: "highlights", body: "new body" },
+    ],
+    edited: [
+      { key: "zeta", body: "user section" },
+      { key: "highlights", body: "hand edit" },
+      { key: "alpha", body: "another user section" },
+    ],
+  };
+  const first = mergeRecapUserEdits(input);
+  const second = mergeRecapUserEdits(input);
+  assert.deepEqual(first, second);
+  assert.deepEqual(
+    first.sections.map((s) => s.key),
+    ["notes", "highlights", "alpha", "zeta"],
+  );
+});
+
+test("preserved and regenerated are disjoint and cover every output key", () => {
+  const result = mergeRecapUserEdits({
+    generated: [
+      { key: "highlights", body: "new body" },
+      { key: "notes", body: "generated notes" },
+    ],
+    edited: [
+      { key: "highlights", body: "hand edit" },
+      { key: "zeta", body: "user section" },
+    ],
+  });
+  const outputKeys = result.sections.map((s) => s.key).sort();
+  const accounted = [...result.preserved, ...result.regenerated].sort();
+  assert.deepEqual(accounted, outputKeys);
+  for (const key of result.preserved) {
+    assert.equal(result.regenerated.includes(key), false);
+  }
+});
+
+test("inputs are not mutated", () => {
+  const generated: RecapSection[] = [
+    { key: "highlights", body: "new body" },
+    { key: "notes", body: "generated notes" },
+  ];
+  const edited: RecapSection[] = [
+    { key: "highlights", body: "hand edit" },
+    { key: "zeta", body: "user section" },
+  ];
+  const generatedSnapshot = structuredClone(generated);
+  const editedSnapshot = structuredClone(edited);
+  mergeRecapUserEdits({ generated, edited, reset: false });
+  mergeRecapUserEdits({ generated, edited, reset: true });
+  assert.deepEqual(generated, generatedSnapshot);
+  assert.deepEqual(edited, editedSnapshot);
+});

package/src/activity/timeline/recap-merge-edits.ts

@@ -0,0 +1,70 @@
+/**
+ * Merge user hand-edits into a regenerated journal recap (issue #2051).
+ *
+ * Rule: user edits survive regeneration; an explicit reset is the only
+ * way to discard them. Pure — no I/O, no clock, no randomness.
+ */
+
+export interface RecapSection {
+  /** Stable section key, e.g. "highlights". */
+  key: string;
+  body: string;
+}
+
+export type MergeRecapEditsResult = {
+  sections: RecapSection[];
+  /** Section keys whose user edit was kept over the regenerated body. */
+  preserved: string[];
+  /** Section keys taken from the regenerated recap. */
+  regenerated: string[];
+};
+
+function dedupeByFirst(list: readonly RecapSection[]): RecapSection[] {
+  const seen = new Set<string>();
+  const out: RecapSection[] = [];
+  for (const section of list) {
+    if (seen.has(section.key)) continue;
+    seen.add(section.key);
+    out.push(section);
+  }
+  return out;
+}
+
+export function mergeRecapUserEdits(input: {
+  generated: readonly RecapSection[];
+  edited?: readonly RecapSection[];
+  reset?: boolean;
+}): MergeRecapEditsResult {
+  const generated = dedupeByFirst(input.generated);
+  const edited = dedupeByFirst(input.edited ?? []);
+  const editedByKey = new Map(edited.map((s) => [s.key, s]));
+
+  const sections: RecapSection[] = [];
+  const preserved: string[] = [];
+  const regenerated: string[] = [];
+
+  for (const gen of generated) {
+    const edit = editedByKey.get(gen.key);
+    if (!input.reset && edit !== undefined && edit.body.trim() !== "") {
+      sections.push({ key: gen.key, body: edit.body });
+      preserved.push(gen.key);
+    } else {
+      sections.push({ key: gen.key, body: gen.body });
+      regenerated.push(gen.key);
+    }
+  }
+
+  if (!input.reset) {
+    const generatedKeys = new Set(generated.map((s) => s.key));
+    const editedOnly = edited
+      .filter((s) => !generatedKeys.has(s.key))
+      .filter((s) => s.body.trim() !== "")
+      .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+    for (const edit of editedOnly) {
+      sections.push({ key: edit.key, body: edit.body });
+      preserved.push(edit.key);
+    }
+  }
+
+  return { sections, preserved, regenerated };
+}

package/src/extraction-span-gate.test.ts

@@ -0,0 +1,202 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import {
+  evaluateSpanPhaseGate,
+  SPAN_GATE_MAX_FALLBACK_RATE_PCT,
+  SPAN_GATE_MAX_JUDGE_DROP_POINTS,
+  SPAN_GATE_MIN_WALLCLOCK_REDUCTION_PCT,
+} from "./extraction-span-gate.js";
+
+function assertRangeError(fn: () => unknown, field: string): void {
+  assert.throws(fn, (err: unknown) => {
+    assert.ok(err instanceof RangeError, `expected RangeError, got ${String(err)}`);
+    assert.match((err as RangeError).message, new RegExp(field));
+    return true;
+  });
+}
+
+describe("evaluateSpanPhaseGate", () => {
+  it("passes the Phase A bench numbers from the issue", () => {
+    const verdict = evaluateSpanPhaseGate({
+      wallClockReductionPct: 45,
+      judgeScoreDropPoints: 0.3,
+      fallbackRatePct: 4,
+    });
+    assert.deepEqual(verdict, {
+      pass: true,
+      conditions: { wallClockReduction: true, judgeQuality: true, fallbackRate: true },
+      failed: [],
+    });
+  });
+
+  it("treats the wall-clock boundary 20.0 as a pass (>= 20)", () => {
+    const verdict = evaluateSpanPhaseGate({
+      wallClockReductionPct: SPAN_GATE_MIN_WALLCLOCK_REDUCTION_PCT,
+      judgeScoreDropPoints: 0,
+      fallbackRatePct: 0,
+    });
+    assert.equal(verdict.conditions.wallClockReduction, true);
+  });
+
+  it("treats a judge drop of exactly 2.0 as a failure (< 2)", () => {
+    const verdict = evaluateSpanPhaseGate({
+      wallClockReductionPct: 45,
+      judgeScoreDropPoints: SPAN_GATE_MAX_JUDGE_DROP_POINTS,
+      fallbackRatePct: 4,
+    });
+    assert.equal(verdict.pass, false);
+    assert.deepEqual(verdict.failed, ["judgeQuality"]);
+  });
+
+  it("treats a fallback rate of exactly 15.0 as a failure (< 15)", () => {
+    const verdict = evaluateSpanPhaseGate({
+      wallClockReductionPct: 45,
+      judgeScoreDropPoints: 0.3,
+      fallbackRatePct: SPAN_GATE_MAX_FALLBACK_RATE_PCT,
+    });
+    assert.equal(verdict.pass, false);
+    assert.deepEqual(verdict.failed, ["fallbackRate"]);
+  });
+
+  it("fails on wall-clock reduction alone", () => {
+    const verdict = evaluateSpanPhaseGate({
+      wallClockReductionPct: 19.9,
+      judgeScoreDropPoints: 0.3,
+      fallbackRatePct: 4,
+    });
+    assert.equal(verdict.pass, false);
+    assert.deepEqual(verdict.failed, ["wallClockReduction"]);
+  });
+
+  it("fails on judge quality alone", () => {
+    const verdict = evaluateSpanPhaseGate({
+      wallClockReductionPct: 45,
+      judgeScoreDropPoints: 2.5,
+      fallbackRatePct: 4,
+    });
+    assert.equal(verdict.pass, false);
+    assert.deepEqual(verdict.failed, ["judgeQuality"]);
+  });
+
+  it("fails on fallback rate alone", () => {
+    const verdict = evaluateSpanPhaseGate({
+      wallClockReductionPct: 45,
+      judgeScoreDropPoints: 0.3,
+      fallbackRatePct: 15.1,
+    });
+    assert.equal(verdict.pass, false);
+    assert.deepEqual(verdict.failed, ["fallbackRate"]);
+  });
+
+  it("lists all three failures in declaration order", () => {
+    const verdict = evaluateSpanPhaseGate({
+      wallClockReductionPct: 10,
+      judgeScoreDropPoints: 3,
+      fallbackRatePct: 20,
+    });
+    assert.equal(verdict.pass, false);
+    assert.deepEqual(verdict.conditions, {
+      wallClockReduction: false,
+      judgeQuality: false,
+      fallbackRate: false,
+    });
+    assert.deepEqual(verdict.failed, ["wallClockReduction", "judgeQuality", "fallbackRate"]);
+  });
+
+  it("fails a negative wall-clock reduction without throwing", () => {
+    const verdict = evaluateSpanPhaseGate({
+      wallClockReductionPct: -5,
+      judgeScoreDropPoints: 0.3,
+      fallbackRatePct: 4,
+    });
+    assert.equal(verdict.pass, false);
+    assert.deepEqual(verdict.failed, ["wallClockReduction"]);
+  });
+
+  it("passes a negative judge drop (quality improved)", () => {
+    const verdict = evaluateSpanPhaseGate({
+      wallClockReductionPct: 45,
+      judgeScoreDropPoints: -0.5,
+      fallbackRatePct: 4,
+    });
+    assert.equal(verdict.conditions.judgeQuality, true);
+    assert.equal(verdict.pass, true);
+  });
+
+  it("throws RangeError naming the field on non-finite wall-clock reduction", () => {
+    assertRangeError(
+      () =>
+        evaluateSpanPhaseGate({
+          wallClockReductionPct: Number.NaN,
+          judgeScoreDropPoints: 0.3,
+          fallbackRatePct: 4,
+        }),
+      "wallClockReductionPct",
+    );
+  });
+
+  it("throws RangeError naming the field on non-finite judge drop", () => {
+    assertRangeError(
+      () =>
+        evaluateSpanPhaseGate({
+          wallClockReductionPct: 45,
+          judgeScoreDropPoints: Number.POSITIVE_INFINITY,
+          fallbackRatePct: 4,
+        }),
+      "judgeScoreDropPoints",
+    );
+  });
+
+  it("throws RangeError naming the field on non-finite fallback rate", () => {
+    assertRangeError(
+      () =>
+        evaluateSpanPhaseGate({
+          wallClockReductionPct: 45,
+          judgeScoreDropPoints: 0.3,
+          fallbackRatePct: Number.NEGATIVE_INFINITY,
+        }),
+      "fallbackRatePct",
+    );
+  });
+
+  it("throws RangeError on a fallback rate of 101", () => {
+    assertRangeError(
+      () =>
+        evaluateSpanPhaseGate({
+          wallClockReductionPct: 45,
+          judgeScoreDropPoints: 0.3,
+          fallbackRatePct: 101,
+        }),
+      "fallbackRatePct",
+    );
+  });
+
+  it("throws RangeError on a fallback rate of -1", () => {
+    assertRangeError(
+      () =>
+        evaluateSpanPhaseGate({
+          wallClockReductionPct: 45,
+          judgeScoreDropPoints: 0.3,
+          fallbackRatePct: -1,
+        }),
+      "fallbackRatePct",
+    );
+  });
+
+  it("accepts the fallback-rate endpoints 0 and 100 as measurements", () => {
+    assert.doesNotThrow(() =>
+      evaluateSpanPhaseGate({
+        wallClockReductionPct: 45,
+        judgeScoreDropPoints: 0.3,
+        fallbackRatePct: 0,
+      }),
+    );
+    const verdict = evaluateSpanPhaseGate({
+      wallClockReductionPct: 45,
+      judgeScoreDropPoints: 0.3,
+      fallbackRatePct: 100,
+    });
+    assert.deepEqual(verdict.failed, ["fallbackRate"]);
+  });
+});

package/src/extraction-span-gate.ts

@@ -0,0 +1,58 @@
+/**
+ * Span-mode Phase B gate (issue #2333).
+ *
+ * Phase A must earn >= 20% extraction wall-clock reduction, keep the LLM-judge
+ * score drop under 2 points, and keep the span fallback rate under 15% before
+ * Phase B wiring starts. A failed gate is reported, never rounded into a pass.
+ *
+ * Pure. No I/O, no clock, no randomness.
+ */
+
+export const SPAN_GATE_MIN_WALLCLOCK_REDUCTION_PCT = 20;
+export const SPAN_GATE_MAX_JUDGE_DROP_POINTS = 2;
+export const SPAN_GATE_MAX_FALLBACK_RATE_PCT = 15;
+
+export interface SpanGateConditions {
+  wallClockReduction: boolean;
+  judgeQuality: boolean;
+  fallbackRate: boolean;
+}
+
+export interface SpanGateVerdict {
+  /** True only when every condition passes. */
+  pass: boolean;
+  conditions: SpanGateConditions;
+  /** Condition names that failed, in declaration order. Empty when pass. */
+  failed: string[];
+}
+
+function requireFinite(value: number, field: string): void {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new RangeError(`span gate input ${field} must be a finite number, got ${value}`);
+  }
+}
+
+export function evaluateSpanPhaseGate(input: {
+  wallClockReductionPct: number;
+  judgeScoreDropPoints: number;
+  fallbackRatePct: number;
+}): SpanGateVerdict {
+  requireFinite(input.wallClockReductionPct, "wallClockReductionPct");
+  requireFinite(input.judgeScoreDropPoints, "judgeScoreDropPoints");
+  requireFinite(input.fallbackRatePct, "fallbackRatePct");
+  if (input.fallbackRatePct < 0 || input.fallbackRatePct > 100) {
+    throw new RangeError(
+      `span gate input fallbackRatePct must be within [0, 100], got ${input.fallbackRatePct}`,
+    );
+  }
+
+  const conditions: SpanGateConditions = {
+    wallClockReduction: input.wallClockReductionPct >= SPAN_GATE_MIN_WALLCLOCK_REDUCTION_PCT,
+    judgeQuality: input.judgeScoreDropPoints < SPAN_GATE_MAX_JUDGE_DROP_POINTS,
+    fallbackRate: input.fallbackRatePct < SPAN_GATE_MAX_FALLBACK_RATE_PCT,
+  };
+  const failed = (Object.keys(conditions) as (keyof SpanGateConditions)[]).filter(
+    (name) => !conditions[name],
+  );
+  return { pass: failed.length === 0, conditions, failed };
+}

package/src/recall-navigate-window.test.ts

@@ -0,0 +1,104 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  DEFAULT_NAVIGATION_WINDOW_SNAPSHOTS,
+  assertIdInNavigationWindow,
+  type NavigationSnapshot,
+} from "./recall-navigate-window.js";
+
+const snap = (...servedIds: string[]): NavigationSnapshot => ({ servedIds });
+const malformed = (value: unknown): NavigationSnapshot => value as NavigationSnapshot;
+
+test("default window is 3 snapshots", () => {
+  assert.equal(DEFAULT_NAVIGATION_WINDOW_SNAPSHOTS, 3);
+});
+
+test("id in the newest snapshot is ok", () => {
+  assert.deepEqual(
+    assertIdInNavigationWindow({ snapshots: [snap("fact-1"), snap("fact-2")], memoryId: "fact-1" }),
+    { ok: true, memoryId: "fact-1" },
+  );
+});
+
+test("id in the 3rd snapshot is ok at the default window", () => {
+  const snapshots = [snap("fact-a"), snap("fact-b"), snap("fact-c"), snap("fact-d")];
+  assert.deepEqual(assertIdInNavigationWindow({ snapshots, memoryId: "fact-c" }), {
+    ok: true,
+    memoryId: "fact-c",
+  });
+});
+
+test("id only in a 4th snapshot is not_served", () => {
+  const snapshots = [snap("fact-a"), snap("fact-b"), snap("fact-c"), snap("fact-d")];
+  assert.deepEqual(assertIdInNavigationWindow({ snapshots, memoryId: "fact-d" }), {
+    ok: false,
+    error: "not_served",
+  });
+});
+
+test("windowSnapshots 1 rejects an id from the 2nd snapshot", () => {
+  const snapshots = [snap("fact-a"), snap("fact-b")];
+  assert.deepEqual(
+    assertIdInNavigationWindow({ snapshots, memoryId: "fact-b", windowSnapshots: 1 }),
+    { ok: false, error: "not_served" },
+  );
+});
+
+test("windowSnapshots 0, negative, fractional, NaN, Infinity throw", () => {
+  const snapshots = [snap("fact-a")];
+  for (const windowSnapshots of [0, -1, 1.5, Number.NaN, Number.POSITIVE_INFINITY]) {
+    assert.throws(
+      () => assertIdInNavigationWindow({ snapshots, memoryId: "fact-a", windowSnapshots }),
+      { name: "RangeError", message: /windowSnapshots/ },
+    );
+  }
+});
+
+test("non-string and whitespace ids are empty_id, never not_served", () => {
+  const snapshots = [snap("fact-a")];
+  for (const memoryId of [null, undefined, 42, {}, "", "   ", "\t\n"]) {
+    assert.deepEqual(assertIdInNavigationWindow({ snapshots, memoryId }), {
+      ok: false,
+      error: "empty_id",
+    });
+  }
+});
+
+test("padded id matches after trim", () => {
+  const snapshots = [snap("fact-1")];
+  assert.deepEqual(assertIdInNavigationWindow({ snapshots, memoryId: "  fact-1 \t" }), {
+    ok: true,
+    memoryId: "fact-1",
+  });
+});
+
+test("case-different id is not_served", () => {
+  const snapshots = [snap("Fact-1")];
+  assert.deepEqual(assertIdInNavigationWindow({ snapshots, memoryId: "fact-1" }), {
+    ok: false,
+    error: "not_served",
+  });
+});
+
+test("empty snapshots list is not_served", () => {
+  assert.deepEqual(assertIdInNavigationWindow({ snapshots: [], memoryId: "fact-1" }), {
+    ok: false,
+    error: "not_served",
+  });
+});
+
+test("malformed snapshot consumes its window slot without throwing", () => {
+  // Missing servedIds on the newest snapshot: it still burns the only
+  // window slot, so the id served by the 2nd snapshot stays not_served.
+  assert.doesNotThrow(() => {
+    assert.deepEqual(
+      assertIdInNavigationWindow({
+        snapshots: [malformed({}), malformed({ servedIds: "fact-1" })],
+        memoryId: "fact-1",
+        windowSnapshots: 1,
+      }),
+      { ok: false, error: "not_served" },
+    );
+  });
+});

package/src/recall-navigate-window.ts

@@ -0,0 +1,48 @@
+/**
+ * Recall navigation window authority (issue #1956).
+ *
+ * Pure. An expandable id must have been served by one of the session's
+ * last `windowSnapshots` recall snapshots, ordered newest first. Unknown
+ * or foreign ids are rejected, not reinterpreted (pattern 39).
+ */
+
+export const DEFAULT_NAVIGATION_WINDOW_SNAPSHOTS = 3;
+
+/** Ids served by one recall snapshot, newest snapshot first when passed in. */
+export interface NavigationSnapshot {
+  servedIds: readonly string[];
+}
+
+export type NavigationAuthorityResult =
+  | { ok: true; memoryId: string }
+  | { ok: false; error: "empty_id" | "not_served" };
+
+export function assertIdInNavigationWindow(input: {
+  snapshots: readonly NavigationSnapshot[];
+  memoryId: unknown;
+  windowSnapshots?: number;
+}): NavigationAuthorityResult {
+  const windowSnapshots = input.windowSnapshots ?? DEFAULT_NAVIGATION_WINDOW_SNAPSHOTS;
+  if (!Number.isInteger(windowSnapshots) || windowSnapshots < 1) {
+    throw new RangeError(
+      `windowSnapshots must be a positive integer; got ${JSON.stringify(windowSnapshots)}`,
+    );
+  }
+  if (typeof input.memoryId !== "string" || input.memoryId.trim() === "") {
+    return { ok: false, error: "empty_id" };
+  }
+  const wanted = input.memoryId.trim();
+  for (const snapshot of input.snapshots.slice(0, windowSnapshots)) {
+    // A malformed entry (missing or non-array servedIds) was still a real
+    // recall turn: it consumes a window slot but contributes no ids.
+    if (!snapshot || !Array.isArray(snapshot.servedIds)) {
+      continue;
+    }
+    for (const served of snapshot.servedIds) {
+      if (typeof served === "string" && served.trim() === wanted) {
+        return { ok: true, memoryId: wanted };
+      }
+    }
+  }
+  return { ok: false, error: "not_served" };
+}