omml 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2cc9754f1577e9e79ba68c5d841c61067b6c8eb88223a695d0a335a84724c177
-  data.tar.gz: 3c4677636e4951c68c99fe9af4ce85f7348a12cbec14f9b68431eccda957523b
+  metadata.gz: bda4c28c48972ee48e21e79fbec32b5dcdfb63ffb2f3aa503fef7de30e3c4ca9
+  data.tar.gz: 8acc0ec6b5465135f64e65e2f9d5ed430efbc5e3fa10f24fd10c4f056f3a3c15
 SHA512:
-  metadata.gz: 98fe061fee5b9906b97db4cf6826c86638d2c7ec8b9a2b16538b9027f404abac6a3f2062db6d02c25a35d70f55c738f219a2387c7c421049bee7c5a899de7b85
-  data.tar.gz: fb05a68e0d0855cfb314a3531857b920ee4b56113a7986f943a2800c25bf99957efefb0a110cda39fc82ffbdbb517c140754a65491fb464d057fb1d29784d3ad
+  metadata.gz: 18b8ce8eab3d4114104bcf90d87faf2edb8be5d42542ee4d347faca30dd8cc78ff258cd911af62cd05b5a1d0c5e177471a9dc040ae8ff165e8fe7d4a11543c79
+  data.tar.gz: 5d5fd0178c24ce73e0b18985604e214e66b84d9b1de01725e50349942065a0a3ff64c7f53a97e36dc6e74659eaeefcf9bd4f9137fed56bc9abdd0863f369f83b

data/CLAUDE.md

@@ -27,24 +27,28 @@ The top-level API is in `lib/omml.rb`. `Parser` in `lib/omml/parser.rb` handles
 
 ### Type context system (`Omml::Configuration`)
 
-`Configuration` manages a Lutaml `GlobalContext` (context ID `:omml`) that holds a registry of all model classes. Models are registered via `Omml::Configuration.register_model(Class)` at load time, and the context is populated lazily on first parse. Custom contexts can be created for downstream libraries (e.g., Plurimath) that fall back to the OMML context.
+`Configuration` manages a Lutaml `GlobalContext` (context ID `:omml`) that holds a registry of all model classes. The context is populated lazily on first parse via `populate_context!`, which eager-loads every model so its `inherited` hook fires and registers it.
 
 Model IDs are derived from class names: prefix `CT`/`EG`/`ST` is stripped and snake-cased with the prefix (e.g., `CTOMath` → `:ct_o_math`).
 
+Consumers (e.g. Uniword) register their own context via `Omml::Configuration.register_in(:consumer_id)`. This populates the consumer's type registry directly with all Omml types so OMML subtrees embedded in foreign-context models resolve without falling back through `:omml`. See `spec/omml/cross_context_spec.rb` for the contract.
+
 ### Model layer (`lib/omml/models/`)
 
-Three categories of models, all extending `Lutaml::Model::Serializable`:
+All model loading is `autoload`-based. `lib/omml/models.rb` declares every class as an `autoload` on the `Omml::Models` module, plus an `eager_load!` helper that `populate_context!` invokes to trigger class definition (and thus registration).
 
-- **Complex types** (`ct_*.rb`) — represent OMML schema complex types. Each defines attributes and XML element mappings, and self-registers via `Omml::Configuration.register_model`.
-- **Simple types** (`simple_types/*.rb`) — enum/value types like `STJc`, `STOnOff`. These wrap string values with validation.
-- **Group models** (`groups/*.rb`) — shared compositional groups (e.g., `EGOMathElements`). These use `import_model_attributes` / `import_model_mappings` to compose attributes from other groups, implementing the OMML schema's choice/sequence patterns.
+Three categories of models:
 
