@remnic/core 9.66.2 → 9.66.3

package/src/extraction-span-length.test.ts

@@ -0,0 +1,25 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { spanLength } from "./extraction-span-length.js";
+
+test("spanLength: empty span is zero", () => {
+  assert.equal(spanLength({ start: 0, end: 0 }), 0);
+  assert.equal(spanLength({ start: 4, end: 4 }), 0);
+});
+
+test("spanLength: mid span is half-open end-start", () => {
+  assert.equal(spanLength({ start: 1, end: 4 }), 3);
+  assert.equal(spanLength({ start: 0, end: 5 }), 5);
+  assert.equal(spanLength({ start: 4, end: 5 }), 1);
+});
+
+test("spanLength: inverted span throws", () => {
+  assert.throws(() => spanLength({ start: 3, end: 2 }), /inverted/i);
+  assert.throws(() => spanLength({ start: 1, end: 0 }), /inverted/i);
+});
+
+test("spanLength: non-integers throw", () => {
+  assert.throws(() => spanLength({ start: 1.5, end: 3 }), /integers/);
+  assert.throws(() => spanLength({ start: 0, end: 3.2 }), /integers/);
+  assert.throws(() => spanLength({ start: Number.NaN, end: 3 }), /integers/);
+});

package/src/extraction-span-length.ts

@@ -0,0 +1,16 @@
+/**
+ * Isolated span-length helper (issue #2333 leftover).
+ *
+ * Pure. Extraction wiring waits on the Phase A bench gate.
+ */
+
+export function spanLength(opts: { start: number; end: number }): number {
+  const { start, end } = opts;
+  if (!Number.isInteger(start) || !Number.isInteger(end)) {
+    throw new TypeError("span offsets must be integers");
+  }
+  if (end < start) {
+    throw new RangeError("span offsets inverted");
+  }
+  return end - start;
+}

package/src/extraction-span-overlap.test.ts

@@ -0,0 +1,34 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { spansOverlap } from "./extraction-span-overlap.js";
+
+test("spansOverlap: interior overlap is true", () => {
+  assert.equal(spansOverlap({ start: 0, end: 4 }, { start: 2, end: 6 }), true);
+  assert.equal(spansOverlap({ start: 2, end: 6 }, { start: 0, end: 4 }), true);
+  assert.equal(spansOverlap({ start: 1, end: 5 }, { start: 2, end: 3 }), true);
+});
+
+test("spansOverlap: touching at an endpoint is false", () => {
+  assert.equal(spansOverlap({ start: 0, end: 3 }, { start: 3, end: 5 }), false);
+  assert.equal(spansOverlap({ start: 3, end: 5 }, { start: 0, end: 3 }), false);
+  assert.equal(spansOverlap({ start: 1, end: 1 }, { start: 1, end: 4 }), false);
+});
+
+test("spansOverlap: disjoint spans are false", () => {
+  assert.equal(spansOverlap({ start: 0, end: 2 }, { start: 4, end: 6 }), false);
+  assert.equal(spansOverlap({ start: 4, end: 6 }, { start: 0, end: 2 }), false);
+});
+
+test("spansOverlap: inverted span throws", () => {
+  assert.throws(() => spansOverlap({ start: 3, end: 2 }, { start: 0, end: 1 }), /inverted/i);
+  assert.throws(() => spansOverlap({ start: 0, end: 1 }, { start: 5, end: 4 }), /inverted/i);
+});
+
+test("spansOverlap: non-integers throw", () => {
+  assert.throws(() => spansOverlap({ start: 1.5, end: 3 }, { start: 0, end: 1 }), /integers/);
+  assert.throws(() => spansOverlap({ start: 0, end: 3 }, { start: 1, end: 2.2 }), /integers/);
+  assert.throws(
+    () => spansOverlap({ start: Number.NaN, end: 3 }, { start: 0, end: 1 }),
+    /integers/,
+  );
+});

package/src/extraction-span-overlap.ts

