@remnic/core 9.67.0 → 9.68.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" };
+}

package/src/shared-context/supersession-chain.test.ts

@@ -0,0 +1,158 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  MAX_SUPERSESSION_DEPTH,
+  resolveSupersessionHead,
+  type SupersessionItem,
+} from "./supersession-chain.js";
+
+const link = (id: string, supersedes?: string): SupersessionItem =>
+  supersedes === undefined ? { id } : { id, supersedes };
+
+test("single item resolves to itself", () => {
+  assert.deepEqual(resolveSupersessionHead({ items: [link("a")], startId: "a" }), {
+    ok: true,
+    headId: "a",
+    chain: ["a"],
+  });
+});
+
+test("3-link chain resolves to the newest head with the full chain", () => {
+  const items = [link("a"), link("b", "a"), link("c", "b")];
+  assert.deepEqual(resolveSupersessionHead({ items, startId: "a" }), {
+    ok: true,
+    headId: "c",
+    chain: ["a", "b", "c"],
+  });
+});
+
+test("2-cycle returns cycle_detected without hanging", () => {
+  const items = [link("a", "b"), link("b", "a")];
+  assert.deepEqual(resolveSupersessionHead({ items, startId: "a" }), {
+    ok: false,
+    error: "cycle_detected",
+    chain: ["a", "b"],
+  });
+});
+
+test("longer cycle is also detected", () => {
+  // b supersedes a, c supersedes b, a supersedes c.
+  const items = [link("a", "c"), link("b", "a"), link("c", "b")];
+  assert.deepEqual(resolveSupersessionHead({ items, startId: "a" }), {
+    ok: false,
+    error: "cycle_detected",
+    chain: ["a", "b", "c"],
+  });
+});
+
+test("depth_exceeded with a small maxDepth", () => {
+  const items = [link("a"), link("b", "a"), link("c", "b"), link("d", "c")];
+  assert.deepEqual(resolveSupersessionHead({ items, startId: "a", maxDepth: 2 }), {
+    ok: false,
+    error: "depth_exceeded",
+    chain: ["a", "b"],
+  });
+  assert.deepEqual(resolveSupersessionHead({ items, startId: "a", maxDepth: 1 }), {
+    ok: false,
+    error: "depth_exceeded",
+    chain: ["a"],
+  });
+  // A chain exactly maxDepth ids long still resolves.
+  assert.deepEqual(resolveSupersessionHead({ items, startId: "b", maxDepth: 3 }), {
+    ok: true,
+    headId: "d",
+    chain: ["b", "c", "d"],
+  });
+});
+
+test("default depth is MAX_SUPERSESSION_DEPTH", () => {
+  assert.equal(MAX_SUPERSESSION_DEPTH, 32);
+  const items: SupersessionItem[] = [link("i0")];
+  for (let i = 1; i <= 60; i++) items.push(link(`i${i}`, `i${i - 1}`));
+  assert.deepEqual(resolveSupersessionHead({ items, startId: "i0" }), {
+    ok: false,
+    error: "depth_exceeded",
+    chain: Array.from({ length: MAX_SUPERSESSION_DEPTH }, (_, i) => `i${i}`),
+  });
+});
+
+test("unknown startId returns unknown_id with an empty chain", () => {
+  assert.deepEqual(resolveSupersessionHead({ items: [link("a")], startId: "zzz" }), {
+    ok: false,
+    error: "unknown_id",
+    chain: [],
+  });
+});
+
+test("empty and whitespace-only startId return unknown_id", () => {
+  const items = [link("a")];
+  for (const startId of ["", "   "]) {
+    assert.deepEqual(resolveSupersessionHead({ items, startId }), {
+      ok: false,
+      error: "unknown_id",
+      chain: [],
+    });
+  }
+});
+
+test("startId is trimmed on the happy path", () => {
+  const items = [link("a"), link("b", "a")];
+  assert.deepEqual(resolveSupersessionHead({ items, startId: "  a  " }), {
+    ok: true,
+    headId: "b",
+    chain: ["a", "b"],
+  });
+});
+
+test("maxDepth 0, negative, and float throw RangeError naming maxDepth", () => {
+  const items = [link("a")];
+  for (const bad of [0, -1, -32, 2.5, Number.NaN]) {
+    assert.throws(
+      () => resolveSupersessionHead({ items, startId: "a", maxDepth: bad }),
+      (err: unknown) =>
+        err instanceof RangeError && /maxDepth/.test(String(err.message)),
+    );
+  }
+});
+
+test("fork resolves to the smallest successor id, stable across shuffles", () => {
+  // Both b and c supersede a; b < c, so b wins even though c appears first.
+  const ordered = [link("a"), link("c", "a"), link("b", "a"), link("d", "b")];
+  const shuffled = [link("d", "b"), link("b", "a"), link("a"), link("c", "a")];
+  const expected = { ok: true, headId: "d", chain: ["a", "b", "d"] };
+  assert.deepEqual(resolveSupersessionHead({ items: ordered, startId: "a" }), expected);
+  assert.deepEqual(resolveSupersessionHead({ items: shuffled, startId: "a" }), expected);
+  // Same shuffled input twice: identical results.
+  assert.deepEqual(resolveSupersessionHead({ items: shuffled, startId: "a" }), expected);
+});
+
+test("blank-id items are ignored", () => {
+  const items: SupersessionItem[] = [
+    link("a"),
+    link("b", "a"),
+    { id: "", supersedes: "b" },
+    { id: "   ", supersedes: "b" },
+    { supersedes: "b" } as unknown as SupersessionItem,
+    link("z", "   "),
+  ];
+  // The blank-id items must not make themselves successors of b.
+  assert.deepEqual(resolveSupersessionHead({ items, startId: "a" }), {
+    ok: true,
+    headId: "b",
+    chain: ["a", "b"],
+  });
+  // z has a blank supersedes pointer: it supersedes nothing.
+  assert.deepEqual(resolveSupersessionHead({ items, startId: "z" }), {
+    ok: true,
+    headId: "z",
+    chain: ["z"],
+  });
+});
+
+test("input is not mutated", () => {
+  const items = [link("c", "b"), link("a"), link("b", "a")];
+  const snapshot = structuredClone(items);
+  resolveSupersessionHead({ items, startId: "a" });
+  assert.deepEqual(items, snapshot);
+});

