@remnic/core 9.66.9 → 9.66.10

package/src/activity/timeline/week-previous.test.ts

@@ -0,0 +1,119 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { compareWeeklyPreviousPeriod } from "./week-previous.js";
+
+const CURRENT = {
+  activeMs: 3_600_000,
+  idleMs: 600_000,
+  pauseMs: 120_000,
+  gapMs: 300_000,
+  unclassifiedMs: 60_000,
+};
+
+const PREVIOUS = {
+  activeMs: 1_800_000,
+  idleMs: 900_000,
+  pauseMs: 120_000,
+  gapMs: 100_000,
+  unclassifiedMs: 0,
+};
+
+test("null previous is unavailable, not zero", () => {
+  const result = compareWeeklyPreviousPeriod({
+    previous: null,
+    current: CURRENT,
+    previousStartUtc: "2026-07-06T00:00:00Z",
+    previousEndUtc: "2026-07-13T00:00:00Z",
+  });
+  assert.deepEqual(result, { available: false });
+  assert.equal("deltaActiveMs" in result, false);
+});
+
+test("undefined previous is unavailable", () => {
+  const result = compareWeeklyPreviousPeriod({
+    previous: undefined,
+    current: CURRENT,
+  });
+  assert.deepEqual(result, { available: false });
+});
+
+test("previous without timestamps is unavailable", () => {
+  const result = compareWeeklyPreviousPeriod({ previous: PREVIOUS, current: CURRENT });
+  assert.deepEqual(result, { available: false });
+});
+
+test("previous with blank timestamps is unavailable", () => {
+  const result = compareWeeklyPreviousPeriod({
+    previous: PREVIOUS,
+    current: CURRENT,
+    previousStartUtc: "   ",
+    previousEndUtc: "\t",
+  });
+  assert.deepEqual(result, { available: false });
+});
+
+test("mixed deltas keep sign and trim timestamps", () => {
+  const result = compareWeeklyPreviousPeriod({
+    previous: PREVIOUS,
+    current: CURRENT,
+    previousStartUtc: " 2026-07-06T00:00:00Z ",
+    previousEndUtc: " 2026-07-13T00:00:00Z ",
+  });
+  assert.equal(result.available, true);
+  if (!result.available) return;
+  assert.equal(result.previousStartUtc, "2026-07-06T00:00:00Z");
+  assert.equal(result.previousEndUtc, "2026-07-13T00:00:00Z");
+  assert.equal(result.deltaActiveMs, 1_800_000);
+  assert.equal(result.deltaIdleMs, -300_000);
+  assert.equal(result.deltaPauseMs, 0);
+  assert.equal(result.deltaGapMs, 200_000);
+  assert.equal(result.deltaUnclassifiedMs, 60_000);
+});
+
+test("NaN duration on previous throws TypeError", () => {
+  assert.throws(
+    () =>
+      compareWeeklyPreviousPeriod({
+        previous: { ...PREVIOUS, gapMs: Number.NaN },
+        current: CURRENT,
+        previousStartUtc: "2026-07-06T00:00:00Z",
+        previousEndUtc: "2026-07-13T00:00:00Z",
+      }),
+    TypeError,
+  );
+});
+
+test("Infinity duration on current throws TypeError", () => {
+  assert.throws(
+    () =>
+      compareWeeklyPreviousPeriod({
+        previous: PREVIOUS,
+        current: { ...CURRENT, activeMs: Number.POSITIVE_INFINITY },
+      }),
+    /current\.activeMs/,
+  );
+});
+
+test("all-zero current with present previous is available with negative deltas", () => {
+  const zeros = {
+    activeMs: 0,
+    idleMs: 0,
+    pauseMs: 0,
+    gapMs: 0,
+    unclassifiedMs: 0,
+  };
+  const result = compareWeeklyPreviousPeriod({
+    previous: PREVIOUS,
+    current: zeros,
+    previousStartUtc: "2026-07-06T00:00:00Z",
+    previousEndUtc: "2026-07-13T00:00:00Z",
+  });
+  assert.equal(result.available, true);
+  if (!result.available) return;
+  assert.equal(result.deltaActiveMs, -PREVIOUS.activeMs);
+  assert.equal(result.deltaIdleMs, -PREVIOUS.idleMs);
+  assert.equal(result.deltaPauseMs, -PREVIOUS.pauseMs);
+  assert.equal(result.deltaGapMs, -PREVIOUS.gapMs);
+  assert.equal(result.deltaUnclassifiedMs, 0);
+});

