moxml 0.5.146 → 0.5.147

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b529948a14e67202c6ad6fc9acbe6c06c033ba022f93ada6bc9e4001554ea583
-  data.tar.gz: 68a76e1a69397aef0d0356e3ddd7bc200737a41333a70d6688cfca34d44e4c27
+  metadata.gz: 2e5797a825682b992d84b5ab9155d74f81fdeca24293b40ad7b9e58860c407f0
+  data.tar.gz: 11accb2da9da7cf656d28ab7e128da698f1702120332d94d06b4a20ea39ad112
 SHA512:
-  metadata.gz: 3775a27419325f8c764d6d686c547e88f75bdc073cbe354bdd97d2e0516e68a4f83896d4cd840c25be26f7d6aafdca24a596d3c6aa2893e8596ed95d646c16fa
-  data.tar.gz: 84c2f0abec2a55d990cdc921f9abac0c9206def8190d609fd298256dd035d586334dedc04bb97af496a98fe9053b2fa3b65f716a11e22e94516f2f8b91837e1b
+  metadata.gz: 2b8980eb872815020ed2b6d582172ffd62c08a426c2fa2104bd891cd5e2f1e69392fd82d9573215383399087cb686852c47fb10e1d93e812c1641f8eb5e4eeef
+  data.tar.gz: 924b76844411af051e0a9b02ea55788dbc4f5d0e6ec0be31ade4ded2c17c6c6e58356f687ef42e2d7934a4a8f684720f77b0d7688e108437aa64c68a41b68d06

data/.github/workflows/rake.yml

@@ -71,3 +71,38 @@ jobs:
         env:
           LEPTRIS_BENCH_LOCK: "1"
         run: bundle exec rake benchmark:plan
+
+  # Order-flake tripwire (TODO.model/06 checker integrity): the same
+  # example order every run - a red here reproduces locally with
+  # `rspec --bisect --order rand:424242`. The per-PR matrix legs keep
+  # their random seeds for breadth; this one is the deterministic twin.
+  battery-fixed-seed:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: "recursive"
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: false
+
+      - name: Install ragel
+        run: sudo apt-get update && sudo apt-get install -y ragel
+
+      - name: Install ruby-ll (for rake vendor:prepare)
+        run: gem install ruby-ll --no-document
+
+      - name: Generate ragel / ruby-ll outputs in vendored forks
+        run: rake vendor:prepare
+
+      - name: Install dependencies
+        run: bundle install
+
+      - name: Compile liboga / libll native extensions
+        run: rake vendor:compile
+
+      - name: Full battery at the fixed seed
+        run: bundle exec rspec --order rand:424242

data/README.adoc

@@ -15,10 +15,28 @@ It offers a consistent API that abstracts away the underlying XML implementation
 details while maintaining high performance through efficient node mapping and
 native XPath querying.
 
+Moxml's mission: **make "which XML engine am I running?" a deployment decision
+instead of an API decision.** Libraries write once against a single XML
+processing model — one object model, one name/namespace resolution model, one
+XPath, one serialization and canonicalization contract — and the engine
+underneath (Nokogiri, Leptris, REXML, Oga, Ox, LibXML) is a configuration
+choice.
+
+The invariant that makes this work: any program written against the facade
+produces the same observable outcome on every adapter. Performance may vary
+across engines — semantics may not. Where an engine cannot deliver a
+capability, it fails loudly (a named error); where an engine genuinely
+diverges, the divergence is registered and pinned — never silent. The model is
+specified normatively in the
+https://lutaml.github.io/moxml/_references/processing-model[Processing Model]
+document, pinned as executable expectations in the consistency suite, and its
+known engine differences are tracked in the
+https://lutaml.github.io/moxml/_pages/divergences[divergence register].
+
 Key features:
 
 * Intuitive, Ruby-idiomatic API for XML manipulation
-* Consistent interface across different XML libraries
+* One processing model, consistently implemented across different XML libraries
 * Efficient node mapping for XPath queries
 * Support for all XML node types and features
 * Easy switching between XML processing engines

data/docs/_pages/adapter-compatibility.adoc

@@ -8,6 +8,13 @@ toc::[]
 
 This document provides detailed compatibility information for all supported XML adapters in Moxml, explaining which features are fully supported, partially supported, or not supported by each adapter.
 
+The authoritative sources for cross-adapter semantics are the
+link:../_references/processing-model[Processing Model] (the normative
+single model every adapter implements) and the
+link:divergences[divergence register] (every known, pinned engine
+difference, D-01..D-12). A capability an adapter cannot deliver raises
+a named error — it never answers a divergent result silently.
+
 == Test suite results
 
 **Overall:** 2,182 examples, 0 failures, 97 pending

