moxml 0.5.178 → 0.6.0

data/README.adoc

@@ -56,8 +56,7 @@ widely used implementation which wraps around the performant
 https://github.com/GNOME/libxml2[libxml2] C library.
 
 Oga:: https://github.com/yorickpeterse/oga[Oga], a pure Ruby XML parser.
-Recommended when you need a pure Ruby solution say for
-https://github.com/opal/opal[Opal].
+Useful when you need a dependency with no native code.
 
 Ox:: https://github.com/ohler55/ox[Ox], a fast XML parser.
 
@@ -100,9 +99,8 @@ or :nokogiri. Removal after the deprecation cycle.
 
 |Oga
 |3.4 / 3.5
-|The moxml repository vendors an Opal-compatible fork of oga 3.4
-for development and CI. Oga 4.x is not yet validated against
-moxml's customized generator and decoder overrides.
+|Oga 4.x is not yet validated against moxml's customized generator
+and decoder overrides.
 
 |LibXML (libxml-ruby)
 |>= 5.0
@@ -131,8 +129,7 @@ matrix tests exactly those floors.
 When no adapter is explicitly specified, Moxml selects one automatically based on
 the runtime environment:
 
-. If running on Opal (`RUBY_ENGINE == "opal"`), Oga is used (pure Ruby, no C extensions)
-. Otherwise, if the installed leptris gem supports programmatic document
+. If the installed leptris gem supports programmatic document
   construction (`Leptris::XML::Document.create`, leptris >= 1.9.386.0), Leptris is used
 . Otherwise, Moxml detects already-loaded XML libraries in this order:
   .. Nokogiri
@@ -144,7 +141,7 @@ the runtime environment:
 ----
 # Automatic detection — picks the best available adapter
 ctx = Moxml.new
-ctx.config.adapter_name  # => :leptris (leptris >= 1.9.386.0), :nokogiri otherwise, :oga on Opal
+ctx.config.adapter_name  # => :leptris (leptris >= 1.9.386.0), :nokogiri otherwise
 
 # Explicit override — always takes precedence
 ctx = Moxml.new(:ox)
@@ -1238,384 +1235,4 @@ performance optimization, and testing strategies, see
 link:docs/_pages/best-practices.adoc[Best Practices Guide].
 
 
