coulomb/evidence-source
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
evidence-source/SCOPE.md
tegwick cb93c322c0
All checks were successful
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / container-smoke (push) Successful in 2s
Details
feat(pdf): extract standalone PDF ingest package (ESRC-WP-0001) 
Bootstrap evidence-source from the citation-evidence src/source PDF slice.

- Headless core (src/pdf): ingest/extract/fingerprint, importing domain
  contracts from @citation-evidence/engine/shared (no local copies)
- Browser upload helpers isolated under src/browser behind a ./browser
  entry point, with an eslint boundary keeping the core browser-free
- pnpm/TS/vitest/eslint scaffold; 52 tests (contract + determinism)
- Fixtures resolved from the sibling citation-evidence checkout, not
  duplicated (real PII) — see docs/ADR-0002; suites skip when absent
- Boundary + fixture decisions recorded as docs/ADR-0001 / ADR-0002
- README/SCOPE rewritten; capability.infotech.pdf-evidence-ingest
  registered, NO_CAPABILITIES removed
- Follow-on workplans ESRC-WP-0002..0004 queued; ESRC-WP-0001 finished

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-08 20:55:28 +02:00

3.3 KiB
Raw Blame History

SCOPE

This file helps you quickly understand what this repository is about, when it is relevant, and when it is not. It is intentionally lightweight and may be incomplete.

One-liner

Headless PDF ingest that turns document bytes into engine-owned evidence contracts (fingerprint, canonical text, page/offset maps).

Core Idea

The rest of the citation-evidence ecosystem (anchoring, evidence linking, binders) needs a stable, runtime-agnostic way to go from raw document bytes to a Document + DocumentRepresentation. This repo owns that transformation for PDFs — pure over bytes, no persistence, no viewer, no UI framework.

In Scope

  • PDF byte ingest → { document, representation } (ingestPdf)
  • PDF text extraction → canonical text + page map + gap-free offset map (extractPdf)
  • SHA-256 byte fingerprinting (fingerprintBytes)
  • Browser upload helpers behind a separate entry point (createPdfByteStore, ingestPdfFromFile)

Out of Scope

  • HTML / Markdown representations (deferred — see workplans/)
  • Persisting documents or representations (caller's job)
  • Viewer URL resolution and blob-vs-fixture policy (stays in citation-evidence)
  • Citation recovery / external source discovery (deferred)
  • Defining domain contracts — those are owned by citation-engine

Relevant When

  • You have PDF bytes and need engine-shaped evidence contracts
  • You need a deterministic content fingerprint of document bytes
  • You are wiring a new consumer to ingest without pulling in a viewer

Not Relevant When

  • You need HTML/Markdown ingest (not yet implemented)
  • You need viewer/session/UI behavior (see citation-evidence)
  • You are changing the Document/DocumentRepresentation contract (see citation-engine)

Current State

  • Status: active
  • Implementation: partial (PDF slice implemented; HTML/MD and recovery deferred)
  • Stability: evolving
  • Usage: internal (consumed by citation-evidence across the repo boundary)

How It Fits

  • Upstream dependencies: citation-engine (@citation-evidence/engine/shared)
  • Downstream consumers: citation-evidence (umbrella app)
  • Often used with: citation-engine, citation-evidence

Terminology

  • Preferred terms: ingest, canonical text, fingerprint, representation
  • Also known as: "source" (its former location was citation-evidence/src/source/)
  • Potentially confusing terms: "representation" (a derived view of a document, not the document itself)

Related / Overlapping Repositories

  • citation-engine — owns the shared Document/DocumentRepresentation contracts this repo produces
  • citation-evidence — umbrella app that consumes this ingest core; still owns viewer-url resolution

Getting Oriented

  • Start with: README.md, then docs/ADR-0001-extraction-boundary.md
  • Key files / directories: src/pdf/ (headless core), src/browser/ (upload helpers)
  • Entry points: src/index.ts (headless), src/browser/index.ts (browser)

Provided Capabilities

  • capability.infotech.pdf-evidence-ingest — headless PDF → evidence contracts (see registry/capabilities/)

Notes

Fixture corpus is owned upstream by citation-evidence and resolved from a sibling checkout (ADR-0002); it is not duplicated here.