@remnic/core 9.66.2 → 9.66.3

package/src/recall-deep-stop.test.ts

@@ -0,0 +1,34 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { shouldStopDeepRecall } from "./recall-deep-stop.js";
+
+test("budgetLeft 0 stops", () => {
+  assert.equal(shouldStopDeepRecall({ budgetLeft: 0, policy: "expand-once" }), true);
+});
+
+test("stop policy stops", () => {
+  assert.equal(shouldStopDeepRecall({ budgetLeft: 3, policy: "stop" }), true);
+});
+
+test("expand-once stops only after one expansion", () => {
+  assert.equal(
+    shouldStopDeepRecall({ budgetLeft: 3, policy: "expand-once", alreadyExpanded: false }),
+    false,
+  );
+  assert.equal(
+    shouldStopDeepRecall({ budgetLeft: 3, policy: "expand-once", alreadyExpanded: true }),
+    true,
+  );
+});
+
+test("unknown policy throws", () => {
+  assert.throws(
+    () => shouldStopDeepRecall({ budgetLeft: 3, policy: "refine-twice" }),
+    /unknown deep recall stop policy/,
+  );
+  assert.throws(
+    () => shouldStopDeepRecall({ budgetLeft: 3, policy: "refine-twice" }),
+    /stop, expand-once/,
+  );
+});

package/src/recall-deep-stop.ts

@@ -0,0 +1,31 @@
+/**
+ * Deep-recall stop predicate (issue #2332 leftover).
+ *
+ * Pure. Surfaces wait. Budget 0, stop policy, and expand-once after
+ * one expansion halt. Unknown policy throws.
+ */
+
+export const DEEP_RECALL_STOP_POLICIES = ["stop", "expand-once"] as const;
+
+export type DeepRecallStopPolicy = (typeof DEEP_RECALL_STOP_POLICIES)[number];
+
+export interface DeepRecallStopInput {
+  budgetLeft: number;
+  policy: string;
+  alreadyExpanded?: boolean;
+}
+
+export function isDeepRecallStopPolicy(value: unknown): value is DeepRecallStopPolicy {
+  return typeof value === "string" && (DEEP_RECALL_STOP_POLICIES as readonly string[]).includes(value);
+}
+
+export function shouldStopDeepRecall(input: DeepRecallStopInput): boolean {
+  if (!isDeepRecallStopPolicy(input.policy)) {
+    throw new Error(
+      `unknown deep recall stop policy: ${JSON.stringify(input.policy)}. Valid: ${DEEP_RECALL_STOP_POLICIES.join(", ")}`,
+    );
+  }
+  if (input.budgetLeft <= 0) return true;
+  if (input.policy === "stop") return true;
+  return input.alreadyExpanded === true;
+}

package/src/recall-deep-working-set.test.ts

@@ -0,0 +1,21 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { isEmptyWorkingSet } from "./recall-deep-working-set.js";
+
+test("null, undefined, and empty array are empty", () => {
+  assert.equal(isEmptyWorkingSet(null), true);
+  assert.equal(isEmptyWorkingSet(undefined), true);
+  assert.equal(isEmptyWorkingSet([]), true);
+});
+
+test("a non-empty array is not empty", () => {
+  assert.equal(isEmptyWorkingSet([{ id: 1 }]), false);
+  assert.equal(isEmptyWorkingSet([0]), false);
+});
+
+test("a non-array throws", () => {
+  assert.throws(() => isEmptyWorkingSet({}), TypeError);
+  assert.throws(() => isEmptyWorkingSet("items"), TypeError);
+  assert.throws(() => isEmptyWorkingSet(1), TypeError);
+});

package/src/recall-deep-working-set.ts

@@ -0,0 +1,14 @@
+/**
+ * Empty-set guard for a deep-recall working set (issue #2332 leftover).
+ *
+ * null, undefined, and [] are empty. A non-array throws. Any other array is not empty.
+ */
+
+/** True when the working set is absent or has no items. */
+export function isEmptyWorkingSet(items: unknown): boolean {
+  if (items == null) return true;
+  if (!Array.isArray(items)) {
+    throw new TypeError("items must be an array");
+  }
+  return items.length === 0;
+}

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

