@remnic/core 9.66.1 → 9.66.3

package/src/extraction-span-clip.ts

@@ -0,0 +1,26 @@
+/**
+ * Isolated span clipper (issue #2333 leftover).
+ *
+ * Pure. Extraction wiring waits on the Phase A bench gate.
+ */
+
+export type SpanClipOk = { ok: true; start: number; end: number };
+export type SpanClipErr = { ok: false; error: "empty" };
+export type SpanClipResult = SpanClipOk | SpanClipErr;
+
+export function clipSpan(opts: {
+  start: number;
+  end: number;
+  textLength: number;
+}): SpanClipResult {
+  const { start, end, textLength } = opts;
+  if (!Number.isInteger(start) || !Number.isInteger(end) || !Number.isInteger(textLength)) {
+    throw new TypeError("span offsets must be integers");
+  }
+  const clippedStart = Math.max(0, Math.min(start, textLength));
+  const clippedEnd = Math.max(0, Math.min(end, textLength));
+  if (clippedStart >= clippedEnd) {
+    return { ok: false, error: "empty" };
+  }
+  return { ok: true, start: clippedStart, end: clippedEnd };
+}

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

@@ -0,0 +1,30 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { spanContainsOffset } from "./extraction-span-contains.js";
+
+test("spanContainsOffset: inside is true", () => {
+  assert.equal(spanContainsOffset({ start: 1, end: 4, offset: 2 }), true);
+  assert.equal(spanContainsOffset({ start: 1, end: 4, offset: 3 }), true);
+});
+
+test("spanContainsOffset: start is inclusive", () => {
+  assert.equal(spanContainsOffset({ start: 1, end: 4, offset: 1 }), true);
+  assert.equal(spanContainsOffset({ start: 0, end: 5, offset: 0 }), true);
+});
+
+test("spanContainsOffset: end is exclusive", () => {
+  assert.equal(spanContainsOffset({ start: 1, end: 4, offset: 4 }), false);
+  assert.equal(spanContainsOffset({ start: 0, end: 5, offset: 5 }), false);
+});
+
+test("spanContainsOffset: inverted span throws", () => {
+  assert.throws(() => spanContainsOffset({ start: 3, end: 2, offset: 2 }), /inverted/i);
+  assert.throws(() => spanContainsOffset({ start: 1, end: 0, offset: 0 }), /inverted/i);
+});
+
+test("spanContainsOffset: non-integers throw", () => {
+  assert.throws(() => spanContainsOffset({ start: 1.5, end: 3, offset: 2 }), /integers/);
+  assert.throws(() => spanContainsOffset({ start: 0, end: 3.2, offset: 1 }), /integers/);
+  assert.throws(() => spanContainsOffset({ start: 0, end: 3, offset: 1.1 }), /integers/);
+  assert.throws(() => spanContainsOffset({ start: Number.NaN, end: 3, offset: 1 }), /integers/);
+});

package/src/extraction-span-contains.ts

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

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

@@ -0,0 +1,50 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { joinAdjacentSpans } from "./extraction-span-join.js";
+
+test("joinAdjacentSpans: adjacent half-open spans join", () => {
+  assert.deepEqual(joinAdjacentSpans({ start: 0, end: 3 }, { start: 3, end: 5 }), {
+    start: 0,
+    end: 5,
+  });
+  assert.deepEqual(joinAdjacentSpans({ start: 1, end: 1 }, { start: 1, end: 4 }), {
+    start: 1,
+    end: 4,
+  });
+});
+
+test("joinAdjacentSpans: gap is not_adjacent", () => {
+  assert.deepEqual(joinAdjacentSpans({ start: 0, end: 2 }, { start: 4, end: 6 }), {
+    ok: false,
+    error: "not_adjacent",
+  });
+  assert.deepEqual(joinAdjacentSpans({ start: 4, end: 6 }, { start: 0, end: 2 }), {
+    ok: false,
+    error: "not_adjacent",
+  });
+});
+
+test("joinAdjacentSpans: overlap is not_adjacent", () => {
+  assert.deepEqual(joinAdjacentSpans({ start: 0, end: 4 }, { start: 2, end: 6 }), {
+    ok: false,
+    error: "not_adjacent",
+  });
+  assert.deepEqual(joinAdjacentSpans({ start: 1, end: 5 }, { start: 2, end: 3 }), {
+    ok: false,
+    error: "not_adjacent",
+  });
+});
+
+test("joinAdjacentSpans: inverted span throws", () => {
+  assert.throws(() => joinAdjacentSpans({ start: 3, end: 2 }, { start: 0, end: 1 }), /inverted/i);
+  assert.throws(() => joinAdjacentSpans({ start: 0, end: 1 }, { start: 5, end: 4 }), /inverted/i);
+});
+
+test("joinAdjacentSpans: non-integers throw", () => {
+  assert.throws(() => joinAdjacentSpans({ start: 1.5, end: 3 }, { start: 3, end: 5 }), /integers/);
+  assert.throws(() => joinAdjacentSpans({ start: 0, end: 3 }, { start: 3, end: 5.2 }), /integers/);
+  assert.throws(
+    () => joinAdjacentSpans({ start: Number.NaN, end: 3 }, { start: 3, end: 5 }),
+    /integers/,
+  );
+});

