@remnic/core 9.66.2 → 9.66.3

package/src/dedup/merge-empty.test.ts

@@ -0,0 +1,22 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { rejectEmptyMergeIds } from "./merge-empty.js";
+
+test("empty set is empty_set", () => {
+  assert.deepEqual(rejectEmptyMergeIds([]), { ok: false, error: "empty_set" });
+});
+
+test("empty id is empty_id", () => {
+  assert.deepEqual(rejectEmptyMergeIds([""]), { ok: false, error: "empty_id" });
+  assert.deepEqual(rejectEmptyMergeIds(["alpha", ""]), { ok: false, error: "empty_id" });
+  assert.deepEqual(rejectEmptyMergeIds(["", "alpha"]), { ok: false, error: "empty_id" });
+});
+
+test("ok returns the same ids in order and does not mutate", () => {
+  const ids = ["zeta", "alpha", "beta"];
+  const result = rejectEmptyMergeIds(ids);
+  assert.deepEqual(result, { ok: true, ids: ["zeta", "alpha", "beta"] });
+  assert.equal(result.ok && result.ids, ids);
+  assert.deepEqual(ids, ["zeta", "alpha", "beta"]);
+});

package/src/dedup/merge-empty.ts

@@ -0,0 +1,18 @@
+/**
+ * Merge-id empty-set guard (issue #2330 leftover).
+ *
+ * Empty list → empty_set. Any empty string → empty_id.
+ * Otherwise returns the same ids in order. Does not mutate input.
+ */
+
+export type RejectEmptyMergeIdsResult =
+  | { ok: true; ids: readonly string[] }
+  | { ok: false; error: "empty_set" | "empty_id" };
+
+export function rejectEmptyMergeIds(ids: readonly string[]): RejectEmptyMergeIdsResult {
+  if (ids.length === 0) return { ok: false, error: "empty_set" };
+  for (const id of ids) {
+    if (id === "") return { ok: false, error: "empty_id" };
+  }
+  return { ok: true, ids };
+}

package/src/dedup/merge-id.test.ts

@@ -0,0 +1,18 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { pickMergeTargetId } from "./merge-id.js";
+
+test("empty candidates return null", () => {
+  assert.equal(pickMergeTargetId([]), null);
+});
+
+test("picks lowest id by localeCompare", () => {
+  assert.equal(pickMergeTargetId(["zeta", "alpha", "beta"]), "alpha");
+});
+
+test("does not mutate candidates", () => {
+  const candidates = ["zeta", "alpha", "beta"];
+  pickMergeTargetId(candidates);
+  assert.deepEqual(candidates, ["zeta", "alpha", "beta"]);
+});

package/src/dedup/merge-id.ts

@@ -0,0 +1,14 @@
+/**
+ * Merge-target id picker (issue #2330 leftover).
+ *
+ * Empty candidates return null. Otherwise the lowest id by localeCompare.
+ * Does not mutate the input list.
+ */
+
+export function pickMergeTargetId(candidates: readonly string[]): string | null {
+  let lowest: string | undefined;
+  for (const id of candidates) {
+    if (lowest === undefined || id.localeCompare(lowest) < 0) lowest = id;
+  }
+  return lowest ?? null;
+}

package/src/dedup/merge-min-score.test.ts

