Complete the Compact DOM fidelity contract and html5lib parity

[dv00d00]

Current status

Compact parsing now constructs directly through AngleSharp's handle-oriented tree builder into an arena backed by integer handles and pooled columns. It does not build an intermediate mutable or read-only wrapper tree.

Already present on main:

• public string, character-memory, byte-memory, and bounded async stream inputs;
• FrozenColumns and Packed publication paths;
• focused differential coverage for foster parenting, formatting adoption, templates, SVG/MathML integration points, malformed markup, text ownership, and both layouts;
• a maintained CompactBuildStageBenchmark for arena setup, combined construction, and publication;
• documented retained-layout and performance decisions in docs/COMPACT_DOM_DECISION.md.

The remaining gap is a precise full-fidelity contract and broader tree-construction parity, not another public parser-profile hierarchy.

Remaining work

1. Document the fidelity contract

• State exactly what the default Compact parser retains and suppresses. Today the default suppresses comments and processing instructions.
• Document how caller-provided HtmlParserOptions opt back into additional node kinds and which browser-only behaviors are intentionally unsupported.
• Keep extraction-oriented suppression as explicit parser/plan policy rather than a second construction architecture.

2. Adopt a tree-construction corpus

• Differentially compare canonical Compact and standard AngleSharp trees over the relevant html5lib tree-construction corpus.
• Cover comments, doctypes, whitespace-sensitive text, duplicate attributes, malformed EOF, templates, foster parenting, adoption agency, implied elements, and foreign content.
• Run the corpus across both FrozenColumns and Packed output where applicable.

3. Complete performance decomposition

The current stage benchmark separates arena setup, combined construction, and publication. Extend measurement only where it changes a decision:

• byte-to-UTF-16 decoding;
• tokenizer/tree-builder work versus arena mutation;
• publication and retained-text ownership;
• name/attribute classification and wrapper/reference counts that remain after the handle seam.

Use canonical-tree parity as the gate for every optimization.

Acceptance criteria

• The default and full-fidelity Compact contracts are documented without requiring a new public named preset.
• Compact and standard AngleSharp canonical trees agree across the adopted tree-construction corpus, with intentional differences listed explicitly.
• Both FrozenColumns and Packed layouts pass the applicable parity matrix.
• Byte input has enough stage decomposition to identify the dominant remaining construction/publication cost.
• At least one highest-cost candidate is benchmarked A/B/A and either retained with evidence or rejected and removed.
• The relationship to lexical streaming semantics and Feed stream queries corrected HTML tree-construction topology #42 remains explicit.

Non-goals

• Mutable DOM compatibility, scripting, layout, browser events, or style processing.
• Raw UTF-8 storage as a prerequisite for the retained full-fidelity lane.
• Post-parse mutation/rewrite APIs.
• Public storage handles, arena columns, or diagnostic machinery.

[dv00d00]

2026-08-20 triage: this is now the sole corrected-topology/fidelity epic. Keep the contract documentation and html5lib canonical-tree parity as the acceptance gate. Performance decomposition is conditional: run it only after parity exposes a cost or a concrete consumer requires a decision. The rejected speculative TextRef child #44 is no longer part of the roadmap.