package/src/activity/timeline/week-previous.ts

@@ -0,0 +1,83 @@
+/**
+ * Previous-week duration comparison (issue #2052).
+ *
+ * The prior week is explicit when unavailable. It is never silently treated
+ * as zero.
+ */
+
+export interface WeeklyDurationTotals {
+  activeMs: number;
+  idleMs: number;
+  pauseMs: number;
+  gapMs: number;
+  unclassifiedMs: number;
+}
+
+export type WeeklyPreviousPeriod =
+  | { available: false }
+  | {
+      available: true;
+      previousStartUtc: string;
+      previousEndUtc: string;
+      deltaActiveMs: number;
+      deltaIdleMs: number;
+      deltaPauseMs: number;
+      deltaGapMs: number;
+      deltaUnclassifiedMs: number;
+    };
+
+const DURATION_FIELDS = [
+  "activeMs",
+  "idleMs",
+  "pauseMs",
+  "gapMs",
+  "unclassifiedMs",
+] as const;
+
+function assertFiniteTotals(totals: WeeklyDurationTotals, label: string): void {
+  for (const field of DURATION_FIELDS) {
+    const value = totals[field];
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+      throw new TypeError(`${label}.${field} must be a finite number; got ${String(value)}.`);
+    }
+  }
+}
+
+/**
+ * Compare this week's duration totals against the previous week's.
+ *
+ * `previous` absent (null/undefined) or lacking trimmed start/end timestamps
+ * returns `{ available: false }` — never zero deltas. Otherwise returns the
+ * per-field deltas (`current - previous`, may be negative). Pure.
+ */
+export function compareWeeklyPreviousPeriod(input: {
+  previous: WeeklyDurationTotals | null | undefined;
+  current: WeeklyDurationTotals;
+  previousStartUtc?: string;
+  previousEndUtc?: string;
+}): WeeklyPreviousPeriod {
+  const { previous, current, previousStartUtc, previousEndUtc } = input;
+  assertFiniteTotals(current, "current");
+
+  if (previous === null || previous === undefined) {
+    return { available: false };
+  }
+  assertFiniteTotals(previous, "previous");
+
+  const start = previousStartUtc?.trim() ?? "";
+  const end = previousEndUtc?.trim() ?? "";
+  if (start === "" || end === "") {
+    return { available: false };
+  }
+
+  return {
+    available: true,
+    previousStartUtc: start,
+    previousEndUtc: end,
+    deltaActiveMs: current.activeMs - previous.activeMs,
+    deltaIdleMs: current.idleMs - previous.idleMs,
+    deltaPauseMs: current.pauseMs - previous.pauseMs,
+    deltaGapMs: current.gapMs - previous.gapMs,
+    deltaUnclassifiedMs: current.unclassifiedMs - previous.unclassifiedMs,
+  };
+}

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

