@remnic/core 9.66.1 → 9.66.3

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

@@ -0,0 +1,21 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { hasDuplicateMergeIds } from "./merge-dup.js";
+
+test("none is false", () => {
+  assert.equal(hasDuplicateMergeIds([]), false);
+  assert.equal(hasDuplicateMergeIds(["alpha"]), false);
+  assert.equal(hasDuplicateMergeIds(["alpha", "beta"]), false);
+});
+
+test("duplicate non-empty id is true", () => {
+  assert.equal(hasDuplicateMergeIds(["alpha", "beta", "alpha"]), true);
+});
+
+test("empty strings are ignored and input is not mutated", () => {
+  const ids = ["alpha", "", "", "beta"];
+  assert.equal(hasDuplicateMergeIds(ids), false);
+  assert.equal(hasDuplicateMergeIds(["", "", "alpha", "", "alpha"]), true);
+  assert.deepEqual(ids, ["alpha", "", "", "beta"]);
+});

package/src/dedup/merge-dup.ts

@@ -0,0 +1,16 @@
+/**
+ * Merge-id duplicate detector (issue #2330 leftover).
+ *
+ * True if any non-empty id appears twice. Empty strings are ignored.
+ * Does not mutate the input list.
+ */
+
+export function hasDuplicateMergeIds(ids: readonly string[]): boolean {
+  const seen = new Set<string>();
+  for (const id of ids) {
+    if (id === "") continue;
+    if (seen.has(id)) return true;
+    seen.add(id);
+  }
+  return false;
+}

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-on-write-wire.test.ts

@@ -0,0 +1,101 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import type { MergeJudge, MergeJudgeVerdict, MergeOnWritePair } from "./merge-on-write.js";
+import { applyMergeOnWriteAtPersist } from "./merge-on-write-wire.js";
+
+type PersistResult = { action: "merged"; id: string } | { action: "created" };
+
+function pair(overrides: Partial<MergeOnWritePair> = {}): MergeOnWritePair {
+  return {
+    category: "fact",
+    score: 0.85,
+    incomingContent: "User prefers dark mode on laptops.",
+    existingContent: "User likes dark mode.",
+    existingId: "mem-1",
+    ...overrides,
+  };
+}
+
+function trackers() {
+  const merged: string[] = [];
+  const created: number[] = [];
+  return {
+    merged,
+    created,
+    writeMerged: async (id: string): Promise<PersistResult> => {
+      merged.push(id);
+      return { action: "merged", id };
+    },
+    writeNew: async (): Promise<PersistResult> => {
+      created.push(1);
+      return { action: "created" };
+    },
+  };
+}
+
+const mergeJudge: MergeJudge = async (): Promise<MergeJudgeVerdict> => "merge";
+const createJudge: MergeJudge = async (): Promise<MergeJudgeVerdict> => "create";
+
+test("merge-on-write-wire: disabled writes a new fact", async () => {
+  let judged = 0;
+  const io = trackers();
+  const result = await applyMergeOnWriteAtPersist({
+    enabled: false,
+    pair: pair(),
+    judge: async (): Promise<MergeJudgeVerdict> => {
+      judged += 1;
+      return "merge";
+    },
+    writeMerged: io.writeMerged,
+    writeNew: io.writeNew,
+  });
+  assert.equal(result.action, "created");
+  assert.deepEqual(io.merged, []);
+  assert.equal(io.created.length, 1);
+  assert.equal(judged, 0);
+});
+
+test("merge-on-write-wire: mergeMin 0 writes a new fact", async () => {
+  let judged = 0;
+  const io = trackers();
+  const result = await applyMergeOnWriteAtPersist({
+    enabled: true,
+    mergeMin: 0,
+    pair: pair(),
+    judge: mergeJudge,
+    writeMerged: io.writeMerged,
+    writeNew: io.writeNew,
+  });
+  assert.equal(result.action, "created");
+  assert.deepEqual(io.merged, []);
+  assert.equal(io.created.length, 1);
+  assert.equal(judged, 0);
+});
+
+test("merge-on-write-wire: merge updates the existing id", async () => {
+  const io = trackers();
+  const result = await applyMergeOnWriteAtPersist({
+    enabled: true,
+    pair: pair(),
+    judge: mergeJudge,
+    writeMerged: io.writeMerged,
+    writeNew: io.writeNew,
+  });
+  assert.deepEqual(result, { action: "merged", id: "mem-1" });
+  assert.deepEqual(io.merged, ["mem-1"]);
+  assert.equal(io.created.length, 0);
+});
+
+test("merge-on-write-wire: create writes a new fact", async () => {
+  const io = trackers();
+  const result = await applyMergeOnWriteAtPersist({
+    enabled: true,
+    pair: pair(),
+    judge: createJudge,
+    writeMerged: io.writeMerged,
+    writeNew: io.writeNew,
+  });
+  assert.equal(result.action, "created");
+  assert.deepEqual(io.merged, []);
+  assert.equal(io.created.length, 1);
+});

package/src/dedup/merge-on-write-wire.ts

@@ -0,0 +1,34 @@
+/**
+ * Persist seam for merge-on-write (issue #2330 leftover slice).
+ *
+ * Default off. Failures and disabled gates create. Persist callers inject
+ * writeMerged / writeNew. This module does not touch extraction-persist.
+ */
+
+import {
+  applyMergeOnWrite,
+  type MergeJudge,
+  type MergeOnWritePair,
+} from "./merge-on-write.js";
+
+export async function applyMergeOnWriteAtPersist<T>(opts: {
+  enabled?: boolean;
+  pair: MergeOnWritePair;
+  judge: MergeJudge;
+  mergeMin?: number;
+  skipThreshold?: number;
+  writeMerged: (id: string) => T | Promise<T>;
+  writeNew: () => T | Promise<T>;
+}): Promise<T> {
+  const decision = await applyMergeOnWrite({
+    enabled: opts.enabled,
+    pair: opts.pair,
+    judge: opts.judge,
+    mergeMin: opts.mergeMin,
+    skipThreshold: opts.skipThreshold,
+  });
+  if (decision === "merge" && opts.pair.existingId) {
+    return opts.writeMerged(opts.pair.existingId);
+  }
+  return opts.writeNew();
+}

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