moxml 0.5.146 → 0.5.148

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b529948a14e67202c6ad6fc9acbe6c06c033ba022f93ada6bc9e4001554ea583
-  data.tar.gz: 68a76e1a69397aef0d0356e3ddd7bc200737a41333a70d6688cfca34d44e4c27
+  metadata.gz: 1b51347e90c3dae3f4b0b41268b4ee8cd92fa91a4210a17b1ea75da85db0f82a
+  data.tar.gz: d251705fd512baed6295dad6a56c12e7db531dfa4845b2f77983c9c305bfaffd
 SHA512:
-  metadata.gz: 3775a27419325f8c764d6d686c547e88f75bdc073cbe354bdd97d2e0516e68a4f83896d4cd840c25be26f7d6aafdca24a596d3c6aa2893e8596ed95d646c16fa
-  data.tar.gz: 84c2f0abec2a55d990cdc921f9abac0c9206def8190d609fd298256dd035d586334dedc04bb97af496a98fe9053b2fa3b65f716a11e22e94516f2f8b91837e1b
+  metadata.gz: 8ffcc8a80a304b656005d171627c40a982ba1b1594bbd2cb9090f390150f799b69041e338a54d2e79245a3fdf526639406938f4fdd82b290f55092c43ac20f34
+  data.tar.gz: 764dd4cd2fa5346a701224b7841ff0fb7cfced542b68ad914f4200acda168c5060813cb737429a5bcfd67eca12e74870b8bc4449bc83214678f5c86beaf3aa8c

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

@@ -105,6 +105,9 @@ module Moxml
         ::Leptris::XML::Document.method(:parse)
           .parameters.any? { |_, key| key == :strict }
 
+      ADD_CHILD_NATIVE =
+        NATIVE_READ_LAYER && NN.method_defined?(:add_child_native)
+
       if NATIVE_READ_LAYER
         NN_ATTRIBUTE = NN.instance_method(:attribute)
         NN_NAME = NN.instance_method(:name)
@@ -624,6 +627,31 @@ module Moxml
               end
               TEXT.include(TextContractReads)
             end
+
+            # leptris-ruby#507: children_read joins the alias set. The
+            # generation-checked memo STAYS — re-walks of the same
+            # document are the common harness/consumer shape and the
+            # memo serves them allocation-free (dropping it regressed
+            # the walk 2x in GC). Only the MISS gets cheaper: the
+            # klass-children face plain-dispatches and returns the
+            # already-minted wrappers, so the adapter crossing
+            # (bind_call + to_a + keep-refs probe) drops out, and
+            # entity-marker documents take super for the split.
+            if NN.method_defined?(:children_read)
+              module ChildReads
+                def children
+                  @children = nil if @children_gen != context.children_generation
+                  @children_gen = context.children_generation
+                  @children ||= if doc_entity_bearing?
+                                  super
+                                else
+                                  NodeSet.new(children_read, context, self)
+                                end
+                end
+              end
+              ELEMENT.include(ChildReads)
+              TEXT.include(ChildReads)
+            end
           end
 
           # leptris-ruby#246 klass-propagating reads: the read
@@ -1333,10 +1361,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
@@ -1446,6 +1492,14 @@ module Moxml
           count = ffi.leptris_document_parse_diag_count(doc)
           return [] if count.zero?
 
+          # leptris#1771: one face carries the diag's machine-readable
+          # code plus line/column with the entry (nil when the engine
+          # has no token code — pre-#1771 records). The face probe
+          # keeps older bindings on kind+message (issue #408).
+          lint_code = if ffi.respond_to?(:leptris_document_parse_diag_code)
+                        ffi.method(:leptris_document_parse_diag_code)
+                      end
+
           kind_ptr = ::FFI::MemoryPointer.new(:int)
           diagnostics = []
           count.times do |i|
@@ -1455,7 +1509,19 @@ module Moxml
             ) == 1
 
             kind = DIAG_KINDS[kind_ptr.read_int] || :unknown
