@remnic/core 9.69.4 → 9.69.5

package/src/activity/vault-dry-run.test.ts

@@ -0,0 +1,114 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { planVaultDryRun } from "./vault-dry-run.js";
+import type { VaultDryRunInput } from "./vault-dry-run.js";
+import { VAULT_PUBLISH_OUTCOMES } from "./vault-status.js";
+
+test("planVaultDryRun predicts a mixed batch with correct per-file outcomes and counts", () => {
+  const status = planVaultDryRun([
+    { path: "notes/b.md", currentText: "same", nextText: "same" },
+    { path: "notes/a.md", currentText: null, nextText: "new body" },
+    { path: "notes/c.md", currentText: "old", nextText: "new" },
+    { path: "notes/d.md", currentText: "text", nextText: null, skipReason: "no_marker" },
+  ]);
+  assert.deepEqual(status.counts, { updated: 1, unchanged: 1, skipped: 2, error: 0 });
+  assert.equal(status.hasError, false);
+  assert.deepEqual(status.results, [
+    { path: "notes/a.md", outcome: "skipped", reason: "missing_file" },
+    { path: "notes/b.md", outcome: "unchanged" },
+    { path: "notes/c.md", outcome: "updated" },
+    { path: "notes/d.md", outcome: "skipped", reason: "no_marker" },
+  ]);
+});
+
+// The real publisher refuses to create missing notes (missing_file), so a
+// dry run must predict that skip rather than promise an update.
+test("a missing note predicts the publisher's skip, not a create", () => {
+  const status = planVaultDryRun([{ path: "new.md", currentText: null, nextText: "body" }]);
+  assert.deepEqual(status.counts, { updated: 0, unchanged: 0, skipped: 1, error: 0 });
+  assert.deepEqual(status.results, [{ path: "new.md", outcome: "skipped", reason: "missing_file" }]);
+});
+
+test("byte-identical text is unchanged", () => {
+  const status = planVaultDryRun([{ path: "same.md", currentText: "line\nline\n", nextText: "line\nline\n" }]);
+  assert.deepEqual(status.counts, { updated: 0, unchanged: 1, skipped: 0, error: 0 });
+  assert.deepEqual(status.results, [{ path: "same.md", outcome: "unchanged" }]);
+});
+
+test("a whitespace-only difference is updated, not unchanged", () => {
+  const status = planVaultDryRun([
+    { path: "trailing.md", currentText: "body", nextText: "body " },
+    { path: "newline.md", currentText: "body\n", nextText: "body" },
+  ]);
+  assert.deepEqual(status.counts, { updated: 2, unchanged: 0, skipped: 0, error: 0 });
+});
+
+test("nextText null with a reason is skipped carrying that exact reason", () => {
+  const status = planVaultDryRun([
+    { path: "skip.md", currentText: "text", nextText: null, skipReason: "no_marker" },
+  ]);
+  assert.deepEqual(status.results, [{ path: "skip.md", outcome: "skipped", reason: "no_marker" }]);
+  assert.equal(status.counts.skipped, 1);
+});
+
+test("nextText null without a reason throws TypeError naming skipReason", () => {
+  assert.throws(
+    () => planVaultDryRun([{ path: "skip.md", currentText: "text", nextText: null }]),
+    (err: unknown) => err instanceof TypeError && /skipReason/.test(err.message),
+  );
+  assert.throws(
+    () => planVaultDryRun([{ path: "skip.md", currentText: "text", nextText: null, skipReason: "   " }]),
+    (err: unknown) => err instanceof TypeError && /skipReason/.test(err.message),
+  );
+});
+
+test("skipReason with a non-null nextText throws TypeError", () => {
+  assert.throws(
+    () => planVaultDryRun([{ path: "conflict.md", currentText: "a", nextText: "b", skipReason: "no_marker" }]),
+    (err: unknown) => err instanceof TypeError && /skipReason/.test(err.message),
+  );
+});
+
+test("blank path throws RangeError naming path", () => {
+  assert.throws(
+    () => planVaultDryRun([{ path: "", currentText: "a", nextText: "a" }]),
+    (err: unknown) => err instanceof RangeError && /path/.test(err.message),
+  );
+  assert.throws(
+    () => planVaultDryRun([{ path: "   ", currentText: "a", nextText: "a" }]),
+    (err: unknown) => err instanceof RangeError && /path/.test(err.message),
+  );
+});
+
+test("unused outcome keys are present at zero", () => {
+  const status = planVaultDryRun([{ path: "only.md", currentText: "a", nextText: "a" }]);
+  for (const outcome of VAULT_PUBLISH_OUTCOMES) {
+    assert.ok(outcome in status.counts, `count key ${outcome} must exist`);
+    assert.equal(status.counts[outcome], outcome === "unchanged" ? 1 : 0);
+  }
+});
+
+test("input is not mutated", () => {
+  const inputs: VaultDryRunInput[] = [
+    { path: "a.md", currentText: "old", nextText: "new" },
+    { path: "b.md", currentText: "x", nextText: null, skipReason: "no_marker" },
+  ];
+  const snapshot = JSON.parse(JSON.stringify(inputs));
+  planVaultDryRun(inputs);
+  assert.deepEqual(inputs, snapshot);
+});
+
+// Round 3: undefined and non-string text fields are malformed input, never a
+// prediction. Two undefined fields used to compare equal and report unchanged.
+test("undefined and non-string text fields throw rather than predict", () => {
+  for (const bad of [
+    { path: "a.md", currentText: undefined as unknown as string, nextText: "x" },
+    { path: "a.md", currentText: "x", nextText: undefined as unknown as string },
+    { path: "a.md", currentText: 5 as unknown as string, nextText: "x" },
+    { path: "a.md", currentText: "x", nextText: {} as unknown as string },
+    { path: "a.md", currentText: undefined as unknown as string, nextText: undefined as unknown as string },
+  ]) {
+    assert.throws(() => planVaultDryRun([bad]), /must be a string or null/);
+  }
+});