@@ -0,0 +1,105 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { insertMarkersUnderHeading } from "./vault-insert.js";
+
+const START = "<!-- remnic:daily:start -->";
+const END = "<!-- remnic:daily:end -->";
+
+test("inserts markers under a unique heading before existing body", () => {
+  const fileText = ["# Notes", "", "## Journal", "", "Existing entry.", ""].join("\n");
+  const result = insertMarkersUnderHeading(fileText, {
+    heading: "Journal",
+    name: "daily",
+    content: "Line one.\nLine two.",
+  });
+  assert.ok(result.ok && result.inserted);
+  assert.equal(
+    result.text,
+    ["# Notes", "", "## Journal", START, "Line one.", "Line two.", END, "", "Existing entry.", ""].join("\n"),
+  );
+});
+
+test("returns text unchanged when both markers already exist", () => {
+  const fileText = ["## Journal", START, "old", END, "tail", ""].join("\n");
+  const result = insertMarkersUnderHeading(fileText, { heading: "Journal", name: "daily", content: "new" });
+  assert.deepEqual(result, { ok: true, text: fileText, inserted: false });
+});
+
+test("fails with no_heading when no heading matches exactly", () => {
+  const fileText = ["## Journal entry", "body", ""].join("\n");
+  const result = insertMarkersUnderHeading(fileText, { heading: "Journal", name: "daily", content: "new" });
+  assert.deepEqual(result, { ok: false, reason: "no_heading", text: fileText });
+});
+
+test("fails with duplicate_heading and both 1-based line numbers", () => {
+  const fileText = ["# Top", "## Journal", "a", "## Journal", "b", ""].join("\n");
+  const result = insertMarkersUnderHeading(fileText, { heading: "Journal", name: "daily", content: "new" });
+  assert.ok(!result.ok && result.reason === "duplicate_heading");
+  assert.deepEqual(result.lines, [2, 4]);
+  assert.equal(result.text, fileText);
+});
+
+test("inserts before a later same-level heading and leaves that section intact", () => {
+  const fileText = ["## Journal", "existing", "## Other", "other body", ""].join("\n");
+  const result = insertMarkersUnderHeading(fileText, { heading: "Journal", name: "daily", content: "cards" });
+  assert.ok(result.ok && result.inserted);
+  assert.equal(
+    result.text,
+    ["## Journal", START, "cards", END, "existing", "## Other", "other body", ""].join("\n"),
+  );
+});
+
+test("deeper headings do not end the section", () => {
+  const fileText = ["## Journal", "### Nested", "nested body", "## Other", ""].join("\n");
+  const result = insertMarkersUnderHeading(fileText, { heading: "Journal", name: "daily", content: "cards" });
+  assert.ok(result.ok && result.inserted);
+  assert.equal(
+    result.text,
+    ["## Journal", START, "cards", END, "### Nested", "nested body", "## Other", ""].join("\n"),
+  );
+});
+
+test("inserts under a heading at EOF without trailing newline", () => {
+  const result = insertMarkersUnderHeading("## Journal", { heading: "Journal", name: "daily", content: "cards" });
+  assert.ok(result.ok && result.inserted);
+  assert.equal(result.text, `## Journal\n${START}\ncards\n${END}\n`);
+});
+
+test("keeps content ending in a newline without doubling it", () => {
+  const result = insertMarkersUnderHeading("## Journal\nbody\n", {
+    heading: "Journal",
+    name: "daily",
+    content: "cards\n",
+  });
+  assert.ok(result.ok && result.inserted);
+  assert.equal(result.text, `## Journal\n${START}\ncards\n${END}\nbody\n`);
+});
+
+test("empty content inserts adjacent markers", () => {
+  const result = insertMarkersUnderHeading("## Journal\n", { heading: "Journal", name: "daily", content: "" });
+  assert.ok(result.ok && result.inserted);
+  assert.equal(result.text, `## Journal\n${START}\n${END}\n`);
+});
+
+test("preserves CRLF as the dominant EOL", () => {
+  const fileText = ["## Journal", "body", ""].join("\r\n");
+  const result = insertMarkersUnderHeading(fileText, {
+    heading: "Journal",
+    name: "daily",
+    content: "line a\r\nline b",
+  });
+  assert.ok(result.ok && result.inserted);
+  assert.equal(result.text, `## Journal\r\n${START}\r\nline a\r\nline b\r\n${END}\r\nbody\r\n`);
+});
+
+test("empty heading or name throws RangeError", () => {
+  assert.throws(
+    () => insertMarkersUnderHeading("## Journal\n", { heading: "", name: "daily", content: "" }),
+    (err) => err instanceof RangeError && /empty/i.test(err.message),
+  );
+  assert.throws(
+    () => insertMarkersUnderHeading("## Journal\n", { heading: "Journal", name: "", content: "" }),
+    (err) => err instanceof RangeError && /empty/i.test(err.message),
+  );
+});

package/src/activity/vault-insert.ts