-== Running under Opal (JavaScript)
-
-Opal compiles Ruby to JavaScript and cannot load C extensions. To run
-Moxml on Opal you need three things: an adapter with no native code, a
-XML library fork that exposes pure-Ruby fallbacks for its lexer and
-parser driver, and an Opal build that puts those pure-Ruby
-implementations on the load path.
-
-=== Default adapter under Opal
-
-Under `RUBY_ENGINE == "opal"`, Moxml's default adapter is `:oga` (see
-<<Default adapter selection>>). Oga is a pure-Ruby XML parser; under
-standard CRuby its lexer and parsers are accelerated by the `liboga`
-and `libll` C extensions. Those extensions cannot be compiled into
-JavaScript, so on Opal they are replaced by the pure-Ruby fallbacks
-shipped in `ext/pureruby/` of the Opal-compatible forks below.
-
-The REXML adapter is also available on Opal (`Moxml.new(:rexml)`) but
-relies on a number of compatibility shims because REXML uses Ruby
-regular-expression features (the `/n` flag, `\u{...}` codepoint
-escapes, inline flag groups) and String APIs that do not all transpile
-to JavaScript today. `:oga` is the recommended path for new Opal
-projects.
-
-=== Required XML library forks
-
-Upstream https://github.com/yorickpeterse/oga[oga] and
-https://github.com/yorickpeterse/ruby-ll[ruby-ll] do not currently
-ship Opal-compatible fallbacks. Moxml vendors the following forks:
-
-* https://github.com/lutaml/opal-oga[lutaml/opal-oga] — oga with an
-  `ext/pureruby/oga/native/lexer.rb` fallback that fires when
-  `RUBY_PLATFORM == 'opal'`. Under CRuby/JRuby the fork behaves
-  identically to upstream oga.
-* https://github.com/lutaml/opal-ruby-ll[lutaml/opal-ruby-ll] —
-  ruby-ll with `ext/pureruby/ll/native/{driver,driver_config}.rb`
-  fallbacks selected by the same conditional in `lib/ll/setup.rb`.
-
-Both forks are vendored as submodules under `vendor/opal-oga` and
-`vendor/opal-ruby-ll` in the Moxml repository. Moxml's own `Gemfile`
-references them via `path:` source so that any consumer of Moxml under
-Opal resolves to the same fork commits Moxml was tested against.
-
-=== Wiring the forks in a downstream Gemfile
-
-Downstream libraries that run on Opal (for example
-https://github.com/plurimath/plurimath-js[plurimath-js]) must also use
-the Opal-compatible forks rather than upstream `oga` and `ruby-ll`.
-Wire them as `path:` or `git:` sources so the fork's
-`RUBY_PLATFORM == 'opal'` conditional can fire:
-
-[source,ruby]
-----
-# In your downstream gem's Gemfile (or gemspec)
-gem "moxml",    "~> 0.1.24"        # provides the :oga adapter
-gem "oga",      git: "https://github.com/lutaml/opal-oga.git",
-                ref: "<commit-sha-moxml-tests-against>"
-gem "ruby-ll",  git: "https://github.com/lutaml/opal-ruby-ll.git",
-                ref: "<commit-sha-moxml-tests-against>"
-----
-
-Pin the `ref:` to the submodule commits Moxml ships in
-`vendor/opal-oga` and `vendor/opal-ruby-ll` (recorded in
-`.gitmodules`) so your fork and Moxml's fork stay in lockstep. If you
-prefer to vendor the forks yourself, replace the `git:` source with
-`path: "vendor/opal-oga"` and `path: "vendor/opal-ruby-ll"` after
-copying them in.
-
-=== Opal build configuration
-
-Under Opal, the forks' `lib/` directory is on the load path (via the
-gem), but the pure-Ruby implementations live under `ext/pureruby/`.
-That directory must be added to Opal's load path so the
-`if RUBY_PLATFORM == 'opal'` branch in `lib/oga.rb` and
-`lib/ll/setup.rb` resolves to the pure-Ruby files instead of trying to
-load the C extension.
-
-For consumers using https://github.com/opal/opal[Opal] directly:
-
-[source,ruby]
-----
-require "opal"
-
-# Opal path: put both lib/ and ext/pureruby/ on the load path so the
-# fork's conditional requires resolve to the pure-Ruby fallback.
-%w[opal-oga opal-ruby-ll].each do |fork|
-  Opal.append_path File.expand_path("vendor/#{fork}/lib", __dir__)
-  Opal.append_path File.expand_path("vendor/#{fork}/ext/pureruby", __dir__)
-end
-
-# Moxml's Opal boot file (lib/compat/opal/moxml_boot.rb) explicitly
-# requires every module that would normally be autoloaded under CRuby.
-require "moxml_boot"
-----
-
-For consumers using https://github.com/opal/opal-compiler[Opal via
-Sprockets/Webpack], the equivalent is to add both `lib/` and
-`ext/pureruby/` from each fork to the Opal `paths` array.
-
-=== Verifying the Opal build
-
-Moxml's own Opal test suite exercises the wiring described above. To
-reproduce:
-
-[source,shell]
-----
-# One-time setup: install ragel + ruby-ll so the forks' gitignored
-# generated lexer/parser sources can be produced. ruby-ll must be
-# installed outside the bundle: vendor:prepare runs it outside Bundler.
-gem install ruby-ll --no-document
-# (Install ragel via your package manager, e.g. apt-get install ragel
-#  or brew install ragel.)
-
-# Generate the gitignored outputs in the vendored forks.
-bundle exec rake vendor:prepare
-
-# Run the Opal (JavaScript) test suite.
-bundle exec rake spec:opal
-----
-
-Reference implementation: https://github.com/plurimath/plurimath-js[plurimath-js]
-is the canonical downstream consumer; its `Rakefile` and `env/` wrapper
-scripts show the full pattern end-to-end.
-
-
-== Specific adapter limitations
-
-=== Ox adapter
-
-The Ox adapter provides maximum parsing speed but has XPath limitations.
-
-**XPath limitations:**
-
-* No attribute value predicates: `//book[@id='123']` ❌
-* No logical operators, position predicates, text predicates ❌
-* No namespace queries, parent axis, sibling axes ❌
-* No XPath functions ❌
-
-**Workaround:** Use Ruby enumerable methods:
-
-[source,ruby]
-----
-# Instead of: doc.xpath("//book[@id='123']")
-doc.xpath("//book").find { |book| book["id"] == "123" }
-----
-
-**Upstream Ox gem limitations:**
-
-These limitations exist in the Ox gem itself and cannot be worked around in Moxml
-without changes to the Ox C extension:
-
-* *Namespace introspection* — Ox stores `xmlns` attributes but does not expose
-  namespace accessors on `Ox::Element`. Methods like `node.namespace`,
-  `node.namespaces`, and namespace inheritance are unavailable.
-* *Parent node reparenting* — Ox has no method to change a node's parent after
-  creation, preventing `node.parent=` functionality. Nodes are immutable with
-  respect to their parent relationship.
-
-For complete Ox adapter documentation including all limitations and workarounds,
-see link:docs/_pages/adapters/ox.adoc[Ox Adapter Guide].
-
-=== HeadedOx adapter
-
-The HeadedOx adapter combines Ox's fast C-based XML parsing with Moxml's
-comprehensive pure Ruby XPath 1.0 engine.
-
-**Status:** Production-ready v1.2 (99.20% pass rate, 1,992/2,008 tests)
-
-**Key features:**
-
-* Fast XML parsing (Ox C extension)
-* All 27 XPath 1.0 functions
-* 6 XPath axes (child, descendant, parent, attribute, self, descendant-or-self)
-* Expression caching for performance
-* Pure Ruby XPath engine (debuggable)
-
-**When to use:**
-
-* Need Ox's fast parsing with comprehensive XPath
-* Want XPath functions (count, sum, contains, etc.)
-* Prefer pure Ruby XPath for debugging
-* Basic namespace queries are sufficient
-
-**Inherited Ox limitations:**
-
-HeadedOx inherits the upstream Ox gem limitations described above (namespace
-introspection and parent node reparenting). Additionally, some sibling axes
-are not fully supported due to Ox's tree structure.
-
-[source,ruby]
-----
-# Use HeadedOx adapter
-context = Moxml.new(:headed_ox)
-doc = context.parse(xml_string)
-
-# Full XPath 1.0 support
-books = doc.xpath('//book[@price < 20]')
-count = doc.xpath('count(//book)')
-titles = doc.xpath('//book/title[contains(., "Ruby")]')
-----
-
-For complete HeadedOx documentation including architecture, XPath capabilities, known limitations, and usage examples, see link:docs/_pages/adapters/headed-ox.adoc[HeadedOx Adapter Guide] and link:docs/HEADED_OX_LIMITATIONS.md[Limitations Documentation].
-
-
-==== LibXML adapter
-
-*Performance:*
-
-* Serialization speed: ~120 ips (slower than target)
-* Parsing speed: Good
-* For high-throughput serialization, consider Ox or Nokogiri
-
-=== Other adapters
-
-*Nokogiri, Oga, REXML:*
-
-All three adapters have near-complete feature support with only minor edge case
-limitations. Use these adapters when you need full XPath and namespace support.
-
-
-
-== Round-trip XML Testing
-
-Moxml includes comprehensive round-trip testing to verify that XML documents remain
-semantically equivalent when parsed and serialized across different adapters.
-
-=== Purpose
-
-Round-trip testing ensures:
-
-* **Cross-adapter compatibility** - XML parsed with one adapter (e.g., Nokogiri) can be
-  serialized and re-parsed with another adapter (e.g., Oga) while preserving content
-* **Structural fidelity** - Element names, attributes, and document structure are maintained
-* **Content preservation** - Text content and entity references survive multiple parse/serialize cycles
-* **Double round-trip verification** - Source → Target → Source sequences produce semantically
-  equivalent output
-
-=== Test Fixtures
-
-Round-trip tests use real-world XML documents organized into collections:
-
-**rfcxml** - IETF RFC documents in XML format. These provide complex, standards-compliant
-XML with mixed content, namespaces, and attributes. The collection includes:
-
-* Large documents (500KB-2.4MB) for stress testing
-* Rich metadata and cross-references
-* Various XML schema patterns
-
-**metanorma** - Metanorma document processing XML. These test:
-
-* Document structure preservation
-* Nested elements and complex hierarchies
-* Standard XML vocabularies
-
-**niso-jats** - NISO Journal Article Tag Suite XML. These provide:
-
-* Scholarly publishing XML schemas
-* Rich bibliographic metadata
-* Mixed content models
-
-=== Running Round-trip Tests
-
-[source,bash]
-----
-# Run all round-trip tests
-bundle exec rake spec:consistency
-
-# Exclude REXML for larger fixtures (faster, REXML is pure Ruby)
-MOXML_ROUNDTRIP_REXML_MAX_SIZE=0 bundle exec rake spec:consistency
-
-# Adjust the per-example timeout (default: 120 seconds)
-MOXML_ROUNDTRIP_TIMEOUT=300 bundle exec rake spec:consistency
-----
-
-REXML is a pure Ruby XML parser and becomes very slow on large documents (500KB+).
-By default, REXML adapter pairs are skipped for fixtures exceeding 500KB. All other
-adapters (Nokogiri, Oga, Ox) are tested against every fixture.
-
-=== Test Mechanics
-
-For each fixture, tests run across all adapter pairs (4 adapters = 12 combinations):
-
-1. Parse with source adapter
-2. Serialize to XML string
-3. Parse serialized output with target adapter
-4. Compare semantic equivalence (element names, attributes, text content)
-
-A "double round-trip" test additionally verifies: Source → Target → Source → Target
-produces consistent results.
-
-NOTE: REXML is excluded from adapter pairs for fixtures larger than 500KB (configurable
-via `MOXML_ROUNDTRIP_REXML_MAX_SIZE`). This is because REXML is pure Ruby and cannot
-parse large XML documents in a practical timeframe. A per-example timeout
-(`MOXML_ROUNDTRIP_TIMEOUT`, default 120s) prevents tests from hanging indefinitely.
-
-=== Ox Adapter Element Ordering Caveat
-
-The Ox adapter produces elements in a different order than other adapters for certain
-fixtures with complex nested structures (e.g., `element_citation.xml`,
-`collection1nested.xml`, `pnas_sample.xml`). This causes the `elements_with_attributes`
-comparison to fail with "Array length mismatch" even though the semantic equivalence
-check (double round-trip) passes.
-
-Round-trip tests automatically skip the `elements_with_attributes` comparison for these
-known Ox ordering issues. The `ruby-versions` CI job tests only Nokogiri and Oga adapters;
-the `nokogiri-ox` and `nokogiri-rexml` CI jobs test Ox and REXML respectively but are
-marked as **experimental** since these adapters lack full XML feature support:
-
-* **Ox**: Lacks proper namespace support, XPath with predicates, and uses a custom
-  `locate()` method instead of standard XPath
-* **REXML**: Pure Ruby, exponential time complexity with document size, impractical for
-  documents over ~500KB
-
-For production use, prefer Nokogiri or Oga which provide complete XML conformance.
-
-To run tests with a specific adapter set locally:
-
-[source,bash]
-----
-# Nokogiri + Oga only (fast, full test suite)
-MOXML_ROUNDTRIP_ADAPTERS=nokogiri,oga bundle exec rspec spec/consistency/ --tag round_trip
-
-# Nokogiri × Ox only (experimental)
-MOXML_ROUNDTRIP_ADAPTERS=nokogiri,ox MOXML_ROUNDTRIP_TIMEOUT=300 bundle exec rspec spec/consistency/ --tag round_trip
-
-# Nokogiri × REXML only (experimental, small fixtures due to exponential complexity)
-MOXML_ROUNDTRIP_ADAPTERS=nokogiri,rexml MOXML_ROUNDTRIP_TIMEOUT=300 MOXML_ROUNDTRIP_REXML_MAX_SIZE=50000 bundle exec rspec spec/consistency/ --tag round_trip
-----
-
-=== Why Semantic Equivalence?
-
-While a pure round-trip test with raw XML comparison would be ideal, different XML adapters
-have fundamentally different philosophies for handling:
-
-* **Element ordering** - Some preserve document order, others sort alphabetically
-* **Whitespace handling** - Some normalize spaces, others preserve exactly
-* **Attribute representation** - Different data structures for the same attributes
-* **Text extraction** - Varying approaches to concatenating text content
-
-Instead of raw comparison, Moxml implements semantic equivalence testing that focuses on
-meaningful XML structure and content:
-
-[source,ruby]
-----
-# Element name must match
-expect(target_element.name).to eq(source_element.name)
-
-# Attributes must be semantically equivalent
-expect(target_attributes).to eq(source_attributes)
-
-# Text content must be preserved (whitespace-normalized)
-expect(normalized_text(target)).to eq(normalized_text(source))
-
-# Document structure (element count) must match
-expect(doc.xpath("//*").size).to eq(original.xpath("//*").size)
-----
-
-This approach tolerates adapter-specific serialization differences while ensuring
-the actual XML content remains intact.
-
-
-== Development and testing
-
-For complete information on development setup, testing strategies, benchmarking,
-and coverage reporting, see the
-link:docs/_guides/development-testing.adoc[Development and Testing Guide].
-
-== Contributing
-
-. Fork the repository
-. Create your feature branch (`git checkout -b feature/my-new-feature`)
-. Commit your changes (`git commit -am 'Add some feature'`)
-. Push to the branch (`git push origin feature/my-new-feature`)
-. Create a new Pull Request
-
-== License
-
-Copyright Ribose.
-
-This project is licensed under the Ribose 3-Clause BSD License. See the
 link:LICENSE.md[] file for details.

