Fidelity construct inventory: reference links, footnotes, raw HTML, frontmatter

[Mearman]

Research audit feeding the schema's fidelity vocabulary (ExaDev/document-schema.js#22, part of the DocumentPackage promotion ExaDev/document-schema.js#20). Markdown is the pole case that proves the model works even for a format with almost no machinery -- its constructs map almost entirely onto mechanisms the promotion is already defining:

• Reference-style link definitions ([ref]: url at document foot) -- a package-level reference table, the same shape as the styles table (Package-local referenced styles and group inheritance: compression-only, materialised on flatten document-schema.js#21).
• Footnotes (definition plus marker reference) -- the anchor/footnote vocabulary: extent-as-containment.
• Raw HTML blocks and inline HTML -- the residue channel's canonical use case: opaque, quarantined, never semantically interpreted, restorable on re-emission.
• Frontmatter -- metadata.
• GFM extensions to check for gaps: task list items, tables (already carried), strikethrough, autolinks.

Deliverable: the verdict table (semantic / residue / derivable) with example documents per candidate, and an explicit list of anything markdown carries that has no home in the proposed vocabulary -- expected to be empty or near-empty, which is itself the finding.

[Mearman]

Verified against the reader on origin/main (git grep per construct, citations are file:line on that ref), not spec recollection. Headline: markdown needs no new generic construct kind — every semantic verdict lands on a mechanism #22/#20/#21 already define (definitions table, anchor, link, ContentFormula, list-membership/tree fields). The expected near-empty finding holds.

Construct	Carried today	Verdict	Harmonisation target	Evidence
Reference link definitions ([label]: dest "title")	Resolve-and-drop. parseMarkdown builds the map and returns it, but lowerParsedMarkdown reads only parsed.document.children — the map dies at lowering; a definitions-only paragraph leaves no block behind	semantic	Package-level definitions table, same facility as the styles table (ExaDev/document-schema.js#21 riding #20). Resolved links themselves stay ContentRun.hyperlink per the reconciliation decision on #22	src/block/definitions.ts:66 (extract + consume); src/block/block.ts:782 (map returned); src/lower/lower.ts:258,275 (map ignored); fixtures src/block/block.test.ts:139-158,233 (forward-visible resolution, first-wins duplicates, empty-paragraph case)
Reference link form (full [t][l] / collapsed [t][] / shortcut [t])	Materialised to a concrete destination during inline parse; form and label spelling gone	derivable (the semantics — where the link points — survive on hyperlink; the label spelling is a serialisation choice restorable from the definitions table)	Nothing new — falls out of the definitions-table row above	src/inline/inline.ts:356-372 (inline → full → collapsed → shortcut, failure leaves literal ])
Footnotes ([^n] marker + definition)	Nothing. No code path, no AST node, no diagnostic. grep -i footnote over src/ is zero hits; the marker parses as a failed shortcut reference and stays literal text; the definition line fails the definition grammar (its "destination" is prose) and survives as a paragraph	semantic — but this is new reading work, not a mapping exercise	Marker = anchor; definition = definitions-table entry. Not a pure extent — per the standing decision on ExaDev/document-schema.js#22, a footnote is marker-plus-tail-definition, never one contiguous span	Absence: src/ast/ast.ts (no node type), src/diagnostics/diagnostics.ts:27-47 (no code); would-be paths src/inline/inline.ts:356-372, src/block/definitions.ts:66
Raw HTML blocks (7 kinds)	Preserved verbatim as literal text, styleId HTMLPreformatted (default), or dropped entirely by rawHtml: 'drop'. Never parsed	residue	The canonical residue-channel use case from #22: per-node source: { format, ... }, restorable on re-emission. Also fixes a live ambiguity — literal text that happens to look like a tag is indistinguishable from preserved HTML today (RAW_TEXT_TAG_AMBIGUITY exclusion)	src/html/html.ts (recogniser, all 7 block kinds + inline grammar); src/lower/lower.ts:130-141; codes md/raw-html-preserved-as-text, md/raw-html-dropped; fixtures src/diagnostics/diagnostics.test.ts:110-121, src/lower/lower.test.ts:281-290
Raw HTML inline	Same: preserved as run text (default) or dropped	residue	Per-run source channel, same as above	src/lower/inline.ts:57-62; same diagnostics
Frontmatter	Flat key: value subset only: title/author/subject/creator/date→createdIso/keywords. Unmapped keys → md/front-matter-key-unmapped + dropped; a non-key: value line (nested mapping, block list, multi-line scalar) is silently skipped	split — mapped keys semantic, everything else residue	Mapped keys → ContentDocument.metadata (already); the unmapped remainder and non-flat shapes → raw front-matter block in the package-level residue channel. No new vocabulary	src/lower/front-matter.ts:66-87 (switch + default-drop); emit inverse src/emit/front-matter.ts
GFM task lists	Carried, degraded: checked on the AST item becomes a checkbox-glyph text run prepended to the first paragraph, plus a task bit encoded into the minted numId. Lost entirely when the item's first block is a table or resolved image	semantic (carried, but as glyph text — not a first-class state)	A real checked/task field on the list-membership representation, replacing glyph text + numId encoding	src/ast/ast.ts:81; src/block/block.ts:685-700 (marker stripped); src/lower/lower.ts:165-208 (applyTaskCheckbox, false-return case documented)
GFM tables (incl. column alignment)	Fully carried: alignment → per-cell ContentParagraph.alignment; header-ness positional (row 0); widths invented evenly (diagnosed invention is page geometry, not widths)	nothing dropped	Existing ContentTable	src/lower/table.ts:27-47
Strikethrough	Carried → ContentRun.strike	nothing dropped	Existing run field	src/lower/inline.ts strikethrough case
Autolinks (CommonMark <...>, GFM extended bare)	Carried → ContentRun.hyperlink (mailto: prepended for email); the GFM extension becomes a link node with distinct text/destination, correctly	carried; the <...> spelling is derivable (emit re-derives it when text = destination)	ContentRun.hyperlink — per the standing decision, run-level links stay put and need no link node	src/lower/inline.ts:68-71; src/inline/gfm-autolink.ts (extension → link node, rationale in header); re-derivation src/emit/inline.ts:157-170
Link/image titles	Dropped everywhere: inline links, images (both run-degraded and resolved-block), and the definitions table's own titles (parsed, then die with the map)	semantic	link — exactly the "annotated link extent a flat run field cannot express" the #22 decision reserves link nodes for; ContentRun.hyperlink demonstrably cannot carry it	md/link-title-dropped; src/lower/inline.ts:72-84; src/lower/lower.ts:98; src/test-support/conformance-exclusions.ts (LINK_TITLE)
Code fence info string	Dropped (diagnosed) when non-empty	split — semantic for the language word, residue for the remainder	Language → an annotation on the code representation (a field, not a node kind); remainder (pandoc-style {.class #id} attributes) → residue. Uncertainty flagged below on real-world shape	md/code-block-info-string-dropped; src/lower/lower.ts:117-124
Math ($$ block, \(...\) inline, #53)	Carried as literal LaTeX text (styleId MathBlock; inline via a marker fontFamily), deliberately unparsed here	semantic — today's preserved-as-text is the interim, not the destination	ContentFormula — the canonical-plus-source pattern #22 itself cites; LaTeX as the source spelling beside whatever canonical form the schema settles	src/lower/lower.ts:143-152; src/lower/inline.ts:64-67; src/ast/ast.ts MarkdownMathInlineNode comment
Multi-block list item boundary	Flattened: ContentListMembership carries numId/level only — "one item, several blocks" and "several items" are indistinguishable; tables/images in an item additionally lose membership entirely	semantic (structural)	Item identity on the list-membership model (the schema major's list work), not a construct-vocabulary node	md/list-item-multi-block-flattened, md/list-item-block-unlisted; src/lower/lower.ts lowerListItem
Blockquote container / nesting depth	Carried degraded as indentLeftPt + Quote styleId; depth beyond 1 approximate, container boundary lost	semantic (structural)	A container representation in the schema major's tree — sibling of the item-boundary gap, not one of the five construct kinds	md/blockquote-nested-depth; src/lower/lower.ts lowerBlockquote; conformance-exclusions.ts (BLOCKQUOTE_STRUCTURE, ADJACENT_SAME_DEPTH)
Entity spelling (&amp; vs &#38; vs literal)	Value carried, raw spelling dropped	derivable — emit re-escapes as needed; same character, no meaning lost	None	src/ast/ast.ts:239; src/lower/inline.ts entity case
Serialisation choices (ATX/setext, bullet glyph, ./) delimiter, fence char, thematic-break char, CRLF, tight/loose)	Re-picked on emit; tight/loose and ordered start encoded into the numId, the rest not preserved	derivable	None — the writer's own style options	src/options/options.ts WriteMarkdownStyleOptions; src/shared/list-id.ts
Soft line break	Collapsed to a literal space (hard break survives as \n — the distinction lives)	derivable, with the honest caveat that this is the single largest conformance-exclusion bucket by count	None	conformance-exclusions.ts (SOFT_BREAK); src/lower/inline.ts softBreak/hardBreak cases

New generic kinds proposed

None. That is the finding: markdown's semantic verdicts decompose onto anchor (footnote markers), link (annotated extents carrying titles), the definitions table (reference definitions, footnote definitions), ContentFormula (math), and fields on models the #20 major already owns (task-checked on list membership, item boundary, blockquote container, code-language annotation). Nothing here is format-specific enough to justify a bespoke node kind — which is what "pole case" predicted.

Missed by the issue's candidate list

• Link/image titles — the largest genuine drop the candidate list omits: dropped on every path (inline link, image, definitions table), and the standing link-node decision already names its home.
• Code fence info string — the language word is cross-format meaning (highlighting, code style with language), not residue.
• Math ($$ / \(...\)) — a construct this package genuinely reads (issue 53) that the candidate list predates; verdict is semantic via ContentFormula, not the preserved-as-text interim.
• List item boundary and blockquote container — structural drops the content model makes today; they belong to the tree/membership work in the build(deps): bump document-schema.js from 2.5.2 to 2.5.3 #20 major rather than the construct vocabulary, but an inventory of "carried-but-dropped" would be incomplete without them.

Uncertainty

Real-world info strings beyond the first word: I have not surveyed how prevalent pandoc-style attribute syntax (```rust {.line-numbers}) is versus bare language words in the wild, so the semantic-word/residue-remainder split is a design proposal, not an observed distribution. Same caveat for frontmatter: the flat-subset reader matches the de facto key: value convention, but I have not measured how often real documents use nested shapes the reader silently skips. Pandoc also has inline footnotes (^[...]) with no GFM analogue — I have treated the marker-plus-tail-definition pair as the scope and inline notes as out of scope unless wanted.

[Mearman]

Footnotes are implemented in #69 — the first row of this inventory to reach real code, now that document-schema.js 4.2.0 has put construct boundary markers on ContentBlock.

Worth recording against the inventory itself, because the verdict this issue reached ("marker is anchor, definition is a definitions-table entry") is backwards on both halves once you read the published AnchorDescriptorSchema rather than the issue text:

• The definition is what becomes the anchor construct, with its body as the construct's extent. definition on the descriptor is a key into a package-level definitions table, and a flat ContentDocument has no root to carry one — but more to the point, a footnote body is block content that a string field could not have held whichever table it pointed at.
• The marker cannot be an anchor. src/construct.ts binds every kind to block scope and names inline anchors as waiting on a run-level extent mechanism that has not shipped. It is carried as a marked ContentRun with md/footnote-reference-preserved-as-text, which is a real remaining schema gap rather than a finished mapping.

The other rows here are unchanged. Raw HTML and the frontmatter remainder both still wait on ExaDev/document-schema.js#22's residue channel, which 4.2.0 did not ship and src/construct.ts explicitly declines to define as a construct field; reference-link definitions wait on the same definitions-table-is-DocumentPackage-only gap described above. Full detail in the comment on #66.