@@ -0,0 +1,86 @@
+/**
+ * Managed-region marker insertion (issue #1985).
+ *
+ * Inserts a `<!-- remnic:<name>:start/end -->` pair under a unique ATX
+ * heading when the region is absent. This helper never replaces (see
+ * `vault-publish.ts`), never creates files, and never invents a heading.
+ * Pure string-in/string-out.
+ */
+
+export type InsertVaultRegionResult =
+  | { ok: true; text: string; inserted: true }
+  | { ok: true; text: string; inserted: false }
+  | { ok: false; reason: "no_heading"; text: string }
+  | { ok: false; reason: "duplicate_heading"; lines: readonly number[]; text: string };
+
+export function insertMarkersUnderHeading(
+  fileText: string,
+  opts: { heading: string; name: string; content: string },
+): InsertVaultRegionResult {
+  if (typeof opts.heading !== "string" || opts.heading.length === 0) {
+    throw new RangeError("Heading must be non-empty.");
+  }
+  if (typeof opts.name !== "string" || opts.name.length === 0) {
+    throw new RangeError("Region name must be non-empty.");
+  }
+
+  const startMarker = `<!-- remnic:${opts.name}:start -->`;
+  const endMarker = `<!-- remnic:${opts.name}:end -->`;
+  if (fileText.includes(startMarker) && fileText.includes(endMarker)) {
+    return { ok: true, text: fileText, inserted: false };
+  }
+
+  const rows = fileLines(fileText);
+  const hits: Array<{ row: (typeof rows)[number]; level: number }> = [];
+  for (const row of rows) {
+    const heading = parseAtxHeading(row.line);
+    if (heading && heading.text === opts.heading) {
+      hits.push({ row, level: heading.level });
+    }
+  }
+  if (hits.length === 0) return { ok: false, reason: "no_heading", text: fileText };
+  if (hits.length > 1) {
+    return { ok: false, reason: "duplicate_heading", lines: hits.map((hit) => hit.row.number), text: fileText };
+  }
+
+  const hit = hits[0]!;
+
+  const eol = fileText.includes("\r\n") ? "\r\n" : "\n";
+  const prefix =
+    hit.row.next === fileText.length && !fileText.endsWith("\n") && !fileText.endsWith("\r")
+      ? `${fileText}${eol}`
+      : fileText.slice(0, hit.row.next);
+  let content = opts.content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  if (eol === "\r\n") content = content.replace(/\n/g, "\r\n");
+  if (content.length > 0 && !content.endsWith(eol)) content += eol;
+
+  const text = `${prefix}${startMarker}${eol}${content}${endMarker}${eol}${fileText.slice(hit.row.next)}`;
+  return { ok: true, text, inserted: true };
+}
+
+type FileLine = { line: string; start: number; next: number; number: number };
+
+function fileLines(fileText: string): FileLine[] {
+  const rows: FileLine[] = [];
+  let start = 0;
+  let number = 1;
+  while (start < fileText.length) {
+    let i = start;
+    while (i < fileText.length && fileText[i] !== "\n" && fileText[i] !== "\r") i++;
+    let next = i;
+    if (fileText[i] === "\r" && fileText[i + 1] === "\n") next = i + 2;
+    else if (fileText[i] === "\n" || fileText[i] === "\r") next = i + 1;
+    else next = fileText.length;
+    rows.push({ line: fileText.slice(start, i), start, next, number });
+    number += 1;
+    start = next;
+  }
+  return rows;
+}
+
+function parseAtxHeading(line: string): { level: number; text: string } | null {
+  let level = 0;
+  while (level < line.length && level < 6 && line[level] === "#") level++;
+  if (level === 0 || line[level] !== " ") return null;
+  return { level, text: line.slice(level + 1) };
+}

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

@@ -0,0 +1,69 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  estimateGeneratedTokens,
+  estimateOffsetTokens,
+  spanModeSavesTokens,
+} from "./extraction-span-tokens.js";
+
+test("estimateGeneratedTokens: 0 chars -> 0 tokens", () => {
+  assert.equal(estimateGeneratedTokens(0), 0);
+});
+
+test("estimateGeneratedTokens: 1..4 chars -> 1 token", () => {
+  for (const chars of [1, 2, 3, 4]) {
+    assert.equal(estimateGeneratedTokens(chars), 1);
+  }
+});
+
+test("estimateGeneratedTokens: 5 chars -> 2 tokens", () => {
+  assert.equal(estimateGeneratedTokens(5), 2);
+});
+
+test("estimateGeneratedTokens: invalid charCount throws", () => {
+  assert.throws(() => estimateGeneratedTokens(-1), /charCount/);
+  assert.throws(() => estimateGeneratedTokens(Number.NaN), /charCount/);
+  assert.throws(() => estimateGeneratedTokens(3.7), /charCount/);
+  assert.throws(() => estimateGeneratedTokens(-1), RangeError);
+  assert.throws(() => estimateGeneratedTokens(Number.NaN), RangeError);
+});
+
+test("estimateOffsetTokens: (0, 12) cost is a positive integer", () => {
+  const cost = estimateOffsetTokens(0, 12);
+  assert.equal(Number.isInteger(cost), true);
+  assert.ok(cost > 0);
+});
+
+test("estimateOffsetTokens: offset 0 costs one character (one token)", () => {
+  assert.equal(estimateOffsetTokens(0, 0), 2);
+});
+
+test("estimateOffsetTokens: reversed span throws", () => {
+  assert.throws(() => estimateOffsetTokens(13, 12), RangeError);
+  assert.throws(() => estimateOffsetTokens(13, 12), /reversed/);
+});
+
+test("estimateOffsetTokens: non-finite or non-integer offsets throw", () => {
+  assert.throws(() => estimateOffsetTokens(Number.NaN, 12), RangeError);
+  assert.throws(() => estimateOffsetTokens(0, Number.POSITIVE_INFINITY), RangeError);
+  assert.throws(() => estimateOffsetTokens(0.5, 12), RangeError);
+});
+
+test("spanModeSavesTokens: long generated value beats small offsets", () => {
+  assert.equal(
+    spanModeSavesTokens({ generatedCharCount: 1000, start: 0, end: 12 }),
+    true,
+  );
+});
+
+test("spanModeSavesTokens: equal costs return false", () => {
+  // (0, 12) costs 2 tokens; 5..8 generated chars also cost 2 tokens.
+  assert.equal(
+    spanModeSavesTokens({ generatedCharCount: 8, start: 0, end: 12 }),
+    false,
+  );
+  assert.equal(
+    spanModeSavesTokens({ generatedCharCount: 5, start: 0, end: 0 }),
+    false,
+  );
+});