data/Rakefile

@@ -2,161 +2,22 @@
 
 require "bundler/gem_tasks"
 
-# vendor:prepare must be runnable before `bundle install` (CI runs it
-# first so the path-source oga/ruby-ll forks' gitignored lexer/parser
-# outputs exist before their extconf.rb runs). Guard the rspec/opal
-# requires so the file loads with only `rake` + `bundler` available.
+# Guard the rspec requires so the file loads with only `rake` +
+# `bundler` available.
 begin
   require "rspec/core/rake_task"
   RSpec::Core::RakeTask.new(:spec)
 rescue LoadError
 end
 
-begin
-  require "opal/rspec/rake_task"
-
-  # REXML is a bundled gem since Ruby 3.4; its source must be on Opal's
-  # global load path so the compiler can follow `require "rexml/document"`.
-  # Opal-compatible overrides go first so they shadow the gem originals.
-  if defined?(Opal)
-    Opal.append_path File.expand_path("lib/compat/opal", __dir__)
-    rexml_lib = $LOAD_PATH.find do |p|
-      File.exist?(File.join(p, "rexml", "document.rb"))
-    end
-    Opal.append_path rexml_lib if rexml_lib
-
-    # The Opal-compatible oga and ruby-ll forks (vendored as submodules)
-    # expose pure-Ruby implementations under ext/pureruby/. Their top-level
-    # lib/oga.rb and lib/ll/setup.rb conditionally require them when
-    # RUBY_PLATFORM == 'opal'. Both lib/ and ext/pureruby/ must be on
-    # Opal's load path so the conditional resolves correctly.
-    %w[opal-oga opal-ruby-ll].each do |fork_name|
-      fork_path = File.expand_path("vendor/#{fork_name}", __dir__)
-      Opal.append_path File.join(fork_path, "lib")
-      Opal.append_path File.join(fork_path, "ext/pureruby")
-    end
-  end
-rescue LoadError
-  # Opal not available or incompatible with current Ruby version
-end
-
 begin
   require "rubocop/rake_task"
   RuboCop::RakeTask.new
 rescue LoadError
 end
 