data/docs/_pages/divergences.adoc

@@ -0,0 +1,90 @@
+---
+title: Divergences
+nav_order: 4
+---
+
+== Divergence register
+
+Every known cross-adapter divergence from the
+link:../_references/processing-model[processing model] is registered
+here. Contract:
+
+* A divergence is either **fixed**, **loud** (a named raise), or
+  **SPEC'D** (documented here and pinned with a skip in the
+  consistency suite, citing the entry ID).
+* Consistency-suite exemptions must cite a register ID. An
+  undocumented divergence is a bug — report it against this register.
+
+[cols="2,4,6"]
+|===
+| 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`.
+
+| D-03
+| ox, headed_ox
+| `
` character references collapse to LF. 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`.
+
+| 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
+`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
+`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`.
+
+| D-12
+| 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`.
+|===

data/docs/_references/index.adoc

@@ -7,6 +7,15 @@ nav_order: 1
 
 Detailed technical specifications and API documentation for Moxml.
 
+=== Processing model
+
+link:processing-model[Processing Model]::
+The normative statement of Moxml's single XML processing model — the
+semantics every adapter implements.
+
+link:../_pages/divergences[Divergences]::
+The register of known, pinned cross-adapter divergences.
+
 === API reference
 
 link:document-api[Document API]::

data/docs/_references/processing-model.adoc