-Root element wrappers (`o_math.rb`, `o_math_para.rb`) extend `CommonCode::RootModel` and use `omml_root_element` to declare themselves as XML root elements with the OMML namespace.
+- **Complex types** (`ct_*.rb`) and root element wrappers (`o_math.rb`, `o_math_para.rb`) — extend `Omml::Models::Base`, which provides:
+  - `lutaml_default_register` returning `Omml::Configuration.context_id` (single source of truth), so consumers referencing Omml classes route serialization and parsing back to `:omml`.
+  - An `inherited` hook that auto-registers each subclass with `Omml::Configuration`. No per-file `register_model` call is needed.
+- **Simple types** (`simple_types/*.rb`) — enum/value types like `STJc`, `STOnOff`. Most extend `EnumString` or `Token`, both of which carry an `inherited` hook for auto-registration. A handful extend Lutaml types directly (`Lutaml::Model::Type::Integer`, `::Decimal`, `::Value`) and are registered explicitly. Three classes (`STAdjCoordinate`, `STHexColor`, `STLang`) include `Omml::Models::Registerable` because they resolve dependent types via a class-level register accessor.
+- **Group models** (`groups/*.rb`) — shared compositional groups (e.g., `EGOMathElements`). These use `import_model_attributes` / `import_model_mappings` to compose attributes from other groups, implementing the OMML schema's choice/sequence patterns. Like complex types, they extend `Base`.
 
 ### Namespaces
 
-- `Omml::Namespace` — the OMML namespace (`http://schemas.openxmlformats.org/officeDocument/2006/math`, prefix `m`)
-- `Omml::WordprocessingNamespace` — the Word ML namespace (prefix `w`), used for elements like `w:rPr` that appear inside OMML
+- `Omml::Namespace` — the OMML namespace (`http://schemas.openxmlformats.org/officeDocument/2006/math`, prefix `m`). This is the canonical OMML namespace class; downstream consumers (Uniword, Plurimath) should reference it directly rather than redefine their own.
+- `Omml::WordprocessingNamespace` — the Word ML namespace (prefix `w`), used for elements like `w:rPr` that appear inside OMML.
 
 ### Type substitutions (`TypeSubstitutions`)
 