-# Regenerate the ragel / ruby-ll outputs that the Opal-compatible forks
-# (vendored as submodules under vendor/) gitignore. The forks ship the
-# grammar sources (.rl / .rll) but not the generated .rb / .c, since
-# those are large and version-controllable upstream. Both ragel and
-# ruby-ll must be on PATH; the upstream ruby-ll gem is sufficient for
-# generation (the fork is only needed at runtime).
-namespace :vendor do
-  desc "Generate ragel / ruby-ll outputs in vendored opal-oga and opal-ruby-ll"
-  task :prepare do
-    require "fileutils"
-
-    oga = File.expand_path("vendor/opal-oga", __dir__)
-    ruby_ll = File.expand_path("vendor/opal-ruby-ll", __dir__)
-
-    generators = [
-      # oga: ruby-ll grammar → Ruby parser
-      ["ruby-ll #{oga}/lib/oga/xml/parser.rll -o #{oga}/lib/oga/xml/parser.rb",
-       "#{oga}/lib/oga/xml/parser.rb",
-       "#{oga}/lib/oga/xml/parser.rll"],
-      ["ruby-ll #{oga}/lib/oga/xpath/parser.rll -o #{oga}/lib/oga/xpath/parser.rb",
-       "#{oga}/lib/oga/xpath/parser.rb",
-       "#{oga}/lib/oga/xpath/parser.rll"],
-      ["ruby-ll #{oga}/lib/oga/css/parser.rll -o #{oga}/lib/oga/css/parser.rb",
-       "#{oga}/lib/oga/css/parser.rb",
-       "#{oga}/lib/oga/css/parser.rll"],
-      # oga: ragel Ruby lexer
-      ["ragel -R -F1 #{oga}/lib/oga/xpath/lexer.rl -o #{oga}/lib/oga/xpath/lexer.rb",
-       "#{oga}/lib/oga/xpath/lexer.rb",
-       "#{oga}/lib/oga/xpath/lexer.rl"],
-      ["ragel -R -F1 #{oga}/lib/oga/css/lexer.rl -o #{oga}/lib/oga/css/lexer.rb",
-       "#{oga}/lib/oga/css/lexer.rb",
-       "#{oga}/lib/oga/css/lexer.rl"],
-      # oga: ragel C lexer for liboga
-      ["ragel -C -I #{oga}/ext/ragel -G2 #{oga}/ext/c/lexer.rl -o #{oga}/ext/c/lexer.c",
-       "#{oga}/ext/c/lexer.c",
-       "#{oga}/ext/c/lexer.rl"],
-      # ruby-ll: ruby-ll grammar → Ruby parser
-      ["ruby-ll #{ruby_ll}/lib/ll/parser.rll -o #{ruby_ll}/lib/ll/parser.rb --no-requires",
-       "#{ruby_ll}/lib/ll/parser.rb",
-       "#{ruby_ll}/lib/ll/parser.rll"],
-    ]
-
-    # Under bundle exec, ruby-ll resolves to the vendored opal-ruby-ll
-    # binstub, which needs the not-yet-compiled libll.
-    Bundler.with_unbundled_env do
-      generators.each do |cmd, output, source|
-        if File.exist?(output) && File.mtime(output) >= File.mtime(source)
-          next
-        end
-
-        FileUtils.mkdir_p(File.dirname(output))
-        sh cmd
-      end
-    end
-  end
-
-  # Bundler does not reliably compile native extensions for path-source
-  # gems. Build liboga/libll explicitly so `require "oga"` resolves.
-  desc "Compile liboga / libll native extensions for vendored forks"
-  task :compile do
-    require "fileutils"
-    require "rbconfig"
-
-    dlext = RbConfig::CONFIG["DLEXT"]
-
-    {
-      "vendor/opal-ruby-ll" => "libll",
-      "vendor/opal-oga" => "liboga",
-    }.each do |fork_path, ext_name|
-      abs_fork = File.expand_path(fork_path, __dir__)
-      lib_bundle = File.join(abs_fork, "lib", "#{ext_name}.#{dlext}")
-      ext_dir = File.join(abs_fork, "ext", "c")
-      extconf = File.join(ext_dir, "extconf.rb")
-      lib_dir = File.join(abs_fork, "lib")
-      next if File.exist?(lib_bundle)
-
-      Dir.chdir(ext_dir) do
-        sh "ruby #{extconf}"
-        sh "make"
-        FileUtils.cp("#{ext_name}.#{dlext}", lib_dir)
-      end
-    end
-  end
-end
-
 if defined?(RSpec)
 namespace :spec do
