moxml 0.5.145 → 0.5.147

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 042f6cd21672a36e869b19c158819a3624d3a79a53de1fd083e83a377b577442
-  data.tar.gz: 7cacbfbd44bb9a87aa252a638b8ac9d25fb5cb67b6e3845c8fdf9c5cf943df24
+  metadata.gz: 2e5797a825682b992d84b5ab9155d74f81fdeca24293b40ad7b9e58860c407f0
+  data.tar.gz: 11accb2da9da7cf656d28ab7e128da698f1702120332d94d06b4a20ea39ad112
 SHA512:
-  metadata.gz: 507216b5acdf26ae9cd5b4d69c12d2519b949fbe2017c39a804954a04659780c5432b4fe8b11262642ca1699e09eb453af08e230a653a9b530f55404b6d6f5f1
-  data.tar.gz: 5d19c7d3d7e1ad18864d13b0b3eaf69f481b5f1a0c68fd652f29cd9bff4e7b9f95f4adf57698d77849371bc635f9ba3ef36c945f12a1b63e2a350e50fc886bbb
+  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

@@ -463,25 +463,72 @@ module Moxml
           # instances). The hot bare reads super into the C methods
           # (exact-name = the bare-name contract).
           module Identity
+            # The C faces are captured before the contract modules
+            # shadow them — alias copies bind at this point, so the
+            # overrides below plain-dispatch the native reads
+            # (leptris-ruby#463 completed the surface: every contract
+            # face is a C method at 50-84ns).
             ELEMENT = Class.new(::Leptris::XML::NativeNode) do
+              alias_method :native_name, :name
               include ::Moxml::Node
               include ::Moxml::Element
+
+              # Memo form kept: a warm read is an ivar hit (~30ns
+              # vs the C call's 84ns); the cold read drops the
+              # adapter round-trip and its PI-check bind_call.
+              def name
+                @name ||= native_name
+              end
             end
             TEXT = Class.new(::Leptris::XML::NativeNode) do
+              alias_method :native_content, :content
               include ::Moxml::Node
               include ::Moxml::Text
+
+              # Text#content's memo + entity restore are the
+              # contract; the backing read drops the adapter
+              # round-trip (dispatch + is_a? + bind_call) for the
+              # C face.
+              def raw_content
+                native_content
+              end
             end
             CDATA = Class.new(::Leptris::XML::NativeNode) do
+              alias_method :native_content, :content
               include ::Moxml::Node
               include ::Moxml::Cdata
+
+              def content
+                native_content
+              end
             end
             COMMENT = Class.new(::Leptris::XML::NativeNode) do
+              alias_method :native_content, :content
               include ::Moxml::Node
               include ::Moxml::Comment
+
+              # The nil bridge stays for floor-admitted bindings
+              # where the native face answers nil for comment-kind
+              # (leptris-ruby#313).
+              def content
+                content = native_content
+                return ::Moxml::Adapter::Leptris.to_binding(self).content if content.nil?
+
+                content
+              end
             end
             PROCESSING_INSTRUCTION = Class.new(::Leptris::XML::NativeNode) do
+              alias_method :native_content, :content
               include ::Moxml::Node
               include ::Moxml::ProcessingInstruction
+
+              # Same nil bridge as Comment (leptris-ruby#344).
+              def content
+                content = native_content
+                return ::Moxml::Adapter::Leptris.to_binding(self).content if content.nil?
+
+                content
+              end
             end
 
             TYPES = {
@@ -537,6 +584,46 @@ module Moxml
             end
             ELEMENT.include(Reads)
             TEXT.include(Reads)
+
+            # leptris-ruby#503: name_read joins attr_read/text_read as
+            # the unshadowed contract faces. With them, the hot reads
+            # plain-dispatch the C faces (one Ruby frame over the
+            # ~45ns native call) instead of the adapter bind_call
+            # crossing. Face-probed — older bindings keep the
+            # adapter paths. The memos ride the existing
+            # invalidation: name= and clear_native_memo! clear
+            # @name, content= clears @content.
+            if NN.method_defined?(:name_read)
+              module ContractReads
+                def name
+                  @name ||= name_read
+                end
+              end
+              ELEMENT.include(ContractReads)
+            end
+
+            if NN.method_defined?(:text_read)
+              module TextContractReads
+                # The stamp fast path is inlined (same ivar protocol
+                # as Reads#doc_entity_bearing?, which stays the
+                # single writer on recompute) — the two frames it
+                # saves are ~20% of the cold read.
+                def content
+                  value = @content
+                  return value if value
+
+                  value = text_read
+                  stamp = @doc_entity_stamp
+                  if stamp && (stamp >> 1) == ::Moxml::Adapter::Leptris.serialize_generation
+                    value = ::Moxml::Adapter::Leptris.restore_entities(value) if stamp.allbits?(1)
+                  elsif doc_entity_bearing?
+                    value = ::Moxml::Adapter::Leptris.restore_entities(value)
+                  end
+                  @content = value
+                end
+              end
+              TEXT.include(TextContractReads)
+            end
           end
 
           # leptris-ruby#246 klass-propagating reads: the read
@@ -1246,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
@@ -2743,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)
@@ -2842,6 +2957,7 @@ module Moxml
         PARENT_AXIS_CACHE = XPath::Cache.new(100)
 
         def xpath(node, expression, namespaces = {})
+          namespaces = normalize_xpath_namespaces(namespaces)
           node = to_binding(node) if NATIVE_READ_LAYER
           native = native_xpath(node, expression, namespaces)
           return native unless native.nil?
@@ -2873,6 +2989,7 @@ module Moxml
         end
 
         def at_xpath(node, expression, namespaces = {})
+          namespaces = normalize_xpath_namespaces(namespaces)
           native = native_xpath(node, expression, namespaces, first_only: true)
           return native unless native.nil?
 
@@ -2880,6 +2997,16 @@ module Moxml
           result.is_a?(Array) ? result.first : result
         end
 
+        # Bindings arrive in both spellings (symbol keys are the
+        # common Nokogiri idiom); every seam below — the "xmlns"
+        # reserved-key check and the native pairs set — is
+        # string-keyed (issue #395).
+        def normalize_xpath_namespaces(namespaces)
+          return namespaces unless namespaces.is_a?(Hash)
+
+          namespaces.transform_keys(&:to_s)
+        end
+
         # @return [Array, Object, nil] native results, or nil when the
         #   query must run on the Ruby engine
         def native_xpath(node, expression, namespaces, first_only: false)

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/adapter/rexml.rb

@@ -607,6 +607,11 @@ module Moxml
           # XPath.match for every expression: get_elements only
           # handles simple child-name paths — attribute terminals,
           # absolute paths and predicates silently degrade there.
+          # REXML resolves prefixes by string spelling — symbol-keyed
+          # bindings (the common Nokogiri idiom) must normalize or
+          # namespaced elements never match (issue #395).
+          namespaces = namespaces.transform_keys(&:to_s) if
+            namespaces.is_a?(Hash)
           if namespaces && !namespaces.empty?
             ::REXML::XPath.match(node, expression, namespaces).to_a
           else