@remnic/core 9.66.1 → 9.66.3

package/src/recall-deep-access.ts

@@ -0,0 +1,71 @@
+/**
+ * Named-policy access facade for the deep-recall stepper (issue #2332 leftover).
+ *
+ * Not the hot path. Surfaces and parseConfig wait. Policy names are
+ * allow-listed. Budget 0 returns a tagged refusal without a policy call.
+ */
+
+import { runDeepRecall, type DeepRecallResult, type DeepRecallState } from "./recall-deep.js";
+
+export const DEEP_RECALL_ACCESS_POLICIES = ["stop", "expand-once"] as const;
+
+export type DeepRecallAccessPolicyName = (typeof DEEP_RECALL_ACCESS_POLICIES)[number];
+
+export interface DeepRecallAccessInput {
+  query: string;
+  budget: number;
+  policyName: string;
+}
+
+export interface DeepRecallAccessRefusal {
+  tag: "budget_exhausted";
+}
+
+export interface DeepRecallAccessResult {
+  ok: boolean;
+  refusal?: DeepRecallAccessRefusal;
+  state: DeepRecallState;
+  trace: DeepRecallResult["trace"];
+  traceJson: string;
+}
+
+export function isDeepRecallAccessPolicyName(value: unknown): value is DeepRecallAccessPolicyName {
+  return typeof value === "string" && (DEEP_RECALL_ACCESS_POLICIES as readonly string[]).includes(value);
+}
+
+export function runDeepRecallAccess(input: DeepRecallAccessInput): DeepRecallAccessResult {
+  if (!isDeepRecallAccessPolicyName(input.policyName)) {
+    throw new Error(
+      `unknown deep recall access policy: ${JSON.stringify(input.policyName)}. Valid: ${DEEP_RECALL_ACCESS_POLICIES.join(", ")}`,
+    );
+  }
+
+  const start: DeepRecallState = { query: input.query, workingSet: [], frontier: [], budget: input.budget };
+  if (!Number.isFinite(input.budget) || input.budget <= 0) {
+    const result = runDeepRecall(start, () => {
+      throw new Error("policy must not run when budget is 0");
+    });
+    return {
+      ok: false,
+      refusal: { tag: "budget_exhausted" },
+      state: result.state,
+      trace: result.trace,
+      traceJson: JSON.stringify(result.trace),
+    };
+  }
+
+  let expanded = false;
+  const result = runDeepRecall(start, () => {
+    if (input.policyName === "expand-once" && !expanded) {
+      expanded = true;
+      return "expand";
+    }
+    return "stop";
+  });
+  return {
+    ok: true,
+    state: result.state,
+    trace: result.trace,
+    traceJson: JSON.stringify(result.trace),
+  };
+}

package/src/recall-deep-budget-left.test.ts

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

package/src/recall-deep-budget-left.ts

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

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

@@ -0,0 +1,19 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { clampDeepRecallBudget } from "./recall-deep-budget.js";
+
+test("budget 0 stays 0", () => {
+  assert.equal(clampDeepRecallBudget(0), 0);
+});
+
+test("budget 3 stays 3", () => {
+  assert.equal(clampDeepRecallBudget(3), 3);
+});
+
+test("invalid budget throws", () => {
+  assert.throws(() => clampDeepRecallBudget(-1), /non-negative integer/);
+  assert.throws(() => clampDeepRecallBudget(1.5), /non-negative integer/);
+  assert.throws(() => clampDeepRecallBudget(Number.NaN), /non-negative integer/);
+  assert.throws(() => clampDeepRecallBudget(Number.POSITIVE_INFINITY), /non-negative integer/);
+});

package/src/recall-deep-budget.ts

@@ -0,0 +1,14 @@
+/**
+ * Deep-recall budget clamp (issue #2332 leftover).
+ *
+ * Pure. Surfaces wait. 0 stays 0. Positive integers pass through.
+ * Negative, non-finite, and non-integer values throw.
+ */
+export function clampDeepRecallBudget(n: number): number {
+  if (!Number.isFinite(n) || !Number.isInteger(n) || n < 0) {
+    throw new Error(
+      `deep recall budget must be a non-negative integer; got ${JSON.stringify(n)}`,
+    );
+  }
+  return n;
+}

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