-  if defined?(Opal::RSpec::RakeTask)
-    desc "Run Opal (JavaScript) tests"
-    Opal::RSpec::RakeTask.new(:opal) do |server, runner|
-      server.append_path "lib"
-      server.append_path "spec"
-
-      runner.default_path = "spec"
-      # `oga` and `ll/setup` must be required before moxml_boot so that
-      # the forks' Opal-aware conditional requires fire (lib/oga.rb calls
-      # `require 'oga/native/lexer'` when RUBY_PLATFORM == 'opal'; that
-      # resolves against vendor/opal-oga/ext/pureruby/, which the global
-      # Opal.append_path calls above add to the load path).
-      runner.requires = %w[rexml_compat rexml/document rexml/xpath
-                           oga ll/setup
-                           moxml_boot spec_helper support/opal]
-      runner.files = Dir.glob("spec/moxml/*opal*_spec.rb") +
-        Dir.glob("spec/moxml/native_attachment/opal_spec.rb") +
-        Dir.glob("spec/moxml/adapter/shared_examples/*.rb")
-    end
-
-    desc "Alias for spec:opal that also runs vendor:prepare"
-    task opal: "vendor:prepare"
-  end
-
   desc "Validate XML fixtures are well-formed (requires xmllint)"
   task :validate_fixtures do
     fixtures = Dir.glob("spec/fixtures/**/*.xml")