@@ -0,0 +1,37 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseMinMergeScore } from "./merge-min-score.js";
+
+test("minScore 0 is accepted", () => {
+  assert.equal(parseMinMergeScore(0), 0);
+});
+
+test("minScore 1 is accepted", () => {
+  assert.equal(parseMinMergeScore(1), 1);
+});
+
+test("minScore 0.5 is accepted", () => {
+  assert.equal(parseMinMergeScore(0.5), 0.5);
+});
+
+test("out of range minScore throws", () => {
+  assert.throws(() => parseMinMergeScore(-0.1), /\[0, 1\]/);
+  assert.throws(() => parseMinMergeScore(1.1), /\[0, 1\]/);
+});
+
+test("non-finite minScore throws", () => {
+  assert.throws(() => parseMinMergeScore(Number.NaN), RangeError);
+  assert.throws(() => parseMinMergeScore(Number.POSITIVE_INFINITY), RangeError);
+  assert.throws(() => parseMinMergeScore("0.5"), RangeError);
+});
+
+test("bigint minScore throws RangeError, not TypeError", () => {
+  assert.throws(() => parseMinMergeScore(10n), RangeError);
+});
+
+test("cyclic object minScore throws RangeError, not TypeError", () => {
+  const cyclic: Record<string, unknown> = {};
+  cyclic.self = cyclic;
+  assert.throws(() => parseMinMergeScore(cyclic), RangeError);
+});

package/src/dedup/merge-min-score.ts

@@ -0,0 +1,22 @@
+/**
+ * Parse merge-on-write min score (issue #2330 leftover).
+ *
+ * Finite number in [0, 1] is returned. Outside range or non-finite throws.
+ */
+function describeValue(value: unknown): string {
+  try {
+    const serialized = JSON.stringify(value);
+    return serialized === undefined ? String(value) : serialized;
+  } catch {
+    return String(value);
+  }
+}
+
+export function parseMinMergeScore(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) {
+    throw new RangeError(
+      `merge minScore must be a finite number in [0, 1]; got ${describeValue(value)}`,
+    );
+  }
+  return value;
+}

package/src/dedup/merge-pair.test.ts

@@ -0,0 +1,19 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { orderMergePair } from "./merge-pair.js";
+
+test("orders ids by localeCompare", () => {
+  assert.deepEqual(orderMergePair("zeta", "alpha"), ["alpha", "zeta"]);
+  assert.deepEqual(orderMergePair("alpha", "zeta"), ["alpha", "zeta"]);
+});
+
+test("same id returns both sides", () => {
+  assert.deepEqual(orderMergePair("alpha", "alpha"), ["alpha", "alpha"]);
+});
+
+test("empty id throws", () => {
+  assert.throws(() => orderMergePair("", "alpha"), /empty merge id/);
+  assert.throws(() => orderMergePair("alpha", ""), /empty merge id/);
+  assert.throws(() => orderMergePair("", ""), /empty merge id/);
+});

package/src/dedup/merge-pair.ts

@@ -0,0 +1,13 @@
+/**
+ * Merge-pair id orderer (issue #2330 leftover).
+ *
+ * Returns [lower, higher] by localeCompare. Same id returns [id, id].
+ * Empty id throws.
+ */
+
+export function orderMergePair(aId: string, bId: string): [string, string] {
+  if (aId === "" || bId === "") {
+    throw new Error("empty merge id");
+  }
+  return aId.localeCompare(bId) <= 0 ? [aId, bId] : [bId, aId];
+}

package/src/dedup/merge-score.test.ts

@@ -0,0 +1,20 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { compareMergeScore } from "./merge-score.js";
+
+test("higher score wins", () => {
+  assert.equal(compareMergeScore(0.9, 0.8), 1);
+  assert.equal(compareMergeScore(0.8, 0.9), -1);
+});
+
+test("equal scores return 0", () => {
+  assert.equal(compareMergeScore(0.85, 0.85), 0);
+});
+
+test("NaN or non-finite scores throw", () => {
+  assert.throws(() => compareMergeScore(Number.NaN, 0.5), /invalid merge score/);
+  assert.throws(() => compareMergeScore(0.5, Number.NaN), /invalid merge score/);
+  assert.throws(() => compareMergeScore(Number.POSITIVE_INFINITY, 0.5), /invalid merge score/);
+  assert.throws(() => compareMergeScore(0.5, Number.NEGATIVE_INFINITY), /invalid merge score/);
+});

package/src/dedup/merge-score.ts

