evidence-source/docs/ADR-0001-extraction-boundary.md

# ADR-0001 — PDF extraction boundary for `evidence-source`

- **Status:** accepted
- **Date:** 2026-07-08
- **Workplan:** ESRC-WP-0001 (T01)

## Context

`evidence-source` is being bootstrapped from the PDF slice that currently
lives in `../citation-evidence/src/source/`. That slice already implements a
working, tested headless ingest pipeline plus a set of browser/session helpers.
This ADR locks *which* files cross the boundary, *where* they land, and *which
contracts* they may depend on, so the extraction is mechanical rather than a
series of ad-hoc judgement calls.

The shared domain contracts (`Document`, `DocumentRepresentation`, `PageMap`,
`OffsetMap`, `newId`, `normalize`, …) are owned by `citation-engine` and are
published from its package as `@citation-evidence/engine/shared`. Nothing in
this extraction copies those types locally.

## Decision

### In-scope — headless ingest core (`src/pdf/`)

Moved into this repo immediately; these are pure, runtime-agnostic, and the
reason this repo exists:

| Upstream file | New home | Notes |
| --- | --- | --- |
| `src/source/pdf/ingest.ts` | `src/pdf/ingest.ts` | `ingestPdf` |
| `src/source/pdf/extract.ts` | `src/pdf/extract.ts` | `extractPdf` |
| `src/source/pdf/fingerprint.ts` | `src/pdf/fingerprint.ts` | `fingerprintBytes` |

The only change to these files is the import specifier: `@shared/*` becomes the
published package subpath `@citation-evidence/engine/shared`.

### In-scope but explicitly isolated — browser helpers (`src/browser/`)

Useful for browser upload flows, but *not* headless ingest. They are kept in
this repo behind a separate `./browser` entry point and documented as
browser-facing so they never blur into the headless core:

| Upstream file | New home | Notes |
| --- | --- | --- |
| `src/source/pdf/byte-store.ts` | `src/browser/byte-store.ts` | in-memory `blob:` byte store |
| `src/source/pdf/upload.ts` | `src/browser/upload.ts` | `ingestPdfFromFile` — thin wrapper over `ingestPdf` |

### Out of scope — stays in `citation-evidence`

| Upstream file | Reason |
| --- | --- |
| `src/source/pdf/viewer-url.ts` | Pure viewer/app concern: it encodes the umbrella's `/fixtures/pdfs/…` URL convention and the app's blob-vs-fixture fallback policy. It consumes `PdfByteStore` (a type this repo now owns) but the resolution *policy* belongs to the viewer. It stays upstream and imports the `PdfByteStore` type from this package. |
| `tests/integration/anchor-source-roundtrip.test.ts` | Cross-subsystem (source ↔ anchor) contract. Remains an umbrella integration test; it is not a private test of this repo. |

### Contracts

All domain contracts come from `@citation-evidence/engine/shared`. This repo
declares `@citation-evidence/engine` as a `link:../citation-engine` dependency
and never re-declares `Document`/`DocumentRepresentation`/etc. locally.

### Fixture corpus

The PDF fixture corpus (`../citation-evidence/fixtures/pdfs/`) is **not** copied
into this repo. The files are real personal/legal documents (utility statements,
court letters, admission forms) containing PII; duplicating them into a package
that advertises reusable ingest capability is undesirable. Instead this repo's
tests resolve the corpus from the sibling checkout (default
`../citation-evidence/fixtures/pdfs`, override via
`EVIDENCE_SOURCE_FIXTURE_DIR`). This mirrors the sibling-checkout `link:` model
already used for the engine dependency and keeps the corpus single-owned
upstream. See ADR-0002.

## Consequences

- The extraction is a 5-file move (3 core + 2 browser) plus import rewrites.
- `citation-evidence` keeps `viewer-url.ts` and the round-trip integration test.
- Tests here require a sibling `citation-evidence` checkout for fixtures — an
  accepted coupling, identical in spirit to the engine `link:` dependency.