@@ -0,0 +1,23 @@
+/**
+ * Isolated span-overlap helper (issue #2333 leftover).
+ *
+ * Pure. Extraction wiring waits on the Phase A bench gate.
+ */
+
+export function spansOverlap(
+  a: { start: number; end: number },
+  b: { start: number; end: number },
+): boolean {
+  if (
+    !Number.isInteger(a.start) ||
+    !Number.isInteger(a.end) ||
+    !Number.isInteger(b.start) ||
+    !Number.isInteger(b.end)
+  ) {
+    throw new TypeError("span offsets must be integers");
+  }
+  if (a.end < a.start || b.end < b.start) {
+    throw new RangeError("span offsets inverted");
+  }
+  return a.start < b.end && b.start < a.end;
+}

package/src/extraction-span-shift.test.ts

@@ -0,0 +1,25 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { shiftSpan } from "./extraction-span-shift.js";
+
+test("shiftSpan: +delta", () => {
+  assert.deepEqual(shiftSpan({ start: 1, end: 4, delta: 3 }), { start: 4, end: 7 });
+  assert.deepEqual(shiftSpan({ start: 0, end: 0, delta: 5 }), { start: 5, end: 5 });
+});
+
+test("shiftSpan: -delta", () => {
+  assert.deepEqual(shiftSpan({ start: 5, end: 8, delta: -2 }), { start: 3, end: 6 });
+  assert.deepEqual(shiftSpan({ start: 2, end: 2, delta: -2 }), { start: 0, end: 0 });
+});
+
+test("shiftSpan: inverted span throws", () => {
+  assert.throws(() => shiftSpan({ start: 3, end: 2, delta: 1 }), /inverted/i);
+  assert.throws(() => shiftSpan({ start: 1, end: 0, delta: 0 }), /inverted/i);
+});
+
+test("shiftSpan: non-integers throw", () => {
+  assert.throws(() => shiftSpan({ start: 1.5, end: 3, delta: 1 }), /integers/);
+  assert.throws(() => shiftSpan({ start: 0, end: 3.2, delta: 1 }), /integers/);
+  assert.throws(() => shiftSpan({ start: 0, end: 3, delta: 1.5 }), /integers/);
+  assert.throws(() => shiftSpan({ start: Number.NaN, end: 3, delta: 0 }), /integers/);
+});

package/src/extraction-span-shift.ts

@@ -0,0 +1,20 @@
+/**
+ * Isolated span-shift helper (issue #2333 leftover).
+ *
+ * Pure. Extraction wiring waits on the Phase A bench gate.
+ */
+
+export function shiftSpan(opts: {
+  start: number;
+  end: number;
+  delta: number;
+}): { start: number; end: number } {
+  const { start, end, delta } = opts;
+  if (!Number.isInteger(start) || !Number.isInteger(end) || !Number.isInteger(delta)) {
+    throw new TypeError("span offsets must be integers");
+  }
+  if (end < start) {
+    throw new RangeError("span offsets inverted");
+  }
+  return { start: start + delta, end: end + delta };
+}

package/src/extraction-span-slice.test.ts

@@ -0,0 +1,32 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { sliceSpanText } from "./extraction-span-slice.js";
+
+const TEXT = "hello";
+
+test("sliceSpanText: empty span is empty string", () => {
+  assert.equal(sliceSpanText({ text: TEXT, start: 2, end: 2 }), "");
+  assert.equal(sliceSpanText({ text: TEXT, start: 0, end: 0 }), "");
+  assert.equal(sliceSpanText({ text: TEXT, start: TEXT.length, end: TEXT.length }), "");
+  assert.equal(sliceSpanText({ text: "", start: 0, end: 0 }), "");
+});
+
+test("sliceSpanText: mid span is half-open [start, end)", () => {
+  assert.equal(sliceSpanText({ text: TEXT, start: 1, end: 4 }), "ell");
+  assert.equal(sliceSpanText({ text: TEXT, start: 0, end: 5 }), "hello");
+  assert.equal(sliceSpanText({ text: TEXT, start: 0, end: 1 }), "h");
+  assert.equal(sliceSpanText({ text: TEXT, start: 4, end: 5 }), "o");
+});
+
+test("sliceSpanText: out of range throws", () => {
+  assert.throws(() => sliceSpanText({ text: TEXT, start: -1, end: 2 }), /out of range/i);
+  assert.throws(() => sliceSpanText({ text: TEXT, start: 0, end: 6 }), /out of range/i);
+  assert.throws(() => sliceSpanText({ text: TEXT, start: 3, end: 2 }), /out of range/i);
+  assert.throws(() => sliceSpanText({ text: TEXT, start: 6, end: 6 }), /out of range/i);
+});
+
+test("sliceSpanText: non-integers throw", () => {
+  assert.throws(() => sliceSpanText({ text: TEXT, start: 1.5, end: 3 }), /integers/);
+  assert.throws(() => sliceSpanText({ text: TEXT, start: 0, end: 3.2 }), /integers/);
+  assert.throws(() => sliceSpanText({ text: TEXT, start: Number.NaN, end: 3 }), /integers/);
+});