@@ -53,12 +57,18 @@ Many OMML simple types are aliases for built-in Lutaml types (e.g., `STString`
 ## Testing
 
 - `spec/omml_spec.rb` — unit tests for parsing, context management, and error handling
-- `spec/fixture_round_trip_spec.rb` — parses 279 OMML fixture files from `spec/fixtures/omml/`, round-trips them through parse → serialize, and compares the XML trees structurally (not string-equality). This is the primary correctness check.
+- `spec/omml_fixture_round_trip_spec.rb` — parses 279 OMML fixture files from `spec/fixtures/omml/`, round-trips them through parse → serialize, and compares the XML trees structurally (not string-equality). This is the primary correctness check.
 - The round-trip spec expects exact XML structural fidelity: same elements, attributes, namespaces, text content, and child ordering.
+- `spec/omml/lutaml_default_register_spec.rb` — asserts every `Serializable` subclass under `Omml::Models` carries `:omml` as its default register (mirrors the Mml gem's coverage spec).
+- `spec/omml/cross_context_spec.rb` — proves embedded OMML parses correctly when a foreign-context parent references Omml types (the Uniword scenario).
+- `spec/omml/opal_boot_spec.rb` — verifies the Opal boot file stays in sync with autoload declarations.
 
 ## Key conventions
 
 - All models are in the `Omml::Models` module namespace
+- New complex types or groups inherit `Omml::Models::Base`; new enum-like simple types inherit `EnumString` or `Token`. No `register_model` call is needed — `inherited` handles it.
+- All internal library loading uses Ruby `autoload`, never `require_relative`
+- No `instance_variable_set` / `instance_variable_get` / `send(:private_method)` / `respond_to?` — use public APIs and structural type checks (`is_a?`, `<`, `include?`)
 - The XML adapter is resolved by lutaml-model's AdapterResolver (lazy auto-detection)
 - Models use `ordered` and `sequence` blocks for XML mapping to preserve element order
 - `render_empty: true` is used on elements that must be emitted even when empty

data/TODO.uniwordfix/00-overview.md

@@ -0,0 +1,29 @@
+# Uniwordfix — Plan & Overview
+
+Goal: make `omml` cleanly consumable by Uniword (and any other OOXML
+consumer). No redefinitions, no imperative mutation, no encapsulation
+violations. Fully model-driven, declarative, autoload-based.
+
+## Sequence
+
+| # | File | Subject |
+|---|---|---|
+| 01 | revert-contributor-changes.md | Drop the two unstaged diffs that broke specs / used runtime hooks |
+| 02 | models-base.md | Introduce `Omml::Models::Base` with declarative `lutaml_default_register` and `inherited` auto-registration |
+| 03 | migrate-models.md | Change every model class to inherit `Base`; remove side-effect `register_model` calls |
+| 04 | autoload-conversion.md | Replace `require_relative` chains with `autoload` declarations; add `eager_load!` for context populate |
+| 05 | encapsulation-cleanup.md | Eliminate `instance_variable_set`, `respond_to?`, `send` from library and specs |
+| 06 | register-in-api.md | Public `Omml::Configuration.register_in(consumer_id)` API for consumers |
+| 07 | spec-coverage.md | `lutaml_default_register` coverage spec (mirrors Mml pattern) |
+| 08 | spec-cross-context.md | Cross-context integration spec (embedded Omml in foreign parent) |
+| 09 | spec-cleanup.md | Replace private-API reaching in existing specs with public API |
+| 10 | claude-md-stale.md | Remove `CommonCode::RootModel` reference; document the new architecture |
+
+## Principles enforced
+
+- Single source of truth for register context (`Omml::Configuration.context_id`)
+- Declarative class-level tagging (no `define_singleton_method`)
+- Auto-registration via `inherited` hook (no per-file `register_model` calls)
+- Autoload everywhere; no `require_relative` for internal library code
+- Public API for cross-cutting concerns; no reaching into internals
+- Real model instances in specs; no doubles; no `send`/`instance_variable_get`

data/TODO.uniwordfix/01-revert-contributor-changes.md

@@ -0,0 +1,25 @@
+# 01 — Revert contributor's two unstaged changes
+
+## What
+
+Two unstaged edits on `feat/opal-boot-and-workflow` need to go:
+
+1. `lib/omml/namespace.rb` — added `element_form_default :qualified`
+2. `lib/omml/configuration/model_registry.rb` — added `define_singleton_method(:lutaml_default_register)` runtime hook
+
+## Why
+
+- The namespace change breaks 86 of 306 round-trip specs. Real-world OMML
+  documents mix prefixed and unqualified locals (`<br/>` inside `<m:r>`).
+  Forcing `:qualified` emits `<m:br/>` and breaks fidelity.
+- The runtime hook is imperative mutation that bypasses lutaml-model's
+  intended inheritance pattern. It hardcodes `:omml` instead of using
+  `context_id`. Replaced declaratively in step 02.
+
+## How
+
+`git checkout -- lib/omml/namespace.rb lib/omml/configuration/model_registry.rb`
+
+## Verification
+
+`bundle exec rspec` returns to 306 examples, 0 failures.

data/TODO.uniwordfix/02-models-base.md

@@ -0,0 +1,55 @@
+# 02 — Introduce `Omml::Models::Base`
+
+## What
+
+New file `lib/omml/models/base.rb`:
+
+```ruby
+module Omml
+  module Models
+    class Base < Lutaml::Model::Serializable
+      def self.inherited(subclass)
+        super
+        Omml::Configuration.register_model(subclass)
+      end
+
+      def self.lutaml_default_register
+        Omml::Configuration.context_id
+      end
+    end
+  end
+end
+```
+
+`EnumString` also gains an `inherited` hook so `ST*` types auto-register:
+
+```ruby
+class EnumString < Lutaml::Model::Type::String
+  def self.inherited(subclass)
+    super
+    Omml::Configuration.register_model(subclass)
+  end
+  # ...
+end
+```
+
+## Why
+
+- Declarative: each model class self-documents via inheritance
+- Single source of truth: `context_id` referenced, not hardcoded `:omml`
+- OCP: adding a new model = adding a file, no other code changes
+- DRY: no per-file `register_model` boilerplate
+- Matches Mml's proven pattern (with one improvement: auto-registration
+  via `inherited` removes Mml's centralized registration block)
+
+## Note on `lutaml_default_register` for `EnumString`
+
+Upstream's `Register.resolve_for_child` only consults `lutaml_default_register`
+for `Serializable` subclasses (register.rb:98-100). `EnumString` extends
+`Type::String`, so the method is never called on it. No need to declare it.
+
+## Verification
+
+- `Omml::Models::CTAcc.lutaml_default_register == :omml`
+- `Omml::Models::STJc` auto-registers without explicit `register_model` call
+- `Omml::Models::CTBookmark < CTBookmarkRange` — auto-registers through chain

data/TODO.uniwordfix/03-migrate-models.md

@@ -0,0 +1,38 @@
+# 03 — Migrate every model to inherit `Base`
+
+## What
+
+For every model file under `lib/omml/models/`:
+
+1. Change `< Lutaml::Model::Serializable` to `< Base` (or `< Omml::Models::Base`)
+2. Delete the trailing `Omml::Configuration.register_model(...)` call
+3. Delete the `id:` parameter where present (derivation handles it)
+
+For `EnumString` descendants (`ST*`):
+1. Inheritance unchanged (`< EnumString`)
+2. Delete the trailing `Omml::Configuration.register_model(...)` call
+
+For root wrappers `OMath` and `OMathPara`:
+1. Change to `< Base`
+2. Delete `Omml::Configuration.register_model(OMath, id: :o_math)` — derivation produces `:o_math` from "OMath" via snake_case, so explicit ID is redundant. Same for `OMathPara`.
+
+## Why
+
+- Removes ~250 lines of boilerplate registration calls
+- Single registration path via `Base.inherited` / `EnumString.inherited`
+- Adding a new model = adding a file with `class CTNew < Base` — done
+
+## How
+
+Script-based mechanical edit across 249 files. Manual inspection of:
+- Files with inheritance from another model (`CTBookmarkRange < CTMarkupRange`)
+  — these propagate `inherited` through the chain automatically
+- Files with `EnumString` parent (ST* types)
+- Root wrappers `OMath`, `OMathPara`
+
+## Verification
+
+After migration:
+- `Omml::Configuration.registered_models.keys.size` == 249 (same as before)
+- Full spec suite passes (306 examples)
+- Round-trip corpus unaffected

data/TODO.uniwordfix/04-autoload-conversion.md

@@ -0,0 +1,52 @@
+# 04 — Convert `require_relative` chains to `autoload`
+
+## What
+
+Three files use `require_relative` for internal library code:
+
+- `lib/omml/models.rb` (176 declarations)
+- `lib/omml/models/simple_types.rb` (57 declarations)
+- `lib/omml/models/groups.rb` (16 declarations)
+
+Convert each to `autoload` declarations in the parent namespace's file.
+
+Pattern:
+
+```ruby
+# lib/omml/models.rb
+module Omml
+  module Models
+    autoload :Base, "omml/models/base"
+    autoload :EnumString, "omml/models/simple_types/enum_string"
+    autoload :CTAcc, "omml/models/ct_acc"
+    # ...
+
+    def self.eager_load!
+      constants.each { |name| const_get(name) }
+    end
+  end
+end
+```
+
+`populate_context!` calls `Omml::Models.eager_load!` to trigger every
+file load → class definition → auto-registration via `inherited`.
+
+## Why
+
+- Per global rule: "NEVER use `require_relative` for internal library code"
+- Lazy loading: programmatic consumers can use individual models without
+  pulling in the entire 250-file tree
+- Cleaner load path
+- Removes Opal boot file's special-casing of `models.rb`
+
+## Sub-module structure
+
+- `lib/omml/models/simple_types.rb` becomes the parent for `ST*` autoloads
+- `lib/omml/models/groups.rb` becomes the parent for `EG*` autoloads
+- Each is itself autoloaded from `lib/omml/models.rb`
+
+## Verification
+
+- `bundle exec rspec` — all 306 examples pass
+- `bundle exec ruby -e "require 'omml'; Omml::Models::CTAcc"` — lazy loads single file
+- `Omml::Configuration.populate_context!` triggers full registration

data/TODO.uniwordfix/05-encapsulation-cleanup.md

@@ -0,0 +1,67 @@
+# 05 — Encapsulation cleanup
+
+## What
+
+Remove forbidden patterns from library and spec code:
+
+### `lib/omml/configuration/model_registry.rb`
+
+Current:
+```ruby
+def clear_cache(klass, register_id)
+  klass.instance_variable_set(:@register, register_id)
+  klass.clear_cache(register_id) if klass.respond_to?(:clear_cache)
+end
+```
+
+Problem: `instance_variable_set` bypasses upstream's `set_register_context`
+public method. `respond_to?` is duck typing.
+
+Replace with: use upstream's public API. `Lutaml::Model::Serializable` has
+`set_register_context(register_id)` which sets `@register` with a guard
+against double-assignment. Call it directly. Remove the `respond_to?` check
+since `clear_cache` is always defined on `Serializable` subclasses.
+
+### `lib/omml/configuration/type_resolver.rb`
+
+Current:
+```ruby
+def root_namespace_uri(root)
+  return unless root.respond_to?(:namespace)
+  root.namespace&.uri
+end
+```
+
+Problem: `respond_to?` for duck typing on a parsed XML document.
+
+Replace with: check the document adapter's actual type. The parsed document
+root is either an `Ox::Element`, `Nokogiri::XML::Element`, or
+`Moxml::Element` depending on adapter. Rather than branching on adapter,
+trust the upstream contract: the root returned by `xml_adapter.parse` always
+responds to `namespace`. If it doesn't, that's an upstream bug — let it
+NoMethodError naturally.
+
+If a nil-check is genuinely needed for the test scenario at
+`spec/omml_spec.rb:122` (Struct-based fake), restructure the test to use a
+real adapter output instead.
+
+### `spec/omml_spec.rb`
+
+Current lines 301-320 use:
+- `Omml::Configuration.send(:register_models_in, custom_context)` — private send
+- `Omml::Models::OMath.instance_variable_get(:@register)` — IVAR get
+
+Replace with: exercise the public API. Either expose a public accessor for
+the register a class is bound to, or assert via behavior (parse and verify
+the round-trip works in the custom context).
+
+## Why
+
+- Global rule: "NEVER use `send` to call private methods"
+- Global rule: "NEVER use `instance_variable_set` or `instance_variable_get`"
+- Global rule: "NEVER use `respond_to?` for type checking"
+
+## Verification
+
+- `grep -rn "instance_variable_set\|instance_variable_get\|\.send(:\|respond_to?" lib/` returns empty (excluding legitimately-needed external API calls)
+- All specs pass

data/TODO.uniwordfix/06-register-in-api.md

@@ -0,0 +1,44 @@
+# 06 — `Omml::Configuration.register_in` public API
+
+## What
+
+Add to `lib/omml/configuration/context_registry.rb`:
+
+```ruby
+def register_in(consumer_id, fallback_to: nil)
+  populate_context!
+  Lutaml::Model::GlobalContext.create_context(
+    id: consumer_id.to_sym,
+    registry: Lutaml::Model::TypeRegistry.new,
+    fallback_to: Array(fallback_to || [:default, context_id]),
+  )
+end
+```
+
+## Why
+
+Consumers (Uniword) currently need to know:
+- That `populate_context!` must run first
+- The `Lutaml::Model::GlobalContext.create_context` API
+- The right fallback chain (`[:default, :omml]`)
+
+That's too much internal knowledge. `register_in(:uniword)` does it all.
+
+The fallback chain `[:default, context_id]` lets consumer types resolve via
+`:default` first (so consumer-defined types take precedence), then Omml
+types via `:omml`. Order is overridable for advanced consumers.
+
+## Usage
+
+```ruby
+# In Uniword boot
+Omml::Configuration.register_in(:uniword)
+
+# Then parse
+DocumentRoot.from_xml(xml, register: :uniword)
+```
+
+## Verification
+
+- New spec: register a `:test_consumer` context, parse embedded OMML,
+  assert resolution works end-to-end

data/TODO.uniwordfix/07-spec-coverage.md

@@ -0,0 +1,43 @@
+# 07 — `lutaml_default_register` coverage spec
+
+## What
+
+`spec/omml/lutaml_default_register_spec.rb` — mirrors Mml's coverage spec.
+
+```ruby
+RSpec.describe "Omml::Models lutaml_default_register coverage" do
+  before { Omml::Configuration.populate_context! }
+
+  it "every Serializable subclass returns :omml" do
+    classes = Omml::Models.constants
+      .map { |c| Omml::Models.const_get(c) }
+      .select { |c| c.is_a?(Class) && c < Lutaml::Model::Serializable }
+
+    expect(classes).not_to be_empty
+
+    wrong = classes.reject { |c| c.lutaml_default_register == :omml }
+    expect(wrong).to be_empty,
+                     "Classes with wrong default register: " \
+                     "#{wrong.map { |c| "#{c.name}=#{c.lutaml_default_register}" }.join(', ')}"
+  end
+
+  it "includes inherited subclasses (CTBookmark via CTBookmarkRange)" do
+    expect(Omml::Models::CTBookmark.lutaml_default_register).to eq(:omml)
+    expect(Omml::Models::CTBookmarkRange.lutaml_default_register).to eq(:omml)
+  end
+
+  it "includes simple types via EnumString" do
+    expect(Omml::Models::STJc.lutaml_default_register).to eq(:omml)
+  end
+end
+```
+
+## Why
+
+- Catches any future model class that forgets to inherit `Base`
+- Documents the contract: every Omml model carries `:omml`
+- Mirrors Mml's proven pattern
+
+## Verification
+
+All three examples pass.

data/TODO.uniwordfix/08-spec-cross-context.md

@@ -0,0 +1,63 @@
+# 08 — Cross-context integration spec
+
+## What
+
+`spec/omml/cross_context_spec.rb` — proves embedded Omml-in-foreign-parent
+works end-to-end via `register_in`.
+
+```ruby
+RSpec.describe "cross-context embedding (Uniword scenario)" do
+  before do
+    Omml::Configuration.register_in(:test_consumer)
+  end
+
+  after do
+    Omml::Configuration.reset_context!(id: :test_consumer)
+  end
+
+  let(:consumer_class) do
+    Class.new(Lutaml::Model::Serializable) do
+      attribute :o_math, "Omml::Models::CTOMath", collection: true
+
+      xml do
+        element "container"
+        map_element "oMath", to: :o_math
+      end
+    end
+  end
+
+  let(:xml) do
+    <<~XML
+      <container xmlns:m="http://schemas.openxmlformats.org/officeDocument/2006/math">
+        <m:oMath>
+          <m:r><m:t>x</m:t></m:r>
+        </m:oMath>
+      </container>
+    XML
+  end
+
+  it "parses Omml embedded in a foreign-context parent" do
+    parsed = consumer_class.from_xml(xml, register: :test_consumer)
+    expect(parsed.o_math.first.r.first.t.first.content).to eq("x")
+  end
+
+  it "round-trips through the consumer context" do
+    parsed = consumer_class.from_xml(xml, register: :test_consumer)
+    serialized = parsed.to_xml(register: :test_consumer)
+    expect(serialized).to include("<m:t>x</m:t>")
+  end
+end
+```
+
+## Why
+
+- This is THE spec that proves the cross-context contract works
+- Without it, the contributor's earlier claim was unverified
+- Reproduces the actual Uniword scenario (Paragraph referencing Omml types)
+
+## Known limitation
+
+If `lutaml-model` 0.8.0 (currently pinned via Gemfile github override) doesn't
+fully consult `lutaml_default_register` during parsing, this spec may fail
+with "Attribute 'acc' not found". That's an upstream bug; pin to 0.8.17 or
+file an issue upstream. Document the expected behavior in the spec comment.

data/TODO.uniwordfix/09-spec-cleanup.md

@@ -0,0 +1,37 @@
+# 09 — Spec cleanup
+
+## What
+
+`spec/omml_spec.rb` line 301-320 — "registers schema models against the
+context being populated" — uses:
+
+```ruby
+Omml::Configuration.send(:register_models_in, custom_context)
+Omml::Models::OMath.instance_variable_get(:@register)
+```
+
+Both violate global rules (private send, IVAR get).
+
+## Fix
+
+Restructure the spec to exercise public API:
+
+1. Drop the private `register_models_in` call — instead use the public
+   `register_in(custom_context_id)` API (new from TODO 06). It performs the
+   same registration via the public path.
+2. Drop the `instance_variable_get(:@register)` — instead assert via
+   behavior: parse a document in the custom context and verify the OMML
+   types resolve.
+
+Alternatively, expose a public reader if behavior-based testing is
+insufficient. Prefer behavior-based.
+
+## Why
+
+- Private methods are private for a reason
+- IVAR access breaks encapsulation
+- Tests should verify behavior, not implementation
+
+## Verification
+
+Updated spec passes without using `send` or `instance_variable_get`.

data/TODO.uniwordfix/10-claude-md-stale.md

@@ -0,0 +1,34 @@
+# 10 — Update stale CLAUDE.md
+
+## What
+
+`CLAUDE.md` currently references:
+
+> Root element wrappers (`o_math.rb`, `o_math_para.rb`) extend
+> `CommonCode::RootModel` and use `omml_root_element` to declare themselves
+> as XML root elements with the OMML namespace.
+
+No `CommonCode::RootModel` module or `omml_root_element` method exists in
+the codebase. The wrappers extend `Lutaml::Model::Serializable` directly
+(will become `Omml::Models::Base` after TODO 02).
+
+## Fix
+
+Update the CLAUDE.md "Model layer" section to reflect:
+
+- All Omml model classes (CT*, ST*, EG*, root wrappers) inherit from
+  `Omml::Models::Base`
+- `Base` declares `lutaml_default_register :omml` declaratively
+- `Base.inherited` auto-registers each subclass with `Omml::Configuration`
+- No per-file `register_model` call is needed
+
+Also document:
+
+- The `Omml::Configuration.register_in(consumer_id)` public API
+- The autoload-based loading in `lib/omml/models.rb`
+- The cross-context contract (proven by `spec/omml/cross_context_spec.rb`)
+
+## Why
+
+Stale docs mislead future contributors. CLAUDE.md is the entry point for
+AI-assisted work on this repo — accuracy matters.

data/lib/omml/configuration/context_registry.rb

@@ -23,8 +23,9 @@ module Omml
       end
 
       def populate_context!
-        # Trigger the model manifest autoload before replaying registrations.
-        Omml.const_get(:Models)
+        # Eager-load every model so its `inherited` hook fires and the class
+        # is registered before we replay registrations into the new context.
+        Omml::Models.eager_load!
         reset_context!
         register_models_in(populate_base_context)
       end
@@ -37,6 +38,39 @@ module Omml
         raise Omml::Errors::MissingContextError, normalized_id
       end
 
+      # Register Omml's models into a consumer-owned context.
+      #
+      # Consumers (e.g. Uniword) call this once during boot to make every
+      # OMML schema type resolvable from the consumer's own context. The
+      # consumer's registry is populated directly (via register_models_in)
+      # rather than via fallback, so the Omml register does not need to be
+      # in the chain — the consumer becomes self-sufficient for OMML types.
+      #
+      # The default fallback is `[:default]` so consumer-defined types
+      # still resolve through lutaml-model's built-in type set when not
+      # shadowed by an Omml registration.
+      #
+      # @example Uniword boot
+      #   Omml::Configuration.register_in(:uniword)
+      #   Uniword::DocumentRoot.from_xml(xml, register: :uniword)
+      #
+      # @param consumer_id [Symbol, String] The consumer's context id.
+      # @param fallback_to [Array<Symbol>, nil] Override fallback chain.
+      #   Defaults to `[:default]`.
+      # @return [Lutaml::Model::Context] The created context.
+      def register_in(consumer_id, fallback_to: nil)
+        normalized_id = normalize_context_id(consumer_id)
+        chain = Array(fallback_to || [:default])
+        populate_context!
+        create_context(
+          id: normalized_id,
+          registry: Lutaml::Model::TypeRegistry.new,
+          fallback_to: chain,
+        ).tap do |type_context|
+          register_models_in(type_context)
+        end
+      end
+
       def reset_context!(id: context_id)
         normalized_id = normalize_context_id(id)
         existing_context = Lutaml::Model::GlobalContext.context(normalized_id)

data/lib/omml/configuration/model_registry.rb

@@ -52,8 +52,12 @@ module Omml
       end
 
       def clear_cache(klass, register_id)
-        klass.instance_variable_set(:@register, register_id)
-        klass.clear_cache(register_id) if klass.respond_to?(:clear_cache)
+        if klass.is_a?(Class) && klass < Lutaml::Model::Serializable
+          klass.set_register_context(register_id)
+          klass.clear_cache(register_id)
+        elsif klass.include?(Omml::Models::Registerable)
+          klass.register = register_id
+        end
       end
     end
   end

data/lib/omml/configuration/type_resolver.rb

@@ -32,8 +32,6 @@ module Omml
       end
 
       def root_namespace_uri(root)
-        return unless root.respond_to?(:namespace)
-
         root.namespace&.uri
       end
 

data/lib/omml/configuration.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
-require_relative "configuration/adapter"
-require_relative "configuration/context_registry"
-require_relative "configuration/model_registry"
-require_relative "configuration/type_resolver"
-
 module Omml
   module Configuration
+    autoload :Adapter, "omml/configuration/adapter"
+    autoload :ContextRegistry, "omml/configuration/context_registry"
+    autoload :ModelRegistry, "omml/configuration/model_registry"
+    autoload :TypeResolver, "omml/configuration/type_resolver"
+
     extend Adapter
     extend ContextRegistry
     extend ModelRegistry