---
id: ESRC-WP-0002
type: workplan
title: "HTML and Markdown source representations"
domain: infotech
repo: evidence-source
status: finished
owner: codex
topic_slug: citation_evidence_mvp
created: "2026-07-08"
updated: "2026-07-09"
spec_refs:
  - README.md
  - docs/ADR-0001-extraction-boundary.md
  - docs/ADR-0003-html-markdown-representation.md
  - ../citation-engine/src/shared/document.ts
state_hub_workstream_id: "12f0b386-0df1-50d9-8cf7-4829d5257382"
---

# ESRC-WP-0002 — HTML and Markdown source representations

The PDF slice (ESRC-WP-0001) established the ingest boundary and contract shape.
This workplan extends ingest to HTML and Markdown sources, producing the same
`{ document, representation }` pair over engine-owned contracts.

## Decisions (ADR-0003)

- HTML maps to `representationType: "html-dom"`; Markdown to
  `"markdown-rendered"`.
- Pageless formats omit `pageMap`; `offsetMap` is a single synthetic page-1
  range covering `[0, canonicalText.length)`.
- Inline fixtures owned by this repo (no PII); PDF corpus rules unchanged.

## Sketch

```task
id: ESRC-WP-0002-T01
status: done
priority: medium
state_hub_task_id: "f875c025-2c08-56d7-bbde-60e0643a7b9c"
```
Define the HTML/MD representation contract with `citation-engine`; agree
`representationType` and any offset/page semantics for pageless formats.

```task
id: ESRC-WP-0002-T02
status: done
priority: medium
state_hub_task_id: "e7936d67-188d-50f3-8dc8-684c9f03fb4a"
```
Implement `ingestHtml` / `ingestMarkdown` in `src/html/` and `src/markdown/`,
reusing `fingerprintBytes` and the canonical-text normalizer.

```task
id: ESRC-WP-0002-T03
status: done
priority: medium
state_hub_task_id: "18fcce8a-92f6-5e52-b613-ffa52f18bc71"
```
Add fixture-driven contract tests mirroring the PDF suite; decide fixture
ownership per ADR-0002.