moxml 0.1.15 → 0.1.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41df5c029544cf0136de3a87a60a1926df913b973b2653f7bb56c2e3725176b8
-  data.tar.gz: 59ef11350181ac4b5ddec209128f26cc17e629cb778776b6a198df6853a5ce22
+  metadata.gz: 378f1400934e3a65fb230779fc4b1783aab059efb449912a6dc2d97c8d82903e
+  data.tar.gz: 7cd2739dd2dc41c2edb69c129cc4ec175a7a6b8e455d4d63cfd56bd2a93e808f
 SHA512:
-  metadata.gz: c1e5e7f0a5a036bc900bd2d13522ff381cdb01fdc02d501aac6b328816bf4c2a953a0f47721665b1a209b9cdf89f29081a6410b286d6f4bdab7389b411e5475e
-  data.tar.gz: 7d05e346a9b0e32da8de5e26b29500dee443fed6c356ba12a3dafc4247b9fb2be454a02d41105e370d91c363f6bfd8445fa79c664003fa1e8f7eca8adb8da31e
+  metadata.gz: 311f4905dcf14fb3ec209491d9a5eae9b8fe460152f29c7f7b428db37b1c2adac09e538ce9c0a8a4eeff2b0af83a2e8b4a787adca59cb04d1c7f1b14b7fbf37d
+  data.tar.gz: 36cc3ce0e2328547137f1716d7b7ef3de4e07cbca160b08d8fbe74ef126edd6e61fe4dc0ed1d8767ed19f573792fc8fdc52c41e332802698218584db559576e0

data/Rakefile

@@ -10,6 +10,37 @@ require "rubocop/rake_task"
 RuboCop::RakeTask.new
 
 namespace :spec do
+  desc "Validate XML fixtures are well-formed (requires xmllint)"
+  task :validate_fixtures do
+    fixtures = Dir.glob("spec/fixtures/**/*.xml")
+    if fixtures.empty?
+      abort "No XML fixtures found in spec/fixtures/"
+    end
+
+    unless system("which xmllint > /dev/null 2>&1")
+      abort "xmllint not found. Install with: brew install libxml2 (macOS) or apt install libxml2-utils (Linux)"
+    end
+
+    # Intentionally malformed fixtures (W3C test cases for error handling)
+    exemptions = %w[
+      spec/fixtures/w3c/namespaces/1.0/035.xml
+    ]
+
+    errors = []
+    fixtures.each do |path|
+      next if exemptions.include?(path)
+
+      output = `xmllint --noout "#{path}" 2>&1`
+      errors << "#{path}: #{output.strip}" unless $?.success?
+    end
+
+    if errors.empty?
+      puts "#{fixtures.size} XML fixtures validated OK"
+    else
+      abort "Invalid fixtures:\n#{errors.join("\n")}"
+    end
+  end
+
   desc "Run unit tests only"
   RSpec::Core::RakeTask.new(:unit) do |t|
     t.pattern = "spec/unit/**/*_spec.rb"

data/TODO.remaining/1-entity-reference-adapter-support.md

