@remnic/core 9.68.0 → 9.69.1

package/src/dedup/merge-provenance.test.ts

@@ -0,0 +1,185 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  buildMergeFrontmatterUpdate,
+  MERGE_DERIVED_VIA,
+  type MergeProvenanceSource,
+} from "./merge-provenance.js";
+
+const NOW = "2026-08-19T12:00:00.000Z";
+
+function source(overrides: Partial<MergeProvenanceSource> = {}): MergeProvenanceSource {
+  return {
+    sessionKey: "project/demo/1",
+    observedAt: "2026-08-18T09:00:00.000Z",
+    quote: "the API limit is 100/min",
+    ...overrides,
+  };
+}
+
+test("appends incoming sources after target sources in order", () => {
+  const a = source({ quote: "first" });
+  const b = source({ quote: "second" });
+  const update = buildMergeFrontmatterUpdate({
+    targetSources: [a],
+    incomingSources: [b],
+    nowIso: NOW,
+  });
+  assert.deepEqual(
+    update.sources.map((s) => s.quote),
+    ["first", "second"],
+  );
+});
+
+test("uses the serializer's allow-listed operator, not an invented one", () => {
+  const update = buildMergeFrontmatterUpdate({ incomingSources: [source()], nowIso: NOW });
+  assert.equal(update.derived_via, "merge");
+  assert.equal(MERGE_DERIVED_VIA, "merge");
+});
+
+test("preserves every canonical optional field on an accepted source", () => {
+  const full = source({ turnId: "turn-7", charStart: 4, charEnd: 12 });
+  const update = buildMergeFrontmatterUpdate({ incomingSources: [full], nowIso: NOW });
+  assert.deepEqual(update.sources, [
+    {
+      sessionKey: full.sessionKey,
+      observedAt: full.observedAt,
+      quote: full.quote,
+      turnId: "turn-7",
+      charStart: 4,
+      charEnd: 12,
+    },
+  ]);
+});
+
+test("accepts a source with no turnId, which the canonical shape allows", () => {
+  const update = buildMergeFrontmatterUpdate({ incomingSources: [source()], nowIso: NOW });
+  assert.equal(update.sources.length, 1);
+  assert.equal("turnId" in update.sources[0]!, false);
+});
+
+test("deduplicates on the full field tuple and keeps the first", () => {
+  const first = source({ turnId: "turn-1" });
+  const update = buildMergeFrontmatterUpdate({
+    targetSources: [first],
+    incomingSources: [{ ...first }, source({ turnId: "turn-2" })],
+    nowIso: NOW,
+  });
+  assert.deepEqual(
+    update.sources.map((s) => s.turnId),
+    ["turn-1", "turn-2"],
+  );
+});
+
+test("sources differing only in offsets are both kept", () => {
+  const update = buildMergeFrontmatterUpdate({
+    incomingSources: [source({ charStart: 0, charEnd: 5 }), source({ charStart: 6, charEnd: 9 })],
+    nowIso: NOW,
+  });
+  assert.equal(update.sources.length, 2);
+});
+
+test("a blank sessionKey or quote is rejected", () => {
+  for (const bad of [source({ sessionKey: "  " }), source({ quote: "" })]) {
+    assert.throws(() => buildMergeFrontmatterUpdate({ incomingSources: [bad], nowIso: NOW }), /non-blank/);
+  }
+});
+
+test("a missing or malformed observedAt is rejected", () => {
+  for (const bad of ["", "2026-08-18", "not-a-date", undefined as unknown as string]) {
+    assert.throws(
+      () => buildMergeFrontmatterUpdate({ incomingSources: [source({ observedAt: bad })], nowIso: NOW }),
+      /observedAt/,
+    );
+  }
+});
+
+test("a blank turnId is rejected while an absent one is fine", () => {
+  assert.throws(
+    () => buildMergeFrontmatterUpdate({ incomingSources: [source({ turnId: " " })], nowIso: NOW }),
+    /turnId/,
+  );
+});
+
+test("negative, non-integer, and inverted offsets are rejected", () => {
+  assert.throws(
+    () => buildMergeFrontmatterUpdate({ incomingSources: [source({ charStart: -1 })], nowIso: NOW }),
+    /charStart/,
+  );
+  assert.throws(
+    () => buildMergeFrontmatterUpdate({ incomingSources: [source({ charEnd: 1.5 })], nowIso: NOW }),
+    /charEnd/,
+  );
+  assert.throws(
+    () =>
+      buildMergeFrontmatterUpdate({
+        incomingSources: [source({ charStart: 9, charEnd: 2 })],
+        nowIso: NOW,
+      }),
+    /charEnd must be >= charStart/,
+  );
+});
+
+test("reinforcement_count starts at 1 and increments from the target", () => {
+  assert.equal(
+    buildMergeFrontmatterUpdate({ incomingSources: [source()], nowIso: NOW }).reinforcement_count,
+    1,
+  );
+  assert.equal(
+    buildMergeFrontmatterUpdate({
+      incomingSources: [source()],
+      targetReinforcementCount: 2,
+      nowIso: NOW,
+    }).reinforcement_count,
+    3,
+  );
+});
+
+test("an invalid target reinforcement_count is rejected", () => {
+  for (const bad of [-1, 1.5, Number.NaN, "2" as unknown as number]) {
+    assert.throws(
+      () =>
+        buildMergeFrontmatterUpdate({
+          incomingSources: [source()],
+          targetReinforcementCount: bad,
+          nowIso: NOW,
+        }),
+      /reinforcement_count/,
+    );
+  }
+});
+
+// Date.parse alone accepts "123" and rolls 2026-02-30 into March; the value is
+// echoed verbatim into frontmatter, so the full ISO shape is required.
+test("nowIso must be a full ISO instant with a real calendar date", () => {
+  for (const bad of ["", "   ", "123", "2026-01-01", "2026-02-30T00:00:00Z", "nope"]) {
+    assert.throws(
+      () => buildMergeFrontmatterUpdate({ incomingSources: [source()], nowIso: bad }),
+      /nowIso/,
+    );
+  }
+  assert.equal(
+    buildMergeFrontmatterUpdate({ incomingSources: [source()], nowIso: "2026-08-19T12:00:00+02:00" }).updated,
+    "2026-08-19T12:00:00+02:00",
+  );
+});
+
+test("empty incomingSources still bumps the counter and preserves target sources", () => {
+  const update = buildMergeFrontmatterUpdate({
+    targetSources: [source()],
+    incomingSources: [],
+    targetReinforcementCount: 1,
+    nowIso: NOW,
+  });
+  assert.equal(update.sources.length, 1);
+  assert.equal(update.reinforcement_count, 2);
+});
+
+test("inputs are not mutated", () => {
+  const target = [source({ turnId: "t" })];
+  const incoming = [source({ quote: "other" })];
+  const snapshot = JSON.stringify({ target, incoming });
+  buildMergeFrontmatterUpdate({ targetSources: target, incomingSources: incoming, nowIso: NOW });
+  assert.equal(JSON.stringify({ target, incoming }), snapshot);
+});

