@remnic/core 9.69.0 → 9.69.1

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

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