package/src/extraction-span-join.ts

@@ -0,0 +1,30 @@
+/**
+ * Isolated span-join helper (issue #2333 leftover).
+ *
+ * Pure. Extraction wiring waits on the Phase A bench gate.
+ */
+
+export type SpanJoinOk = { start: number; end: number };
+export type SpanJoinErr = { ok: false; error: "not_adjacent" };
+export type SpanJoinResult = SpanJoinOk | SpanJoinErr;
+
+export function joinAdjacentSpans(
+  a: { start: number; end: number },
+  b: { start: number; end: number },
+): SpanJoinResult {
+  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");
+  }
+  if (a.end !== b.start) {
+    return { ok: false, error: "not_adjacent" };
+  }
+  return { start: a.start, end: b.end };
+}

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/extraction-span-wire.test.ts

@@ -0,0 +1,20 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { applySpanMode } from "./extraction-span-wire.js";
+
+const TEXT = "Alice moved to Seattle";
+
+test("applySpanMode: disabled or 0 is identity", () => {
+  const span = { text: TEXT, start: 6, end: 11 };
+  assert.deepEqual(applySpanMode({ enabled: false, ...span }), { text: TEXT });
+  assert.deepEqual(applySpanMode({ enabled: 0, ...span }), { text: TEXT });
+  assert.deepEqual(applySpanMode(span), { text: TEXT });
+});
+
+test("applySpanMode: enabled slices half-open [start, end)", () => {
+  assert.deepEqual(applySpanMode({ enabled: true, text: TEXT, start: 6, end: 11 }), {
+    text: "moved",
+    start: 6,
+    end: 11,
+  });
+});

package/src/extraction-span-wire.ts

@@ -0,0 +1,17 @@
+/**
+ * Extraction seam for span mode (issue #2333 leftover slice).
+ *
+ * Default off. Callers pass `enabled`. This module does not touch
+ * extraction.ts; Phase A still gates production wiring.
+ */
+
+import { parseSpanOffsets, type ParsedSpan } from "./extraction-span.js";
+
+export function applySpanMode(opts: {
+  enabled?: boolean | 0 | 1;
+  text: string;
+  start: number;
+  end: number;
+}): ParsedSpan {
+  return parseSpanOffsets(opts.text, { start: opts.start, end: opts.end }, opts.enabled);
+}

package/src/extraction-span.test.ts

@@ -0,0 +1,59 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { parseSpanOffsets } from "./extraction-span.js";
+
+const TEXT = "Alice moved to Seattle";
+
+test("parseSpanOffsets: disabled or 0 is identity", () => {
+  const offsets = { start: 6, end: 11 };
+  assert.deepEqual(parseSpanOffsets(TEXT, offsets, false), { text: TEXT });
+  assert.deepEqual(parseSpanOffsets(TEXT, offsets, 0), { text: TEXT });
+  assert.deepEqual(parseSpanOffsets(TEXT, offsets), { text: TEXT });
+});
+
+test("parseSpanOffsets: enabled slices half-open [start, end)", () => {
+  assert.deepEqual(parseSpanOffsets(TEXT, { start: 6, end: 11 }, true), {
+    text: "moved",
+    start: 6,
+    end: 11,
+  });
+});
+
+test("parseSpanOffsets: boundary offsets stay inside the string", () => {
+  assert.deepEqual(parseSpanOffsets(TEXT, { start: 0, end: TEXT.length }, true), {
+    text: TEXT,
+    start: 0,
+    end: TEXT.length,
+  });
+  assert.deepEqual(parseSpanOffsets(TEXT, { start: 0, end: 1 }, true), {
+    text: "A",
+    start: 0,
+    end: 1,
+  });
+  assert.deepEqual(parseSpanOffsets(TEXT, { start: TEXT.length - 1, end: TEXT.length }, true), {
+    text: "e",
+    start: TEXT.length - 1,
+    end: TEXT.length,
+  });
+});
+
+test("parseSpanOffsets: reversed and out-of-range offsets reject", () => {
+  assert.throws(() => parseSpanOffsets(TEXT, { start: 12, end: 6 }, true), /reversed|out of range|invalid span/i);
+  assert.throws(() => parseSpanOffsets(TEXT, { start: -1, end: 6 }, true), /out of range|invalid span/i);
+  assert.throws(() => parseSpanOffsets(TEXT, { start: 0, end: TEXT.length + 1 }, true), /out of range|invalid span/i);
+});
+
+test("parseSpanOffsets: empty source and empty span", () => {
+  assert.deepEqual(parseSpanOffsets("", { start: 0, end: 0 }, false), { text: "" });
+  assert.deepEqual(parseSpanOffsets("", { start: 0, end: 0 }, true), {
+    text: "",
+    start: 0,
+    end: 0,
+  });
+  assert.deepEqual(parseSpanOffsets(TEXT, { start: 6, end: 6 }, true), {
+    text: "",
+    start: 6,
+    end: 6,
+  });
+  assert.throws(() => parseSpanOffsets("", { start: 0, end: 1 }, true), /out of range|invalid span/i);
+});