@@ -0,0 +1,14 @@
+/**
+ * Merge-score comparator (issue #2330 leftover).
+ *
+ * Higher score wins. NaN or non-finite scores throw.
+ */
+
+export function compareMergeScore(a: number, b: number): -1 | 0 | 1 {
+  if (!Number.isFinite(a) || !Number.isFinite(b)) {
+    throw new Error(`invalid merge score: ${a}, ${b}`);
+  }
+  if (a > b) return 1;
+  if (a < b) return -1;
+  return 0;
+}

package/src/dedup/merge-self.test.ts

@@ -0,0 +1,19 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { rejectSelfMerge } from "./merge-self.js";
+
+test("same id is self_merge", () => {
+  assert.deepEqual(rejectSelfMerge("alpha", "alpha"), { ok: false, error: "self_merge" });
+});
+
+test("different ids are ok", () => {
+  assert.deepEqual(rejectSelfMerge("alpha", "beta"), { ok: true });
+  assert.deepEqual(rejectSelfMerge("beta", "alpha"), { ok: true });
+});
+
+test("empty id throws", () => {
+  assert.throws(() => rejectSelfMerge("", "alpha"), /empty merge id/);
+  assert.throws(() => rejectSelfMerge("alpha", ""), /empty merge id/);
+  assert.throws(() => rejectSelfMerge("", ""), /empty merge id/);
+});

package/src/dedup/merge-self.ts

@@ -0,0 +1,17 @@
+/**
+ * Merge-self guard (issue #2330 leftover).
+ *
+ * Same id → self_merge. Empty id throws. Otherwise ok.
+ */
+
+export type RejectSelfMergeResult =
+  | { ok: true }
+  | { ok: false; error: "self_merge" };
+
+export function rejectSelfMerge(aId: string, bId: string): RejectSelfMergeResult {
+  if (aId === "" || bId === "") {
+    throw new Error("empty merge id");
+  }
+  if (aId === bId) return { ok: false, error: "self_merge" };
+  return { ok: true };
+}

package/src/dedup/merge-threshold.test.ts

@@ -0,0 +1,46 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { shouldSkipMergeJudge } from "./merge-threshold.js";
+
+test("disabled merge skips the judge", () => {
+  assert.equal(shouldSkipMergeJudge({ enabled: false, score: 0.85, skipThreshold: 0.92 }), true);
+});
+
+test("skipThreshold 0 never skips on score", () => {
+  assert.equal(shouldSkipMergeJudge({ enabled: true, score: 1, skipThreshold: 0 }), false);
+  assert.equal(shouldSkipMergeJudge({ enabled: true, score: 0, skipThreshold: 0 }), false);
+});
+
+test("score at or above skipThreshold skips", () => {
+  assert.equal(shouldSkipMergeJudge({ enabled: true, score: 0.92, skipThreshold: 0.92 }), true);
+  assert.equal(shouldSkipMergeJudge({ enabled: true, score: 0.99, skipThreshold: 0.92 }), true);
+  assert.equal(shouldSkipMergeJudge({ enabled: true, score: 0.91, skipThreshold: 0.92 }), false);
+});
+
+test("invalid score or threshold throws", () => {
+  assert.throws(
+    () => shouldSkipMergeJudge({ enabled: true, score: Number.NaN, skipThreshold: 0.92 }),
+    /invalid merge score/,
+  );
+  assert.throws(
+    () => shouldSkipMergeJudge({ enabled: true, score: -0.1, skipThreshold: 0.92 }),
+    /invalid merge score/,
+  );
+  assert.throws(
+    () => shouldSkipMergeJudge({ enabled: true, score: 1.1, skipThreshold: 0.92 }),
+    /invalid merge score/,
+  );
+  assert.throws(
+    () => shouldSkipMergeJudge({ enabled: true, score: 0.5, skipThreshold: Number.NaN }),
+    /invalid merge skipThreshold/,
+  );
+  assert.throws(
+    () => shouldSkipMergeJudge({ enabled: true, score: 0.5, skipThreshold: -0.01 }),
+    /invalid merge skipThreshold/,
+  );
+  assert.throws(
+    () => shouldSkipMergeJudge({ enabled: true, score: 0.5, skipThreshold: 1.01 }),
+    /invalid merge skipThreshold/,
+  );
+});

