moxml 0.5.148 → 0.5.150

data/docs/_pages/divergences.adoc

@@ -19,72 +19,121 @@ here. Contract:
 |===
 | ID | Adapter(s) | Divergence
 
-| D-01
-| oga
-| The `xmlns:` default-namespace XPath idiom is unsupported by oga's
-own engine (explicit bindings work). Pinned in
-`spec/consistency/xpath_idioms_spec.rb`.
-
 | D-02
 | oga
 | Raw CR preserved in text content — §2.11 EOL normalization not
-applied at parse. Pinned in `spec/consistency/eol_normalization_spec.rb`.
+applied at parse. Decided permanent: normalization belongs at the
+engine's parse layer; a facade read arm would only cover the read
+verbs it touches and change content/source-position consistency.
+Pinned in `spec/consistency/eol_normalization_spec.rb`.
 
 | D-03
 | ox, headed_ox
-| `
` character references collapse to LF. Pinned in
+| `
` character references collapse to LF. Decided permanent:
+the reference-vs-literal distinction is lost at parse, so no facade
+read can recover it. Pinned in
 `spec/consistency/eol_normalization_spec.rb`.
 
-| D-04
-| oga
-| The XML declaration surfaces as a `<?xml?>` PI; PI content keeps its
-separator space. Pinned in `spec/moxml/c14n/adapter_delegation_spec.rb`.
-
 | D-05
 | ox, headed_ox
-| PI content dropped at parse. Pinned in
-`spec/moxml/c14n/adapter_delegation_spec.rb`.
+| PI content is dropped on parse for element-child PIs, XPath-minted
+wrappers, and quoted data (some document-level shapes retain it).
+Pinned in `spec/moxml/c14n/adapter_delegation_spec.rb` and the
+taxonomy differential.
 
 | D-06
 | ox, headed_ox
 | Comment content padding stripped at parse. Pinned in
 `spec/moxml/c14n/subset_spec.rb`.
 
-| D-07
-| rexml
-| `text()` node tests return no text nodes (adapter XPath capability
-gap, both axes). Pinned in `spec/moxml/c14n/subset_spec.rb`.
-
-| D-08
-| c14n subsystem
-| Document-level PI/comment rendering not yet implemented (all
-adapters; a subsystem TODO, not an engine divergence). Tracked in
-`TODO.c14n/09-comments-pis-tests.md`.
-
 | D-09
 | oga, ox, headed_ox, libxml, leptris
-| Element-level `to_xml(indent:)` silently ignored (libxml emits a
-partial, unindented newline form). Document-level HTML/XHTML
-indentation is honored on leptris/nokogiri and raises on incapable
-engines. Pinned in
+| Element-level `to_xml(indent:)` is not supported by these engines:
+the facade raises the named `Moxml::AdapterError` instead of
+answering unindented output; `indent: 0` and the no-option path stay
+common. The engine-level `serialize(indent:)` lane (direct
+`Adapter.serialize`) still ignores or partially applies the knob.
+Pinned in `spec/moxml/element_indent_spec.rb` and
 `spec/moxml/adapter/shared_examples/adapter_contract.rb`.
 
 | D-10
 | ox, headed_ox
-| SAX emits no separate CDATA/comment/processing-instruction events
-(sequences fold into text or are dropped). Pinned in
+| SAX reports no separate CDATA/comment/processing-instruction
+events. A handler that subscribes to one of those families gets the
+named `Moxml::NotImplementedError` — loud, never a silently
+incomplete stream. Text-only handlers still receive CDATA folded
+into character data as the engine delivers it. Pinned in
 `spec/moxml/sax_spec.rb`.
 
 | D-11
 | oga
 | SAX parse is more lenient with malformed input than the model's
-error authority. Pinned in `spec/moxml/sax_spec.rb`.
+error authority. Decided permanent: the engine owns error reporting,
+and pre-validating with a strict parse would defeat the streaming
+lane. Pinned in `spec/moxml/sax_spec.rb`.
 
-| D-12
+| D-13
 | ox, headed_ox
