@remnic/core 9.66.11 → 9.67.0

package/src/activity/journal-strip.test.ts

@@ -0,0 +1,126 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { stripRemnicOwnedRegions } from "./journal-strip.js";
+
+test("stripRemnicOwnedRegions removes a marker pair and keeps user text", () => {
+  const text = [
+    "Morning standup.",
+    "<!-- remnic:timeline:start -->",
+    "9:00 deep work",
+    "<!-- remnic:timeline:end -->",
+    "Wrote the parser.",
+  ].join("\n");
+  assert.equal(stripRemnicOwnedRegions(text, []), "Morning standup.\nWrote the parser.");
+});
+
+test("stripRemnicOwnedRegions keeps one blank line where a removal doubled it", () => {
+  const text = [
+    "Before.",
+    "",
+    "<!-- remnic:timeline:start -->",
+    "generated",
+    "<!-- remnic:timeline:end -->",
+    "",
+    "After.",
+  ].join("\n");
+  assert.equal(stripRemnicOwnedRegions(text, []), "Before.\n\nAfter.");
+});
+
+test("stripRemnicOwnedRegions removes two distinct marker pairs", () => {
+  const text = [
+    "head",
+    "<!-- remnic:timeline:start -->",
+    "timeline body",
+    "<!-- remnic:timeline:end -->",
+    "middle",
+    "<!-- remnic:digest:start -->",
+    "digest body",
+    "<!-- remnic:digest:end -->",
+    "tail",
+  ].join("\n");
+  assert.equal(stripRemnicOwnedRegions(text, []), "head\nmiddle\ntail");
+});
+
+test("stripRemnicOwnedRegions strips an unterminated start marker to the end of input", () => {
+  const text = ["kept", "<!-- remnic:timeline:start -->", "generated", "later user text"].join("\n");
+  assert.equal(stripRemnicOwnedRegions(text, []), "kept");
+});
+
+test("stripRemnicOwnedRegions removes an orphan end marker and keeps surrounding text", () => {
+  const text = ["Before.", "<!-- remnic:timeline:end -->", "After."].join("\n");
+  assert.equal(stripRemnicOwnedRegions(text, []), "Before.\nAfter.");
+});
+
+test("stripRemnicOwnedRegions removes an owned heading section up to the next same-level heading", () => {
+  const text = ["## Journal", "intro", "## Timeline", "card one", "## Notes", "kept"].join("\n");
+  assert.equal(stripRemnicOwnedRegions(text, ["Timeline"]), "## Journal\nintro\n## Notes\nkept");
+});
+
+test("stripRemnicOwnedRegions does not end an owned section at a deeper heading", () => {
+  const text = [
+    "## Journal",
+    "## Timeline",
+    "card one",
+    "### Deep",
+    "deep card",
+    "## Notes",
+    "kept",
+  ].join("\n");
+  assert.equal(stripRemnicOwnedRegions(text, ["Timeline"]), "## Journal\n## Notes\nkept");
+});
+
+test("stripRemnicOwnedRegions preserves a non-owned heading section", () => {
+  const text = ["## Journal", "## Timeline", "card one", "## Notes", "kept"].join("\n");
+  assert.equal(stripRemnicOwnedRegions(text, ["Digest"]), text);
+});
+
+test("stripRemnicOwnedRegions ignores blank and whitespace owned heading entries", () => {
+  const text = ["## Timeline", "card one", ""].join("\n");
+  assert.equal(stripRemnicOwnedRegions(text, ["", "   ", "\t"]), text);
+});
+
+test("stripRemnicOwnedRegions trims configured owned heading entries", () => {
+  const text = ["## Timeline", "card", "## Notes", "kept"].join("\n");
+  assert.equal(stripRemnicOwnedRegions(text, ["  Timeline  "]), "## Notes\nkept");
+});
+
+test("stripRemnicOwnedRegions returns empty string for empty input", () => {
+  assert.equal(stripRemnicOwnedRegions("", ["Timeline"]), "");
+});
+
+test("stripRemnicOwnedRegions returns unchanged text when nothing is owned", () => {
+  const text = ["first", "", "second", "", "third"].join("\n");
+  assert.equal(stripRemnicOwnedRegions(text, ["Timeline"]), text);
+});
+
+// Regression: the journal-section reader normalizes tab separators, extra
+// spaces, trailing whitespace, and closing # sequences. The stripper must
+// recognize exactly the same set, or an owned heading the reader treats as
+// the journal section would keep its generated body in the journal text.
+test("owned heading matching accepts every ATX form the section reader accepts", () => {
+  const body = ["generated line", "", "## User Notes", "kept"].join("\n");
+  for (const headingLine of [
+    "## Timeline",
+    "##  Timeline",
+    "##\tTimeline",
+    "## Timeline   ",
+    "## Timeline ##",
+    "## Timeline ### ",
+  ]) {
+    const stripped = stripRemnicOwnedRegions(
+      [headingLine, body].join("\n"),
+      ["Timeline"],
+    );
+    assert.equal(
+      stripped,
+      ["## User Notes", "kept"].join("\n"),
+      `heading line ${JSON.stringify(headingLine)} must strip as owned`,
+    );
+  }
+});
+
+test("an indented heading is not owned, matching the section reader", () => {
+  const text = ["  ## Timeline", "not owned body"].join("\n");
+  assert.equal(stripRemnicOwnedRegions(text, ["Timeline"]), text);
+});