package/src/dedup/merge-threshold.ts

@@ -0,0 +1,26 @@
+/**
+ * Merge-judge skip predicate (issue #2330 leftover).
+ *
+ * Pure. Disabled merge skips the judge (create). skipThreshold 0 never
+ * skips on score. score >= skipThreshold skips. Invalid units throw.
+ */
+
+export interface MergeThresholdInput {
+  enabled: boolean;
+  score: number;
+  skipThreshold: number;
+}
+
+function assertUnitInterval(value: number, name: string): void {
+  if (!Number.isFinite(value) || value < 0 || value > 1) {
+    throw new Error(`invalid merge ${name}: ${value}`);
+  }
+}
+
+export function shouldSkipMergeJudge(input: MergeThresholdInput): boolean {
+  assertUnitInterval(input.score, "score");
+  assertUnitInterval(input.skipThreshold, "skipThreshold");
+  if (!input.enabled) return true;
+  if (input.skipThreshold === 0) return false;
+  return input.score >= input.skipThreshold;
+}

package/src/dedup/merge-tie.test.ts

@@ -0,0 +1,22 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { breakMergeTie } from "./merge-tie.js";
+
+test("a wins when aId is lower", () => {
+  assert.equal(breakMergeTie("alpha", "zeta"), "alpha");
+});
+
+test("b wins when bId is lower", () => {
+  assert.equal(breakMergeTie("zeta", "alpha"), "alpha");
+});
+
+test("same id returns aId", () => {
+  assert.equal(breakMergeTie("alpha", "alpha"), "alpha");
+});
+
+test("empty id throws", () => {
+  assert.throws(() => breakMergeTie("", "alpha"), /empty merge id/);
+  assert.throws(() => breakMergeTie("alpha", ""), /empty merge id/);
+  assert.throws(() => breakMergeTie("", ""), /empty merge id/);
+});

package/src/dedup/merge-tie.ts

@@ -0,0 +1,13 @@
+/**
+ * Merge-tie breaker (issue #2330 leftover).
+ *
+ * Returns the lower id by localeCompare. Same id returns aId.
+ * Empty id throws.
+ */
+
+export function breakMergeTie(aId: string, bId: string): string {
+  if (aId === "" || bId === "") {
+    throw new Error("empty merge id");
+  }
+  return aId.localeCompare(bId) <= 0 ? aId : bId;
+}

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

@@ -0,0 +1,27 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { shouldRunSpanBench } from "./extraction-span-bench.js";
+
+test("shouldRunSpanBench: disabled or zero rate never samples (issue #2333)", () => {
+	assert.equal(shouldRunSpanBench({ enabled: false, sampleRate: 1 }), false);
+	assert.equal(shouldRunSpanBench({ enabled: false, sampleRate: 0 }), false);
+	assert.equal(shouldRunSpanBench({ enabled: true, sampleRate: 0 }), false);
+});
+
+test("shouldRunSpanBench: enabled with full rate always samples (issue #2333)", () => {
+	assert.equal(shouldRunSpanBench({ enabled: true, sampleRate: 1 }), true);
+});
+
+test("shouldRunSpanBench: rejects sampleRate outside [0, 1] or non-finite (issue #2333)", () => {
+	const invalid: number[] = [-0.1, 1.0001, Number.NaN, Number.POSITIVE_INFINITY];
+	for (const sampleRate of invalid) {
+		assert.throws(() => shouldRunSpanBench({ enabled: true, sampleRate }));
+	}
+	assert.throws(() =>
+		shouldRunSpanBench({ enabled: true, sampleRate: "0.5" as unknown as number }),
+	);
+	assert.throws(() =>
+		shouldRunSpanBench({ enabled: true, sampleRate: undefined as unknown as number }),
+	);
+});