-| The XPath translation covers a subset: no positional predicates,
-attribute-value predicates, namespace/default-namespace tests,
-`position()`/`count()`, `text()`, boolean expressions, `child::`/
-`descendant::` axes, or unions. Pinned in
-`spec/moxml/xpath_capabilities_spec.rb` and `spec/moxml/node_spec.rb`.
+| Inter-element whitespace-only text nodes are dropped at parse
+(node counts and leading/trailing text differ from the other
+adapters). Surfaced by the taxonomy differential. Pinned in
+`spec/consistency/differential_taxonomy_spec.rb`.
+
+| D-14
+| oga
+| Processing-instruction content leaks into text reads (oga's own
+`text` folds PIs; the model says only text nodes contribute).
+Surfaced by the taxonomy differential. Pinned in
+`spec/consistency/differential_taxonomy_spec.rb`.
+
+| D-15
+| rexml
+| The whitespace text node between a pre-root PI and the root is
+retained (other adapters drop it). Surfaced by the taxonomy
+differential. Pinned in `spec/consistency/differential_taxonomy_spec.rb`.
+
+| D-16
+| rexml
+| Entity-expansion guard caps huge documents (~10k expansions) and
+raised a bare engine error — the facade now names it a ParseError;
+the cap itself remains (nokogiri's HUGE lane has no such cap).
+Surfaced by the taxonomy differential. Pinned in
+`spec/consistency/differential_taxonomy_spec.rb`.
+
+| D-17
+| oga
+| The strict parse lane does not validate nesting well-formedness
+(oga's strict is lexer-strict, not well-formedness-strict); bad
+nesting parses where other adapters raise. Surfaced by the taxonomy
+differential. Pinned in
+`spec/consistency/differential_taxonomy_spec.rb`.
+
+| D-18
+| leptris, oga, ox, headed_ox
+| Strict parse accepts invalid UTF-8 byte sequences (no encoding
+validation at parse; the bytes flow through as binary). The
+validating adapters (nokogiri, rexml, libxml) raise the named
+ParseError. On leptris the facade raises the named ParseError in the
+strict lane (default-UTF-8 rule; prolog-declared non-UTF-8 encodings
+own their validity) pending engine-side validation —
+leptris-ruby#514. Surfaced by the taxonomy differential. Pinned in
+`spec/consistency/differential_taxonomy_spec.rb`.
+
+| D-19
+| nokogiri, libxml
+| Adjacent text-like leaves (CDATA next to CDATA or text) coalesce
+into a single text node on the libxml2 lane; oga, rexml, ox,
+headed_ox, and leptris keep them as distinct nodes. The `text`
+answer is identical — the node count and kinds differ. The model is
+silent on text-node coalescing (an open decision). Surfaced by the
+generated metamorphic differential (M5). Pinned in
+`spec/consistency/metamorphic_properties_spec.rb` through
+`InputGenerator::FEATURE_EXEMPT`.
+
+| D-20
+| rexml
+| Trailing whitespace in processing-instruction data is dropped at
+parse (the engine's instruction content is trimmed); leading
+separator runs collapse per the model. Pinned in the taxonomy
+differential (`pi trailing whitespace`, face `pi_content`).
 |===

data/docs/_pages/ecosystem.adoc

@@ -0,0 +1,62 @@
+---
+title: Ecosystem
+nav_order: 12
+---
+
+== Ecosystem closure
+
+Moxml's consumer test: **no consumer needs to know which engine is
+running, and every consumer suite runs against moxml main in this
+repository's CI.** The dependent matrix
+(`.github/workflows/dependent-tests.yml`, repo list in
+`dependent-repos.json`) binds each consumer to the checkout at the
+workflow's ref and runs its own suite — the consumer's suite is the
+validation target, never a stand-in.
+
+=== Dependent matrix
+
+[cols="2,1,3",options="header"]
+|===
+| Repository | Tools | Suite (validated 2026-10-21)
+
+| `lutaml/lutaml-model` | — | 6213+ examples green on the released pair
+
+| `lutaml/canon` | — | 2573 examples, 0 failures locally; in CI the Windows leg fails one JSON-engine parity example (`yaml_engine_parity_spec.rb:123`, the resolved json gem's duplicate-key verdict) — unrelated to XML processing, owner-held in canon
+
+| `metanorma/metanorma-standoc` | ghostscript | 627 examples green in CI on main (the boilerplate-fixture failure seen during the 04/05 validation was resolved by the 06 adapter fixes; a few local-only failures still need generated assets)
+
+| `metanorma/metanorma-ietf` | xml2rfc | 405 examples, 0 failures
+
+| `lutaml/expressir` | — | 2026 examples, 0 failures
+
+| `metanorma/svg_conform` | — | 350 examples, 0 failures
+|===
+
+=== Seam audit
+
+An *engine-direct seam* is consumer code that reaches past the facade
+into the engine. Each is retired with a facade capability, or kept as
+a declared, decided lane.
+
+[cols="1,2,3",options="header"]
+|===
+| Consumer | Use | Disposition
+
+| canon | HTML5 parse-lint (`parse_html(collect_errors:)`) | **Facade capability shipped**: `Moxml::Context#parse_html` forwards `collect_errors` and `Document#parse_diagnostics` answers the §13.2.5 token stream with code/line/column. canon adopts it in canon#281, which is owner-held (moxml does not merge canon PRs).
+
+| canon | c14n native delegation (`doc.native.c14n`) | **Decided lane**: canon owns the c14n reference implementation and byte-probes the engine against its Ruby path; it is the backend behind moxml's own native delegation.
+
+| metanorma-standoc | RELAX NG validation (`Leptris::XML::RelaxNG`) | **Facade capability added**: `Moxml::RelaxNG` (`Context#relaxng` / `#relaxng_file`, `valid?` / `validate` / `validate_errors`), loud `NotImplementedError` on engines without an RNG validator. Consumer migration tracked in standoc.
+
+| svg_conform | engine parsing and SAX (`Leptris::XML.parse`, `Leptris::XML::SAX`) | **Consumer work**: moxml's `Context#parse` and `Moxml::SAX` cover both; tracked for the migration.
+
+| standoc / svg_conform | hard adapter selection (`Moxml.new(:leptris)`) | **Supported**: adapter selection is the deployment decision the facade exists for.
+|===
+
+=== Cap policy
+
+A consumer pin (for example `moxml ~> 0.5.84`) is a dependency
+constraint, not a knowledge of the engine. Caps move only after the
+consumer's own suite runs green against the released pair — the
+relaton-only lesson: evidence from one dependent suite does not
+transfer to another.

data/docs/_pages/headed-ox-limitations.adoc

@@ -571,4 +571,4 @@ HeadedOx v1.2 successfully delivers on its core promise: **fast XML parsing with
 - Heavy DOM modifications required
 - 100% feature parity is critical
 
-The documented limitations are transparent, well-understood, and unlikely to affect most XML processing workflows. HeadedOx fills an important niche in the Ruby XML ecosystem as the "fast XPath" option.
+The known limitations are transparent, well-understood, and unlikely to affect most XML processing workflows. HeadedOx fills an important niche in the Ruby XML ecosystem as the "fast XPath" option.

data/docs/_pages/headed-ox.adoc

@@ -658,7 +658,7 @@ following = items[current_index + 1..-1]
 ----
 Total Tests:    2,008
 Passing:        1,992 (99.20%)
-Skipped:        16 (0.80% - documented Ox limitations)
+Skipped:        16 (0.80% - known Ox limitations; see link:divergences.html[the register])
 Failures:       0
 
 Test Categories:
@@ -686,7 +686,7 @@ Production Use:    Ready
 
 === Known limitations with test status
 
-All 16 limitations are comprehensively documented:
+All 16 limitations are catalogued below:
 
 . **Attribute wildcards** (3 tests) - Ox `locate()` doesn't support `@*`
 . **Namespace introspection** (4 tests) - Ox doesn't expose namespace data

data/docs/_pages/index.adoc

@@ -8,6 +8,10 @@ nav_order: 1
 This section covers the fundamental concepts and essential information for
 working with Moxml.
 
+Start with link:why-moxml[Why Moxml] for the invariant and the evidence
+apparatus, then link:model-coverage[Model coverage] for the
+adapter-by-adapter proof.
+
 === Topics covered
 
 link:installation[Installation]::

data/docs/_pages/model-coverage.adoc

@@ -0,0 +1,57 @@
+---
+title: Model coverage
+nav_order: 5
+---
+
+== Model coverage
+
+Every face family of the
+link:../_references/processing-model[processing model] is governed on
+every adapter: **equivalent** by contract, **loud** (a named raise), or
+a **registered divergence**. The table below is generated from the
+coverage matrix that the consistency audit enforces, so the published
+proof cannot drift from the tested proof.
+
+The evidence chain is checkable at every link: the model section names
+the specs that enforce it (`Pins::`), each enforcing spec cites the
+model section, the matrix maps every face family to its section and
+pin, and the divergence IDs resolve in
+link:divergences.html[the register].
+
+// MODEL-COVERAGE:BEGIN
+Generated by `bundle exec rake docs:coverage` from the coverage matrix and the divergence register. Do not edit by hand: `spec/consistency/published_docs_spec.rb` fails when this block is stale.
+
+[cols="4,1,1,1,1,1,1,1",options="header"]
+|===
+| Face family | nokogiri | oga | rexml | ox | headed ox | libxml | leptris
+| document order and children listing | equivalent | equivalent | equivalent | equivalent | equivalent | equivalent | equivalent
+| name resolution | equivalent | equivalent | equivalent | equivalent | equivalent | equivalent | equivalent
+| namespace resolution and bindings normalization | equivalent | equivalent | equivalent | equivalent | equivalent | equivalent | equivalent
+| attribute access | equivalent | equivalent | equivalent | equivalent | equivalent | equivalent | equivalent
+| text/content/raw_content | equivalent | equivalent | equivalent | equivalent | equivalent | equivalent | equivalent
+| parsing modes and diagnostics | equivalent | equivalent | equivalent | equivalent | equivalent | equivalent | equivalent
+| EOL normalization | equivalent | D-02 | equivalent | D-03 | equivalent | equivalent | equivalent
+| entity modes | equivalent | equivalent | equivalent | equivalent | equivalent | equivalent | equivalent
+| XPath evaluation and declared idioms | equivalent | equivalent | equivalent | equivalent | equivalent | equivalent | equivalent
+| serialization shapes (xml/html/xhtml) | equivalent | equivalent | equivalent | equivalent | equivalent | equivalent | equivalent
+| indentation knobs | equivalent | D-09 | equivalent | D-09 | D-09 | D-09 | D-09
+| canonicalization | equivalent | equivalent | equivalent | D-05 | D-05 | equivalent | equivalent
+| XSLT | equivalent | loud (NotImplementedError) | loud (NotImplementedError) | loud (NotImplementedError) | loud (NotImplementedError) | loud (NotImplementedError) | equivalent
+| SAX | equivalent | equivalent | equivalent | equivalent | equivalent | equivalent | equivalent
+| materialization | equivalent | equivalent | equivalent | equivalent | equivalent | equivalent | equivalent
+| loud capability contracts | equivalent | equivalent | equivalent | equivalent | equivalent | equivalent | equivalent
+|===
+
+*equivalent* — all adapters answer the same observable result. *loud (...)* — the adapter raises the named error for that face. *D-NN* — a registered divergence in link:divergences.html[the register], with its rationale. Every cell cites a pin; see the processing model's `Pins::` line for the enforcing specs.
+// MODEL-COVERAGE:END
+
+== Reproducing
+
+`bundle exec rake docs:coverage` regenerates the block above from
+`spec/support/model_coverage.rb`. `spec/consistency/published_docs_spec.rb`
+fails when the published block is stale; the consistency suite runs it
+on every CI build.
+
+The performance commitment has its own published page:
+link:performance.html[Performance], regenerated from the scoreboard
+harness at release time.

data/docs/_pages/performance.adoc

@@ -5,6 +5,35 @@ nav_order: 11
 
 == Performance considerations
 
+=== Scoreboard (generated)
+
+`SCORE_PUBLISH=1 bundle exec ruby benchmark/scoreboard.rb` rewrites
+the marked block below from a live measurement; see
+`benchmark/README.md` for the protocol and row definitions.
+
+// SCOREBOARD:BEGIN
+Generated by `SCORE_PUBLISH=1 bundle exec ruby benchmark/scoreboard.rb`. Protocol: CPU-time medians of an interleaved A/B run (raw nokogiri vs moxml on leptris); the ratio is baseline / candidate, so > 1.0 means the facade is faster. Warmups discarded, GC between samples.
+
+Measurement: Ruby 3.4.8, leptris 1.9.374.0, nokogiri 1.19.4, 2026-10-20T14:53:54Z, 1-minute load 34.01, 9 repetitions.
+
+[cols="2,1,1,1",options="header"]
+|===
+| Row | Ratio | Kind | Status
+| `parse` | 2.59x | parity | met
+| `serialize` | 1.35x | parity | met
+| `xpath //field (count)` | 1.20x | parity | met
+| `xpath //field (each)` | 0.34x | structural | tracked (below parity)
+| `attr pairs listing` | 8.16x | parity | met
+| `build add_element` | 0.60x | structural | tracked (below parity)
+| `walk+read (warm)` | 0.77x | structural | tracked (below parity)
+| `walk+read (cold)` | 0.22x | structural | tracked (below parity)
+| `children recursion (cold)` | 0.27x | structural | tracked (below parity)
+| `plan records (typed)` | 0.79x | data | informational
+|===
+
+*Parity rows* must stay at or above the 0.95 measurement floor. *Structural rows* are measured and trend-locked (10% regression tolerance) while their gaps remain open: per-node wrapper minting costs (#312 endgame) and engine construction. *Data API* rows are informational.
+// SCOREBOARD:END
+
 === Memory management
 
 Moxml maintains a node registry to ensure consistent object mapping:

data/docs/_pages/why-moxml.adoc

@@ -0,0 +1,87 @@
+---
+title: Why Moxml
+nav_order: 2
+---
+
+== Why Moxml
+
+Moxml exists to make **"which XML engine am I running?" a deployment
+decision instead of an API decision**.
+
+Ruby's XML engines — Nokogiri, Oga, REXML, Ox, LibXML, Leptris — each
+carry their own object model, namespace resolution, XPath coverage,
+entity policy, serialization shapes, and error surfaces. An application
+that starts on one cannot move to another without a rewrite; a library
+that supports several accumulates adapter-specific branches and tests.
+Moxml replaces that with a single processing model, specified once and
+enforced on every adapter.
+
+== The invariant
+
+**Engine-choice invariance:** any program written against the Moxml
+facade produces the same observable outcome on every adapter.
+Performance may vary across engines — semantics may not.
+
+Three clauses govern every change:
+
+. **Equivalence is to the model, not merely adapter-to-adapter.** Two
+  engines can agree and both be wrong; the normative document is the
+  reference.
+. **Loud degradation, never silent divergence.** An unsupported
+  capability raises a named error. A different answer is a bug.
+. **A divergence is fixed, promoted to specification, or registered.**
+  The register names it, explains it, and pins the tests that observe
+  it. An undocumented divergence is a bug.
+
+== How the claim is proved
+
+The proof apparatus is itself part of the project, and every link is
+checked in CI:
+
+[cols="1,3"]
+|===
+| Link | What it establishes
+
+| link:../_references/processing-model[Processing model]
+| The single normative statement of every semantic decision, with a
+  `Pins::` line naming the specs that enforce each section.
+
+| link:model-coverage.html[Model coverage]
+| The face-family × adapter matrix: equivalent, loud, or a registered
+  divergence. Generated from the same data the consistency audit
+  enforces.
+
+| link:divergences.html[Divergence register]
+| Every known difference, with its engine cause, its scope, and its
+  pin. Entries are fixed, loud, or decided permanent trades.
+
+| link:performance.html[Performance]
+| The published scoreboard: parity rows are commitments; structural
+  gaps are measured and trend-locked, never hidden.
+
+|===
+
+Behind the pages, the consistency suite runs an engine-free
+**executable reference** (a pure-Ruby reader, writer, and normalizer)
+against every adapter; a seeded **generator** checks metamorphic
+properties over generated documents; and a whole-class **taxonomy
+differential** compares every adapter on every input class the model
+touches. The reference is itself transpiled to JavaScript and runs on
+the Opal lane.
+
+== What Moxml is not
+
+Moxml is not a new XML parser and does not replace the engines — it
+makes them interchangeable. It is not a performance claims contest
+either: performance is a declared, non-semantic channel, and the
+scoreboard reports below-parity rows as plainly as parity rows.
+
+== The consumer commitment
+
+- Upgrading an engine version never changes your program's semantics.
+- Capabilities that an engine lacks raise a named error at the call
+  site, not a surprising result.
+- Every difference you can observe has a register ID and a test.
+- The same program runs on Nokogiri, Oga, REXML, Ox, LibXML, and
+  Leptris — and on a future engine that adopts the model with zero
+  code changes.

data/docs/_references/processing-model.adoc

@@ -17,15 +17,30 @@ skip with their entry ID — an undocumented divergence is a bug.
 
 === Status and precedence
 
+Pins:: none
+
 1. This document — the model.
-2. `spec/consistency/` — the model pinned as executable expectations.
+2. `spec/consistency/` — the model pinned as executable expectations,
+   with `lib/moxml/reference/` as the **engine-free executable
+   reference** (a pure-Ruby reader, writer, and normalizer). Adapters
+   are differentially tested against the reference
+   (`spec/consistency/reference_differential_spec.rb`), not only
+   against each other; the reference is pure Ruby and transpiles to
+   the Opal lane.
 3. Adapter implementations and capability gates — representations.
 
+A pin cites the model section it enforces
+(`# Processing model §<section> (normative)`); the coverage audit
+asserts both directions of that linkage, so removing any of the
+document, a pin, or the reference fails CI.
+
 A semantics change amends this document first (see
 `TODO.model/05-model-evolution-protocol.md`).
 
 === Mission and invariant
 
+Pins:: none
+
 Moxml exists to make "which XML engine am I running?" a **deployment
 decision instead of an API decision**. The invariant that enables it:
 any program written against the facade produces the same observable
@@ -39,6 +54,8 @@ divergences, and performance.
 
 === Object model
 
+Pins:: none
+
 Node kinds:: `Document`, `Element`, `Attribute`, `Text`, `Comment`,
 `Cdata`, `Declaration`, `Doctype`, `ProcessingInstruction`,
 `Namespace`, `EntityReference`.
@@ -48,6 +65,12 @@ the same underlying node; node identity is a property of the
 underlying tree, not of wrapper object identity. Comparisons use node
 equality semantics, never `equal?` on wrappers.
 
+Kind:: Every node answers `node_type` — one of `:document`,
+`:element`, `:attribute`, `:text`, `:comment`, `:cdata`,
+`:processing_instruction`, `:doctype`, `:declaration`,
+`:entity_reference`, `:namespace` — the predicates (`element?`,
+`text?`, …) are its derivatives.
+
 Ownership:: The `Document` owns the tree's lifetime; nodes are valid
 within it. Deterministic release is available via `Document#free`.
 
@@ -57,15 +80,23 @@ listings or serialization child walks.
 
 === Document order and traversal
 
+Pins:: `spec/consistency/adapter_parity_spec.rb`
+
 * `children` lists nodes in document order.
 * Walks (`each_node`, `materialize`) visit depth-first, pre-order.
 * `Document#children` and `#root` never include the declaration;
   doctype exposure follows the Nokogiri contract.
+* Document-level parts (`Declaration`, `Doctype`) are state, not
+  nodes: walks (`traverse`, `each_node`, `materialize`) never yield
+  them, and walks over a DOCTYPE-bearing document are well-defined on
+  every adapter.
 * `NodeSet` preserves document order for axis results; unions preserve
   first-encounter document order.
 
 === Names and namespaces
 
+Pins:: `spec/consistency/xpath_idioms_spec.rb`
+
 * Names are **expanded names**: a name test matches by namespace *URI*,
   never by prefix spelling.
 * Unprefixed element name tests match **no-namespace** elements only
@@ -81,12 +112,16 @@ listings or serialization child walks.
 
 === Access semantics
 
+Pins:: `spec/moxml/attribute_resolver_spec.rb`, `spec/moxml/text_spec.rb`
+
 `text`:: Concatenated descendant text (elements); a text node's own
 content; entity references restored when the document is
 entity-bearing.
 
 `content`:: The node's content per its kind; on text-like nodes, with
-entity-marker restoration; memoized against mutation.
+entity-marker restoration; memoized against mutation. A processing
+instruction's content is its data **without** the separating
+whitespace after the target (uniform across adapters).
 
 `raw_content`:: The backing text **without** entity restoration.
 
@@ -103,6 +138,8 @@ with an unambiguous local name.
 
 === Parsing
 
+Pins:: `spec/consistency/eol_normalization_spec.rb`, `spec/moxml/document_parse_diagnostics_spec.rb`, `spec/moxml/entity_spec.rb`
+
 * Modes: strict (errors raise) and recover (errors surface via
   `parse_diagnostics` / `parse_errors`, both `[{kind:, message:}]`).
 * HUGE mode: over-cap text (> 10 MB) parses completely.
@@ -116,6 +153,8 @@ with an unambiguous local name.
 
 === XPath evaluation
 
+Pins:: `spec/consistency/xpath_idioms_spec.rb`
+
 * XPath 1.0 semantics on every adapter. Engines without an evaluator
   (Ox, HeadedOx; leptris for shapes its engine cannot evaluate) run
   **moxml's own pure-Ruby engine** — the model's semantics do not
@@ -128,16 +167,25 @@ with an unambiguous local name.
   `xmlns:` default-namespace matching; attribute terminals in every
   position (`//a/@id`, `//@id`, `r/a/@id`); symbol- and string-keyed
   bindings resolve identically.
+* `at_xpath` answers the first node of a node-set and passes scalar
+  results (`count()`, `string()`, `boolean()`) through unwrapped,
+  uniformly across adapters. Adapters whose at_xpath lane falls back
+  to the reference engine when the native answer is empty (leptris)
+  use it; the rest evaluate `xpath` and take the first node. Both
+  lanes answer the same model.
 
 === Serialization
 
+Pins:: `spec/moxml/to_html_spec.rb`, `spec/moxml/xhtml_output_spec.rb`
+
 [cols="1,3"]
 |===
 | Shape | Contract
 
 | `to_xml`
 | Declaration per configuration; empty elements per `expand_empty`;
-  namespace declarations preserved.
+  namespace declarations preserved; a parsed DOCTYPE is emitted with
+  its external identifiers and internal subset.
 
 | `to_html`
 | HTML method: void elements unclosed (`<br>`), raw text
@@ -161,15 +209,25 @@ with an unambiguous local name.
 
 === Canonicalization
 
+Pins:: `spec/moxml/c14n/adapter_delegation_spec.rb`
+
 * Algorithms: Inclusive 1.0, Exclusive 1.0, Inclusive 1.1, plus
   XPath-driven subset canonicalization (enveloped-signature oracle).
 * Native delegations (leptris engine, libxml2) answer **byte-identical**
   output to the Ruby reference path (byte-safety probed before
   engagement).
+* Document-level comments and PIs render in document order, separated
+  from adjacent nodes by exactly one line feed; the form starts and
+  ends with its first/last node (no leading or trailing line feed).
+  The XML declaration is document state and never part of the form.
+* PI data excludes the separating whitespace after the target; the
+  canonical form joins target and non-empty data with a single space.
 * `Moxml::C14n.equivalent?` is the algorithm-aware comparison.
 
 === XSLT
 
+Pins:: `spec/consistency/xslt_spec.rb`
+
 XSLT 1.0 through engines that ship a processor (libxslt; leptris
 1.0–3.0). Compilation and transform failures raise named
 `Moxml::XsltError`s. Engines without a processor raise
@@ -177,6 +235,8 @@ XSLT 1.0 through engines that ship a processor (libxslt; leptris
 
 === SAX
 
+Pins:: `spec/moxml/sax_spec.rb`
+
 * The callback stream (`on_start_element`, `on_characters`, `on_error`,
   …) is the authoritative event sequence.
 * The record-drain fast path (`on_sax_records`) replays **exactly** the
@@ -186,6 +246,8 @@ XSLT 1.0 through engines that ship a processor (libxslt; leptris
 
 === Materialization
 
+Pins:: `spec/moxml/plan_conformance_spec.rb`
+
 `materialize`, `materialize_fields`, `Plan`, and `StructPlan` produce
 **identical records across all adapters** (conformance spec). Plan name
 matching is global; unmatched subtrees are dropped per the pinned
@@ -193,6 +255,8 @@ semantics.
 
 === Errors and loud degradation
 
+Pins:: `spec/consistency/loud_degradation_spec.rb`
+
 * `Moxml::Error` hierarchy; `Moxml::XPathError`, `Moxml::XsltError`,
   `Moxml::AdapterError` (e.g. schema-handle/adapter misroute),
   `Moxml::NotImplementedError` for unsupported capability contracts.
@@ -204,6 +268,8 @@ semantics.
 
 === Performance: a declared, non-semantic channel
 
+Pins:: none
+
 Acceleration (native read layers, C minting, record drains, plan
 streams) always lands behind version + face gates and degrades to the
 spec-pinned fallback. Cross-adapter performance variance is sanctioned

data/lib/compat/opal/moxml_boot.rb

@@ -62,3 +62,7 @@ require "moxml/xpath/errors"
 require "moxml/xpath/ast/node"
 require "moxml/xpath/ruby/node"
 require "moxml/xpath/ruby/generator"
+require "moxml/reference"
+require "moxml/reference/parser"
+require "moxml/reference/writer"
+require "moxml/reference/normalizer"