package/src/dedup/merge-provenance.ts

@@ -0,0 +1,151 @@
+/**
+ * Merge frontmatter builder (issue #2330).
+ *
+ * On a create-or-update merge the target keeps its own provenance and gains
+ * the incoming fact's, so a merge can never erase where a claim came from.
+ *
+ * Fields here match the canonical schema in `types.ts` deliberately: the
+ * serializer rejects a `derived_via` outside its allow-list and drops keys
+ * `MemoryFrontmatter` does not define, so an invented operator name or
+ * counter would vanish on write. Pure — no I/O, no clock.
+ */
+
+/** The serializer's allow-listed operator for a create-or-update merge. */
+export const MERGE_DERIVED_VIA = "merge" as const;
+
+/**
+ * Structural mirror of `ProvenanceSource` (types.ts). `sessionKey`,
+ * `observedAt`, and `quote` are required; `turnId` and the character
+ * offsets are optional and MUST survive a merge untouched.
+ */
+export interface MergeProvenanceSource {
+  sessionKey: string;
+  observedAt: string;
+  quote: string;
+  turnId?: string;
+  charStart?: number;
+  charEnd?: number;
+}
+
+export interface MergeFrontmatterUpdate {
+  updated: string;
+  derived_via: typeof MERGE_DERIVED_VIA;
+  /** Follows the `reinforcement_count` convention; the serializer requires > 0. */
+  reinforcement_count: number;
+  sources: MergeProvenanceSource[];
+}
+
+const ISO_TIMESTAMP =
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/;
+
+/**
+ * Require a full ISO 8601 instant whose calendar components round-trip.
+ * `Date.parse` alone accepts `123` and rolls `2026-02-30` over into March,
+ * and this value is echoed verbatim into frontmatter.
+ */
+function assertIsoInstant(value: unknown, field: string): string {
+  if (typeof value !== "string" || !ISO_TIMESTAMP.test(value)) {
+    throw new RangeError(`${field} must be a full ISO 8601 instant, got ${JSON.stringify(value)}`);
+  }
+  const ms = Date.parse(value);
+  if (Number.isNaN(ms)) {
+    throw new RangeError(`${field} must be a full ISO 8601 instant, got ${JSON.stringify(value)}`);
+  }
+  // Reject a rolled-over calendar date (2026-02-30 -> 2026-03-02).
+  if (!new Date(ms).toISOString().startsWith(value.slice(0, 10))) {
+    throw new RangeError(`${field} is not a real calendar date: ${JSON.stringify(value)}`);
+  }
+  return value;
+}
+
+function assertOffset(value: unknown, field: string): void {
+  if (value === undefined) return;
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+    throw new RangeError(`${field} must be a non-negative integer when present, got ${String(value)}`);
+  }
+}
+
+function normalizeSource(source: MergeProvenanceSource, index: number): MergeProvenanceSource {
+  const label = `sources[${index}]`;
+  for (const field of ["sessionKey", "quote"] as const) {
+    const value = source[field];
+    if (typeof value !== "string" || value.trim() === "") {
+      throw new RangeError(`${label}.${field} must be a non-blank string`);
+    }
+  }
+  assertIsoInstant(source.observedAt, `${label}.observedAt`);
+  if (source.turnId !== undefined && (typeof source.turnId !== "string" || source.turnId.trim() === "")) {
+    throw new RangeError(`${label}.turnId must be a non-blank string when present`);
+  }
+  assertOffset(source.charStart, `${label}.charStart`);
+  assertOffset(source.charEnd, `${label}.charEnd`);
+  if (source.charStart !== undefined && source.charEnd !== undefined && source.charEnd < source.charStart) {
+    throw new RangeError(`${label}.charEnd must be >= charStart`);
+  }
+  // Copy every canonical field, including the optional ones: dropping
+  // observedAt or the offsets here would make the serializer discard the
+  // clone, turning "append provenance" into "erase provenance".
+  const copy: MergeProvenanceSource = {
+    sessionKey: source.sessionKey,
+    observedAt: source.observedAt,
+    quote: source.quote,
+  };
+  if (source.turnId !== undefined) copy.turnId = source.turnId;
+  if (source.charStart !== undefined) copy.charStart = source.charStart;
+  if (source.charEnd !== undefined) copy.charEnd = source.charEnd;
+  return copy;
+}
+
+function sourceKey(source: MergeProvenanceSource): string {
+  return JSON.stringify([
+    source.sessionKey,
+    source.turnId ?? null,
+    source.observedAt,
+    source.quote,
+    source.charStart ?? null,
+    source.charEnd ?? null,
+  ]);
+}
+
+export function buildMergeFrontmatterUpdate(input: {
+  /** Existing sources already on the merge target. */
+  targetSources?: readonly MergeProvenanceSource[];
+  /** Sources from the incoming fact being merged in. */
+  incomingSources: readonly MergeProvenanceSource[];
+  /** Existing reinforcement_count on the target, if any. */
+  targetReinforcementCount?: number;
+  nowIso: string;
+}): MergeFrontmatterUpdate {
+  const updated = assertIsoInstant(input.nowIso, "nowIso");
+
+  const previous = input.targetReinforcementCount;
+  if (
+    previous !== undefined &&
+    (typeof previous !== "number" || !Number.isInteger(previous) || previous < 0)
+  ) {
+    throw new RangeError(
+      `reinforcement_count must be a non-negative integer when supplied, got ${String(previous)}`,
+    );
+  }
+
+  const seen = new Set<string>();
+  const sources: MergeProvenanceSource[] = [];
+  const append = (source: MergeProvenanceSource, index: number): void => {
+    const copy = normalizeSource(source, index);
+    const key = sourceKey(copy);
+    if (seen.has(key)) return;
+    seen.add(key);
+    sources.push(copy);
+  };
+
+  const target = input.targetSources ?? [];
+  target.forEach(append);
+  input.incomingSources.forEach((source, i) => append(source, target.length + i));
+
+  return {
+    updated,
+    derived_via: MERGE_DERIVED_VIA,
+    reinforcement_count: (previous ?? 0) + 1,
+    sources,
+  };
+}

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