package/src/activity/vault-dry-run.ts

@@ -0,0 +1,76 @@
+/**
+ * Pure vault publish dry-run planner (issue #1985).
+ *
+ * `planVaultDryRun` predicts per-note publish outcomes from text the caller
+ * has already read. It takes strings, not paths, and returns only a report:
+ * zero writes is a property of the signature, not a promise. Reporting a
+ * note as `skipped` with reason `missing_file` when `currentText` is null,
+ * matching the real publisher, which refuses to create a missing note.
+ *
+ * Internal helper: nothing calls it yet. CLI/HTTP wiring for the `--dry-run`
+ * flag is a later slice of #1985.
+ */
+import { summarizeVaultPublish } from "./vault-status.js";
+import type { VaultPublishOutcome, VaultPublishResult, VaultPublishStatus } from "./vault-status.js";
+
+export interface VaultDryRunInput {
+  /** Vault-relative note path, for reporting only. */
+  path: string;
+  /** Current note text, or null when the note does not exist. */
+  currentText: string | null;
+  /** The text a real publish would produce, or null when it would skip. */
+  nextText: string | null;
+  /** Required when nextText is null: why the publish would skip. */
+  skipReason?: string;
+}
+
+export function planVaultDryRun(inputs: readonly VaultDryRunInput[]): VaultPublishStatus {
+  const results: VaultPublishResult[] = [];
+  for (const input of inputs) {
+    if (typeof input !== "object" || input === null) {
+      throw new TypeError(`vault dry-run inputs must be objects (got ${typeof input})`);
+    }
+    if (typeof input.path !== "string" || input.path.trim() === "") {
+      throw new RangeError(`vault dry-run input requires a non-blank path (got ${JSON.stringify(input.path)})`);
+    }
+    // Validate the exact values before classification: a non-string or
+    // undefined text field is malformed input, and letting it reach the
+    // comparison would silently report a prediction for data the contract
+    // does not permit (two undefined fields would read as "unchanged").
+    for (const field of ["currentText", "nextText"] as const) {
+      const value = input[field];
+      if (value !== null && typeof value !== "string") {
+        throw new TypeError(
+          `vault dry-run input ${field} must be a string or null (got ${typeof value})`,
+        );
+      }
+    }
+    if (input.nextText === null) {
+      if (typeof input.skipReason !== "string" || input.skipReason.trim() === "") {
+        throw new TypeError(
+          `vault dry-run skip (nextText null) requires a non-blank skipReason (got ${JSON.stringify(input.skipReason)})`,
+        );
+      }
+      results.push({ path: input.path, outcome: "skipped", reason: input.skipReason });
+      continue;
+    }
+    if (input.skipReason !== undefined) {
+      throw new TypeError(
+        `vault dry-run skipReason is only valid when nextText is null (path ${JSON.stringify(input.path)})`,
+      );
+    }
+    // A missing note is NOT a create: the real publisher (vault-publish.ts
+    // publishVaultRegion) refuses to create missing files and returns
+    // missing_file, so the dry run must predict that skip rather than promise
+    // an update the real run will not perform.
+    if (input.currentText === null) {
+      results.push({ path: input.path, outcome: "skipped", reason: "missing_file" });
+      continue;
+    }
+    // Byte-exact compare: a publish that rewrites only trailing whitespace is
+    // still a write.
+    const outcome: VaultPublishOutcome = input.currentText === input.nextText ? "unchanged" : "updated";
+    results.push({ path: input.path, outcome });
+  }
+  return summarizeVaultPublish(results);
+}

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

