feat(utils): add source-span resolver for claim-packet provenance

[jeffgreendesign]

Pure utility that verifies a claim's quote against its source text and
resolves the exact character span it occupies. This is the provenance
invariant for future source-backed claim packets: a quote must be present
in the source (anchored to chunks.content, not raw_content, since the
chunker normalizes/trims before computing offsets) before any claim is
stored.

• resolveSourceSpan / isQuoteSupported / requireSourceSpan
• exact case-sensitive matching by default; opt-in whitespace-normalized
  matching that still maps offsets back to the original source
• requireSourceSpan throws ValidationError on unsupported quotes
• 24 unit tests covering exact/normalized/unicode/rejection paths

No schema, DB, tool, API, dashboard, search, or LLM changes.

Co-Authored-By: Claude Opus 4.8 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_018uJvN394ihHqDRUkWjPh7H

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
dashboard	Building		Jun 21, 2026 11:10am
textrawl	Ready	Preview, Comment	Jun 21, 2026 11:10am

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a757e04f-755d-4f36-b884-c726cffa72a0

📥 Commits

Reviewing files that changed from the base of the PR and between 4d287d1 and a6d245f.

📒 Files selected for processing (2)

• src/utils/__tests__/source-span.test.ts
• src/utils/source-span.ts

---

Walkthrough

A new src/utils/source-span.ts module is introduced containing three exported types (SourceSpan, ResolveSpanOptions, SpanResolution), two internal helpers (foldWhitespace, foldQuote), and three exported functions. resolveSourceSpan performs a two-step match: first an exact indexOf on quote.trim(), then—when normalizeWhitespace is enabled—a normalized match that folds whitespace runs in both the quote and source while tracking original index mappings. isQuoteSupported wraps it as a boolean check; requireSourceSpan returns the span or throws ValidationError with the failure reason. A corresponding Vitest suite in src/utils/__tests__/source-span.test.ts covers all match paths, rejection reasons, case sensitivity, and UTF-16 offsets for multi-byte characters.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly and clearly summarizes the main change: adding a source-span resolver utility for handling claim-packet provenance verification.
Description check	✅ Passed	The description covers the purpose, key functions, matching modes, test coverage, and explicitly clarifies out-of-scope changes, but is missing the required checklist items and type-of-change selection from the template.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/rag-enhancement-research-4af047

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}