@@ -305,44 +166,6 @@ namespace :benchmark do
   end
 end
 
-namespace :opal do
-  desc "Regenerate entity data for Opal from w3c_entities.json"
-  task :generate_entity_data do
-    require "json"
-
-    source = File.join(__dir__, "data", "w3c_entities.json")
-    target = File.join(__dir__, "lib", "moxml", "entity_registry_opal_data.rb")
-
-    data = JSON.parse(File.read(source))
-    chars = data["characters"]
-
-    lines = []
-    lines << "# frozen_string_literal: true"
-    lines << "#"
-    lines << "# Auto-generated entity data for Opal runtime."
-    lines << "# Source: data/w3c_entities.json (#{chars.size} entities)"
-    lines << "# Regenerate with: rake opal:generate_entity_data"
-    lines << ""
-    lines << "module Moxml"
-    lines << "  class EntityRegistry"
-    lines << "    OPAL_ENTITY_DATA = {"
-    chars.each do |name, char|
-      codepoint = if char.start_with?("\\u")
-                    char.unicode_normalize(:nfc)[2..].to_i(16)
-                  else
-                    char.ord
-                  end
-      lines << "      #{name.inspect} => #{codepoint},"
-    end
-    lines << "    }.freeze"
-    lines << "  end"
-    lines << "end"
-
-    File.write(target, "#{lines.join("\n")}\n")
-    puts "Generated #{target} (#{chars.size} entities, #{lines.size} lines)"
-  end
-end
-
 namespace :docs do
   desc "Regenerate the published model-coverage page from the matrix"
   task :coverage do