package/src/activity/journal-strip.ts

@@ -0,0 +1,115 @@
+/**
+ * Strip Remnic-owned regions from a vault journal section (issue #1987).
+ *
+ * Loop prevention for vault journals: before daily-note text is treated
+ * as journal text, every managed marker region and every configured
+ * owned heading section is removed, so published output can never
+ * re-enter the journal. An unterminated start marker fails closed and
+ * strips to the end of the section. Pure string-in/string-out. No
+ * filesystem. Heading lines parse through the SAME exported ATX
+ * parser the journal-section reader uses, so a heading the reader
+ * recognizes is always a heading this stripper strips.
+ */
+
+import { parseAtxHeading } from "./journal-section.js";
+
+const MARKER_OPEN = "<!-- remnic:";
+const MARKER_CLOSE = "-->";
+const START_SUFFIX = ":start";
+const END_SUFFIX = ":end";
+
+type RegionMarker = { kind: "start" | "end"; name: string };
+
+export function stripRemnicOwnedRegions(
+  sectionText: string,
+  ownedHeadings: readonly string[],
+): string {
+  return stripOwnedHeadings(stripMarkerRegions(sectionText), ownedHeadings);
+}
+
+function stripMarkerRegions(text: string): string {
+  const lines = text.split("\n");
+  const keep = lines.map(() => true);
+  let openName: string | null = null;
+  for (let i = 0; i < lines.length; i++) {
+    const marker = parseRegionMarker(lines[i]!);
+    if (openName !== null) {
+      keep[i] = false;
+      if (marker && marker.kind === "end" && marker.name === openName) openName = null;
+      continue;
+    }
+    if (marker) {
+      keep[i] = false;
+      if (marker.kind === "start") openName = marker.name;
+    }
+  }
+  return emitKeptLines(lines, keep);
+}
+
+function stripOwnedHeadings(text: string, ownedHeadings: readonly string[]): string {
+  const wanted = ownedHeadingSet(ownedHeadings);
+  if (wanted.size === 0 || text.length === 0) return text;
+  const lines = text.split("\n");
+  const keep = lines.map(() => true);
+  for (let i = 0; i < lines.length; i++) {
+    if (!keep[i]) continue;
+    const heading = parseAtxHeading(lines[i]!);
+    if (!heading || !wanted.has(heading.text)) continue;
+    keep[i] = false;
+    for (let j = i + 1; j < lines.length; j++) {
+      const next = parseAtxHeading(lines[j]!);
+      if (next && next.level <= heading.level) break;
+      keep[j] = false;
+    }
+  }
+  return emitKeptLines(lines, keep);
+}
+
+/**
+ * Emit kept lines, collapsing the one blank line each removal would
+ * otherwise double. Text outside removals is preserved byte-for-byte.
+ */
+function emitKeptLines(lines: readonly string[], keep: readonly boolean[]): string {
+  const out: string[] = [];
+  let dropped = false;
+  for (let i = 0; i < lines.length; i++) {
+    if (!keep[i]) {
+      dropped = true;
+      continue;
+    }
+    const line = lines[i]!;
+    const previous = out.length > 0 ? out[out.length - 1]! : null;
+    if (dropped && previous !== null && previous.trim().length === 0 && line.trim().length === 0) {
+      dropped = false;
+      continue;
+    }
+    out.push(line);
+    dropped = false;
+  }
+  return out.join("\n");
+}
+
+function parseRegionMarker(line: string): RegionMarker | null {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith(MARKER_OPEN) || !trimmed.endsWith(MARKER_CLOSE)) return null;
+  const inner = trimmed.slice(MARKER_OPEN.length, trimmed.length - MARKER_CLOSE.length).trim();
+  if (inner.endsWith(START_SUFFIX)) {
+    const name = inner.slice(0, -START_SUFFIX.length);
+    return name.length > 0 ? { kind: "start", name } : null;
+  }
+  if (inner.endsWith(END_SUFFIX)) {
+    const name = inner.slice(0, -END_SUFFIX.length);
+    return name.length > 0 ? { kind: "end", name } : null;
+  }
+  return null;
+}
+
+function ownedHeadingSet(ownedHeadings: readonly string[]): Set<string> {
+  const wanted = new Set<string>();
+  for (const entry of ownedHeadings) {
+    if (typeof entry !== "string") continue;
+    const trimmed = entry.trim();
+    if (trimmed.length > 0) wanted.add(trimmed);
+  }
+  return wanted;
+}