package/src/shared-context/supersession-chain.ts

@@ -0,0 +1,95 @@
+/**
+ * Supersession chain resolution for shared-context curation (issue #1957).
+ *
+ * A shared item may supersede another item, which may itself be superseded.
+ * Curation needs the live head of that chain. This module resolves the head
+ * deterministically and survives malformed input: cycles, forks, and depth
+ * blowups return errors instead of throwing or looping.
+ */
+
+export interface SupersessionItem {
+  id: string;
+  /** Id of the item this one replaces, when any. */
+  supersedes?: string;
+}
+
+export type SupersessionChainResult =
+  | { ok: true; headId: string; chain: string[] }
+  | {
+      ok: false;
+      error: "unknown_id" | "cycle_detected" | "depth_exceeded";
+      chain: string[];
+    };
+
+export const MAX_SUPERSESSION_DEPTH = 32;
+
+/**
+ * Resolve the live head of the supersession chain that starts at `startId`.
+ *
+ * Direction: forward. The successor of id X is the item whose `supersedes`
+ * points at X. The head is the item that nothing supersedes.
+ *
+ * Fork policy: when two items supersede the same id, the lexicographically
+ * smallest successor id wins. This keeps the result dependent only on the
+ * item set, never on array order.
+ *
+ * Pure: reads the input, mutates nothing, performs no I/O.
+ */
+export function resolveSupersessionHead(input: {
+  items: readonly SupersessionItem[];
+  startId: string;
+  maxDepth?: number;
+}): SupersessionChainResult {
+  const { items, maxDepth } = input;
+  if (maxDepth !== undefined && (!Number.isInteger(maxDepth) || maxDepth < 1)) {
+    throw new RangeError(`maxDepth must be a positive integer, got ${maxDepth}`);
+  }
+  const depth = maxDepth ?? MAX_SUPERSESSION_DEPTH;
+
+  const start = input.startId.trim();
+  if (start === "") {
+    return { ok: false, error: "unknown_id", chain: [] };
+  }
+
+  // Build the id set and the successor map. Blank ids cannot participate,
+  // and a blank `supersedes` value cannot point at anything.
+  const ids = new Set<string>();
+  const successorOf = new Map<string, string>();
+  for (const item of items) {
+    if (typeof item?.id !== "string") continue;
+    const id = item.id.trim();
+    if (id === "") continue;
+    ids.add(id);
+    const target =
+      typeof item.supersedes === "string" ? item.supersedes.trim() : "";
+    if (target === "") continue;
+    // Fork resolution: keep the smallest successor id for determinism.
+    const best = successorOf.get(target);
+    if (best === undefined || id < best) {
+      successorOf.set(target, id);
+    }
+  }
+
+  if (!ids.has(start)) {
+    return { ok: false, error: "unknown_id", chain: [] };
+  }
+
+  const chain = [start];
+  const visited = new Set<string>([start]);
+  let current = start;
+  for (;;) {
+    const next = successorOf.get(current);
+    if (next === undefined) {
+      return { ok: true, headId: current, chain };
+    }
+    if (visited.has(next)) {
+      return { ok: false, error: "cycle_detected", chain };
+    }
+    if (chain.length + 1 > depth) {
+      return { ok: false, error: "depth_exceeded", chain };
+    }
+    chain.push(next);
+    visited.add(next);
+    current = next;
+  }
+}