@@ -0,0 +1,128 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  disclosureRank,
+  planDisclosureStep,
+} from "./recall-navigate-disclosure.js";
+import { RECALL_DISCLOSURE_LEVELS } from "./types.js";
+
+// The declared input type is strings; agents send arbitrary JSON. Cast only
+// at this boundary so the invalid-shape cases stay one line each.
+const plan = (from: unknown, to: unknown) =>
+  planDisclosureStep({ from, to } as unknown as { from: string; to: string });
+
+test("disclosureRank returns the index of every level, shallowest first", () => {
+  for (const [i, level] of RECALL_DISCLOSURE_LEVELS.entries()) {
+    assert.equal(disclosureRank(level), i);
+  }
+  assert.ok(
+    disclosureRank(RECALL_DISCLOSURE_LEVELS[0]) < disclosureRank(RECALL_DISCLOSURE_LEVELS[1]),
+  );
+  assert.ok(
+    disclosureRank(RECALL_DISCLOSURE_LEVELS[1]) < disclosureRank(RECALL_DISCLOSURE_LEVELS[2]),
+  );
+});
+
+test("disclosureRank throws a RangeError listing allowed values", () => {
+  assert.throws(
+    () => disclosureRank("full"),
+    (err: unknown) =>
+      err instanceof RangeError &&
+      /disclosure level/.test(err.message) &&
+      err.message.includes("chunk") &&
+      err.message.includes("section") &&
+      err.message.includes("raw"),
+  );
+});
+
+test("chunk→section is one step", () => {
+  assert.deepEqual(planDisclosureStep({ from: "chunk", to: "section" }), {
+    ok: true,
+    from: "chunk",
+    to: "section",
+    steps: 1,
+  });
+});
+
+test("section→raw is one step", () => {
+  assert.deepEqual(planDisclosureStep({ from: "section", to: "raw" }), {
+    ok: true,
+    from: "section",
+    to: "raw",
+    steps: 1,
+  });
+});
+
+test("chunk→raw is two steps", () => {
+  assert.deepEqual(planDisclosureStep({ from: "chunk", to: "raw" }), {
+    ok: true,
+    from: "chunk",
+    to: "raw",
+    steps: 2,
+  });
+});
+
+test("every level pair is only deeper in one direction", () => {
+  for (const shallower of RECALL_DISCLOSURE_LEVELS) {
+    for (const deeper of RECALL_DISCLOSURE_LEVELS) {
+      const result = planDisclosureStep({ from: shallower, to: deeper });
+      if (disclosureRank(shallower) < disclosureRank(deeper)) {
+        assert.deepEqual(result, {
+          ok: true,
+          from: shallower,
+          to: deeper,
+          steps: disclosureRank(deeper) - disclosureRank(shallower),
+        });
+      } else {
+        assert.deepEqual(result, { ok: false, error: "not_deeper" });
+      }
+    }
+  }
+});
+
+test("equal levels are not_deeper", () => {
+  for (const level of RECALL_DISCLOSURE_LEVELS) {
+    assert.deepEqual(planDisclosureStep({ from: level, to: level }), {
+      ok: false,
+      error: "not_deeper",
+    });
+  }
+});
+
+test("shallower pairs are not_deeper", () => {
+  for (const [from, to] of [
+    ["section", "chunk"],
+    ["raw", "section"],
+    ["raw", "chunk"],
+  ] as const) {
+    assert.deepEqual(planDisclosureStep({ from, to }), {
+      ok: false,
+      error: "not_deeper",
+    });
+  }
+});
+
+test("unknown level on either side is unknown_level, not a throw", () => {
+  assert.deepEqual(plan("full", "raw"), { ok: false, error: "unknown_level" });
+  assert.deepEqual(plan("chunk", "full"), { ok: false, error: "unknown_level" });
+  assert.deepEqual(plan("full", "worse"), { ok: false, error: "unknown_level" });
+});
+
+test("non-string level on either side is unknown_level", () => {
+  for (const bad of [5, null, undefined, true, { level: "raw" }, ["raw"]]) {
+    assert.deepEqual(plan(bad, "raw"), { ok: false, error: "unknown_level" });
+    assert.deepEqual(plan("chunk", bad), { ok: false, error: "unknown_level" });
+  }
+});
+
+test("empty string level is unknown_level", () => {
+  assert.deepEqual(plan("", "raw"), { ok: false, error: "unknown_level" });
+  assert.deepEqual(plan("chunk", ""), { ok: false, error: "unknown_level" });
+});
+
+test("levels match exactly — no case folding, no trimming", () => {
+  assert.deepEqual(plan("Raw", "chunk"), { ok: false, error: "unknown_level" });
+  assert.deepEqual(plan(" raw", "raw"), { ok: false, error: "unknown_level" });
+  assert.deepEqual(plan("raw", "RAW"), { ok: false, error: "unknown_level" });
+});