package/src/activity/timeline/analysis-failure.test.ts

@@ -0,0 +1,104 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  ANALYSIS_FAILURE_KINDS,
+  classifyAnalysisFailure,
+  isAnalysisFailureKind,
+  type AnalysisFailureKind,
+} from "./analysis-failure.js";
+
+test("every known kind classifies with the explicit retryable split", () => {
+  const retryableKinds: readonly AnalysisFailureKind[] = [
+    "provider_unavailable",
+    "timeout",
+    "rate_limited",
+  ];
+  const nonRetryableKinds: readonly AnalysisFailureKind[] = [
+    "aborted",
+    "malformed_json",
+    "invalid_schema",
+    "partial_output",
+    "invalid_config",
+  ];
+  for (const kind of ANALYSIS_FAILURE_KINDS) {
+    const failure = classifyAnalysisFailure(kind);
+    assert.equal(failure.kind, kind);
+    assert.equal(failure.preservesDeterministic, true);
+    const expectedRetryable = retryableKinds.includes(kind);
+    assert.ok(
+      expectedRetryable || nonRetryableKinds.includes(kind),
+      `${kind} missing from the explicit retryable split`,
+    );
+    assert.equal(
+      failure.retryable,
+      expectedRetryable,
+      `${kind} retryable must be ${expectedRetryable}`,
+    );
+  }
+});
+
+test("the explicit retryable split covers all kinds exactly once", () => {
+  const split: readonly string[] = [
+    "provider_unavailable",
+    "timeout",
+    "rate_limited",
+    "aborted",
+    "malformed_json",
+    "invalid_schema",
+    "partial_output",
+    "invalid_config",
+  ];
+  assert.equal(new Set(split).size, split.length);
+  assert.deepEqual(
+    [...ANALYSIS_FAILURE_KINDS].sort(),
+    [...split].sort(),
+  );
+});
+
+test("unknown string kind throws TypeError naming the allowed kinds", () => {
+  assert.throws(
+    () => classifyAnalysisFailure("provider_on_fire"),
+    (err: unknown) => {
+      assert.ok(err instanceof TypeError);
+      assert.match((err as Error).message, /unknown analysis failure/);
+      for (const kind of ANALYSIS_FAILURE_KINDS) {
+        assert.ok((err as Error).message.includes(kind));
+      }
+      return true;
+    },
+  );
+});
+
+test("empty, null, undefined, and non-string kinds throw", () => {
+  for (const bad of ["", undefined, null, 42]) {
+    assert.throws(
+      () => classifyAnalysisFailure(bad as string),
+      TypeError,
+      `expected throw for ${String(bad)}`,
+    );
+  }
+});
+
+test("isAnalysisFailureKind is false for non-strings, empty, and unknown", () => {
+  assert.equal(isAnalysisFailureKind(undefined), false);
+  assert.equal(isAnalysisFailureKind(null), false);
+  assert.equal(isAnalysisFailureKind(42), false);
+  assert.equal(isAnalysisFailureKind({ kind: "timeout" }), false);
+  assert.equal(isAnalysisFailureKind(""), false);
+  assert.equal(isAnalysisFailureKind("timeout "), false);
+  assert.equal(isAnalysisFailureKind("TIMEOUT"), false);
+  assert.equal(isAnalysisFailureKind("provider_on_fire"), false);
+  for (const kind of ANALYSIS_FAILURE_KINDS) {
+    assert.equal(isAnalysisFailureKind(kind), true);
+  }
+});
+
+test("preservesDeterministic is true for every kind", () => {
+  for (const kind of ANALYSIS_FAILURE_KINDS) {
+    assert.deepEqual(
+      classifyAnalysisFailure(kind).preservesDeterministic,
+      true,
+    );
+  }
+});