@@ -0,0 +1,211 @@
+---
+title: Processing Model
+nav_order: 3
+---
+
+== The processing model (normative)
+
+This document is the **single normative statement of Moxml's XML
+processing model**. Every adapter implements this model; no adapter's
+native semantics leak through it. When implementations disagree, the
+model wins — engines converge to it, never the reverse.
+
+The model's executable form is the consistency suite
+(`spec/consistency/`). Known, unfixable engine differences are
+registered in link:../_pages/divergences[the divergence register] and
+skip with their entry ID — an undocumented divergence is a bug.
+
+=== Status and precedence
+
+1. This document — the model.
+2. `spec/consistency/` — the model pinned as executable expectations.
+3. Adapter implementations and capability gates — representations.
+
+A semantics change amends this document first (see
+`TODO.model/05-model-evolution-protocol.md`).
+
+=== Mission and invariant
+
+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
+outcome on every adapter. The engine is unobservable except through
+declared channels: capability gates (loud raises), registered
+divergences, and performance.
+
+* Performance may vary across engines — semantics may not.
+* Absence of capability is legal (a named raise). Absence of
+  equivalence is not (a different answer).
+
+=== Object model
+
+Node kinds:: `Document`, `Element`, `Attribute`, `Text`, `Comment`,
+`Cdata`, `Declaration`, `Doctype`, `ProcessingInstruction`,
+`Namespace`, `EntityReference`.
+
+Identity:: Parsing and traversal may mint distinct wrapper objects for
+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.
+
+Ownership:: The `Document` owns the tree's lifetime; nodes are valid
+within it. Deterministic release is available via `Document#free`.
+
+Declarations are state:: `Declaration` (and the doctype token) are
+document *state*, not child nodes: they never appear in `children`
+listings or serialization child walks.
+
+=== Document order and traversal
+
+* `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.
+* `NodeSet` preserves document order for axis results; unions preserve
+  first-encounter document order.
+
+=== Names and namespaces
+
+* Names are **expanded names**: a name test matches by namespace *URI*,
+  never by prefix spelling.
+* Unprefixed element name tests match **no-namespace** elements only
+  (XPath 1.0). Unprefixed attribute name tests likewise match
+  no-namespace attributes.
+* Reserved prefixes: `xml` is bound to the XML namespace always;
+  `xmlns:` in an expression addresses the **default namespace** (the
+  libxml2 idiom, adopted model-wide).
+* Bindings hashes accept both string and symbol keys; explicit
+  bindings **win** over in-scope document declarations.
+* `Element#name` returns the bare tag name; non-element DOM names are
+  `"text"` / `"comment"`; a PI's name is its target.
+
+=== Access semantics
+
+`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.
+
+`raw_content`:: The backing text **without** entity restoration.
+
+`[]` / `attributes` / `attribute_pairs`:: `[]` reads an attribute by
+bare name (no-namespace) or prefixed name (resolved by URI);
+values are entity-restored when the document bears markers.
+`attribute_pairs` is the read-only listing ([name, value] pairs,
+document order, duplicates included). `remove_attribute` returns the
+removed attribute or nil — including for namespace-prefixed targets
+with an unambiguous local name.
+
+`remove`/mutation returns:: Mutators return the contract object
+(removed node, new node) — never a silent no-op self.
+
+=== Parsing
+
+* 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.
+* EOL normalization (XML 1.0 §2.11): CRLF → LF; bare CR → LF in text,
+  CDATA, and parsed content; attribute-value CRLF collapses to one
+  space; `
` survives as a literal CR.
+* Entity modes: `:expand` (default — built-ins resolved at parse),
+  `:keep` (reference nodes preserved with marker machinery),
+  `:disabled`, `:custom` (provider). Restoration of marker-bearing
+  values is marker-driven and generation-stamped.
+
+=== XPath evaluation
+
+* 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
+  depend on the engine shipping one.
+* Document-context **relative name-test paths** resolve laxly —
+  descendant-anchored at the root (`doc.at("a/b")` finds `//a/b`),
+  matching Nokogiri's `Document#at`/`#search`. Axes, node types, `.`
+  and `..` keep strict document context.
+* Declared idioms (pinned in `spec/consistency/xpath_idioms_spec.rb`):
+  `xmlns:` default-namespace matching; attribute terminals in every
+  position (`//a/@id`, `//@id`, `r/a/@id`); symbol- and string-keyed
+  bindings resolve identically.
+
+=== Serialization
+
+[cols="1,3"]
+|===
+| Shape | Contract
+
+| `to_xml`
+| Declaration per configuration; empty elements per `expand_empty`;
+  namespace declarations preserved.
+
+| `to_html`
+| HTML method: void elements unclosed (`<br>`), raw text
+  (script/style) verbatim, no XML declaration, DOCTYPE first.
+
+| `to_xhtml`
+| XML method on HTML trees: void elements self-closed (`<br/>`),
+  non-void elements paired, raw text XML-escaped, no declaration
+  unless asked. Also selected by `to_html(xhtml: true)`.
+
+| Indentation
+| Document-level `to_html`/`to_xhtml` indentation composes with the
+  `indent:`/`indent_text:` knobs and raises `Moxml::AdapterError` on
+  incapable engines. Element-level `to_xml(indent:)` is honored on
+  nokogiri/rexml; other engines currently ignore it — registered as
+  link:../_pages/divergences[D-09], not silently blessed.
+
+| Line endings
+| `line_ending:` normalizes output newlines on every shape.
+|===
+
+=== Canonicalization
+
+* 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).
+* `Moxml::C14n.equivalent?` is the algorithm-aware comparison.
+
+=== XSLT
+
+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
+`Moxml::NotImplementedError` — the face is never silently absent.
+
+=== SAX
+
+* 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
+  callback stream (spec-pinned equality). Documents whose parse would
+  emit an ERROR event are outside the drainable subset — the drain
+  refuses them so `on_error` retains authority.
+
+=== Materialization
+
+`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
+semantics.
+
+=== Errors and loud degradation
+
+* `Moxml::Error` hierarchy; `Moxml::XPathError`, `Moxml::XsltError`,
+  `Moxml::AdapterError` (e.g. schema-handle/adapter misroute),
+  `Moxml::NotImplementedError` for unsupported capability contracts.
+* Every gated surface answers the contract or raises the named error —
+  never returns a divergent answer.
+* Adapter degradation is loud: a present-but-unusable preferred adapter
+  warns at configuration and misroutes fail at the wrap, not deep in
+  a call.
+
+=== Performance: a declared, non-semantic channel
+
+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
+exactly one place: the benchmark parity locks. Semantics never ride a
+gate.

data/docs/index.adoc

@@ -14,6 +14,15 @@ applications. It offers a consistent API that abstracts away the underlying
 XML implementation details while maintaining high performance through
 efficient node mapping and native XPath querying.
 
+Moxml's mission: **make "which XML engine am I running?" a deployment
+decision instead of an API decision.** Libraries write once against a single
+XML processing model; the engine underneath is a configuration choice. Any
+program written against the facade produces the same observable outcome on
+every adapter — performance may vary, semantics may not. The model is
+specified normatively in the
+link:_references/processing-model[Processing Model] document; known engine
+differences are tracked in the link:_pages/divergences[divergence register].
+
 == Key features
 
 * **Unified interface** - Consistent API across different XML libraries

data/lib/moxml/adapter/leptris.rb

@@ -1333,10 +1333,28 @@ module Moxml
           native_fragment.to_html
         end
 
-        def parse_html(html, _options = {}, _context = nil)
+        # leptris#1771's parse-lint (§13.2.5): the binding's parse_html
+        # accepts collect_errors (and mode) and records the error-token
+        # stream into the document's diagnostic channel, which
+        # parse_diagnostics reads. Face-probed — the zero-dep gem lets
+        # consumers resolve bindings predating the kwarg.
+        COLLECT_ERRORS_NATIVE = ::Leptris::XML
+          .method(:parse_html).parameters.any? do |_, key|
+            key == :collect_errors
+          end
+
+        def parse_html(html, options = {}, _context = nil)
           html_string = html.is_a?(IO) || html.is_a?(StringIO) ? html.read : html.to_s
           native_doc = begin
-            ::Leptris::XML.parse_html(html_string)
+            if COLLECT_ERRORS_NATIVE && options[:collect_errors]
+              ::Leptris::XML.parse_html(
+                html_string,
+                mode: options.fetch(:mode, :whatwg),
+                collect_errors: true,
+              )
+            else
+              ::Leptris::XML.parse_html(html_string)
+            end
           rescue ::Leptris::XML::ParseError => e
             raise Moxml::ParseError.new(e.message)
           end
@@ -2830,6 +2848,16 @@ module Moxml
           else
             node.content = content.to_s
           end
+        rescue ::Leptris::XML::Error => e
+          # Detached (parentless) nodes answer the engine's bare
+          # "Invalid argument" (issue #401); created-unattached nodes
+          # work, so only the failing detachment is re-raised, named.
+          raise if node.parent
+
+          raise Moxml::Error,
+                "cannot set text content on a detached (parentless) " \
+                "node — attach it to a document first (issue #401): " \
+                "#{e.message}"
         end
 
         def cdata_content(node)

data/lib/moxml/adapter/libxml.rb

@@ -768,6 +768,11 @@ module Moxml
 
           native_node = unpatch_node(node)
           return nil unless native_node
+          # Documents are container nodes (issue #400): their text is
+          # the root's concatenated descendant text; LibXML::XML::
+          # Document carries no content face of its own.
+          return native_node.root&.content.to_s if
+            native_node.is_a?(::LibXML::XML::Document)
 
           native_node.content
         end

data/lib/moxml/adapter/oga.rb

@@ -452,6 +452,16 @@ module Moxml
         end
 
         def text_content(node)
+          # Documents are container nodes (issue #400): their text is
+          # the whole tree's text; Oga documents carry no text face
+          # (root_node answers the document itself), so fold the
+          # element children.
+          if node.is_a?(::Oga::XML::Document)
+            return node.children
+                .filter_map { |c| c.text if c.is_a?(::Oga::XML::Element) }
+                .join
+          end
+
           node.text
         end
 

data/lib/moxml/document.rb

@@ -73,6 +73,15 @@ module Moxml
       root_element ? Moxml::Node.wrap(root_element, context) : nil
     end
 
+    # Documents are container nodes: #text concatenates descendant
+    # text, Nokogiri's Document#text contract (issue #400) — the base
+    # Node#text answered "" and silently emptied consumers'
+    # content-preservation checks.
+    def text
+      val = adapter.text_content(@native)
+      entity_bearing? ? adapter.restore_entities(val) : val
+    end
+
     # Materialize the root subtree — see Moxml::Materializer.
     def materialize(&block)
       return to_enum(:materialize) unless block

data/lib/moxml/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Moxml
-  VERSION = "0.5.146"
+  VERSION = "0.5.147"
 end

data/spec/consistency/divergence_register_spec.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# Divergence register linkage (TODO.model/02): the register
+# (docs/_pages/divergences.adoc) and the consistency suite must stay
+# mechanically consistent — every capability-related skip cites a
+# register ID, every register entry is cited by at least one spec, and
+# no spec cites an unregistered ID.
+RSpec.describe "divergence register linkage" do
+  REGISTER_PATH = "docs/_pages/divergences.adoc" # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
+  SCAN_GLOBS = %w[spec/consistency/**/*.rb spec/moxml/**/*.rb].freeze # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
+  NEXT_GATE = [ # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
+    /same engine as/, # engine dedup, not a divergence
+    /source_adapter == target_adapter/, # self round-trip
+    /MAX_SIZE/, # size guard
+    /AVAILABLE_ADAPTERS\.include/, # availability filter
+    /skip_shapes/,              # shape routing (IDs cited above)
+    /leptris_fixed\?/,          # version gate
+    /source_elements/,          # data-presence guard
+    /next unless match/,        # scanner-internal guard
+  ].freeze
+
+  # Version/availability gates are not divergences: a binding too old
+  # or an adapter not installed is a deployment fact, not an
+  # engine-vs-model difference at equal versions.
+  GATE = [ # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
+    /unavailable/i, /not available/, /predates/, /not installed/i,
+    /not present/i, /requires/i, /required\z/, /has no \S+ face/,
+    /lacks the /, /carries /, /degraded below/, /lockstep/i,
+    /unreleased/i, /stood down/, /recovered without/,
+    /Only \S+ available in CI/i, /adapter-specific/i, /noblanks/,
+    /SKIP_ parse flags/, /engine < \d/
+  ].freeze
+
+  def register_ids
+    File.readlines(REGISTER_PATH)
+      .filter_map { |line| line[/\A\|\s*(D-\d+)\s*$/, 1] }
+      .uniq
+  end
+
+  def spec_files
+    SCAN_GLOBS.flat_map { |g| Dir[g] }.uniq
+  end
+
+  def cited_ids
+    spec_files.flat_map { |path| File.readlines(path) }
+      .flat_map { |line| line.scan(/D-\d+/) }
+      .uniq
+  end
+
+  it "has a register with entries" do
+    expect(register_ids).not_to be_empty
+  end
+
+  it "requires capability-related skips to cite a register ID" do
+    offenders = []
+    spec_files.each do |path|
+      File.readlines(path).each_with_index do |line, i|
+        next unless (msg = line[/skip\s+[&(]?\s*["'](.*?)["']/, 1])
+
+        next if GATE.any? { |re| re.match?(msg) }
+        next if msg.match?(/D-\d+/)
+
+        offenders << "#{path}:#{i + 1} #{msg.strip[0, 60]}"
+      end
+    end
+    expect(offenders).to be_empty,
+                         "capability skips must cite a divergence-register " \
+                         "ID (D-NN): #{offenders.join('; ')}"
+  end
+
+  it "requires adapter-exempting next-guards to cite a nearby register ID" do
+    offenders = []
+    spec_files.each do |path|
+      next if path.end_with?("divergence_register_spec.rb")
+
+      lines = File.readlines(path)
+      lines.each_with_index do |line, i|
+        next unless line.match?(/^\s*next\s+(if|unless)\s/)
+        next if NEXT_GATE.any? { |re| re.match?(line) }
+        next if line.match?(/D-\d+/)
+
+        context = lines[[i - 4, 0].max...i] + lines[(i + 1)..(i + 4)].to_a
+        next if context.any? { |l| l.match?(/D-\d+/) }
+
+        offenders << "#{path}:#{i + 1} #{line.strip[0, 60]}"
+      end
+    end
+    expect(offenders).to be_empty,
+                         "adapter-exempting next-guards must cite a " \
+                         "divergence-register ID (D-NN) on or above the " \
+                         "line: #{offenders.join('; ')}"
+  end
+
+  it "cites every register entry from at least one spec" do
+    missing = register_ids - cited_ids
+    expect(missing).to be_empty,
+                       "register entries never cited by a spec: " \
+                       "#{missing.join(', ')}"
+  end
+
+  it "never cites an unregistered divergence ID" do
+    orphans = cited_ids - register_ids
+    expect(orphans).to be_empty,
+                       "specs cite IDs missing from the register: " \
+                       "#{orphans.join(', ')}"
+  end
+end

data/spec/consistency/document_text_spec.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# Issue #400: documents are container nodes — Document#text
+# concatenates descendant text (Nokogiri's Document#text contract).
+# The base Node#text answered "" and silently emptied consumers'
+# content-preservation checks (canon's formatter asserted through
+# doc.text).
+RSpec.describe "Document#text concatenates descendant text" do
+  Moxml::Adapter::AVAILABLE_ADAPTERS.each do |adapter_name|
+    context "with #{adapter_name}" do
+      let(:ctx) { Moxml.new(adapter_name) }
+
+      it "answers the concatenated descendant text" do
+        doc = ctx.parse("<r><a>x</a><b>y</b></r>")
+        expect(doc.text).to eq("xy")
+      end
+
+      it "matches root.text (both containers recurse)" do
+        doc = ctx.parse("<r><a>x</a><b>y</b></r>")
+        expect(doc.text).to eq(doc.root.text)
+      end
+
+      it "answers an empty string for element-free documents" do
+        expect(ctx.parse("<r/>").text).to eq("")
+      end
+    end
+  end
+end