package/src/recall-navigate-disclosure.ts

@@ -0,0 +1,45 @@
+/**
+ * Disclosure-step planning for recall navigation (issue #1956).
+ *
+ * The ladder itself is NOT redefined here: `types.ts` designates
+ * `RECALL_DISCLOSURE_LEVELS` the single source of truth and forbids
+ * hard-coding disclosure strings elsewhere, so a second copy could drift out
+ * of agreement with recall validation and rendering. This module only adds
+ * the rule that an expansion must go strictly deeper, so a caller cannot
+ * re-pay recall budget for output it already holds. Pure — no I/O.
+ */
+
+import {
+  isRecallDisclosure,
+  RECALL_DISCLOSURE_LEVELS,
+  type RecallDisclosure,
+} from "./types.js";
+
+export type DisclosureStepResult =
+  | { ok: true; from: RecallDisclosure; to: RecallDisclosure; steps: number }
+  | { ok: false; error: "unknown_level" | "not_deeper" };
+
+/** Index in the canonical shallow-to-deep ladder. Throws for a non-level. */
+export function disclosureRank(level: string): number {
+  const index = (RECALL_DISCLOSURE_LEVELS as readonly string[]).indexOf(level);
+  if (index < 0) {
+    throw new RangeError(
+      `unknown disclosure level ${JSON.stringify(level)}; expected one of ${RECALL_DISCLOSURE_LEVELS.join(", ")}`,
+    );
+  }
+  return index;
+}
+
+/**
+ * Plan one expansion. A bad level from an agent is a typed refusal rather
+ * than a throw; equal or shallower targets are `not_deeper`.
+ */
+export function planDisclosureStep(input: { from: string; to: string }): DisclosureStepResult {
+  if (!isRecallDisclosure(input.from) || !isRecallDisclosure(input.to)) {
+    return { ok: false, error: "unknown_level" };
+  }
+  const fromRank = disclosureRank(input.from);
+  const toRank = disclosureRank(input.to);
+  if (toRank <= fromRank) return { ok: false, error: "not_deeper" };
+  return { ok: true, from: input.from, to: input.to, steps: toRank - fromRank };
+}

