@remnic/core 9.69.0 → 9.69.2

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-deep-expand-select.test.ts

@@ -0,0 +1,163 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  DEFAULT_MAX_EXPAND_PER_STEP,
+  selectExpandNodeIds,
+} from "./recall-deep-expand-select.js";
+
+const FRONTIER = ["n1", "n2", "n3", "n4", "n5"] as const;
+
+test("subset request passes untruncated", () => {
+  const result = selectExpandNodeIds({
+    frontierIds: FRONTIER,
+    requestedIds: ["n3", "n1"],
+  });
+  assert.deepEqual(result, {
+    ok: true,
+    nodeIds: ["n3", "n1"],
+    truncated: false,
+  });
+});
+
+test("five-id valid request truncates to three in requested order", () => {
+  const result = selectExpandNodeIds({
+    frontierIds: FRONTIER,
+    requestedIds: ["n5", "n2", "n4", "n1", "n3"],
+  });
+  assert.deepEqual(result, {
+    ok: true,
+    nodeIds: ["n5", "n2", "n4"],
+    truncated: true,
+  });
+});
+
+test("one foreign id among valid ones refuses and lists only the foreign id", () => {
+  const result = selectExpandNodeIds({
+    frontierIds: FRONTIER,
+    requestedIds: ["n1", "ghost", "n2"],
+  });
+  assert.deepEqual(result, {
+    ok: false,
+    error: "invalid_policy_output",
+    foreignIds: ["ghost"],
+  });
+});
+
+test("several foreign ids are sorted and deduplicated", () => {
+  const result = selectExpandNodeIds({
+    frontierIds: FRONTIER,
+    requestedIds: ["z9", "a1", "z9", "n1"],
+  });
+  assert.deepEqual(result, {
+    ok: false,
+    error: "invalid_policy_output",
+    foreignIds: ["a1", "z9"],
+  });
+});
+
+test("duplicates collapse before the cap", () => {
+  const result = selectExpandNodeIds({
+    frontierIds: FRONTIER,
+    requestedIds: ["n1", "n1", "n1", "n2"],
+  });
+  assert.deepEqual(result, {
+    ok: true,
+    nodeIds: ["n1", "n2"],
+    truncated: false,
+  });
+});
+
+test("padded and case-different ids are foreign", () => {
+  const result = selectExpandNodeIds({
+    frontierIds: FRONTIER,
+    requestedIds: [" n1", "N1"],
+  });
+  assert.deepEqual(result, {
+    ok: false,
+    error: "invalid_policy_output",
+    foreignIds: [" n1", "N1"],
+  });
+});
+
+test("non-array requestedIds refuses with empty foreignIds", () => {
+  for (const bad of [undefined, null, "n1"]) {
+    const result = selectExpandNodeIds({
+      frontierIds: FRONTIER,
+      requestedIds: bad,
+    });
+    assert.deepEqual(result, {
+      ok: false,
+      error: "invalid_policy_output",
+      foreignIds: [],
+    });
+  }
+});
+
+test("non-string array entry is reported as its String form", () => {
+  const result = selectExpandNodeIds({
+    frontierIds: FRONTIER,
+    requestedIds: ["n1", 42],
+  });
+  assert.deepEqual(result, {
+    ok: false,
+    error: "invalid_policy_output",
+    foreignIds: ["42"],
+  });
+});
+
+test("blank string entry is foreign", () => {
+  const result = selectExpandNodeIds({
+    frontierIds: FRONTIER,
+    requestedIds: ["   "],
+  });
+  assert.deepEqual(result, {
+    ok: false,
+    error: "invalid_policy_output",
+    foreignIds: ["   "],
+  });
+});
+
+test("empty array succeeds and expands nothing", () => {
+  const result = selectExpandNodeIds({
+    frontierIds: FRONTIER,
+    requestedIds: [],
+  });
+  assert.deepEqual(result, { ok: true, nodeIds: [], truncated: false });
+});
+
+test("default cap is three", () => {
+  assert.equal(DEFAULT_MAX_EXPAND_PER_STEP, 3);
+  const result = selectExpandNodeIds({
+    frontierIds: FRONTIER,
+    requestedIds: ["n1", "n2", "n3", "n4"],
+  });
+  assert.deepEqual(result, {
+    ok: true,
+    nodeIds: ["n1", "n2", "n3"],
+    truncated: true,
+  });
+});
+
+test("maxExpandPerStep 0, -1, and 1.5 throw RangeError naming the field", () => {
+  for (const bad of [0, -1, 1.5]) {
+    assert.throws(
+      () =>
+        selectExpandNodeIds({
+          frontierIds: FRONTIER,
+          requestedIds: ["n1"],
+          maxExpandPerStep: bad,
+        }),
+      (err: unknown) =>
+        err instanceof RangeError && /maxExpandPerStep/.test(err.message),
+    );
+  }
+});
+
+test("inputs are not mutated", () => {
+  const frontierIds = ["n1", "n2"];
+  const requestedIds = ["n2", "n2", "ghost"];
+  selectExpandNodeIds({ frontierIds, requestedIds });
+  assert.deepEqual(frontierIds, ["n1", "n2"]);
+  assert.deepEqual(requestedIds, ["n2", "n2", "ghost"]);
+});

package/src/recall-deep-expand-select.ts

@@ -0,0 +1,65 @@
+/**
+ * Select EXPAND node ids for deep recall (issue #2332).
+ *
+ * A foreign id refuses the whole selection; an oversized request truncates.
+ * Duplicates collapse before the cap. Pure. Surfaces wait.
+ */
+export const DEFAULT_MAX_EXPAND_PER_STEP = 3;
+
+export type ExpandSelectionResult =
+  | { ok: true; nodeIds: string[]; truncated: boolean }
+  | { ok: false; error: "invalid_policy_output"; foreignIds: string[] };
+
+export function selectExpandNodeIds(input: {
+  frontierIds: readonly string[];
+  requestedIds: unknown;
+  maxExpandPerStep?: number;
+}): ExpandSelectionResult {
+  const max =
+    input.maxExpandPerStep === undefined
+      ? DEFAULT_MAX_EXPAND_PER_STEP
+      : input.maxExpandPerStep;
+  if (!Number.isInteger(max) || max < 1) {
+    throw new RangeError(
+      `maxExpandPerStep must be an integer >= 1; got ${JSON.stringify(max)}`,
+    );
+  }
+
+  if (!Array.isArray(input.requestedIds)) {
+    return { ok: false, error: "invalid_policy_output", foreignIds: [] };
+  }
+
+  const frontier = new Set(input.frontierIds);
+  const seen = new Set<string>();
+  const foreign = new Set<string>();
+  const ordered: string[] = [];
+
+  for (const entry of input.requestedIds) {
+    if (typeof entry !== "string" || entry.trim().length === 0) {
+      foreign.add(String(entry));
+      continue;
+    }
+    if (!frontier.has(entry)) {
+      foreign.add(entry);
+      continue;
+    }
+    if (seen.has(entry)) continue;
+    seen.add(entry);
+    ordered.push(entry);
+  }
+
+  if (foreign.size > 0) {
+    return {
+      ok: false,
+      error: "invalid_policy_output",
+      foreignIds: [...foreign].sort(),
+    };
+  }
+
+  const truncated = ordered.length > max;
+  return {
+    ok: true,
+    nodeIds: truncated ? ordered.slice(0, max) : ordered,
+    truncated,
+  };
+}

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