@remnic/core 9.67.0 → 9.69.0

package/src/activity/vault-status.test.ts

@@ -0,0 +1,138 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { VAULT_PUBLISH_OUTCOMES, summarizeVaultPublish } from "./vault-status.js";
+import type { VaultPublishResult } from "./vault-status.js";
+
+test("summarizeVaultPublish counts a mixed list, sorts by path, and flags the error", () => {
+  const status = summarizeVaultPublish([
+    { path: "notes/e.md", outcome: "updated" },
+    { path: "notes/d.md", outcome: "error", reason: "missing_file" },
+    { path: "notes/a.md", outcome: "updated" },
+    { path: "notes/c.md", outcome: "skipped", reason: "no_marker" },
+    { path: "notes/b.md", outcome: "unchanged" },
+  ]);
+  assert.deepEqual(status.counts, { updated: 2, unchanged: 1, skipped: 1, error: 1 });
+  assert.equal(status.hasError, true);
+  assert.deepEqual(status.results, [
+    { path: "notes/a.md", outcome: "updated" },
+    { path: "notes/b.md", outcome: "unchanged" },
+    { path: "notes/c.md", outcome: "skipped", reason: "no_marker" },
+    { path: "notes/d.md", outcome: "error", reason: "missing_file" },
+    { path: "notes/e.md", outcome: "updated" },
+  ]);
+});
+
+test("empty input returns zeroed counts, no results, and hasError false", () => {
+  const status = summarizeVaultPublish([]);
+  assert.deepEqual(status.counts, { updated: 0, unchanged: 0, skipped: 0, error: 0 });
+  for (const outcome of VAULT_PUBLISH_OUTCOMES) {
+    assert.equal(status.counts[outcome], 0, `count key ${outcome} must exist at zero`);
+  }
+  assert.deepEqual(status.results, []);
+  assert.equal(status.hasError, false);
+});
+
+test("unknown outcome throws TypeError listing the allow-list", () => {
+  assert.throws(
+    () => summarizeVaultPublish([{ path: "notes/a.md", outcome: "deleted" }]),
+    (err: unknown) => {
+      assert.ok(err instanceof TypeError);
+      assert.match(err.message, /unknown vault publish outcome/);
+      for (const outcome of VAULT_PUBLISH_OUTCOMES) {
+        assert.ok(err.message.includes(outcome), `message lists ${outcome}`);
+      }
+      return true;
+    },
+  );
+});
+
+test("skipped without a reason throws TypeError", () => {
+  assert.throws(
+    () => summarizeVaultPublish([{ path: "notes/a.md", outcome: "skipped" }]),
+    (err: unknown) => err instanceof TypeError && /reason/.test(err.message),
+  );
+});
+
+test("error with a missing or whitespace-only reason throws TypeError", () => {
+  assert.throws(
+    () => summarizeVaultPublish([{ path: "notes/a.md", outcome: "error" }]),
+    (err: unknown) => err instanceof TypeError && /reason/.test(err.message),
+  );
+  assert.throws(
+    () => summarizeVaultPublish([{ path: "notes/a.md", outcome: "error", reason: "   " }]),
+    (err: unknown) => err instanceof TypeError && /reason/.test(err.message),
+  );
+});
+
+test("updated and unchanged must not carry a reason", () => {
+  assert.throws(
+    () => summarizeVaultPublish([{ path: "notes/a.md", outcome: "updated", reason: "no_marker" }]),
+    (err: unknown) => err instanceof TypeError && /reason/.test(err.message),
+  );
+  assert.throws(
+    () => summarizeVaultPublish([{ path: "notes/a.md", outcome: "unchanged", reason: "x" }]),
+    (err: unknown) => err instanceof TypeError && /reason/.test(err.message),
+  );
+});
+
+test("blank path throws RangeError", () => {
+  assert.throws(
+    () => summarizeVaultPublish([{ path: "", outcome: "updated" }]),
+    (err: unknown) => err instanceof RangeError && /path/.test(err.message),
+  );
+  assert.throws(
+    () => summarizeVaultPublish([{ path: " \t ", outcome: "updated" }]),
+    (err: unknown) => err instanceof RangeError && /path/.test(err.message),
+  );
+});
+
+test("duplicate paths are all preserved, not deduplicated", () => {
+  const status = summarizeVaultPublish([
+    { path: "notes/a.md", outcome: "updated" },
+    { path: "notes/a.md", outcome: "skipped", reason: "no_marker" },
+    { path: "notes/a.md", outcome: "updated" },
+  ]);
+  assert.equal(status.results.length, 3);
+  assert.deepEqual(status.counts, { updated: 2, unchanged: 0, skipped: 1, error: 0 });
+  assert.deepEqual(
+    status.results.map((entry) => entry.outcome),
+    ["updated", "updated", "skipped"],
+  );
+  assert.equal(status.hasError, false);
+});
+
+test("order is deterministic across shuffled input", () => {
+  const base: VaultPublishResult[] = [
+    { path: "days/2026-08-18.md", outcome: "error", reason: "missing_file" },
+    { path: "days/2026-08-18.md", outcome: "updated" },
+    { path: "days/2026-08-18.md", outcome: "skipped", reason: "no_marker" },
+    { path: "days/2026-08-18.md", outcome: "skipped", reason: "duplicate_heading" },
+    { path: "days/2026-08-17.md", outcome: "unchanged" },
+    { path: "places/office.md", outcome: "updated" },
+  ];
+  const forward = summarizeVaultPublish(base);
+  const reversed = summarizeVaultPublish([...base].reverse());
+  assert.deepEqual(forward, reversed);
+  assert.deepEqual(
+    forward.results.map((entry) => `${entry.path}:${entry.outcome}:${entry.reason ?? ""}`),
+    [
+      "days/2026-08-17.md:unchanged:",
+      "days/2026-08-18.md:updated:",
+      "days/2026-08-18.md:skipped:duplicate_heading",
+      "days/2026-08-18.md:skipped:no_marker",
+      "days/2026-08-18.md:error:missing_file",
+      "places/office.md:updated:",
+    ],
+  );
+});
+
+test("input is not mutated", () => {
+  const input: VaultPublishResult[] = [
+    { path: "notes/b.md", outcome: "updated" },
+    { path: "notes/a.md", outcome: "skipped", reason: "no_marker" },
+  ];
+  const snapshot = structuredClone(input);
+  summarizeVaultPublish(input);
+  assert.deepEqual(input, snapshot);
+});

