@remnic/core 9.69.0 → 9.69.2

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

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

@@ -0,0 +1,128 @@
+/**
+ * Recall state-view evidence packets (issue #1952).
+ *
+ * Groups labeled state-view entries into per-head evidence packets so
+ * superseded records stay visible as ordered history instead of being
+ * hidden or interleaved with another packet's entries. Pure. Surfaces wait.
+ */
+import type { StateLabel } from "./recall-state-view.js";
+
+export type { StateLabel };
+
+export interface StateViewEntry {
+  memoryId: string;
+  stateLabel: StateLabel;
+  /** Id of the entry that superseded this one, when any. */
+  supersededById?: string;
+}
+
+export interface StateEvidencePacket {
+  /** The current (or transition) entry this packet is about. */
+  headId: string;
+  /** Predecessors, nearest to head first. Never interleaved with other packets. */
+  historyIds: string[];
+}
+
+export interface StateEvidencePackets {
+  packets: StateEvidencePacket[];
+  /** Historical entries whose successor is absent from the input. */
+  orphanHistoryIds: string[];
+}
+
+const STATE_LABELS: readonly StateLabel[] = ["current", "historical", "transition"];
+
+interface HeadResolution {
+  headId: string;
+  depth: number;
+}
+
+interface Attachment {
+  headId: string;
+  historyId: string;
+  depth: number;
+}
+
+/**
+ * Walk supersededById forward through intermediate historical entries and
+ * stop at the first current/transition successor. Returns undefined when the
+ * walk dead-ends (no or blank successor, successor id absent from the input)
+ * or revisits an id (cycle), so callers treat the entry as an orphan.
+ */
+function resolveHead(
+  entry: StateViewEntry,
+  byId: ReadonlyMap<string, StateViewEntry>,
+): HeadResolution | undefined {
+  const visited = new Set<string>();
+  let current = entry;
+  let depth = 0;
+  for (;;) {
+    const successorId = current.supersededById;
+    if (successorId === undefined || successorId.trim() === "") return undefined;
+    const successor = byId.get(successorId);
+    if (successor === undefined) return undefined;
+    depth += 1;
+    if (successor.stateLabel !== "historical") return { headId: successorId, depth };
+    if (visited.has(successorId)) return undefined;
+    visited.add(successorId);
+    current = successor;
+  }
+}
+
+function compareStrings(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+function compareAttachments(a: Attachment, b: Attachment): number {
+  if (a.headId !== b.headId) return compareStrings(a.headId, b.headId);
+  if (a.depth !== b.depth) return a.depth < b.depth ? -1 : 1;
+  return compareStrings(a.historyId, b.historyId);
+}
+
+export function buildStateEvidencePackets(
+  entries: readonly StateViewEntry[],
+): StateEvidencePackets {
+  // Validate every label before any skip, dedup, or walk.
+  for (const entry of entries) {
+    if (!(STATE_LABELS as readonly string[]).includes(entry.stateLabel)) {
+      throw new TypeError(
+        `unknown state label ${JSON.stringify(entry.stateLabel)}; expected one of "current", "historical", "transition"`,
+      );
+    }
+  }
+
+  // Blank ids are ignored; on duplicate ids the first entry wins.
+  const byId = new Map<string, StateViewEntry>();
+  for (const entry of entries) {
+    if (typeof entry.memoryId !== "string" || entry.memoryId.trim() === "") continue;
+    if (!byId.has(entry.memoryId)) byId.set(entry.memoryId, entry);
+  }
+
+  // ponytail: per-entry chain walks are O(n^2) on one long chain; recall-sized
+  // result sets stay tiny, memoize if packet building ever moves offline.
+  const packets: StateEvidencePacket[] = [];
+  const packetByHead = new Map<string, StateEvidencePacket>();
+  const attachments: Attachment[] = [];
+  const orphanHistoryIds: string[] = [];
+
+  for (const [id, entry] of byId) {
+    if (entry.stateLabel !== "historical") {
+      const packet: StateEvidencePacket = { headId: id, historyIds: [] };
+      packetByHead.set(id, packet);
+      packets.push(packet);
+      continue;
+    }
+    const head = resolveHead(entry, byId);
+    if (head === undefined) orphanHistoryIds.push(id);
+    else attachments.push({ headId: head.headId, historyId: id, depth: head.depth });
+  }
+
+  attachments.sort(compareAttachments);
+  for (const attachment of attachments) {
+    const packet = packetByHead.get(attachment.headId);
+    if (packet) packet.historyIds.push(attachment.historyId);
+  }
+
+  packets.sort((a, b) => compareStrings(a.headId, b.headId));
+  orphanHistoryIds.sort(compareStrings);
+  return { packets, orphanHistoryIds };
+}