--- id: ESRC-WP-0001 type: workplan title: "Bootstrap standalone source repo from citation-evidence PDF slice" domain: infotech repo: evidence-source status: finished owner: codex topic_slug: citation_evidence_mvp created: "2026-06-21" updated: "2026-07-08" spec_refs: - INTENT.md - README.md - ../citation-evidence/src/source/README.md - ../citation-evidence/workplans/CE-WP-0002-pdf-review-slice.md - ../citation-evidence/wiki/ArchitectureOverview.md - ../citation-engine/README.md state_hub_workstream_id: "64771b5d-4b83-4848-a562-4b00aad017b2" --- # ESRC-WP-0001 — Bootstrap Standalone Source Repo This repo is no longer blocked on pure intent. The upstream umbrella repo already contains a small but real `src/source/` slice: PDF ingest, fingerprinting, canonical-text extraction, browser upload helpers, and a source-to-anchor round-trip integration test. What is missing here is the standalone package/tooling, a clean extraction boundary, and the downstream wire-up so `citation-evidence` consumes `evidence-source` instead of its local `src/source/` copy. This workplan extracts the current PDF slice first. It does not try to ship Markdown/HTML representations, richer metadata extraction, or citation recovery in the same pass; those become follow-on workplans once the PDF boundary is stable. ## Reviewed Repo State - `evidence-source` currently contains intent/docs/workplans only. There is no package manifest, source tree, test harness, or fixture corpus here yet. - `../citation-evidence/src/source/` already implements: `ingestPdf`, `extractPdf`, `fingerprintBytes`, `createPdfByteStore`, `ingestPdfFromFile`, and `resolvePdfViewerUrl`. - `../citation-evidence/tests/integration/anchor-source-roundtrip.test.ts` already covers the source-to-anchor contract and should remain an umbrella integration test rather than becoming a private test in this repo. - `../citation-engine` already exposes the shared contracts this repo should consume via `@citation-evidence/engine` and `@citation-evidence/engine/shared`. ## Dependency Order ```text T01 extraction boundary and import plan -> T02 standalone package/tooling scaffold -> T03 headless PDF ingest extraction -> T04 browser/session helper placement -> T05 subsystem test coverage and fixture ownership -> T06 downstream citation-evidence wire-up -> T07 repo docs, registry, and follow-on workplans ``` ## T01 — Lock the Extraction Boundary ```task id: ESRC-WP-0001-T01 status: done priority: high ``` Turn the current umbrella `src/source/` slice into an explicit extraction map. Decide and document: - which files move into `evidence-source` immediately, - which files stay in `citation-evidence` because they are app/session/viewer concerns, - which contracts must come from `@citation-evidence/engine/shared`, - which cross-subsystem tests stay upstream in the umbrella repo. Minimum outcome: - `pdf/ingest.ts`, `pdf/extract.ts`, and `pdf/fingerprint.ts` are confirmed as in-scope for this repo, - `pdf/byte-store.ts`, `pdf/upload.ts`, and `pdf/viewer-url.ts` are explicitly classified instead of carried over by default, - the extraction note points at the exact upstream files being replaced. Acceptance: there is a short boundary note or ADR in this repo and no part of the extraction relies on copying `citation-engine` shared types locally. ## T02 — Add Standalone Package and Tooling ```task id: ESRC-WP-0001-T02 status: done priority: high ``` Create the minimal standalone development surface for this repo. Add: - `package.json` with sibling-checkout dependency on `@citation-evidence/engine` via `link:../citation-engine`, - TypeScript, Vitest, and ESLint configuration, - a `src/` tree for extracted code, - a `tests/` tree and fixture location strategy, - documented repo-local commands for `test`, `typecheck`, and `lint`. Keep the first extraction small: one package is enough until multiple formats or distribution constraints justify a more granular package layout. Acceptance: this repo can install dependencies and run meaningful test, typecheck, and lint commands without depending on `citation-evidence` as its runtime host. ## T03 — Extract the Headless PDF Ingest Core ```task id: ESRC-WP-0001-T03 status: done priority: high ``` Port the current headless PDF ingest pipeline from `../citation-evidence/src/source/pdf/` into this repo. Scope: - `ingestPdf` - `extractPdf` - `fingerprintBytes` Requirements: - preserve the current PDF behavior from `CE-WP-0002-T03`, - import `Document`, `DocumentRepresentation`, `newId`, and `normalize` from `@citation-evidence/engine/shared`, - keep ingest pure over bytes and extraction results, - do not mix persistence, viewer state, or React concerns into the core. Acceptance: a consumer can pass PDF bytes to this repo and receive a valid `{ document, representation }` pair using only engine-owned contracts. ## T04 — Place the Browser and Session Helpers Deliberately ```task id: ESRC-WP-0001-T04 status: done priority: high ``` The upstream source slice currently includes browser-facing helpers for local uploads and `blob:` URL management. Those are useful, but they are not the same thing as headless ingest. Decide one of two outcomes: 1. Keep these helpers in `evidence-source`, but isolate them clearly under a browser-focused surface with documentation that distinguishes them from the headless core. 2. Leave them in `citation-evidence` / `citation-work` because they are viewer or session infrastructure, and remove them from this repo's initial scope. Modules to classify: - `pdf/byte-store.ts` - `pdf/upload.ts` - `pdf/viewer-url.ts` Acceptance: there is no ambiguous mix of headless ingest code and browser/session-only behavior after extraction. ## T05 — Rebuild Subsystem Test Coverage Here ```task id: ESRC-WP-0001-T05 status: done priority: high ``` Re-establish the source repo's own verification surface. Port or recreate: - fixture-driven ingest contract tests, - fingerprint determinism tests, - PDF extraction invariants around `canonicalText`, `pageMap`, and `offsetMap`, - tests for whichever browser/session helpers remain in-scope after T04, - PDF.js worker/test setup for Node-based runs. Also decide fixture ownership: - copy the PDF fixture corpus into this repo, - or define a stable shared-fixture path that does not make this repo's tests implicitly depend on the umbrella app layout. Acceptance: `evidence-source` has its own subsystem test suite, while the source-to-anchor round-trip remains an umbrella integration test. ## T06 — Switch `citation-evidence` to the Extracted Repo ```task id: ESRC-WP-0001-T06 status: done priority: high ``` Finish the extraction by making the umbrella consume this repo instead of its local `src/source/` implementation. Required steps: - add `@citation-evidence/evidence-source` or equivalent local-link dependency strategy for sibling development, - replace local source imports in `citation-evidence` with imports from this repo, - keep the existing source-to-anchor integration test upstream and make it run across the repo boundary, - remove or tombstone the extracted local source files once downstream is green. Acceptance: the umbrella app and its integration tests use the extracted source package rather than the local `src/source/` copy for the PDF slice. ## T07 — Finish Repo Docs and Queue the Next Workplans ```task id: ESRC-WP-0001-T07 status: done priority: medium ``` Once the PDF extraction lands, make the repo describe its actual state. Update: - `README.md` to reflect real install/dev usage, - `SCOPE.md` to replace placeholders with the actual current boundary, - registry metadata so this repo no longer advertises "intent only" if it now provides reusable ingest functionality. Then split the deferred work into separate workplans rather than growing this file indefinitely: - Markdown/HTML representations, - metadata enrichment beyond current pass-through options, - local citation recovery and external source discovery hooks. Acceptance: this repo no longer presents itself as an empty placeholder, and the next feature phases have their own workplan files.