@@ -0,0 +1,73 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { runRecallNavigateAccess } from "./recall-navigate-access.js";
+import type { RecallNavNode } from "./recall-navigate.js";
+
+function node(extra: Partial<RecallNavNode> = {}): RecallNavNode {
+  return {
+    id: "m1",
+    disclosure: "chunk",
+    ...extra,
+  };
+}
+
+test("expand re-renders the next disclosure for the given nodeId", () => {
+  const result = runRecallNavigateAccess({
+    action: "expand",
+    nodeId: "m1",
+    budget: 10,
+    node: node({ payloads: { section: "full section body" } }),
+  });
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+  assert.deepEqual(result.result, {
+    status: "ok",
+    node: { id: "m1", disclosure: "section", text: "full section body" },
+  });
+});
+
+test("traverse returns typed neighbors for the given nodeId", () => {
+  const result = runRecallNavigateAccess({
+    action: "traverse",
+    nodeId: "m1",
+    budget: 10,
+    linkType: "contradicts",
+    node: node({
+      links: [
+        { targetId: "z-mem", linkType: "contradicts" },
+        { targetId: "a-mem", linkType: "contradicts" },
+        { targetId: "skip-me", linkType: "supports" },
+      ],
+    }),
+  });
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+  assert.equal(result.result.status, "ok");
+  if (result.result.status !== "ok") return;
+  assert.ok("neighbors" in result.result);
+  assert.deepEqual(
+    result.result.neighbors.map((row) => row.id),
+    ["a-mem", "z-mem"],
+  );
+});
+
+test("budget 0 is exhausted before any expand or traverse", () => {
+  const result = runRecallNavigateAccess({
+    action: "expand",
+    nodeId: "m1",
+    budget: 0,
+    node: node({ payloads: { section: "full section body" } }),
+  });
+  assert.deepEqual(result, { ok: false, error: "budget_exhausted" });
+});
+
+test("unknown action is rejected", () => {
+  const result = runRecallNavigateAccess({
+    action: "zoom",
+    nodeId: "m1",
+    budget: 10,
+    node: node(),
+  });
+  assert.deepEqual(result, { ok: false, error: "unknown_action" });
+});

package/src/recall-navigate-access.ts

@@ -0,0 +1,48 @@
+/**
+ * Recall navigation access wrapper (issue #1956 leftover slice).
+ *
+ * Validates the request, gates the budget, and delegates to the pure
+ * helpers in recall-navigate.ts. Never calls orchestrator.recall — the
+ * caller supplies the node for `nodeId`.
+ */
+import {
+  expandRecallNode,
+  traverseRecallLink,
+  type RecallNavExpandResult,
+  type RecallNavNode,
+  type RecallNavTraverseResult,
+} from "./recall-navigate.js";
+
+export type RecallNavigateAccessAction = "expand" | "traverse";
+
+export interface RecallNavigateAccessRequest {
+  action: string;
+  nodeId: string;
+  budget: number;
+  node?: RecallNavNode;
+  linkType?: string;
+}
+
+export type RecallNavigateAccessResult =
+  | { ok: true; result: RecallNavExpandResult | RecallNavTraverseResult }
+  | { ok: false; error: "budget_exhausted" | "unknown_action" | "node_not_found" };
+
+export function runRecallNavigateAccess(request: RecallNavigateAccessRequest): RecallNavigateAccessResult {
+  if (request.action !== "expand" && request.action !== "traverse") {
+    return { ok: false, error: "unknown_action" };
+  }
+  if (!Number.isFinite(request.budget) || request.budget <= 0) {
+    return { ok: false, error: "budget_exhausted" };
+  }
+  const node = request.node;
+  if (node === undefined || node.id !== request.nodeId) {
+    return { ok: false, error: "node_not_found" };
+  }
+  if (request.action === "expand") {
+    return { ok: true, result: expandRecallNode(node, { budget: request.budget }) };
+  }
+  return {
+    ok: true,
+    result: traverseRecallLink(node, request.linkType ?? "", { budget: request.budget }),
+  };
+}

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

@@ -0,0 +1,32 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseNavigateAction } from "./recall-navigate-action.js";
+
+test("expand is allowed", () => {
+  assert.deepEqual(parseNavigateAction("expand"), {
+    ok: true,
+    action: "expand",
+  });
+});
+
+test("traverse is allowed", () => {
+  assert.deepEqual(parseNavigateAction("traverse"), {
+    ok: true,
+    action: "traverse",
+  });
+});
+
+test("unknown action is unknown_action", () => {
+  assert.deepEqual(parseNavigateAction("refine"), {
+    ok: false,
+    error: "unknown_action",
+  });
+});
+
+test("empty action is unknown_action", () => {
+  assert.deepEqual(parseNavigateAction(""), {
+    ok: false,
+    error: "unknown_action",
+  });
+});