package/src/extraction-span-tokens.ts

@@ -0,0 +1,44 @@
+/**
+ * Isolated span token-cost estimator (issue #2333, Phase A).
+ *
+ * Pure. Estimates the output-token cost of emitting span offsets versus
+ * generating the memory value, so the Phase A bench can compare both sides
+ * without touching the extraction engine.
+ */
+
+const CHARS_PER_TOKEN = 4;
+
+export function estimateGeneratedTokens(charCount: number): number {
+  if (!Number.isInteger(charCount) || charCount < 0) {
+    throw new RangeError(`charCount must be a non-negative integer, got ${charCount}`);
+  }
+  return Math.ceil(charCount / CHARS_PER_TOKEN);
+}
+
+export function estimateOffsetTokens(start: number, end: number): number {
+  if (!Number.isInteger(start)) {
+    throw new RangeError(`start must be a finite integer, got ${start}`);
+  }
+  if (!Number.isInteger(end)) {
+    throw new RangeError(`end must be a finite integer, got ${end}`);
+  }
+  if (start > end) {
+    throw new RangeError(`reversed span: start ${start} > end ${end}`);
+  }
+  return offsetTokens(start) + offsetTokens(end);
+}
+
+export function spanModeSavesTokens(input: {
+  generatedCharCount: number;
+  start: number;
+  end: number;
+}): boolean {
+  return (
+    estimateOffsetTokens(input.start, input.end) <
+    estimateGeneratedTokens(input.generatedCharCount)
+  );
+}
+
+function offsetTokens(offset: number): number {
+  return Math.ceil(String(offset).length / CHARS_PER_TOKEN);
+}

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