package/src/extraction-span-slice.ts

@@ -0,0 +1,20 @@
+/**
+ * Isolated span slicer (issue #2333 leftover).
+ *
+ * Pure. Extraction wiring waits on the Phase A bench gate.
+ */
+
+export function sliceSpanText(opts: {
+  text: string;
+  start: number;
+  end: number;
+}): string {
+  const { text, start, end } = opts;
+  if (!Number.isInteger(start) || !Number.isInteger(end)) {
+    throw new TypeError("span offsets must be integers");
+  }
+  if (start < 0 || end < start || end > text.length) {
+    throw new RangeError("span offsets out of range");
+  }
+  return text.slice(start, end);
+}

package/src/extraction-span-validate.test.ts

@@ -0,0 +1,42 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { validateSpanOffsets } from "./extraction-span-validate.js";
+
+test("validateSpanOffsets: empty span", () => {
+  assert.deepEqual(validateSpanOffsets({ start: 0, end: 0, textLength: 5 }), {
+    ok: false,
+    error: "empty",
+  });
+  assert.deepEqual(validateSpanOffsets({ start: 3, end: 3, textLength: 8 }), {
+    ok: false,
+    error: "empty",
+  });
+});
+
+test("validateSpanOffsets: out of range", () => {
+  assert.deepEqual(validateSpanOffsets({ start: -1, end: 2, textLength: 8 }), {
+    ok: false,
+    error: "out_of_range",
+  });
+  assert.deepEqual(validateSpanOffsets({ start: 5, end: 3, textLength: 8 }), {
+    ok: false,
+    error: "out_of_range",
+  });
+  assert.deepEqual(validateSpanOffsets({ start: 0, end: 9, textLength: 8 }), {
+    ok: false,
+    error: "out_of_range",
+  });
+});
+
+test("validateSpanOffsets: ok half-open span", () => {
+  assert.deepEqual(validateSpanOffsets({ start: 0, end: 5, textLength: 8 }), { ok: true });
+  assert.deepEqual(validateSpanOffsets({ start: 0, end: 8, textLength: 8 }), { ok: true });
+  assert.deepEqual(validateSpanOffsets({ start: 7, end: 8, textLength: 8 }), { ok: true });
+});
+
+test("validateSpanOffsets: non-integers throw", () => {
+  assert.throws(() => validateSpanOffsets({ start: 1.5, end: 3, textLength: 8 }), /integers/);
+  assert.throws(() => validateSpanOffsets({ start: 0, end: 3.2, textLength: 8 }), /integers/);
+  assert.throws(() => validateSpanOffsets({ start: 0, end: 3, textLength: 8.1 }), /integers/);
+  assert.throws(() => validateSpanOffsets({ start: Number.NaN, end: 3, textLength: 8 }), /integers/);
+});

package/src/extraction-span-validate.ts

@@ -0,0 +1,27 @@
+/**
+ * Isolated span-offset validator (issue #2333 leftover).
+ *
+ * Pure. Extraction wiring waits on the Phase A bench gate.
+ */
+
+export type SpanValidateOk = { ok: true };
+export type SpanValidateErr = { ok: false; error: "out_of_range" | "empty" };
+export type SpanValidateResult = SpanValidateOk | SpanValidateErr;
+
+export function validateSpanOffsets(opts: {
+  start: number;
+  end: number;
+  textLength: number;
+}): SpanValidateResult {
+  const { start, end, textLength } = opts;
+  if (!Number.isInteger(start) || !Number.isInteger(end) || !Number.isInteger(textLength)) {
+    throw new TypeError("span offsets must be integers");
+  }
+  if (start < 0 || end < start || end > textLength) {
+    return { ok: false, error: "out_of_range" };
+  }
+  if (start === end) {
+    return { ok: false, error: "empty" };
+  }
+  return { ok: true };
+}

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