package/src/recall-navigate-action.ts

@@ -0,0 +1,20 @@
+/**
+ * Recall navigation action parse (issue #1956 leftover).
+ *
+ * Pure. Surfaces wait. Unknown or empty is unknown_action.
+ */
+
+const NAVIGATE_ACTIONS = ["expand", "traverse"] as const;
+
+export type NavigateAction = (typeof NAVIGATE_ACTIONS)[number];
+
+export type ParseNavigateActionResult =
+  | { ok: true; action: NavigateAction }
+  | { ok: false; error: "unknown_action" };
+
+export function parseNavigateAction(value: string): ParseNavigateActionResult {
+  if ((NAVIGATE_ACTIONS as readonly string[]).includes(value)) {
+    return { ok: true, action: value as NavigateAction };
+  }
+  return { ok: false, error: "unknown_action" };
+}

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

@@ -0,0 +1,23 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { takeNavigateBudget } from "./recall-navigate-budget.js";
+
+test("budget 0 is exhausted", () => {
+  assert.deepEqual(takeNavigateBudget(0, 0), { ok: false, error: "budget_exhausted" });
+  assert.deepEqual(takeNavigateBudget(0, 1), { ok: false, error: "budget_exhausted" });
+});
+
+test("cost above budget is exhausted", () => {
+  assert.deepEqual(takeNavigateBudget(3, 4), { ok: false, error: "budget_exhausted" });
+});
+
+test("remaining is budget minus cost", () => {
+  assert.deepEqual(takeNavigateBudget(5, 2), { ok: true, remaining: 3 });
+  assert.deepEqual(takeNavigateBudget(4, 4), { ok: true, remaining: 0 });
+});
+
+test("negative budget or cost throws", () => {
+  assert.throws(() => takeNavigateBudget(-1, 0));
+  assert.throws(() => takeNavigateBudget(3, -1));
+});

package/src/recall-navigate-budget.ts

@@ -0,0 +1,22 @@
+/**
+ * Recall navigation budget take (issue #1956 leftover).
+ *
+ * Pure. Surfaces wait. Budget 0 or cost above budget is exhausted.
+ * Negative budget or cost throws.
+ */
+
+export type NavigateBudgetResult =
+  | { ok: true; remaining: number }
+  | { ok: false; error: "budget_exhausted" };
+
+export function takeNavigateBudget(budget: number, cost: number): NavigateBudgetResult {
+  if (budget < 0 || cost < 0) {
+    throw new Error(
+      `navigate budget and cost must be non-negative; got budget=${JSON.stringify(budget)} cost=${JSON.stringify(cost)}`,
+    );
+  }
+  if (budget === 0 || cost > budget) {
+    return { ok: false, error: "budget_exhausted" };
+  }
+  return { ok: true, remaining: budget - cost };
+}

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

@@ -0,0 +1,20 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseNavigateCost } from "./recall-navigate-cost.js";
+
+test("cost 0 is allowed", () => {
+  assert.equal(parseNavigateCost(0), 0);
+});
+
+test("cost 2 is returned", () => {
+  assert.equal(parseNavigateCost(2), 2);
+});
+
+test("negative cost throws", () => {
+  assert.throws(() => parseNavigateCost(-1), /non-negative integer/);
+});
+
+test("float cost throws", () => {
+  assert.throws(() => parseNavigateCost(1.5), /non-negative integer/);
+});

package/src/recall-navigate-cost.ts

@@ -0,0 +1,13 @@
+/**
+ * Recall navigation cost parse (issue #1956 leftover).
+ *
+ * Pure. Surfaces wait. 0 is allowed. Negative or non-integer throws.
+ */
+export function parseNavigateCost(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value) || value < 0) {
+    throw new Error(
+      `navigate cost must be a non-negative integer; got ${JSON.stringify(value)}`,
+    );
+  }
+  return value;
+}

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

@@ -0,0 +1,20 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseNavigateDepth } from "./recall-navigate-depth.js";
+
+test("depth 0 is allowed", () => {
+  assert.equal(parseNavigateDepth(0), 0);
+});
+
+test("depth 3 is returned", () => {
+  assert.equal(parseNavigateDepth(3), 3);
+});
+
+test("negative depth throws", () => {
+  assert.throws(() => parseNavigateDepth(-1), /non-negative integer/);
+});
+
+test("float depth throws", () => {
+  assert.throws(() => parseNavigateDepth(1.5), /non-negative integer/);
+});