@@ -0,0 +1,85 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { DEEP_RECALL_FRONTIER_CAP, rankDeepRecallFrontier } from "./recall-deep-frontier.js";
+
+test("empty input returns empty", () => {
+  assert.deepEqual(rankDeepRecallFrontier([]), []);
+});
+
+test("blank nodeIds and counts below 1 are dropped", () => {
+  const result = rankDeepRecallFrontier([
+    { nodeId: "", sharedAnchorCount: 3 },
+    { nodeId: "   ", sharedAnchorCount: 3 },
+    { nodeId: "a", sharedAnchorCount: 0 },
+    { nodeId: "b", sharedAnchorCount: -2 },
+    { nodeId: "c", sharedAnchorCount: 1 },
+  ]);
+  assert.deepEqual(result, [{ nodeId: "c", sharedAnchorCount: 1 }]);
+});
+
+test("NaN and infinite counts are dropped", () => {
+  const result = rankDeepRecallFrontier([
+    { nodeId: "a", sharedAnchorCount: Number.NaN },
+    { nodeId: "b", sharedAnchorCount: Number.POSITIVE_INFINITY },
+    { nodeId: "c", sharedAnchorCount: 2 },
+  ]);
+  assert.deepEqual(result, [{ nodeId: "c", sharedAnchorCount: 2 }]);
+});
+
+test("dedup by nodeId keeps the higher count, first on tie", () => {
+  const result = rankDeepRecallFrontier([
+    { nodeId: "a", sharedAnchorCount: 2 },
+    { nodeId: "a", sharedAnchorCount: 5 },
+    { nodeId: "b", sharedAnchorCount: 4 },
+    { nodeId: "b", sharedAnchorCount: 4 },
+  ]);
+  assert.deepEqual(result, [
+    { nodeId: "a", sharedAnchorCount: 5 },
+    { nodeId: "b", sharedAnchorCount: 4 },
+  ]);
+});
+
+test("sorts by count desc then nodeId asc", () => {
+  const result = rankDeepRecallFrontier([
+    { nodeId: "c", sharedAnchorCount: 3 },
+    { nodeId: "a", sharedAnchorCount: 3 },
+    { nodeId: "b", sharedAnchorCount: 9 },
+    { nodeId: "d", sharedAnchorCount: 1 },
+  ]);
+  assert.deepEqual(
+    result.map((candidate) => candidate.nodeId),
+    ["b", "a", "c", "d"],
+  );
+});
+
+test("caps at 20 keeping the top 20 of 21", () => {
+  const candidates = Array.from({ length: 21 }, (_, i) => ({
+    nodeId: `n${String(i).padStart(2, "0")}`,
+    sharedAnchorCount: i + 1,
+  }));
+  const result = rankDeepRecallFrontier(candidates);
+  assert.equal(result.length, DEEP_RECALL_FRONTIER_CAP);
+  assert.equal(result[0]?.nodeId, "n20");
+  assert.equal(result.at(-1)?.nodeId, "n01");
+  assert.ok(!result.some((candidate) => candidate.nodeId === "n00"));
+});
+
+test("does not mutate the input array or its objects", () => {
+  const input = [
+    { nodeId: " b ", sharedAnchorCount: 2 },
+    { nodeId: "a", sharedAnchorCount: 1 },
+  ];
+  const snapshot = structuredClone(input);
+  rankDeepRecallFrontier(input);
+  assert.deepEqual(input, snapshot);
+});
+
+test("two calls on the same input are deep-equal", () => {
+  const input = [
+    { nodeId: "a", sharedAnchorCount: 2 },
+    { nodeId: "b", sharedAnchorCount: 2 },
+    { nodeId: "a", sharedAnchorCount: 7 },
+  ];
+  assert.deepEqual(rankDeepRecallFrontier(input), rankDeepRecallFrontier(input));
+});

package/src/recall-deep-frontier.ts

@@ -0,0 +1,39 @@
+/**
+ * Deep-recall frontier ranker (issue #2332).
+ *
+ * Pure. After every working-set change the frontier is capped at
+ * DEEP_RECALL_FRONTIER_CAP items ordered by shared-anchor count
+ * descending, then nodeId ascending — a total comparator.
+ */
+
+export const DEEP_RECALL_FRONTIER_CAP = 20;
+
+export interface DeepRecallFrontierCandidate {
+  nodeId: string;
+  sharedAnchorCount: number;
+}
+
+export function rankDeepRecallFrontier(
+  candidates: readonly DeepRecallFrontierCandidate[],
+): DeepRecallFrontierCandidate[] {
+  const byNodeId = new Map<string, DeepRecallFrontierCandidate>();
+  for (const candidate of candidates) {
+    const nodeId = typeof candidate.nodeId === "string" ? candidate.nodeId.trim() : "";
+    if (nodeId === "") continue;
+    const count = candidate.sharedAnchorCount;
+    if (typeof count !== "number" || !Number.isFinite(count) || count < 1) continue;
+    const kept = byNodeId.get(nodeId);
+    if (kept === undefined || count > kept.sharedAnchorCount) {
+      byNodeId.set(nodeId, { nodeId, sharedAnchorCount: count });
+    }
+  }
+  return [...byNodeId.values()]
+    .sort((a, b) => {
+      if (a.sharedAnchorCount !== b.sharedAnchorCount) {
+        return b.sharedAnchorCount - a.sharedAnchorCount;
+      }
+      if (a.nodeId !== b.nodeId) return a.nodeId < b.nodeId ? -1 : 1;
+      return 0;
+    })
+    .slice(0, DEEP_RECALL_FRONTIER_CAP);
+}