@@ -2,18 +2,40 @@ import assert from "node:assert/strict";
 import test from "node:test";
 
 import { parseNavigateLinkType } from "./recall-navigate-link.js";
+import { selectTraverseNeighbors } from "./recall-navigate-traverse.js";
 
-test("parses each allowed link type", () => {
-  for (const type of ["supports", "contradicts", "elaborates", "causes", "caused_by"] as const) {
+test("every navigation relation parses", () => {
+  for (const type of ["supports", "contradicts", "elaborates", "causes", "caused_by"]) {
     assert.deepEqual(parseNavigateLinkType(type), { ok: true, type });
   }
 });
 
-test("unknown link is unknown_link", () => {
-  assert.deepEqual(parseNavigateLinkType("supersedes"), { ok: false, error: "unknown_link" });
-  assert.deepEqual(parseNavigateLinkType("related"), { ok: false, error: "unknown_link" });
+// Persisted MemoryLinkType values must parse too: real frontmatter carries
+// them, and a traversal over stored links loses those neighbors otherwise.
+test("persisted MemoryLinkType values parse", () => {
+  for (const type of ["follows", "references", "related"]) {
+    assert.deepEqual(parseNavigateLinkType(type), { ok: true, type });
+  }
 });
 
-test("empty link is unknown_link", () => {
+test("unknown or empty link types are refused", () => {
+  assert.deepEqual(parseNavigateLinkType("supersedesX"), { ok: false, error: "unknown_link" });
   assert.deepEqual(parseNavigateLinkType(""), { ok: false, error: "unknown_link" });
+  assert.deepEqual(parseNavigateLinkType("Supports"), { ok: false, error: "unknown_link" });
+});
+
+
+// Round 3: the stepper's navigation contract accepts supersedes, so the
+// shared selector vocabulary must too.
+test("supersedes parses and filters", () => {
+  assert.deepEqual(parseNavigateLinkType("supersedes"), { ok: true, type: "supersedes" });
+  const result = selectTraverseNeighbors({
+    links: [
+      { targetId: "m-1", linkType: "supersedes" },
+      { targetId: "m-2", linkType: "supports" },
+    ],
+    relation: "supersedes",
+  });
+  assert.ok(result.ok);
+  assert.deepEqual(result.neighbors, [{ targetId: "m-1", linkType: "supersedes" }]);
 });

package/src/recall-navigate-link.ts

@@ -1,7 +1,13 @@
 /**
- * Recall navigation link-type parse (issue #1956 leftover).
+ * Recall navigation link-type parse (issue #1956).
  *
- * Pure. Surfaces wait. Unknown or empty is unknown_link.
+ * One allow-list covering BOTH vocabularies a traversal can meet:
+ * the navigation set this module originally defined and the persisted
+ * `MemoryLinkType` values (`follows | references | related`) that real
+ * memory frontmatter carries. Review found the narrower list silently
+ * dropped every persisted `follows`/`references`/`related` edge and
+ * rejected `relation: "related"` as unknown — a traversal over actual
+ * stored links would lose valid neighbors. Surfaces wait.
  */
 
 const NAVIGATE_LINK_TYPES = [
@@ -10,6 +16,14 @@ const NAVIGATE_LINK_TYPES = [
   "elaborates",
   "causes",
   "caused_by",
+  // Persisted MemoryLinkType values (types.ts) that real frontmatter carries.
+  "follows",
+  "references",
+  "related",
+  // The stepper's own navigation contract (recall-navigate.ts) accepts
+  // supersedes; omitting it here would reject a relation that surface is
+  // prepared to handle.
+  "supersedes",
 ] as const;
 
 export type NavigateLinkType = (typeof NAVIGATE_LINK_TYPES)[number];

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

@@ -0,0 +1,247 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { DEFAULT_TRAVERSE_LIMIT } from "./recall-navigate-traverse.js";
+import { selectTraverseNeighbors } from "./recall-navigate-traverse.js";
+
+test("no relation returns all known-type links sorted", () => {
+  const result = selectTraverseNeighbors({
+    links: [
+      { targetId: "m-3", linkType: "supports" },
+      { targetId: "m-1", linkType: "elaborates" },
+      { targetId: "m-2", linkType: "causes" },
+    ],
+  });
+  assert.ok(result.ok);
+  assert.equal(result.truncated, false);
+  assert.deepEqual(result.neighbors, [
+    { targetId: "m-2", linkType: "causes" },
+    { targetId: "m-1", linkType: "elaborates" },
+    { targetId: "m-3", linkType: "supports" },
+  ]);
+});
+
+test("relation filter returns only that relation", () => {
+  const result = selectTraverseNeighbors({
+    links: [
+      { targetId: "m-1", linkType: "supports" },
+      { targetId: "m-2", linkType: "contradicts" },
+      { targetId: "m-3", linkType: "supports" },
+    ],
+    relation: "supports",
+  });
+  assert.ok(result.ok);
+  assert.deepEqual(result.neighbors, [
+    { targetId: "m-1", linkType: "supports" },
+    { targetId: "m-3", linkType: "supports" },
+  ]);
+});
+
+test("unknown relation is refused with unknown_relation", () => {
+  const result = selectTraverseNeighbors({
+    links: [{ targetId: "m-1", linkType: "supports" }],
+    relation: "destroys",
+  });
+  assert.deepEqual(result, { ok: false, error: "unknown_relation" });
+});
+
+test("unknown linkType link is skipped while siblings survive", () => {
+  const result = selectTraverseNeighbors({
+    links: [
+      { targetId: "m-1", linkType: "hyperlinks" },
+      { targetId: "m-2", linkType: "supports" },
+    ],
+  });
+  assert.ok(result.ok);
+  assert.deepEqual(result.neighbors, [{ targetId: "m-2", linkType: "supports" }]);
+});
+
+test("duplicate targetIds collapse to the first occurrence", () => {
+  const result = selectTraverseNeighbors({
+    links: [
+      { targetId: "m-1", linkType: "causes" },
+      { targetId: "m-1", linkType: "supports" },
+      { targetId: "m-2", linkType: "elaborates" },
+    ],
+  });
+  assert.ok(result.ok);
+  assert.deepEqual(result.neighbors, [
+    { targetId: "m-1", linkType: "causes" },
+    { targetId: "m-2", linkType: "elaborates" },
+  ]);
+});
+
+test("blank targetId is skipped", () => {
+  const result = selectTraverseNeighbors({
+    links: [
+      { targetId: "", linkType: "supports" },
+      { targetId: "  ", linkType: "supports" },
+      { targetId: "m-1", linkType: "supports" },
+    ],
+  });
+  assert.ok(result.ok);
+  assert.deepEqual(result.neighbors, [{ targetId: "m-1", linkType: "supports" }]);
+});
+
+test("limit truncates after sorting and sets truncated", () => {
+  const result = selectTraverseNeighbors({
+    links: [
+      { targetId: "m-9", linkType: "supports" },
+      { targetId: "m-2", linkType: "causes" },
+      { targetId: "m-5", linkType: "elaborates" },
+    ],
+    limit: 2,
+  });
+  assert.ok(result.ok);
+  assert.equal(result.truncated, true);
+  assert.deepEqual(result.neighbors, [
+    { targetId: "m-2", linkType: "causes" },
+    { targetId: "m-5", linkType: "elaborates" },
+  ]);
+});
+
+test("default limit caps at DEFAULT_TRAVERSE_LIMIT", () => {
+  const links = Array.from({ length: DEFAULT_TRAVERSE_LIMIT + 3 }, (_, i) => ({
+    targetId: `m-${i}`,
+    linkType: "supports",
+  }));
+  const result = selectTraverseNeighbors({ links });
+  assert.ok(result.ok);
+  assert.equal(result.truncated, true);
+  assert.equal(result.neighbors.length, DEFAULT_TRAVERSE_LIMIT);
+});
+
+test("limit 0 is invalid_limit", () => {
+  assert.deepEqual(
+    selectTraverseNeighbors({ links: [], limit: 0 }),
+    { ok: false, error: "invalid_limit" },
+  );
+});
+
+test("limit -1 is invalid_limit", () => {
+  assert.deepEqual(
+    selectTraverseNeighbors({ links: [], limit: -1 }),
+    { ok: false, error: "invalid_limit" },
+  );
+});
+
+test("limit 1.5 is invalid_limit", () => {
+  assert.deepEqual(
+    selectTraverseNeighbors({ links: [], limit: 1.5 }),
+    { ok: false, error: "invalid_limit" },
+  );
+});
+
+test("limit NaN is invalid_limit", () => {
+  assert.deepEqual(
+    selectTraverseNeighbors({ links: [], limit: Number.NaN }),
+    { ok: false, error: "invalid_limit" },
+  );
+});
+
+test("shuffled input is deep-equal to sorted-input result", () => {
+  const sorted = [
+    { targetId: "m-2", linkType: "caused_by" },
+    { targetId: "m-1", linkType: "causes" },
+    { targetId: "m-3", linkType: "elaborates" },
+    { targetId: "m-4", linkType: "supports" },
+  ];
+  const result = selectTraverseNeighbors({
+    links: [...sorted].reverse(),
+  });
+  assert.ok(result.ok);
+  assert.deepEqual(result.neighbors, sorted);
+  assert.deepEqual(selectTraverseNeighbors({ links: sorted }), result);
+});
+
+test("inputs are not mutated", () => {
+  const links = [
+    { targetId: "m-2", linkType: "supports" },
+    { targetId: "m-1", linkType: "causes" },
+  ];
+  selectTraverseNeighbors({ links, relation: "causes", limit: 1 });
+  assert.deepEqual(links, [
+    { targetId: "m-2", linkType: "supports" },
+    { targetId: "m-1", linkType: "causes" },
+  ]);
+});
+
+// Review: the contract said bad stored data is skipped, but a nullish
+// targetId threw before the skip checks could run.
+test("a nullish or non-string targetId is skipped, never thrown", () => {
+  const result = selectTraverseNeighbors({
+    links: [
+      { targetId: undefined as unknown as string, linkType: "supports" },
+      { targetId: null as unknown as string, linkType: "supports" },
+      { targetId: 42 as unknown as string, linkType: "supports" },
+      { targetId: "m-real", linkType: "supports" },
+    ],
+  });
+  assert.ok(result.ok);
+  assert.deepEqual(result.neighbors, [{ targetId: "m-real", linkType: "supports" }]);
+});
+
+// A padded id is malformed, not a variant of the trimmed id: trimming would
+// guess at an identity, so the row is skipped.
+test("a whitespace-padded targetId is skipped rather than trimmed", () => {
+  const result = selectTraverseNeighbors({
+    links: [
+      { targetId: " m-1", linkType: "supports" },
+      { targetId: "m-2", linkType: "supports" },
+    ],
+  });
+  assert.ok(result.ok);
+  assert.deepEqual(result.neighbors, [{ targetId: "m-2", linkType: "supports" }]);
+});
+
+// Review: dedup ran before sorting, so input order decided which relation
+// survived for a doubly-linked target. Sorting first fixes the survivor.
+test("a target under two relations keeps the smallest linkType regardless of input order", () => {
+  const a = { targetId: "m-1", linkType: "supports" };
+  const b = { targetId: "m-1", linkType: "contradicts" };
+  const forward = selectTraverseNeighbors({ links: [a, b] });
+  const reversed = selectTraverseNeighbors({ links: [b, a] });
+  assert.ok(forward.ok && reversed.ok);
+  assert.deepEqual(forward.neighbors, reversed.neighbors);
+  assert.deepEqual(forward.neighbors, [{ targetId: "m-1", linkType: "contradicts" }]);
+});
+
+test("sort-then-dedup also decides which target survives a tight limit", () => {
+  const links = [
+    { targetId: "m-z", linkType: "supports" },
+    { targetId: "m-a", linkType: "supports" },
+    { targetId: "m-a", linkType: "elaborates" },
+  ];
+  const shuffled = selectTraverseNeighbors({ links: [...links].reverse(), limit: 1 });
+  const straight = selectTraverseNeighbors({ links, limit: 1 });
+  assert.ok(shuffled.ok && straight.ok);
+  assert.deepEqual(shuffled.neighbors, straight.neighbors);
+  assert.deepEqual(straight.neighbors, [{ targetId: "m-a", linkType: "elaborates" }]);
+});
+
+
+// Round 2: the persisted MemoryLinkType values are real neighbors, not
+// unknown rows to drop. The selector gets them from the widened parser.
+test("persisted link types survive an unfiltered traversal", () => {
+  const result = selectTraverseNeighbors({
+    links: [
+      { targetId: "m-1", linkType: "follows" },
+      { targetId: "m-2", linkType: "references" },
+      { targetId: "m-3", linkType: "related" },
+    ],
+  });
+  assert.ok(result.ok);
+  assert.equal(result.neighbors.length, 3);
+});
+
+test("relation: related is a valid filter, not unknown", () => {
+  const result = selectTraverseNeighbors({
+    links: [
+      { targetId: "m-1", linkType: "related" },
+      { targetId: "m-2", linkType: "supports" },
+    ],
+    relation: "related",
+  });
+  assert.ok(result.ok);
+  assert.deepEqual(result.neighbors, [{ targetId: "m-1", linkType: "related" }]);
+});

package/src/recall-navigate-traverse.ts

@@ -0,0 +1,73 @@
+/**
+ * Recall navigation traverse selection (issue #1956).
+ *
+ * Pure selection step for `traverseLinks(id, relation?, limit)`: given a
+ * recalled memory's links, pick which neighbors a traverse would visit.
+ * Internal; surfaces wire it in a later slice.
+ */
+import { parseNavigateLinkType } from "./recall-navigate-link.js";
+
+export const DEFAULT_TRAVERSE_LIMIT = 10;
+
+export interface TraverseNeighbor {
+  targetId: string;
+  linkType: string;
+}
+
+export type TraverseSelectionResult =
+  | { ok: true; neighbors: TraverseNeighbor[]; truncated: boolean }
+  | { ok: false; error: "unknown_relation" | "invalid_limit" };
+
+export function selectTraverseNeighbors(input: {
+  links: readonly TraverseNeighbor[];
+  /** Optional relation filter; omitted means every known relation. */
+  relation?: string;
+  limit?: number;
+}): TraverseSelectionResult {
+  const limit = input.limit ?? DEFAULT_TRAVERSE_LIMIT;
+  if (!Number.isFinite(limit) || !Number.isInteger(limit) || limit < 1) {
+    return { ok: false, error: "invalid_limit" };
+  }
+  if (input.relation !== undefined && !parseNavigateLinkType(input.relation).ok) {
+    return { ok: false, error: "unknown_relation" };
+  }
+
+  const kept: TraverseNeighbor[] = [];
+  // Asymmetry is intentional: a bad request (unknown relation, invalid
+  // limit) is refused, but bad stored data is skipped — stored data may
+  // predate a type or carry a malformed id, and one bad row must not fail
+  // the whole traverse. A targetId that is not a non-blank string, including
+  // undefined/null and whitespace-only, is malformed and skipped. Padded ids
+  // are NOT trimmed into validity: an id is an exact identity, and guessing
+  // the intended target is worse than skipping the row.
+  for (const link of input.links) {
+    if (!parseNavigateLinkType(link.linkType).ok) continue;
+    if (input.relation !== undefined && link.linkType !== input.relation) continue;
+    if (typeof link.targetId !== "string" || link.targetId.trim() === "" || link.targetId.trim() !== link.targetId) {
+      continue;
+    }
+    kept.push({ targetId: link.targetId, linkType: link.linkType });
+  }
+
+  // Sort BEFORE deduplicating: first-occurrence dedup on an unsorted list
+  // lets input order decide which relation survives for a target that is
+  // linked under two types, and after the cap is applied, which target is
+  // returned at all. Sorting first makes the survivor deterministic
+  // (smallest linkType wins the tie).
+  kept.sort((a, b) => {
+    if (a.linkType !== b.linkType) return a.linkType < b.linkType ? -1 : 1;
+    if (a.targetId !== b.targetId) return a.targetId < b.targetId ? -1 : 1;
+    return 0;
+  });
+
+  const seen = new Set<string>();
+  const deduped: TraverseNeighbor[] = [];
+  for (const link of kept) {
+    if (seen.has(link.targetId)) continue;
+    seen.add(link.targetId);
+    deduped.push(link);
+  }
+
+  const truncated = deduped.length > limit;
+  return { ok: true, neighbors: truncated ? deduped.slice(0, limit) : deduped, truncated };
+}