package/src/recall-state-view-packet.test.ts

@@ -0,0 +1,158 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { buildStateEvidencePackets } from "./recall-state-view-packet.js";
+import type { StateViewEntry } from "./recall-state-view-packet.js";
+
+test("two-step predecessor chain is ordered nearest to head first", () => {
+  const result = buildStateEvidencePackets([
+    { memoryId: "head", stateLabel: "current" },
+    { memoryId: "old-2", stateLabel: "historical", supersededById: "old-1" },
+    { memoryId: "old-1", stateLabel: "historical", supersededById: "head" },
+  ]);
+  assert.deepEqual(result, {
+    packets: [{ headId: "head", historyIds: ["old-1", "old-2"] }],
+    orphanHistoryIds: [],
+  });
+});
+
+test("two independent packets never interleave", () => {
+  const result = buildStateEvidencePackets([
+    { memoryId: "b-head", stateLabel: "transition" },
+    { memoryId: "a-head", stateLabel: "current" },
+    { memoryId: "b-old", stateLabel: "historical", supersededById: "b-head" },
+    { memoryId: "a-old", stateLabel: "historical", supersededById: "a-head" },
+  ]);
+  assert.deepEqual(result, {
+    packets: [
+      { headId: "a-head", historyIds: ["a-old"] },
+      { headId: "b-head", historyIds: ["b-old"] },
+    ],
+    orphanHistoryIds: [],
+  });
+});
+
+test("historical entry pointing at an absent successor becomes an orphan", () => {
+  const result = buildStateEvidencePackets([
+    { memoryId: "head", stateLabel: "current" },
+    { memoryId: "dangling", stateLabel: "historical", supersededById: "missing" },
+  ]);
+  assert.deepEqual(result, {
+    packets: [{ headId: "head", historyIds: [] }],
+    orphanHistoryIds: ["dangling"],
+  });
+});
+
+test("historical entry with no supersededById becomes an orphan", () => {
+  const result = buildStateEvidencePackets([
+    { memoryId: "rootless", stateLabel: "historical" },
+  ]);
+  assert.deepEqual(result, {
+    packets: [],
+    orphanHistoryIds: ["rootless"],
+  });
+});
+
+test("supersededById cycle terminates and yields orphans", () => {
+  const result = buildStateEvidencePackets([
+    { memoryId: "head", stateLabel: "current" },
+    { memoryId: "loop-a", stateLabel: "historical", supersededById: "loop-b" },
+    { memoryId: "loop-b", stateLabel: "historical", supersededById: "loop-a" },
+    { memoryId: "into-loop", stateLabel: "historical", supersededById: "loop-a" },
+  ]);
+  assert.deepEqual(result, {
+    packets: [{ headId: "head", historyIds: [] }],
+    orphanHistoryIds: ["into-loop", "loop-a", "loop-b"],
+  });
+});
+
+test("lone current entry yields a packet with empty history", () => {
+  const result = buildStateEvidencePackets([
+    { memoryId: "solo", stateLabel: "current" },
+  ]);
+  assert.deepEqual(result, {
+    packets: [{ headId: "solo", historyIds: [] }],
+    orphanHistoryIds: [],
+  });
+});
+
+test("unknown state label throws TypeError listing the allowed values", () => {
+  assert.throws(
+    () =>
+      buildStateEvidencePackets([
+        { memoryId: "x", stateLabel: "archived" as StateViewEntry["stateLabel"] },
+      ]),
+    (error: unknown) => {
+      assert.ok(error instanceof TypeError);
+      const message = String((error as Error).message);
+      assert.match(message, /state label/);
+      assert.ok(message.includes('"current"'));
+      assert.ok(message.includes('"historical"'));
+      assert.ok(message.includes('"transition"'));
+      return true;
+    },
+  );
+});
+
+test("blank memoryId is ignored", () => {
+  const result = buildStateEvidencePackets([
+    { memoryId: "", stateLabel: "historical", supersededById: "head" },
+    { memoryId: "   ", stateLabel: "current" },
+    { memoryId: "head", stateLabel: "current" },
+  ]);
+  assert.deepEqual(result, {
+    packets: [{ headId: "head", historyIds: [] }],
+    orphanHistoryIds: [],
+  });
+});
+
+test("duplicate memoryId keeps the first entry", () => {
+  const result = buildStateEvidencePackets([
+    { memoryId: "dup", stateLabel: "current" },
+    { memoryId: "dup", stateLabel: "historical", supersededById: "other" },
+    { memoryId: "old", stateLabel: "historical", supersededById: "dup" },
+  ]);
+  assert.deepEqual(result, {
+    packets: [{ headId: "dup", historyIds: ["old"] }],
+    orphanHistoryIds: [],
+  });
+});
+
+test("shuffled input produces a deep-equal result", () => {
+  const entries: StateViewEntry[] = [
+    { memoryId: "h2", stateLabel: "transition" },
+    { memoryId: "h1", stateLabel: "current" },
+    { memoryId: "a1", stateLabel: "historical", supersededById: "h1" },
+    { memoryId: "a2", stateLabel: "historical", supersededById: "a1" },
+    { memoryId: "b1", stateLabel: "historical", supersededById: "h2" },
+    { memoryId: "lost", stateLabel: "historical" },
+  ];
+  const expected = {
+    packets: [
+      { headId: "h1", historyIds: ["a1", "a2"] },
+      { headId: "h2", historyIds: ["b1"] },
+    ],
+    orphanHistoryIds: ["lost"],
+  };
+  assert.deepEqual(buildStateEvidencePackets(entries), expected);
+  const byId = new Map(entries.map((entry) => [entry.memoryId, entry]));
+  const orders = [
+    ["lost", "b1", "a2", "a1", "h2", "h1"],
+    ["h2", "lost", "h1", "b1", "a2", "a1"],
+    ["a2", "h1", "lost", "h2", "a1", "b1"],
+  ];
+  for (const order of orders) {
+    const shuffled = order.map((id) => byId.get(id) as StateViewEntry);
+    assert.deepEqual(buildStateEvidencePackets(shuffled), expected);
+  }
+});
+
+test("input entries are not mutated", () => {
+  const entries: StateViewEntry[] = [
+    { memoryId: "head", stateLabel: "current" },
+    { memoryId: "old", stateLabel: "historical", supersededById: "head" },
+  ];
+  const snapshot = structuredClone(entries);
+  buildStateEvidencePackets(entries);
+  assert.deepEqual(entries, snapshot);
+});