@@ -0,0 +1,23 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { mayExpandOnce } from "./recall-deep-expand.js";
+
+test("already expanded is false", () => {
+  assert.equal(mayExpandOnce({ alreadyExpanded: true, budgetLeft: 3 }), false);
+});
+
+test("budget 0 is false", () => {
+  assert.equal(mayExpandOnce({ alreadyExpanded: false, budgetLeft: 0 }), false);
+});
+
+test("ok is true", () => {
+  assert.equal(mayExpandOnce({ alreadyExpanded: false, budgetLeft: 3 }), true);
+});
+
+test("negative budget throws", () => {
+  assert.throws(
+    () => mayExpandOnce({ alreadyExpanded: false, budgetLeft: -1 }),
+    /negative/,
+  );
+});

package/src/recall-deep-expand.ts

@@ -0,0 +1,19 @@
+/**
+ * Deep-recall one-shot expand gate (issue #2332 leftover).
+ *
+ * Pure. Surfaces wait. Already expanded or budget 0 refuse.
+ * Negative budget throws.
+ */
+export function mayExpandOnce(input: {
+  alreadyExpanded: boolean;
+  budgetLeft: number;
+}): boolean {
+  if (input.budgetLeft < 0) {
+    throw new Error(
+      `deep recall expand budget must not be negative; got ${JSON.stringify(input.budgetLeft)}`,
+    );
+  }
+  if (input.alreadyExpanded) return false;
+  if (input.budgetLeft === 0) return false;
+  return true;
+}

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

@@ -0,0 +1,32 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseDeepPolicyName } from "./recall-deep-policy.js";
+
+test("stop is allowed", () => {
+  assert.deepEqual(parseDeepPolicyName("stop"), {
+    ok: true,
+    policy: "stop",
+  });
+});
+
+test("expand-once is allowed", () => {
+  assert.deepEqual(parseDeepPolicyName("expand-once"), {
+    ok: true,
+    policy: "expand-once",
+  });
+});
+
+test("unknown policy is unknown_policy", () => {
+  assert.deepEqual(parseDeepPolicyName("refine-twice"), {
+    ok: false,
+    error: "unknown_policy",
+  });
+});
+
+test("empty policy is unknown_policy", () => {
+  assert.deepEqual(parseDeepPolicyName(""), {
+    ok: false,
+    error: "unknown_policy",
+  });
+});

package/src/recall-deep-policy.ts

@@ -0,0 +1,22 @@
+/**
+ * Parse a deep-recall policy name (issue #2332 leftover).
+ *
+ * Pure. Surfaces wait. Unknown or empty values fail closed.
+ */
+export const DEEP_POLICY_NAMES = ["stop", "expand-once"] as const;
+
+export type DeepPolicyName = (typeof DEEP_POLICY_NAMES)[number];
+
+export type ParseDeepPolicyNameResult =
+  | { ok: true; policy: DeepPolicyName }
+  | { ok: false; error: "unknown_policy" };
+
+export function parseDeepPolicyName(value: unknown): ParseDeepPolicyNameResult {
+  if (typeof value !== "string" || value.length === 0) {
+    return { ok: false, error: "unknown_policy" };
+  }
+  if (!(DEEP_POLICY_NAMES as readonly string[]).includes(value)) {
+    return { ok: false, error: "unknown_policy" };
+  }
+  return { ok: true, policy: value as DeepPolicyName };
+}

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

@@ -0,0 +1,23 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseDeepQuery } from "./recall-deep-query.js";
+
+test("query is returned", () => {
+  assert.deepEqual(parseDeepQuery("what happened"), {
+    ok: true,
+    query: "what happened",
+  });
+});
+
+test("empty query is empty_query", () => {
+  assert.deepEqual(parseDeepQuery(""), { ok: false, error: "empty_query" });
+  assert.deepEqual(parseDeepQuery("   "), { ok: false, error: "empty_query" });
+});
+
+test("query is trimmed", () => {
+  assert.deepEqual(parseDeepQuery("  what happened  "), {
+    ok: true,
+    query: "what happened",
+  });
+});