data/docs/_references/processing-model.adoc

@@ -25,8 +25,9 @@ Pins:: none
    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.
+   against each other; the reference is pure Ruby. (The Opal
+   transpile lane was removed in #489 phase 4 — the JS surface is
+   the moxml-ts wasm binding.)
 3. Adapter implementations and capability gates — representations.
 
 A pin cites the model section it enforces

data/lib/moxml/adapter/customized_oga.rb

@@ -2,10 +2,12 @@
 
 module Moxml
   module Adapter
-    # Lifecycle record (#495): every override serves the :oga adapter,
-    # deprecated in moxml#491 and deleted with the Opal surface in
-    # moxml#489 phase 4. No separate upstream ask -- the adapter's
-    # fate governs this file.
+    # Lifecycle record (#495): every override serves the :oga
+    # adapter. The Opal surface that motivated them is deleted
+    # (moxml#489 phase 4, 2026-10-31); the overrides remain because
+    # the CRuby :oga adapter calls them on core paths, and the
+    # adapter's fate -- the owner's removal decision, consumer
+    # evidence in moxml#490 -- governs this file.
     module CustomizedOga
       autoload :EntityDecoderOverride, "moxml/adapter/customized_oga/entity_decoder"
       autoload :RawValueOverride, "moxml/adapter/customized_oga/raw_value_override"

data/lib/moxml/adapter/customized_rexml.rb

@@ -3,9 +3,11 @@
 module Moxml
   module Adapter
     # Lifecycle record (#495): engine-gap shims for the :rexml
-    # adapter (Opal fallback; deleted with the Opal surface in
-    # moxml#489 phase 4). No separate upstream ask; the adapter's
-    # fate governs this file.
+    # adapter. The Opal surface (this adapter's historical fallback
+    # role) is deleted (moxml#489 phase 4, 2026-10-31); the shims
+    # remain because the CRuby :rexml adapter calls them. The
+    # adapter's fate -- the owner's removal decision, consumer
+    # evidence in moxml#490 -- governs this file.
     module CustomizedRexml
       autoload :EntityReference,
                "moxml/adapter/customized_rexml/entity_reference"

data/lib/moxml/adapter/headed_ox.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-return if RUBY_ENGINE == "opal"
-
 require "moxml/adapter/ox"
 
 module Moxml