package/src/recall-navigate-depth.ts

@@ -0,0 +1,13 @@
+/**
+ * Recall navigation depth parse (issue #1956 leftover).
+ *
+ * Pure. Surfaces wait. 0 is allowed. Negative or non-integer throws.
+ */
+export function parseNavigateDepth(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value) || value < 0) {
+    throw new Error(
+      `navigate depth must be a non-negative integer; got ${JSON.stringify(value)}`,
+    );
+  }
+  return value;
+}

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

@@ -0,0 +1,19 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseNavigateLinkType } from "./recall-navigate-link.js";
+
+test("parses each allowed link type", () => {
+  for (const type of ["supports", "contradicts", "elaborates", "causes", "caused_by"] as const) {
+    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" });
+});
+
+test("empty link is unknown_link", () => {
+  assert.deepEqual(parseNavigateLinkType(""), { ok: false, error: "unknown_link" });
+});

package/src/recall-navigate-link.ts

@@ -0,0 +1,26 @@
+/**
+ * Recall navigation link-type parse (issue #1956 leftover).
+ *
+ * Pure. Surfaces wait. Unknown or empty is unknown_link.
+ */
+
+const NAVIGATE_LINK_TYPES = [
+  "supports",
+  "contradicts",
+  "elaborates",
+  "causes",
+  "caused_by",
+] as const;
+
+export type NavigateLinkType = (typeof NAVIGATE_LINK_TYPES)[number];
+
+export type ParseNavigateLinkTypeResult =
+  | { ok: true; type: NavigateLinkType }
+  | { ok: false; error: "unknown_link" };
+
+export function parseNavigateLinkType(value: string): ParseNavigateLinkTypeResult {
+  if ((NAVIGATE_LINK_TYPES as readonly string[]).includes(value)) {
+    return { ok: true, type: value as NavigateLinkType };
+  }
+  return { ok: false, error: "unknown_link" };
+}

package/src/recall-navigate-max-children.test.ts

@@ -0,0 +1,20 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseMaxChildren } from "./recall-navigate-max-children.js";
+
+test("max children 0 is allowed", () => {
+  assert.equal(parseMaxChildren(0), 0);
+});
+
+test("max children 10 is returned", () => {
+  assert.equal(parseMaxChildren(10), 10);
+});
+
+test("negative max children throws", () => {
+  assert.throws(() => parseMaxChildren(-1), /non-negative integer/);
+});
+
+test("float max children throws", () => {
+  assert.throws(() => parseMaxChildren(1.5), /non-negative integer/);
+});

package/src/recall-navigate-max-children.ts

@@ -0,0 +1,13 @@
+/**
+ * Recall navigation max-children parse (issue #1956 leftover).
+ *
+ * Pure. Surfaces wait. 0 is allowed. Negative or non-integer throws.
+ */
+export function parseMaxChildren(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value) || value < 0) {
+    throw new Error(
+      `max children must be a non-negative integer; got ${JSON.stringify(value)}`,
+    );
+  }
+  return value;
+}

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

@@ -0,0 +1,21 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseNavigateNodeId } from "./recall-navigate-node.js";
+
+test("ok node id returns trimmed nodeId", () => {
+  assert.deepEqual(parseNavigateNodeId("mem-1"), { ok: true, nodeId: "mem-1" });
+});
+
+test("empty node id is missing_node", () => {
+  assert.deepEqual(parseNavigateNodeId(""), { ok: false, error: "missing_node" });
+  assert.deepEqual(parseNavigateNodeId("   "), { ok: false, error: "missing_node" });
+});
+
+test("newline in node id is invalid_node", () => {
+  assert.deepEqual(parseNavigateNodeId("mem-1\nmem-2"), { ok: false, error: "invalid_node" });
+});
+
+test("trims surrounding whitespace", () => {
+  assert.deepEqual(parseNavigateNodeId("  mem-1  "), { ok: true, nodeId: "mem-1" });
+});

package/src/recall-navigate-node.ts