package/src/recall-deep-query.ts

@@ -0,0 +1,15 @@
+/**
+ * Parse a deep-recall query (issue #2332 leftover).
+ *
+ * Pure. Surfaces wait. Trim. Empty is empty_query.
+ */
+
+export type ParseDeepQueryResult =
+  | { ok: true; query: string }
+  | { ok: false; error: "empty_query" };
+
+export function parseDeepQuery(value: string): ParseDeepQueryResult {
+  const query = value.trim();
+  if (query.length === 0) return { ok: false, error: "empty_query" };
+  return { ok: true, query };
+}

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

@@ -0,0 +1,23 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { mayRefine } from "./recall-deep-refine.js";
+
+test("refined is false", () => {
+  assert.equal(mayRefine({ refined: true, budgetLeft: 3 }), false);
+});
+
+test("budget 0 is false", () => {
+  assert.equal(mayRefine({ refined: false, budgetLeft: 0 }), false);
+});
+
+test("ok is true", () => {
+  assert.equal(mayRefine({ refined: false, budgetLeft: 3 }), true);
+});
+
+test("negative budget throws", () => {
+  assert.throws(
+    () => mayRefine({ refined: false, budgetLeft: -1 }),
+    /negative/,
+  );
+});

package/src/recall-deep-refine.ts

@@ -0,0 +1,19 @@
+/**
+ * Deep-recall one-shot refine gate (issue #2332 leftover).
+ *
+ * Pure. Surfaces wait. Already refined or budget 0 refuse.
+ * Negative budget throws.
+ */
+export function mayRefine(input: {
+  refined: boolean;
+  budgetLeft: number;
+}): boolean {
+  if (input.budgetLeft < 0) {
+    throw new Error(
+      `deep recall refine budget must not be negative; got ${JSON.stringify(input.budgetLeft)}`,
+    );
+  }
+  if (input.refined) return false;
+  if (input.budgetLeft === 0) return false;
+  return true;
+}

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

@@ -0,0 +1,68 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  runDeepRecall,
+  type DeepRecallState,
+} from "./recall-deep.js";
+import { renderDeepRecallTrace } from "./recall-deep-render.js";
+
+function seed(extra: Partial<DeepRecallState> = {}): DeepRecallState {
+  return {
+    query: "who met at the cafe",
+    workingSet: [],
+    frontier: ["m-b", "m-c"],
+    budget: 2,
+    ...extra,
+  };
+}
+
+test("empty working set prints (empty)", () => {
+  const result = runDeepRecall(seed({ budget: 0 }), () => {
+    throw new Error("policy must not run when budget is 0");
+  });
+  assert.equal(
+    renderDeepRecallTrace(result),
+    [
+      "# Deep recall",
+      "",
+      "- query: who met at the cafe",
+      "- budget: 0",
+      "- stop: budget exhausted",
+      "",
+      "## Steps",
+      "",
+      "1. stop budget=0 workingSet=(empty) frontier=m-b, m-c",
+      "",
+    ].join("\n"),
+  );
+});
+
+test("expand then stop snapshot", () => {
+  const result = runDeepRecall(seed({ workingSet: ["m-seed"], budget: 2 }), (state) =>
+    state.workingSet.includes("m-b") ? "stop" : "expand",
+  );
+  assert.equal(
+    renderDeepRecallTrace(result),
+    [
+      "# Deep recall",
+      "",
+      "- query: who met at the cafe",
+      "- budget: 1",
+      "- stop: stop",
+      "",
+      "## Steps",
+      "",
+      "1. expand budget=1 workingSet=m-seed, m-b frontier=m-c",
+      "2. stop budget=1 workingSet=m-seed, m-b frontier=m-c",
+      "",
+    ].join("\n"),
+  );
+});
+
+test("same result renders the same bytes", () => {
+  const policy = () => "stop";
+  const first = renderDeepRecallTrace(runDeepRecall(seed({ budget: 3 }), policy));
+  const second = renderDeepRecallTrace(runDeepRecall(seed({ budget: 3 }), policy));
+  assert.equal(first, second);
+});