package/src/activity/timeline/analysis-failure.ts

@@ -0,0 +1,60 @@
+/**
+ * Typed failure classification for timeline analysis (issue #2050).
+ *
+ * Unknown kinds fail closed with a TypeError. Pure: no I/O, no clock, no randomness.
+ */
+
+export const ANALYSIS_FAILURE_KINDS = [
+  "provider_unavailable",
+  "timeout",
+  "aborted",
+  "rate_limited",
+  "malformed_json",
+  "invalid_schema",
+  "partial_output",
+  "invalid_config",
+] as const;
+export type AnalysisFailureKind = (typeof ANALYSIS_FAILURE_KINDS)[number];
+
+export interface AnalysisFailure {
+  kind: AnalysisFailureKind;
+  /** True only when retrying the same request could plausibly succeed. */
+  retryable: boolean;
+  /** True when the deterministic cards must be preserved unchanged. */
+  preservesDeterministic: true;
+}
+
+const RETRYABLE_BY_KIND: Readonly<Record<AnalysisFailureKind, boolean>> = {
+  provider_unavailable: true,
+  timeout: true,
+  rate_limited: true,
+  aborted: false,
+  malformed_json: false,
+  invalid_schema: false,
+  partial_output: false,
+  invalid_config: false,
+};
+
+/** True when the value is one of the known failure kinds. */
+export function isAnalysisFailureKind(
+  value: unknown,
+): value is AnalysisFailureKind {
+  return (
+    typeof value === "string" &&
+    (ANALYSIS_FAILURE_KINDS as readonly string[]).includes(value)
+  );
+}
+
+/** Classify a failure kind. Unknown kinds throw; there is no permissive default. */
+export function classifyAnalysisFailure(kind: string): AnalysisFailure {
+  if (!isAnalysisFailureKind(kind)) {
+    throw new TypeError(
+      `unknown analysis failure kind: ${String(kind)}; allowed kinds: ${ANALYSIS_FAILURE_KINDS.join(", ")}`,
+    );
+  }
+  return {
+    kind,
+    retryable: RETRYABLE_BY_KIND[kind],
+    preservesDeterministic: true,
+  };
+}

package/src/activity/timeline/index.ts

@@ -21,3 +21,4 @@ export * from "./analysis-prompt.js";
 export * from "./analysis-claim.js";
 export * from "./analysis-order.js";
 export * from "./recap-window.js";
+export * from "./analysis-failure.js";

package/src/dedup/index.ts

@@ -467,3 +467,10 @@ export {
   type MergeDecision,
   type MergeDecisionOptions,
 } from "./merge-decision.js";
+
+export {
+  MERGE_JUDGE_VERDICTS,
+  parseMergeJudgeVerdict,
+  type MergeJudgeVerdictName,
+  type ParseMergeVerdictResult,
+} from "./merge-verdict.js";

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