-            diagnostics << { kind: kind, message: buffer.read_string }
+            diag = { kind: kind, message: buffer.read_string }
+            if lint_code
+              code_buf = ::FFI::MemoryPointer.new(:char, 128)
+              line_ptr = ::FFI::MemoryPointer.new(:int)
+              column_ptr = ::FFI::MemoryPointer.new(:int)
+              lint_code.call(doc, i, code_buf, 128, line_ptr, column_ptr)
+              code = code_buf.read_string
+              diag[:code] = code.empty? ? nil : code
+              diag[:line] = line_ptr.read_int.zero? ? nil : line_ptr.read_int
+              diag[:column] =
+                column_ptr.read_int.zero? ? nil : column_ptr.read_int
+            end
+            diagnostics << diag
           end
           diagnostics
         end
@@ -2478,6 +2544,27 @@ module Moxml
         end
 
         def add_child(parent, child)
+          # Same-document Identity append — the builder hot path. One
+          # document pair decides the verdict: the pin, the absorb
+          # checks and the binding bridges only exist for
+          # cross-document work, and the plain C append (version bump
+          # inside) is the whole job. bind_call, not dispatch — the
+          # contract modules shadow add_child on Identity receivers
+          # (moxml#2560 note below).
+          if NATIVE_MUTATIONS_COHERENT && parent.is_a?(NN) && child.is_a?(NN) &&
+              !child.is_a?(CustomizedLeptris::EntityReference)
+            parent_doc = NN_DOCUMENT.bind_call(parent)
+            if parent_doc
+              child_doc = NN_DOCUMENT.bind_call(child)
+              if child_doc && parent_doc.equal?(child_doc)
+                # add_child_native (leptris-ruby#509) plain-dispatches
+                # on Identity receivers — one frame, no bind_call.
+                return parent.add_child_native(child) if ADD_CHILD_NATIVE
+
+                return NN_ADD_CHILD.bind_call(parent, child)
+              end
+            end
+          end
           # 1.9.311: binding-family children (created PIs, texts...) —
           # a DIRECT absorb makes the binding add below move the node
           # by reference. A source already owned elsewhere would need
@@ -2830,6 +2917,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
@@ -154,11 +163,21 @@ module Moxml
     end
 
     def create_element(name)
-      Wrappers::Element.new(adapter.create_element(name, owner_doc: @native), context)
+      native = adapter.create_element(name, owner_doc: @native)
+      # leptris-ruby#508 mints registered klasses at create: the node
+      # IS a contract-carrying identity (@native is self) — prime it
+      # in place instead of shelling a second wrapper (a raw mint
+      # reaching ==/adapter dies on the nil @context).
+      return native.prime_contract(native, context, adapter) if native.is_a?(Moxml::Node)
+
+      Wrappers::Element.new(native, context)
     end
 
     def create_text(content)
-      Wrappers::Text.new(adapter.create_text(content, owner_doc: @native), context)
+      native = adapter.create_text(content, owner_doc: @native)
+      return native.prime_contract(native, context, adapter) if native.is_a?(Moxml::Node)
+
+      Wrappers::Text.new(native, context)
     end
 
     def create_cdata(content)
@@ -218,9 +237,13 @@ module Moxml
         raise Error, "Document already has a root element"
       else
         adapter.add_child(@native, node.native)
-        # Refresh native for adapters where identity changes (e.g., LibXML doc.root=)
+        # Refresh native for adapters where identity changes (e.g., LibXML doc.root=).
+        # Native equality via the adapter, not wrapper !=: re-mints can
+        # arrive without context primed (1.9.373 actual_native), and
+        # wrapper == dispatches through the adapter (issue #409-class).
         refreshed = adapter.actual_native(node.native, @native)
-        node.refresh_native!(refreshed) if refreshed && refreshed != node.native
+        node.refresh_native!(refreshed) if refreshed &&
+          !adapter.same_node?(refreshed, node.native)
       end
       node.parent_node = self
       invalidate_children_cache!