@@ -0,0 +1,157 @@
+# TODO 1: EntityReference Adapter Support for Ox, Oga, REXML, LibXML, HeadedOx
+
+## Problem
+
+Only the Nokogiri adapter implements `create_native_entity_reference` and maps
+its native type to `:entity_reference` in `node_type`. The other 5 adapters
+will raise `NotImplementedError` if `restore_entities` is enabled or if any
+code path calls `create_entity_reference`. This makes the entire
+EntityReference feature **non-functional** outside Nokogiri.
+
+## Current State (verified)
+
+| Adapter   | `create_native_entity_reference` | `node_type` mapping | Serialization | Status |
+|-----------|----------------------------------|---------------------|---------------|--------|
+| Nokogiri  | Done (`Nokogiri::XML::EntityReference.new`) | Done | Native | Working |
+| Ox        | Missing | Missing | Uses `Ox.dump` (C-level, won't handle custom types) | Broken |
+| HeadedOx  | Missing (inherits Ox) | Missing | Same as Ox | Broken |
+| Oga       | Missing | Missing | Uses `CustomizedOga::XmlGenerator` | Broken |
+| REXML     | Missing | Missing | Uses REXML's `write` | Broken |
+| LibXML    | Missing | Missing | Uses custom serializer with wrapper detection | Broken |
+
+## Architecture
+
+EntityReference follows the same pattern as other non-native node types in Moxml:
+a **wrapper class** that represents what the underlying library cannot express natively.
+
+Each adapter needs three things:
+1. **Wrapper class** (`CustomizedXxx::EntityReference`) — holds the entity name
+2. **`node_type` mapping** — so `Node.wrap` can create the correct Moxml type
+3. **Serialization** — so `to_xml` outputs `&name;`
+
+The existing pattern: `CustomizedOx::Text` extends `::Ox::Node`,
+`CustomizedOx::Attribute` extends `::Ox::Node`. EntityReference should follow suit.
+
+### Serialization Challenge for Ox
+
+Ox's `serialize` calls `::Ox.dump(node)` which is C-level — it only handles
+Ox native types. For EntityReference wrappers to survive serialization, we need
+one of:
+
+- **Option A**: Custom serialization in the adapter that walks the tree manually,
+  detecting EntityReference wrappers and emitting `&name;` directly.
+- **Option B**: Convert EntityReferences to their text equivalent before calling
+  `Ox.dump`, restoring them in a post-processing step. This is fragile.
+- **Option C**: Override `serialize` for Element nodes to handle children
+  individually, using `Ox.dump` for native children but handling wrappers
+  directly.
+
+**Recommended: Option A** — it's how `CustomizedOga::XmlGenerator` already works
+for Oga. A similar tree-walking serializer for Ox gives full control.
+
+For LibXML, the existing serializer already checks `node.respond_to?(:to_xml)`
+for wrapper classes, so adding an EntityReference wrapper with `to_xml` returning
+`"&#{name};"` should integrate cleanly.
+
+## Implementation Steps
+
+### Ox Adapter
+
+1. Create `lib/moxml/adapter/customized_ox/entity_reference.rb`:
+   ```ruby
+   module Moxml::Adapter::CustomizedOx
+     class EntityReference < ::Ox::Node
+       attr_reader :name
+
+       def initialize(name)
+         @name = name
+         super()  # Ox::Node requires no args or a value
+       end
+
+       def to_xml
+         "&#{@name};"
+       end
+       alias to_s to_xml
+     end
+   end
+   ```
+
+2. Add to `lib/moxml/adapter/ox.rb`:
+   - `create_native_entity_reference(name)` → `CustomizedOx::EntityReference.new(name)`
+   - `node_type`: add `when CustomizedOx::EntityReference then :entity_reference`
+   - `patch_node`: handle EntityReference wrapper in child list
+   - `entity_reference_name(node)`: return `node.name`
+   - Serialization: handle EntityReference children when walking the tree
+
+3. Add to `lib/moxml/adapter/ox.rb` `unpatch_node`: return wrapper as-is
+   (it extends Ox::Node so it can stay in the tree)
+
+### HeadedOx Adapter
+
+HeadedOx inherits from Ox, so it gets Ox's EntityReference support
+automatically once Ox is done. Verify that the XPath engine doesn't
+break when encountering EntityReference nodes in the tree.
+
+### Oga Adapter
+
+1. Create `lib/moxml/adapter/customized_oga/entity_reference.rb`:
+   ```ruby
+   module Moxml::Adapter::CustomizedOga
+     class EntityReference
+       attr_reader :name
+
+       def initialize(name)
+         @name = name
+       end
+
+       def to_xml
+         "&#{@name};"
+       end
+     end
+   end
+   ```
+
+2. Add to `lib/moxml/adapter/oga.rb`:
+   - `create_native_entity_reference(name)` → `CustomizedOga::EntityReference.new(name)`
+   - `node_type`: add `when CustomizedOga::EntityReference then :entity_reference`
+   - Update `CustomizedOga::XmlGenerator` to handle EntityReference children
+   - `entity_reference_name(node)`: return `node.name`
+
+### REXML Adapter
+
+1. Investigate: REXML has `REXML::Entity` and `REXML::EntityRef` classes.
+   Check if they can be used as native entity reference nodes, or if a
+   wrapper is needed.
+
+2. Add to `lib/moxml/adapter/rexml.rb`:
+   - `create_native_entity_reference(name)` — native or wrapper
+   - `node_type`: add mapping
+   - `entity_reference_name(node)`
+
+### LibXML Adapter
+
+1. Investigate: LibXML Ruby has `LibXML::XML::Node::ENTITY_REF_NODE` constant
+   (value 5). Check if native entity reference nodes can be created.
+
+2. Create `lib/moxml/adapter/customized_libxml/entity_reference.rb` if needed.
+
+3. Add to `lib/moxml/adapter/libxml.rb`:
+   - `create_native_entity_reference(name)`
+   - `node_type`: add `ENTITY_REF_NODE` mapping or wrapper mapping
+   - `entity_reference_name(node)`
+   - The existing serializer already handles wrappers with `to_xml` —
+     verify EntityReference works in this path.
+
+## Files to Create/Modify
+
+### New Files
+- `lib/moxml/adapter/customized_ox/entity_reference.rb`
+- `lib/moxml/adapter/customized_oga/entity_reference.rb`
+- Possibly: `lib/moxml/adapter/customized_libxml/entity_reference.rb`
+
+### Modified Files
+- `lib/moxml/adapter/ox.rb` — create_native_entity_reference, node_type, serialization
+- `lib/moxml/adapter/oga.rb` — create_native_entity_reference, node_type, XmlGenerator
+- `lib/moxml/adapter/rexml.rb` — create_native_entity_reference, node_type
+- `lib/moxml/adapter/libxml.rb` — create_native_entity_reference, node_type
+- `lib/moxml/adapter/headed_ox.rb` — verify inheritance works (likely no changes)

data/TODO.remaining/2-entity-restoration-model-driven.md

@@ -0,0 +1,169 @@
+# TODO 2: Model-Driven Entity Restoration
+
+## Problem
+
+The `restore_entities` feature in `DocumentBuilder` is hardcoded to only handle
+the 5 standard XML entities (amp, lt, gt, quot, apos). It ignores the
+EntityRegistry entirely — despite EntityRegistry knowing 2125+ entities from
+the W3C HTML/MathML set. This means non-standard entities like ` `,
+`©`, `—` are never restored, which is the core round-trip problem
+that motivated the entire entity feature.
+
+Additionally, the restoration logic lives in DocumentBuilder with hardcoded
+knowledge that belongs in the model layer.
+
+## Current State (verified)
+
+`lib/moxml/document_builder.rb:80-110` — `restore_entities_in_text`:
+```ruby
+entity_chars = {
+  "<" => "lt", ">" => "gt", "&" => "amp",
+  '"' => "quot", "'" => "apos",
+}
+```
+
+This is a hardcoded lookup that duplicates knowledge already in EntityRegistry.
+It only triggers for characters `<`, `>`, `&`, `"`, `'` — the regex guard
+`/[<>&"']/` on line 73 prevents it from ever seeing characters like U+00A0
+(non-breaking space, `&nbsp;`).
+
+**Critical**: Because only Nokogiri has `create_native_entity_reference`
+(see TODO 1), `restore_entities` raises `NotImplementedError` on all other
+adapters even for the 5 standard entities.
+
+## XML Entity Model
+
+XML has a clear entity model:
+
+1. **5 predefined entities** (amp, lt, gt, quot, apos) — always available per
+   XML spec. These characters MUST be entity-encoded in certain contexts
+   (e.g., `<` and `&` in text content).
+
+2. **DTD-declared entities** — declared via `<!ENTITY name "value">` in the
+   document's DOCTYPE internal subset or external subset.
+
+3. **API-supplied entities** — registered by the user via
+   `EntityRegistry.register` or `entity_provider` callback.
+
+4. **Bundled detection set** — the W3C HTML/MathML entities bundled in
+   `data/w3c_entities.json`. These are not "declared" in any DTD but are
+   recognized by Moxml for restoration purposes.
+
+The EntityRegistry already knows about categories 1, 3, and 4. Category 2
+(DTD parsing) is future work.
+
+## Design: Model-Driven Restoration
+
+EntityRegistry should be THE source of truth for "should this character become
+an entity reference?" The restoration policy should be:
+
+```ruby
+# In EntityRegistry (or a cooperating policy object)
+STANDARD_CODEPOINTS = [0x26, 0x3C, 0x3E, 0x22, 0x27].freeze  # amp, lt, gt, quot, apos
+
+def should_restore?(codepoint, config:)
+  name = primary_name_for_codepoint(codepoint)
+  return false unless name
+
+  # 1. The 5 standard XML entities are ALWAYS restored.
+  #    These are syntactically required — the XML wouldn't be well-formed
+  #    without encoding them.
+  return true if STANDARD_CODEPOINTS.include?(codepoint)
+
+  # 2. Non-standard entities: only if restore_entities is enabled.
+  return false unless config.restore_entities
+
+  # 3. In the future, strict vs lenient mode will gate this further.
+  #    Strict: only if declared in DTD (not yet implemented).
+  #    Lenient: any known entity name.
+  true
+end
+```
+
+### Changes to DocumentBuilder
+
+Replace the hardcoded hash with delegation to the registry:
+
+```ruby
+def visit_text(node)
+  prepared = adapter.prepare_for_new_document(node, @current_doc.native)
+  content = adapter.text_content(node)
+
+  if should_restore_entities?(content)
+    restore_entities_in_text(content)
+  else
+    @node_stack.last&.add_child(Text.new(prepared, context))
+  end
+end
+
+private
+
+def should_restore_entities?(content)
+  return false unless context.config.restore_entities
+  # Scan for any character that the registry knows about
+  content.to_s.chars.any? { |c| context.entity_registry.should_restore?(c.ord, config: context.config) }
+end
+
+def restore_entities_in_text(content)
+  parent = @node_stack.last
+  return unless parent
+
+  content.to_s.chars.each do |char|
+    codepoint = char.ord
+    name = context.entity_registry.primary_name_for_codepoint(codepoint)
+
+    if context.entity_registry.should_restore?(codepoint, config: context.config)
+      entity_node = adapter.create_entity_reference(name)
+      parent.add_child(EntityReference.new(entity_node, context))
+    else
+      text_node = adapter.create_text(char)
+      parent.add_child(Text.new(text_node, context))
+    end
+  end
+end
+```
+
+**Note**: This splits each text node into per-character nodes. For documents
+with few entity references, this creates unnecessary overhead. A future
+optimization should buffer consecutive non-entity characters into a single
+text node.
+
+### Performance Optimization (deferred)
+
+Instead of character-by-character processing:
+1. Scan the text for characters that have entity names in the registry
+2. Split only at those positions, keeping runs of plain characters together
+3. This reduces node count dramatically for typical documents
+
+```ruby
+def restore_entities_in_text(content)
+  parent = @node_stack.last
+  return unless parent
+
+  buffer = +""
+  content.to_s.chars.each do |char|
+    codepoint = char.ord
+    name = context.entity_registry.primary_name_for_codepoint(codepoint)
+
+    if name && context.entity_registry.should_restore?(codepoint, config: context.config)
+      # Flush buffer before entity
+      if !buffer.empty?
+        parent.add_child(Text.new(adapter.create_text(buffer), context))
+        buffer.clear
+      end
+      parent.add_child(EntityReference.new(adapter.create_entity_reference(name), context))
+    else
+      buffer << char
+    end
+  end
+  # Flush remaining buffer
+  if !buffer.empty?
+    parent.add_child(Text.new(adapter.create_text(buffer), context))
+  end
+end
+```
+
+## Files to Modify
+
+- `lib/moxml/entity_registry.rb` — add `should_restore?` method
+- `lib/moxml/document_builder.rb` — replace hardcoded entity_chars with registry-driven logic

data/TODO.remaining/3-entity-reference-test-coverage.md

@@ -0,0 +1,170 @@
+# TODO 3: EntityReference Test Coverage
+
+## Problem
+
+There are zero tests for EntityReference node behavior, zero tests for
+entity round-trip preservation, and zero adapter-level tests for entity
+reference creation or serialization. Only `EntityRegistry` has tests
+(`spec/moxml/entity_registry_spec.rb`).
+
+This means the entire EntityReference feature is untested — including the
+`restore_entities` config, `create_entity_reference` factory, `visit_entity_reference`
+in DocumentBuilder, and the `entity_reference` Builder DSL method.
+
+## Required Test Coverage
+
+### 1. EntityReference Node Tests
+
+**File**: `spec/moxml/entity_reference_spec.rb`
+
+```ruby
+RSpec.describe Moxml::EntityReference do
+  # Test per adapter (use shared examples)
+  %i[nokogiri].each do |adapter|  # expand as adapters gain support
+    context "with #{adapter} adapter" do
+      let(:ctx) { Moxml.new(adapter) }
+
+      it "creates an entity reference node" do
+        doc = ctx.create_document
+        ref = doc.create_entity_reference("nbsp")
+        expect(ref).to be_a(Moxml::EntityReference)
+        expect(ref.name).to eq("nbsp")
+      end
+
+      it "has empty text content" do
+        doc = ctx.create_document
+        ref = doc.create_entity_reference("amp")
+        expect(ref.text).to eq("")
+        expect(ref.content).to eq("")
+      end
+
+      it "serializes to entity syntax" do
+        doc = ctx.create_document
+        ref = doc.create_entity_reference("mdash")
+        expect(ref.to_xml).to eq("—")
+      end
+
+      it "is recognized as entity_reference type" do
+        doc = ctx.create_document
+        ref = doc.create_entity_reference("copy")
+        expect(ref.entity_reference?).to be true
+      end
+
+      it "survives add_child and retrieval" do
+        doc = ctx.create_document
+        root = doc.create_element("p")
+        doc.root = root
+        ref = doc.create_entity_reference("nbsp")
+        root.add_child(ref)
+        expect(root.children.first).to be_a(Moxml::EntityReference)
+        expect(root.children.first.name).to eq("nbsp")
+      end
+
+      it "validates entity reference name" do
+        doc = ctx.create_document
+        expect {
+          doc.create_entity_reference("123invalid")
+        }.to raise_error(Moxml::ValidationError)
+      end
+    end
+  end
+end
+```
+
+### 2. Builder DSL Tests
+
+**File**: `spec/moxml/builder_spec.rb` (add to existing or create new section)
+
+```ruby
+it "creates entity references via DSL" do
+  doc = Moxml::Builder.new(ctx).build do
+    element("p") { entity_reference("nbsp") }
+  end
+  expect(doc.root.children.first).to be_a(Moxml::EntityReference)
+  expect(doc.to_xml).to include(" ")
+end
+```
+
+### 3. Restore Entities Integration Tests
+
+**File**: `spec/moxml/adapter/entity_restoration_spec.rb` (shared examples)
+
+```ruby
+RSpec.shared_examples "entity restoration" do |adapter_name|
+  context "with #{adapter_name}" do
+    let(:ctx) { Moxml.new(adapter_name, restore_entities: true) }
+
+    it "restores standard XML entities" do
+      doc = ctx.parse("<p>a &amp; b</p>")
+      output = doc.to_xml
+      expect(output).to include("&amp;")
+    end
+
+    it "restores non-standard entities from registry" do
+      # nbsp (U+00A0) is in the bundled W3C entity set
+      doc = ctx.parse("<p>\u00A0</p>")
+      output = doc.to_xml
+      expect(output).to include("&nbsp;")
+    end
+
+    it "preserves entity syntax through round-trip" do
+      doc = ctx.parse("<p>&nbsp;&copy;&mdash;</p>")
+      output = doc.to_xml
+      reparsed = ctx.parse(output)
+      # Text content should be identical after round-trip
+      expect(reparsed.root.text).to eq(doc.root.text)
+    end
+
+    it "does not restore entities when restore_entities is false" do
+      ctx_no_restore = Moxml.new(adapter_name, restore_entities: false)
+      doc = ctx_no_restore.parse("<p>a &amp; b</p>")
+      output = doc.to_xml
+      # Standard entities may still appear as &amp; due to XML escaping,
+      # but no EntityReference nodes should be created
+      expect(doc.root.children).not_to include(a_kind_of(Moxml::EntityReference))
+    end
+  end
+end
+```
+
+### 4. Cross-Adapter Consistency Tests
+
+**File**: `spec/consistency/entity_reference_consistency_spec.rb`
+
+Verify that EntityReference behavior is consistent across all adapters that
+support it:
+- Same entity name produces same serialization
+- Same text content after round-trip
+- Children enumeration includes EntityReference nodes
+
+### 5. EntityRegistry.should_restore? Tests
+
+**File**: Add to `spec/moxml/entity_registry_spec.rb`
+
+```ruby
+describe "#should_restore?" do
+  it "always restores the 5 standard XML entities" do
+    registry = described_class.new
+    config = Moxml::Config.new(:nokogiri)
+    expect(registry.should_restore?(0x26, config: config)).to be true  # amp
+    expect(registry.should_restore?(0x3C, config: config)).to be true  # lt
+  end
+
+  it "restores non-standard entities only when restore_entities is true" do
+    registry = described_class.new
+    config_on = Moxml::Config.new(:nokogiri)
+    config_on.restore_entities = true
+    config_off = Moxml::Config.new(:nokogiri)
+    config_off.restore_entities = false
+
+    expect(registry.should_restore?(0xA0, config: config_on)).to be true   # nbsp
+    expect(registry.should_restore?(0xA0, config: config_off)).to be false
+  end
+end
+```
+
+## Dependencies
+
+- TODO 1 must be partially complete (at least one adapter working) before
+  adapter-level tests can pass
+- TODO 2 must be complete before non-standard entity restoration tests can pass

data/TODO.remaining/4-lenient-entities-mode.md

@@ -0,0 +1,106 @@
+# TODO 4: Lenient Entities Mode
+
+## Problem
+
+XML only defines 5 predefined entities (amp, lt, gt, quot, apos). Any other
+entity must be declared in a DTD. However, real-world XML documents frequently
+use HTML entities (` `, `©`) without DTD declarations — particularly
+office documents (OOXML/ODF) and legacy systems.
+
+Currently Moxml has no way to configure whether undeclared entities should be
+preserved. The `restore_entities` flag is a boolean that enables restoration
+for all known entities from the registry. There is no distinction between
+"only DTD-declared" (strict) and "any recognized" (lenient).
+
+## Design
+
+### Config Option
+
+Add `entity_restoration_mode` to Config with two values:
+
+- `:strict` (default) — Only restore entities that are declared in the DTD
+  internal subset. The 5 standard XML entities are always restored regardless
+  (they are implicitly declared per XML spec). DTD parsing is prerequisite.
+
+- `:lenient` — Restore any character that has a known entity name in the
+  EntityRegistry. This covers the bundled W3C HTML/MathML set (2125 entities)
+  plus any user-registered entities. No DTD required.
+
+This replaces the boolean `restore_entities` which becomes a derived property:
+- `restore_entities = true` + `entity_restoration_mode = :lenient` → restore all known
+- `restore_entities = true` + `entity_restoration_mode = :strict` → restore only declared
+- `restore_entities = false` → don't restore any
+
+### EntityRegistry Enhancement
+
+```ruby
+class EntityRegistry
+  def should_restore?(codepoint, config:)
+    name = primary_name_for_codepoint(codepoint)
+    return false unless name
+
+    # Standard XML entities always restored (XML well-formedness requirement)
+    return true if standard_entity?(codepoint)
+
+    # Must have restoration enabled
+    return false unless config.restore_entities
+
+    case config.entity_restoration_mode
+    when :lenient
+      # Any known entity
+      true
+    when :strict
+      # Only if declared in DTD (future: check DTD declarations)
+      # For now, fall back to lenient behavior until DTD parsing is implemented
+      true
+    else
+      false
+    end
+  end
+
+  def standard_entity?(codepoint)
+    STANDARD_ENTITIES.value?(codepoint)
+  end
+end
+```
+
+### User-Supplied Entities
+
+Users can supply entities through three mechanisms:
+
+1. **EntityRegistry.register** — programmatic registration:
+   ```ruby
+   context = Moxml.new(:nokogiri)
+   context.entity_registry.register({ "myentity" => 0xABCD })
+   ```
+
+2. **entity_provider callback** — for custom/external entity sources:
+   ```ruby
+   Moxml.new(:nokogiri) do |c|
+     c.entity_load_mode = :custom
+     c.entity_provider = -> { { "myentity" => 0xABCD } }
+   end
+   ```
+
+3. **Bundled W3C set** — loaded by default in `:required` mode (2125 entities
+   from HTML/MathML/ISO sets). Controlled by `entity_load_mode` config.
+
+None of these require DTD. They are model-level knowledge in the EntityRegistry.
+
+### DTD-Declared Entities (Future)
+
+Strict mode's full value requires parsing DTD entity declarations from
+`<!DOCTYPE ... [ <!ENTITY name "value"> ]>`. This is a separate feature
+(external to this TODO). Until then, strict mode behaves like lenient mode.
+
+## Files to Modify
+
+- `lib/moxml/config.rb` — add `entity_restoration_mode` attribute
+- `lib/moxml/entity_registry.rb` — add `should_restore?`, `standard_entity?`
+- `lib/moxml/document_builder.rb` — use `should_restore?` from registry (ties into TODO 2)
+
+## Dependencies
+
+- TODO 2 (model-driven restoration) should be done first so the policy is
+  centralized in EntityRegistry
+- TODO 1 (adapter support) should be done first so entities can actually be created