@@ -0,0 +1,16 @@
+/**
+ * Recall navigation node-id parse (issue #1956 leftover).
+ *
+ * Pure. Surfaces wait. Empty is missing_node. Newline is invalid_node.
+ */
+
+export type ParseNavigateNodeIdResult =
+  | { ok: true; nodeId: string }
+  | { ok: false; error: "missing_node" | "invalid_node" };
+
+export function parseNavigateNodeId(value: string): ParseNavigateNodeIdResult {
+  const nodeId = value.trim();
+  if (nodeId.length === 0) return { ok: false, error: "missing_node" };
+  if (nodeId.includes("\n")) return { ok: false, error: "invalid_node" };
+  return { ok: true, nodeId };
+}

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

@@ -0,0 +1,21 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { isEmptyNavigatePath } from "./recall-navigate-path.js";
+
+test("null, undefined, and empty array are empty", () => {
+  assert.equal(isEmptyNavigatePath(null), true);
+  assert.equal(isEmptyNavigatePath(undefined), true);
+  assert.equal(isEmptyNavigatePath([]), true);
+});
+
+test("a non-empty array is not empty", () => {
+  assert.equal(isEmptyNavigatePath([{ id: 1 }]), false);
+  assert.equal(isEmptyNavigatePath([0]), false);
+});
+
+test("a non-array throws", () => {
+  assert.throws(() => isEmptyNavigatePath({}), TypeError);
+  assert.throws(() => isEmptyNavigatePath("nodes"), TypeError);
+  assert.throws(() => isEmptyNavigatePath(1), TypeError);
+});

package/src/recall-navigate-path.ts

@@ -0,0 +1,14 @@
+/**
+ * Empty-set guard for a recall-navigate path (issue #1956 leftover).
+ *
+ * null, undefined, and [] are empty. A non-array throws. Any other array is not empty.
+ */
+
+/** True when the navigate path is absent or has no nodes. */
+export function isEmptyNavigatePath(nodes: unknown): boolean {
+  if (nodes == null) return true;
+  if (!Array.isArray(nodes)) {
+    throw new TypeError("nodes must be an array");
+  }
+  return nodes.length === 0;
+}

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

@@ -0,0 +1,63 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { renderNavigateResult } from "./recall-navigate-render.js";
+
+test("expand empty children prints (empty)", () => {
+  assert.equal(
+    renderNavigateResult({
+      action: "expand",
+      nodeId: "m1",
+      children: [],
+      stopReason: "empty",
+    }),
+    [
+      "# Navigate",
+      "",
+      "- action: expand",
+      "- nodeId: m1",
+      "- children: (empty)",
+      "- stop: empty",
+      "",
+    ].join("\n"),
+  );
+});
+
+test("traverse path lists node ids in order", () => {
+  assert.equal(
+    renderNavigateResult({
+      action: "traverse",
+      nodeId: "m1",
+      path: ["a-mem", "z-mem"],
+      stopReason: "ok",
+    }),
+    [
+      "# Navigate",
+      "",
+      "- action: traverse",
+      "- nodeId: m1",
+      "- path: a-mem, z-mem",
+      "- stop: ok",
+      "",
+    ].join("\n"),
+  );
+});
+
+test("error prints the stop reason", () => {
+  assert.equal(
+    renderNavigateResult({
+      action: "expand",
+      nodeId: "missing",
+      stopReason: "node_not_found",
+    }),
+    [
+      "# Navigate",
+      "",
+      "- action: expand",
+      "- nodeId: missing",
+      "- children: (empty)",
+      "- stop: node_not_found",
+      "",
+    ].join("\n"),
+  );
+});

package/src/recall-navigate-render.ts

@@ -0,0 +1,31 @@
+/**
+ * Markdown renderer for a recall navigate step (issue #1956 leftover).
+ *
+ * Deterministic. Surfaces wait. Empty children prints (empty).
+ */
+
+export type NavigateResult = {
+  action: string;
+  nodeId: string;
+  children?: readonly string[];
+  path?: readonly string[];
+  stopReason: string;
+};
+
+function formatList(items: readonly string[] | undefined): string {
+  if (items === undefined || items.length === 0) return "(empty)";
+  return items.join(", ");
+}
+
+export function renderNavigateResult(result: NavigateResult): string {
+  const usePath = result.action === "traverse" || result.path !== undefined;
+  return [
+    "# Navigate",
+    "",
+    `- action: ${result.action}`,
+    `- nodeId: ${result.nodeId}`,
+    usePath ? `- path: ${formatList(result.path)}` : `- children: ${formatList(result.children)}`,
+    `- stop: ${result.stopReason}`,
+    "",
+  ].join("\n");
+}