Files

tegwick 2f25f99cae Implement CE-WP-0001 Foundations: TS scaffold, lint boundaries, normalize v1, fixtures

T01 Toolchain — vite + pnpm 9.15 + React 18 + strict TS (ADR-0001).
T02 Folder layout — src/{shared,engine,anchor,source,binder,work,app}/
    mirroring the future subsystem split, with path aliases.
T03 Boundary lint — eslint-plugin-boundaries enforcing the dependency
    edges from wiki/DependencyMap.md §4; verified by a violating fixture.
T04 Canonical normalization v1 — src/shared/text/normalize.ts with
    NORMALIZE_VERSION=1; 10/10 vitest covering ligatures, CRLF, soft
    hyphens (including line-break reassembly), mixed whitespace.
T05 PDF fixture corpus — 7 user-supplied German PDFs in fixtures/pdfs/
    (gitignored binaries) plus a manifest with verbatim known-good
    quotes and page counts, ready for CE-WP-0002 selector tests.
T06 README upgrade — umbrella README points at wiki/docs/workplans
    and documents the dev workflow.
T07 ADR-0002..0006 stubs in docs/decisions/.

Toolchain end-to-end: pnpm install + lint + typecheck + test all green.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-05-25 00:13:03 +02:00

1.6 KiB

Raw Blame History

ADR-0003 — W3C Web Annotation mapping: native model or import/export?

Status: proposed
Date: 2026-05-24
Workplan: CE-WP-0001-T07 (stub)

Context

The PRD mandates compatibility with the W3C Web Annotation Data Model (FR-009 of wiki/ProductRequirementsDocument.md). Selector shapes already mirror the W3C taxonomy. Open question: do we serialize our internal types as JSON-LD Web Annotations natively, or maintain our own JSON shape with an import/export mapping?

The choice affects: storage format, the public API of evidence-source's ingest/export paths, what "compatible" means when a user imports an existing W3C annotation collection, and how much our internal model can diverge from the spec (e.g. our EvidenceItem has no W3C analogue).

Options

A. Native JSON-LD as the canonical store
- Pros: maximally interoperable; no mapping layer to keep in sync.
- Cons: JSON-LD adds verbosity and context resolution; our extensions (EvidenceItem, EvidenceLink, EvidenceSet) need custom JSON-LD contexts. Bad fit for an in-memory MVP.
B. Internal model + import/export mapping (currently assumed)
- Pros: terse internal types; clean fit for wiki/SharedContracts.md. Mapping only runs at the system boundary.
- Cons: two shapes to maintain; subtle divergence risk.
C. Hybrid — internal model that is a strict superset of W3C JSON shape
- Pros: serializes losslessly to W3C without a full JSON-LD context.
- Cons: ties internal naming to W3C naming forever, which constrains future extensions.

Decision

(blank — required before evidence-source ships its first export path.)

Consequences

(blank)

1.6 KiB Raw Blame History