package/src/extraction-span-bench.ts

@@ -0,0 +1,28 @@
+/**
+ * Sampling gate for the extraction span benchmark (issue #2333).
+ *
+ * Pure predicate, deliberately standalone: it does not import the extraction
+ * engine and is not wired into the default extraction path. A future caller
+ * opts in explicitly; until then this module changes nothing at runtime.
+ */
+
+export interface SpanBenchOptions {
+	enabled: boolean;
+	sampleRate: number;
+}
+
+export function shouldRunSpanBench({ enabled, sampleRate }: SpanBenchOptions): boolean {
+	if (
+		typeof sampleRate !== "number" ||
+		!Number.isFinite(sampleRate) ||
+		sampleRate < 0 ||
+		sampleRate > 1
+	) {
+		throw new Error(
+			`extraction-span-bench: sampleRate must be a finite number in [0, 1], got ${String(sampleRate)}`,
+		);
+	}
+	if (!enabled || sampleRate === 0) return false;
+	if (sampleRate === 1) return true;
+	return Math.random() < sampleRate;
+}

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

@@ -0,0 +1,71 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { clipSpan } from "./extraction-span-clip.js";
+
+test("clipSpan: in-range span is unchanged", () => {
+  assert.deepEqual(clipSpan({ start: 1, end: 4, textLength: 8 }), {
+    ok: true,
+    start: 1,
+    end: 4,
+  });
+  assert.deepEqual(clipSpan({ start: 0, end: 8, textLength: 8 }), {
+    ok: true,
+    start: 0,
+    end: 8,
+  });
+});
+
+test("clipSpan: clips to [0, textLength]", () => {
+  assert.deepEqual(clipSpan({ start: -3, end: 4, textLength: 10 }), {
+    ok: true,
+    start: 0,
+    end: 4,
+  });
+  assert.deepEqual(clipSpan({ start: 6, end: 20, textLength: 10 }), {
+    ok: true,
+    start: 6,
+    end: 10,
+  });
+  assert.deepEqual(clipSpan({ start: -2, end: 99, textLength: 5 }), {
+    ok: true,
+    start: 0,
+    end: 5,
+  });
+});
+
+test("clipSpan: empty after clip", () => {
+  assert.deepEqual(clipSpan({ start: 3, end: 3, textLength: 8 }), {
+    ok: false,
+    error: "empty",
+  });
+  assert.deepEqual(clipSpan({ start: 5, end: 2, textLength: 8 }), {
+    ok: false,
+    error: "empty",
+  });
+  assert.deepEqual(clipSpan({ start: -4, end: -1, textLength: 8 }), {
+    ok: false,
+    error: "empty",
+  });
+});
+
+test("clipSpan: oob collapses to empty", () => {
+  assert.deepEqual(clipSpan({ start: 10, end: 20, textLength: 8 }), {
+    ok: false,
+    error: "empty",
+  });
+  assert.deepEqual(clipSpan({ start: 8, end: 12, textLength: 8 }), {
+    ok: false,
+    error: "empty",
+  });
+  assert.deepEqual(clipSpan({ start: -5, end: 0, textLength: 8 }), {
+    ok: false,
+    error: "empty",
+  });
+});
+
+test("clipSpan: non-integers throw", () => {
+  assert.throws(() => clipSpan({ start: 1.5, end: 3, textLength: 8 }), /integers/);
+  assert.throws(() => clipSpan({ start: 0, end: 3.2, textLength: 8 }), /integers/);
+  assert.throws(() => clipSpan({ start: 0, end: 3, textLength: 8.1 }), /integers/);
+  assert.throws(() => clipSpan({ start: Number.NaN, end: 3, textLength: 8 }), /integers/);
+});

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