@@ -0,0 +1,74 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { MERGE_JUDGE_VERDICTS, parseMergeJudgeVerdict } from "./merge-verdict.js";
+
+test("every allow-list name parses (loops the constant)", () => {
+  for (const name of MERGE_JUDGE_VERDICTS) {
+    const result = parseMergeJudgeVerdict(name);
+    assert.equal(result.ok, true);
+    assert.ok(result.ok);
+    assert.equal(result.verdict, name);
+    assert.equal(result.decision, name === "merge" ? "merge" : "create");
+  }
+});
+
+test("accepts mixed case and surrounding whitespace", () => {
+  for (const raw of ["MERGE", " merge ", "Create", "\tcreate\n", "UnCertain", "  uncertain  "]) {
+    const result = parseMergeJudgeVerdict(raw);
+    assert.ok(result.ok, `expected "${raw}" to parse`);
+    assert.equal(result.verdict, raw.trim().toLowerCase());
+  }
+});
+
+test("only merge yields decision merge", () => {
+  const merged = parseMergeJudgeVerdict("merge");
+  assert.ok(merged.ok);
+  assert.equal(merged.decision, "merge");
+});
+
+test("uncertain yields decision create", () => {
+  const result = parseMergeJudgeVerdict("uncertain");
+  assert.ok(result.ok);
+  assert.equal(result.verdict, "uncertain");
+  assert.equal(result.decision, "create");
+});
+
+test("empty and non-string inputs give empty_verdict with decision create", () => {
+  const empties: unknown[] = ["", "   ", null, undefined, 42, { verdict: "merge" }, ["merge"]];
+  for (const raw of empties) {
+    const result = parseMergeJudgeVerdict(raw);
+    assert.ok(!result.ok, `expected ${JSON.stringify(raw)} to fail`);
+    assert.equal(result.error, "empty_verdict");
+    assert.equal(result.decision, "create");
+  }
+});
+
+test("unrecognized strings give unknown_verdict with decision create", () => {
+  for (const raw of ["I think merge", "maybe", "merge them", "merg", "MERGE!"]) {
+    const result = parseMergeJudgeVerdict(raw);
+    assert.ok(!result.ok, `expected "${raw}" to fail`);
+    assert.equal(result.error, "unknown_verdict");
+    assert.equal(result.decision, "create");
+  }
+});
+
+test("no input throws", () => {
+  const hostile: unknown[] = [
+    "",
+    "   ",
+    null,
+    undefined,
+    0,
+    NaN,
+    {},
+    [],
+    () => "merge",
+    Symbol("merge"),
+    "I think merge",
+    "merge",
+  ];
+  for (const raw of hostile) {
+    assert.doesNotThrow(() => parseMergeJudgeVerdict(raw));
+  }
+});

package/src/dedup/merge-verdict.ts

@@ -0,0 +1,31 @@
+/**
+ * Strict parser for free-form merge-judge verdicts (issue #2330 slice).
+ *
+ * Keeps "unparseable answer" distinguishable from a deliberate "create"
+ * while still failing closed: every failure carries decision "create".
+ */
+
+export const MERGE_JUDGE_VERDICTS = ["merge", "create", "uncertain"] as const;
+export type MergeJudgeVerdictName = (typeof MERGE_JUDGE_VERDICTS)[number];
+
+export type ParseMergeVerdictResult =
+  | { ok: true; verdict: MergeJudgeVerdictName; decision: "merge" | "create" }
+  | { ok: false; error: "empty_verdict" | "unknown_verdict"; decision: "create" };
+
+export function parseMergeJudgeVerdict(raw: unknown): ParseMergeVerdictResult {
+  if (typeof raw !== "string") {
+    return { ok: false, error: "empty_verdict", decision: "create" };
+  }
+  const normalized = raw.trim().toLowerCase();
+  if (normalized === "") {
+    return { ok: false, error: "empty_verdict", decision: "create" };
+  }
+  if (!(MERGE_JUDGE_VERDICTS as readonly string[]).includes(normalized)) {
+    return { ok: false, error: "unknown_verdict", decision: "create" };
+  }
+  return {
+    ok: true,
+    verdict: normalized as MergeJudgeVerdictName,
+    decision: normalized === "merge" ? "merge" : "create",
+  };
+}

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