package/src/recall-deep-render.ts

@@ -0,0 +1,32 @@
+/**
+ * Markdown renderer for a deep-recall trace (issue #2332 leftover).
+ *
+ * Deterministic. Surfaces wait. Empty working set prints (empty).
+ */
+
+import type { DeepRecallResult } from "./recall-deep.js";
+
+export function renderDeepRecallTrace(result: DeepRecallResult): string {
+  const last = result.trace[result.trace.length - 1];
+  const stop = !last ? "none" : last.budget <= 0 ? "budget exhausted" : last.action;
+  const steps =
+    result.trace.length === 0
+      ? ["(empty)"]
+      : result.trace.map((step, index) => {
+          const workingSet = step.workingSet.length === 0 ? "(empty)" : step.workingSet.join(", ");
+          const frontier = step.frontier.length === 0 ? "(empty)" : step.frontier.join(", ");
+          return `${index + 1}. ${step.action} budget=${step.budget} workingSet=${workingSet} frontier=${frontier}`;
+        });
+  return [
+    "# Deep recall",
+    "",
+    `- query: ${result.state.query}`,
+    `- budget: ${result.state.budget}`,
+    `- stop: ${stop}`,
+    "",
+    "## Steps",
+    "",
+    ...steps,
+    "",
+  ].join("\n");
+}

package/src/recall-deep-step-count.test.ts

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

package/src/recall-deep-step-count.ts

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

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

@@ -0,0 +1,46 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseDeepStopReason } from "./recall-deep-stop-reason.js";
+
+test("budget_exhausted is allowed", () => {
+  assert.deepEqual(parseDeepStopReason("budget_exhausted"), {
+    ok: true,
+    reason: "budget_exhausted",
+  });
+});
+
+test("policy_stop is allowed", () => {
+  assert.deepEqual(parseDeepStopReason("policy_stop"), {
+    ok: true,
+    reason: "policy_stop",
+  });
+});
+
+test("expand_once is allowed", () => {
+  assert.deepEqual(parseDeepStopReason("expand_once"), {
+    ok: true,
+    reason: "expand_once",
+  });
+});
+
+test("refine_done is allowed", () => {
+  assert.deepEqual(parseDeepStopReason("refine_done"), {
+    ok: true,
+    reason: "refine_done",
+  });
+});
+
+test("unknown reason is unknown_reason", () => {
+  assert.deepEqual(parseDeepStopReason("stop"), {
+    ok: false,
+    error: "unknown_reason",
+  });
+});
+
+test("empty reason is unknown_reason", () => {
+  assert.deepEqual(parseDeepStopReason(""), {
+    ok: false,
+    error: "unknown_reason",
+  });
+});

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

@@ -0,0 +1,27 @@
+/**
+ * Parse a deep-recall stop reason (issue #2332 leftover).
+ *
+ * Pure. Surfaces wait. Unknown or empty values fail closed.
+ */
+export const DEEP_STOP_REASONS = [
+  "budget_exhausted",
+  "policy_stop",
+  "expand_once",
+  "refine_done",
+] as const;
+
+export type DeepStopReason = (typeof DEEP_STOP_REASONS)[number];
+
+export type ParseDeepStopReasonResult =
+  | { ok: true; reason: DeepStopReason }
+  | { ok: false; error: "unknown_reason" };
+
+export function parseDeepStopReason(value: unknown): ParseDeepStopReasonResult {
+  if (typeof value !== "string" || value.length === 0) {
+    return { ok: false, error: "unknown_reason" };
+  }
+  if (!(DEEP_STOP_REASONS as readonly string[]).includes(value)) {
+    return { ok: false, error: "unknown_reason" };
+  }
+  return { ok: true, reason: value as DeepStopReason };
+}

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