package/src/activity/vault-status.ts

@@ -0,0 +1,96 @@
+/**
+ * Pure vault-publish outcome aggregator (issue #1985).
+ *
+ * `summarizeVaultPublish` folds per-file publish results into the status
+ * shape the publish report and the dry-run print: sorted per-file outcomes
+ * plus zero-filled counts. It performs no I/O and never mutates its input.
+ *
+ * Fail-closed contract: an unrecognized outcome is refused, never coerced
+ * into `skipped` or `error`, and `skipped`/`error` must carry a non-blank
+ * reason so every un-actionable row says why.
+ */
+
+export const VAULT_PUBLISH_OUTCOMES = ["updated", "unchanged", "skipped", "error"] as const;
+export type VaultPublishOutcome = (typeof VAULT_PUBLISH_OUTCOMES)[number];
+
+export interface VaultPublishResult {
+  /** Vault-relative note path. */
+  path: string;
+  outcome: string;
+  /** Required for skipped and error, e.g. "no_marker". */
+  reason?: string;
+}
+
+export interface VaultPublishStatus {
+  results: Array<{ path: string; outcome: VaultPublishOutcome; reason?: string }>;
+  counts: Record<VaultPublishOutcome, number>;
+  /** True when at least one entry is an error. */
+  hasError: boolean;
+}
+
+interface ValidatedEntry {
+  path: string;
+  outcome: VaultPublishOutcome;
+  reason?: string;
+}
+
+/** Total order: path asc, then outcome in allow-list order, then reason. */
+function compareEntries(a: ValidatedEntry, b: ValidatedEntry): number {
+  if (a.path !== b.path) return a.path < b.path ? -1 : 1;
+  const rankA = VAULT_PUBLISH_OUTCOMES.indexOf(a.outcome);
+  const rankB = VAULT_PUBLISH_OUTCOMES.indexOf(b.outcome);
+  if (rankA !== rankB) return rankA < rankB ? -1 : 1;
+  const reasonA = a.reason ?? "";
+  const reasonB = b.reason ?? "";
+  if (reasonA !== reasonB) return reasonA < reasonB ? -1 : 1;
+  return 0;
+}
+
+export function summarizeVaultPublish(results: readonly VaultPublishResult[]): VaultPublishStatus {
+  if (!Array.isArray(results)) {
+    throw new TypeError(`summarizeVaultPublish expects an array of results (got ${typeof results})`);
+  }
+
+  const entries: ValidatedEntry[] = [];
+  for (const entry of results) {
+    if (typeof entry !== "object" || entry === null) {
+      throw new TypeError(`vault publish result entries must be objects (got ${typeof entry})`);
+    }
+    if (typeof entry.path !== "string" || entry.path.trim() === "") {
+      throw new RangeError(`vault publish result requires a non-blank path (got ${JSON.stringify(entry.path)})`);
+    }
+    const outcome = VAULT_PUBLISH_OUTCOMES.find((candidate) => candidate === entry.outcome);
+    if (outcome === undefined) {
+      throw new TypeError(
+        `unknown vault publish outcome ${JSON.stringify(entry.outcome)}; expected one of: ${VAULT_PUBLISH_OUTCOMES.join(", ")}`,
+      );
+    }
+    if (outcome === "skipped" || outcome === "error") {
+      if (typeof entry.reason !== "string" || entry.reason.trim() === "") {
+        throw new TypeError(
+          `vault publish outcome "${outcome}" requires a non-blank reason, e.g. "no_marker" (got ${JSON.stringify(entry.reason)})`,
+        );
+      }
+      entries.push({ path: entry.path, outcome, reason: entry.reason });
+    } else {
+      if (entry.reason !== undefined) {
+        throw new TypeError(
+          `vault publish outcome "${outcome}" must not carry a reason (got ${JSON.stringify(entry.reason)})`,
+        );
+      }
+      entries.push({ path: entry.path, outcome });
+    }
+  }
+
+  const sorted = [...entries].sort(compareEntries);
+
+  const counts = {} as Record<VaultPublishOutcome, number>;
+  for (const outcome of VAULT_PUBLISH_OUTCOMES) counts[outcome] = 0;
+  for (const entry of sorted) counts[entry.outcome] += 1;
+
+  return {
+    results: sorted,
+    counts,
+    hasError: counts.error > 0,
+  };
+}

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