package/src/extraction-span.ts

@@ -0,0 +1,39 @@
+/**
+ * Isolated span-offset parser (issue #2333 first slice).
+ *
+ * Default off. Extraction wiring waits on the Phase A bench gate.
+ */
+
+export interface SpanOffsets {
+  start: number;
+  end: number;
+}
+
+export interface ParsedSpan {
+  text: string;
+  start?: number;
+  end?: number;
+}
+
+export function parseSpanOffsets(
+  text: string,
+  offsets: SpanOffsets,
+  spanModeEnabled: boolean | 0 | 1 = false,
+): ParsedSpan {
+  if (spanModeEnabled !== true && spanModeEnabled !== 1) {
+    return { text };
+  }
+
+  const { start, end } = offsets;
+  if (!Number.isInteger(start) || !Number.isInteger(end)) {
+    throw new RangeError("invalid span: out of range");
+  }
+  if (start > end) {
+    throw new RangeError("invalid span: reversed");
+  }
+  if (start < 0 || end > text.length) {
+    throw new RangeError("invalid span: out of range");
+  }
+
+  return { text: text.slice(start, end), start, end };
+}

package/src/index.ts

@@ -1458,3 +1458,4 @@ export * from "./maintenance/atomic-file.js";
 export * from "./eval-trajectory.js";
 export { MemoryControllerCoordinator, chooseAction, computeEvidenceReportHash, controllerConfigHash, evaluateActiveGates, hashControllerState, verifyEvidenceReport } from "./memory-controller.js";
 export type { ActiveContextAdapter, ActiveContextMessage, ActiveContextPlan, MemoryControllerActionFamily, MemoryControllerChoice, MemoryControllerConfig, MemoryControllerDeps, MemoryControllerEvent, MemoryControllerEvidence, MemoryControllerEvidenceReport, MemoryControllerExecutors, MemoryControllerMode, MemoryControllerPairedSeedEvidence, MemoryControllerReceipt, MemoryControllerRecorder, MemoryControllerReportReader, MemoryControllerRunResult, MemoryControllerState } from "./memory-controller.js";
+export * from "./recall-navigate.js";

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

@@ -0,0 +1,58 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { runDeepRecallAccess } from "./recall-deep-access.js";
+
+const QUERY = "who met at the cafe";
+
+test("budget 0 stops immediately with a tagged refusal", () => {
+  const result = runDeepRecallAccess({ query: QUERY, budget: 0, policyName: "expand-once" });
+  assert.equal(result.ok, false);
+  assert.deepEqual(result.refusal, { tag: "budget_exhausted" });
+  assert.equal(result.trace.length, 1);
+  assert.equal(result.trace[0]?.action, "stop");
+  assert.equal(result.state.budget, 0);
+  assert.equal(result.state.query, QUERY);
+  assert.deepEqual(result.state.workingSet, []);
+  assert.deepEqual(result.state.frontier, []);
+  assert.equal(result.traceJson, JSON.stringify(result.trace));
+});
+
+test("unknown policyName is rejected", () => {
+  assert.throws(
+    () => runDeepRecallAccess({ query: QUERY, budget: 2, policyName: "refine-twice" }),
+    /unknown deep recall access policy/,
+  );
+  assert.throws(
+    () => runDeepRecallAccess({ query: QUERY, budget: 2, policyName: "refine-twice" }),
+    /stop, expand-once/,
+  );
+});
+
+test("stop policy ends without expanding", () => {
+  const result = runDeepRecallAccess({ query: QUERY, budget: 3, policyName: "stop" });
+  assert.equal(result.ok, true);
+  assert.equal(result.refusal, undefined);
+  assert.equal(result.trace.length, 1);
+  assert.equal(result.trace[0]?.action, "stop");
+  assert.equal(result.state.budget, 3);
+  assert.deepEqual(result.state.workingSet, []);
+});
+
+test("expand-once expands once then stops", () => {
+  const result = runDeepRecallAccess({ query: QUERY, budget: 3, policyName: "expand-once" });
+  assert.equal(result.ok, true);
+  assert.deepEqual(
+    result.trace.map((step) => step.action),
+    ["expand", "stop"],
+  );
+  assert.equal(result.state.budget, 2);
+});
+
+test("same input produces the same trace JSON", () => {
+  const input = { query: QUERY, budget: 4, policyName: "expand-once" as const };
+  const first = runDeepRecallAccess(input);
+  const second = runDeepRecallAccess(input);
+  assert.equal(first.traceJson, second.traceJson);
+  assert.equal(first.traceJson, JSON.stringify(first.trace));
+});