@@ -0,0 +1,85 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { spanToProvenance } from "./extraction-span-provenance.js";
+
+const TEXT = "The quick brown fox jumps over the lazy dog";
+
+test("spanToProvenance: mid-text span yields exact slice with echoed offsets", () => {
+  const result = spanToProvenance({ text: TEXT, start: 4, end: 19 });
+  assert.deepEqual(result, {
+    ok: true,
+    provenance: { quote: "quick brown fox", charStart: 4, charEnd: 19 },
+  });
+  if (result.ok) {
+    assert.ok(result.provenance.charEnd >= result.provenance.charStart);
+  }
+});
+
+test("spanToProvenance: full-text span succeeds", () => {
+  const result = spanToProvenance({ text: TEXT, start: 0, end: TEXT.length });
+  assert.deepEqual(result, {
+    ok: true,
+    provenance: { quote: TEXT, charStart: 0, charEnd: TEXT.length },
+  });
+});
+
+test("spanToProvenance: matching supplied quote succeeds", () => {
+  const result = spanToProvenance({ text: TEXT, start: 4, end: 9, quote: "quick" });
+  assert.deepEqual(result, {
+    ok: true,
+    provenance: { quote: "quick", charStart: 4, charEnd: 9 },
+  });
+});
+
+test("spanToProvenance: whitespace-differing quote is quote_mismatch", () => {
+  const result = spanToProvenance({ text: TEXT, start: 4, end: 15, quote: "quick  brown" });
+  assert.deepEqual(result, { ok: false, error: "quote_mismatch" });
+});
+
+test("spanToProvenance: paraphrase is quote_mismatch", () => {
+  const result = spanToProvenance({ text: TEXT, start: 4, end: 19, quote: "a fast fox" });
+  assert.deepEqual(result, { ok: false, error: "quote_mismatch" });
+});
+
+test("spanToProvenance: empty span", () => {
+  assert.deepEqual(spanToProvenance({ text: TEXT, start: 3, end: 3 }), {
+    ok: false,
+    error: "empty_span",
+  });
+  assert.deepEqual(spanToProvenance({ text: "", start: 0, end: 0 }), {
+    ok: false,
+    error: "empty_span",
+  });
+});
+
+test("spanToProvenance: out of range", () => {
+  assert.deepEqual(spanToProvenance({ text: TEXT, start: -1, end: 4 }), {
+    ok: false,
+    error: "out_of_range",
+  });
+  assert.deepEqual(spanToProvenance({ text: TEXT, start: 0, end: TEXT.length + 1 }), {
+    ok: false,
+    error: "out_of_range",
+  });
+  assert.deepEqual(spanToProvenance({ text: TEXT, start: 10, end: 4 }), {
+    ok: false,
+    error: "out_of_range",
+  });
+});
+
+test("spanToProvenance: non-integers and non-finite offsets throw", () => {
+  assert.throws(() => spanToProvenance({ text: TEXT, start: 1.5, end: 4 }), /integers/);
+  assert.throws(() => spanToProvenance({ text: TEXT, start: 0, end: 3.2 }), /integers/);
+  assert.throws(() => spanToProvenance({ text: TEXT, start: Number.NaN, end: 4 }), /integers/);
+  assert.throws(
+    () => spanToProvenance({ text: TEXT, start: 0, end: Number.POSITIVE_INFINITY }),
+    /integers/,
+  );
+});
+
+test("spanToProvenance: does not mutate the input object", () => {
+  const input = { text: TEXT, start: 4, end: 19, quote: "quick brown fox" };
+  const snapshot = { ...input };
+  spanToProvenance(input);
+  assert.deepEqual(input, snapshot);
+});

package/src/extraction-span-provenance.ts

@@ -0,0 +1,41 @@
+/**
+ * Isolated span-provenance builder (issue #2333).
+ *
+ * Pure. Builds the ProvenanceSource quote/charStart/charEnd triple from
+ * offsets and verifies a model-supplied quote equals the sliced text, so a
+ * bad offset pair can never persist a quote absent from the source.
+ */
+
+export interface SpanProvenance {
+  quote: string;
+  charStart: number;
+  charEnd: number;
+}
+
+export type SpanProvenanceResult =
+  | { ok: true; provenance: SpanProvenance }
+  | { ok: false; error: "empty_span" | "out_of_range" | "quote_mismatch" };
+
+export function spanToProvenance(input: {
+  text: string;
+  start: number;
+  end: number;
+  /** Optional model-supplied quote to verify against the slice. */
+  quote?: string;
+}): SpanProvenanceResult {
+  const { text, start, end, quote } = input;
+  if (!Number.isInteger(start) || !Number.isInteger(end)) {
+    throw new TypeError("span offsets must be integers");
+  }
+  if (start < 0 || end > text.length || end < start) {
+    return { ok: false, error: "out_of_range" };
+  }
+  if (start === end) {
+    return { ok: false, error: "empty_span" };
+  }
+  const sliced = text.slice(start, end);
+  if (quote !== undefined && quote !== sliced) {
+    return { ok: false, error: "quote_mismatch" };
+  }
+  return { ok: true, provenance: { quote: sliced, charStart: start, charEnd: end } };
+}