generated from coulomb/repo-seed
tegwick
2f25f99cae
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>
45 lines
1.6 KiB
Markdown
45 lines
1.6 KiB
Markdown
# 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)
|