tegwick
df6acad828
fix-consistency C-06/C-11 registered ESRC-WP-0002..0004 and the ESRC-WP-0001 tasks; IDs written back into the workplan files. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
258 lines
8.4 KiB
Markdown
258 lines
8.4 KiB
Markdown
---
|
|
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
|
|
state_hub_task_id: "ec3eb16b-cbc1-4a12-af66-5e5b8b6a51ca"
|
|
```
|
|
|
|
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
|
|
state_hub_task_id: "ddf957d8-51bb-4767-9399-f6a3966319fa"
|
|
```
|
|
|
|
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
|
|
state_hub_task_id: "8fa78d4c-8859-4e74-b5e6-245a1ea0f3cc"
|
|
```
|
|
|
|
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
|
|
state_hub_task_id: "c6d27e23-4eaa-4fc7-9d6c-30bab0e003ad"
|
|
```
|
|
|
|
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
|
|
state_hub_task_id: "2724bf73-c93e-4f6e-8709-07b4f9d7df5e"
|
|
```
|
|
|
|
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
|
|
state_hub_task_id: "41bfbb26-e3d3-46f2-9bad-64e3e8eab334"
|
|
```
|
|
|
|
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
|
|
state_hub_task_id: "ca080b04-5c8a-46e4-be87-8592d448f20b"
|
|
```
|
|
|
|
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.
|