evidence-source/workplans/ESRC-WP-0001-bootstrap-standalone-source-repo.md

id	type	title	domain	repo	status	owner	topic_slug	created	updated	spec_refs	state_hub_workstream_id
ESRC-WP-0001	workplan	Bootstrap standalone source repo from citation-evidence PDF slice	infotech	evidence-source	finished	codex	citation_evidence_mvp	2026-06-21	2026-07-08	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	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

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

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

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

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

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

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

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

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.