sts 0.6.7 → 0.6.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53e7ba614487ea4d658f8292c403c6811255a85affd65ef9f98976ccc32aa426
-  data.tar.gz: a750e10d49eddc0664746e85114c7db000638b0a3e3addc4b352d179bb21684b
+  metadata.gz: cd02c307a6e1d5f238e8e05db78958bf73d1bc05c98c170ad89005fb205c7e88
+  data.tar.gz: 0bc64d38cf7f5ffd0151db213b9cc99dd25ca979b9eacabf0fb5b7f78b4b19af
 SHA512:
-  metadata.gz: a03cfc08c64cec197ee4a7a88a9ec41f46b3e94a80ea916092444be3419ec8c5aff06af3888094937be86cd7bbd2ed97b1663a688c16ba46650c0c61eed3cd60
-  data.tar.gz: 9ff6274690f18e27d2528497ffa5f4d0b5f3304e2636d276af5503b17318d6c86a090f3eeb583c0e889d26104878d8df9baed1b0d81ea227ed8b8be44e30573c
+  metadata.gz: 421983c008de22adbe0ca5b7e101590d1a025b76582acb6c750d4d7ebad8582abd9bfa12386ed119d11e9ac2e5ccfe6d6f1216f991ce457fc18e98dd5a86ed91
+  data.tar.gz: d0d7b00dbd0c8c53268c561fdb965228e753f90c7cc52c0c9c3fa842ba22d4a105232a2b0b0bec778387e86e1c76e6fd3f95e6bad3f1593e5c566e126f3d8b42

data/TODO.roadmap/00-overview.md

@@ -23,32 +23,37 @@ noted.
 
 | Track | Subject | Items |
 |---|---|---|
-| A | lutaml-model upstream fixes (file BUGREPORTs, propose patches) | 01, 02 |
-| B | Issue #40 namespace coupling completion | 03, 04 |
-| C | Architectural improvements (DRY, versioning, audit) | 05, 06, 07, 08 |
+| A | lutaml-model upstream analysis (filed as robustness suggestions) | 02 |
+| B | Issue #40 namespace coupling completion | 01 (done), 03 (done), 04 |
+| C | Architectural improvements (DRY, versioning, audit) | 05, 07, 08 |
 | D | Quality, specs, and coverage | 09, 10, 11 |
 
 ## Priority order
 
 The priority is "highest leverage per unit of risk" first:
 
-1. **B.03** (child-bearing roots): model `IsoSts::License`, `IsoSts::TermHead`,
-   `IsoSts::CustomMetaGroup` — closes 5 of 11 issue #40 refs in one PR. Low
-   risk, schema-correct, no recursion.
-2. **A.01, A.02** (lutaml-model BUGREPORTs): pure documentation, zero risk.
-   Unblocks C.06 (MathmlNamespace deduplication).
-3. **C.07** (TbxIsoTml misclassification audit): documents a deferred audit
+1. **B.01** (MathmlNamespace deduplication): DONE 2026-07-27. sts-ruby had
+   two Ruby classes for one XML namespace; deleted one, use `Mml::Namespace`
+   directly. Originally misdiagnosed as a lutaml-model bug — see
+   `01-mathml-namespace-deduplication.md` for the lesson.
+2. **B.03** (child-bearing roots): DONE 2026-07-27. Modelled License,
+   TermHead, CustomMetaGroup closures. Closed 5 of 11 issue #40 refs.
+3. **A.02** (lutaml-model ElementBuilder dispatch): filed as
+   `BUGREPORT.element-builder-dispatch-on-value-class.md` in lutaml-model.
+   Pure documentation; zero risk. **Reframed as a robustness suggestion,
+   not a bug** — sts-ruby's responsibility to use correct types was the
+   actual fix (PR #47 deleted duplicate Fn classes).
+4. **C.07** (TbxIsoTml misclassification audit): documents a deferred audit
    (Xref, TableWrap, etc.) — pattern is already proven by Fn/FnGroup and
    Math removals.
-4. **C.05** (Content MathML unification): 148 parallel classes in
+5. **C.05** (Content MathML unification): 148 parallel classes in
    `lib/sts/niso_sts/mml_content/` — same DRY argument as Presentation
    MathML unification (commit 9e977a5).
-5. **B.04** (recursive roots): the heavy lift. Each root pulls a ~78-element
+6. **B.04** (recursive roots): the heavy lift. Each root pulls a ~78-element
    mutually-recursive core. Requires per-element planning. Most architecturally
    significant.
-6. **C.08** (register versioning): lets ISOSTS v1.1, NISO STS 1.0, NISO STS 1.2
+7. **C.08** (register versioning): lets ISOSTS v1.1, NISO STS 1.0, NISO STS 1.2
    coexist without class-name clashes.
-7. **C.06** (MathmlNamespace deduplication): blocked on A.01.
 8. **D.09, D.10, D.11** (quality, coverage, docs): ongoing.
 
 ## Architectural principles (enforced on all new work)

data/TODO.roadmap/01-mathml-namespace-deduplication.md

@@ -0,0 +1,62 @@
+# 01: MathmlNamespace deduplication (DONE)
+
+**Status**: complete (2026-07-27).
+**Originally tracked as**: `01-lutaml-model-namespace-scope-uri-matching.md`
+(misdiagnosed as a lutaml-model bug) and `06-mathml-namespace-deduplication.md`
+(blocked on the misdiagnosed upstream fix). Merged and completed here.
+
+## Original misdiagnosis
+
+When sts-ruby unified Presentation MathML on the mml gem (commit 9e977a5),
+the `mml:` prefix was dropped on serialization unless both
+`Sts::Namespaces::MathmlNamespace` AND `Mml::Namespace` were listed in
+`IsoSts::Standard#namespace_scope` / `NisoSts::Standard#namespace_scope`.
+
+The initial diagnosis (filed as `BUGREPORT.namespace-scope-uri-matching.md`
+in lutaml-model) blamed `namespace_scope` for matching by class identity
+instead of URI. The proposed fix was to change lutaml-model's matching
+semantics.
+
+## Actual root cause
+
+**sts-ruby had two Ruby classes for one XML namespace.** A namespace IS
+its URI (per Namespaces in XML 1.0). `Sts::Namespaces::MathmlNamespace`
+and `Mml::Namespace` both declared:
+
+```ruby
+uri "http://www.w3.org/1998/Math/MathML"
+prefix_default "mml"
+```
+
+They were the same namespace. The duplication was the smell; the
+"workaround" of listing both was actually papering over the duplication.
+
+The BUGREPORT was retracted. The fix is purely sts-ruby's responsibility.
+
+## Fix shipped (2026-07-27)
+
+- Deleted `Sts::Namespaces::MathmlNamespace` from `lib/sts/namespaces.rb`.
+- Replaced `::Sts::Namespaces::MathmlNamespace` with `::Mml::Namespace` in:
+  - `lib/sts/iso_sts/standard.rb`
+  - `lib/sts/niso_sts/standard.rb`
+  - `lib/sts/niso_sts/mml_content.rb` (the Content MathML module — still
+    scheduled for unification per TODO.roadmap/05)
+- Added 4 regression specs asserting `MathmlNamespace` is undefined and
+  `Mml::Namespace` is used directly.
+
+## Verification
+
+- 5153 examples, 0 failures.
+- TBX fixture round-trip preserves `<mml:math>` prefix.
+- NISO STS fixture round-trip preserves `<mml:math>` prefix.
+- `grep -rn "MathmlNamespace" lib/` returns nothing.
+
+## Lesson
+
+When you see a "framework limitation" that requires you to declare
+something twice, the more likely explanation is that you have two
+definitions of the same thing. Namespaces in particular are URI-identified;
+two classes for one URI is a DRY violation, not a framework bug.
+
+Memory updated: `mml-gem-integration-failure` no longer describes the
+`namespace_scope` duplication as a "known smell" — it's resolved.

data/lib/sts/iso_sts/standard.rb

@@ -15,7 +15,7 @@ module Sts
         element "standard"
         ordered
         namespace_scope [
-          ::Sts::Namespaces::MathmlNamespace,
+          ::Mml::Namespace,
           ::Mml::Namespace,
           ::Sts::Namespaces::TbxNamespace,
           ::Lutaml::Xml::W3c::XlinkNamespace,

data/lib/sts/namespaces.rb

@@ -2,11 +2,6 @@
 
 module Sts
   module Namespaces
-    class MathmlNamespace < Lutaml::Xml::Namespace
-      uri "http://www.w3.org/1998/Math/MathML"
-      prefix_default "mml"
-    end
-
     class TbxNamespace < Lutaml::Xml::Namespace
       uri "urn:iso:std:iso:30042:ed-1"
       uri_aliases "urn:iso:std:iso:30042:ed-2"

data/lib/sts/niso_sts/mml_content.rb

@@ -7,7 +7,7 @@ module Sts
       # Content MathML elements share the MathML namespace
       class Object < Lutaml::Model::Serializable
         xml do
-          namespace ::Sts::Namespaces::MathmlNamespace
+          namespace ::Mml::Namespace
         end
       end
 

data/lib/sts/niso_sts/standard.rb

@@ -17,7 +17,7 @@ module Sts
         element "standard"
         ordered
         namespace_scope [
-          ::Sts::Namespaces::MathmlNamespace,
+          ::Mml::Namespace,
           ::Mml::Namespace,
           ::Sts::Namespaces::TbxNamespace,
           ::Lutaml::Xml::W3c::XlinkNamespace,

data/lib/sts/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Sts
-  VERSION = "0.6.7"
+  VERSION = "0.6.8"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sts
 version: !ruby/object:Gem::Version
-  version: 0.6.7
+  version: 0.6.8
 platform: ruby
 authors:
 - Ribose
@@ -107,12 +107,11 @@ files:
 - TODO.finalize/10-audit-other-duplicates.md
 - TODO.finalize/11-strengthen-anti-patterns-spec.md
 - TODO.roadmap/00-overview.md
-- TODO.roadmap/01-lutaml-model-namespace-scope-uri-matching.md
+- TODO.roadmap/01-mathml-namespace-deduplication.md
 - TODO.roadmap/02-lutaml-model-element-builder-dispatch.md
 - TODO.roadmap/03-issue-40-child-bearing-roots.md
 - TODO.roadmap/04-issue-40-recursive-roots.md
 - TODO.roadmap/05-content-mathml-unification.md
-- TODO.roadmap/06-mathml-namespace-deduplication.md
 - TODO.roadmap/07-tbxisotml-misclassification-audit.md
 - TODO.roadmap/08-register-versioning.md
 - TODO.roadmap/09-test-coverage-gaps.md

data/TODO.roadmap/01-lutaml-model-namespace-scope-uri-matching.md

@@ -1,111 +0,0 @@
-# A.01: lutaml-model `namespace_scope` URI-based matching
-
-**Status**: BUGREPORT drafted; sts-ruby fix blocked on upstream.
-**Repo**: `lutaml/lutaml-model`
-**Estimated effort**: small (lutaml-model: ~20 lines + spec; sts-ruby: ~5 lines once landed)
-
-## Problem
-
-`namespace_scope` in `Lutaml::Model::Serializable.xml do … end` currently
-matches namespace classes by **identity** (`==`), not by URI. Two classes
-that declare the same URI/prefix are treated as different namespaces, so a
-parent that lists one cannot satisfy a child that declares the other.
-
-## Real-world symptom in sts-ruby
-
-`Sts::Namespaces::MathmlNamespace` (lib/sts/namespaces.rb) and
-`Mml::Namespace` (the mml gem's top-level namespace class) both encode:
-
-```ruby
-uri "http://www.w3.org/1998/Math/MathML"
-prefix_default "mml"
-```
-
-They are different classes (different `object_id`s). When `Mml::V3::Math` is
-nested inside `Sts::NisoSts::Standard`, the parent's `namespace_scope` lists
-`MathmlNamespace`. The child declares `Mml::Namespace`. Identity comparison
-fails, the `mml:` prefix is dropped on serialization.
-
-The current workaround — listing both classes in `namespace_scope`:
-
-```ruby
-namespace_scope [
-  ::Sts::Namespaces::MathmlNamespace,
-  ::Mml::Namespace,
-  ::Sts::Namespaces::TbxNamespace,
-  ::Lutaml::Xml::W3c::XlinkNamespace,
-]
-```
-
-— is a DRY violation. It documents the lutaml-model limitation rather than
-fixing it. See `lib/sts/iso_sts/standard.rb:18-19` and
-`lib/sts/niso_sts/standard.rb:20-21`.
-
-## Proposed lutaml-model fix
-
-In `Lutaml::Xml::NamespaceScope` (or wherever the membership check lives),
-compare by URI instead of (or in addition to) class identity. The public
-API doesn't change; only the matching semantics do.
-
-```ruby
-# pseudocode
-def includes?(namespace_class)
-  namespaces.any? do |declared|
-    declared.uri == namespace_class.uri
-  end
-end
-```
-
-## Files
-
-- `BUGREPORT.namespace-scope-uri-matching.md` in
-  `~/src/lutaml/lutaml-model/` (this track files it)
-- lutaml-model spec: `spec/lutaml/xml/namespace_scope_spec.rb` — assert that
-  two classes with the same URI are equivalent for `namespace_scope`
-- sts-ruby: remove the duplicated `MathmlNamespace` entry from
-  `IsoSts::Standard` and `NisoSts::Standard` once the upstream fix lands
-
-## Verification
-
-- Reproduction case (currently failing in 0.8.18):
-
-  ```ruby
-  class A < Lutaml::Model::Serializable
-    xml do
-      namespace SomeNs   # uri "urn:test", prefix "t"
-      element "a"
-    end
-  end
-  class B < Lutaml::Model::Serializable
-    xml do
-      namespace OtherNs  # also uri "urn:test", prefix "t" — different class
-      element "b"
-    end
-  end
-  class Parent < Lutaml::Model::Serializable
-    attribute :child, B
-    xml do
-      namespace_scope [SomeNs]
-      map_element "child", to: :child
-    end
-  end
-  # Currently: child's prefix is dropped on serialize.
-  # After fix: child's prefix is preserved (URIs match).
-  ```
-
-## Why not fix in sts-ruby today
-
-Cannot: the duplication is the only way to make `Mml::V3::Math` and
-`Mml::V2::Math` serialize with the `mml:` prefix inside STS Standard
-elements. Removing `MathmlNamespace` without the upstream fix would
-silently drop the prefix on every IsoSts/NisoSts document with MathML
-content.
-
-Track C.06 (MathmlNamespace deduplication) is the sts-ruby cleanup; it
-blocks on this track.
-
-## How to apply
-
-1. File BUGREPORT in `~/src/lutaml/lutaml-model/BUGREPORT.namespace-scope-uri-matching.md`.
-2. Optionally open PR upstream with the fix sketch above.
-3. After upstream lands and sts-ruby bumps its lutaml-model dep, do C.06.

data/TODO.roadmap/06-mathml-namespace-deduplication.md

@@ -1,59 +0,0 @@
-# C.06: MathmlNamespace deduplication
-
-**Status**: blocked on A.01 (lutaml-model namespace_scope URI matching).
-**Estimated effort**: trivial (delete one class, two `namespace_scope`
-entries).
-
-## Problem
-
-`Sts::Namespaces::MathmlNamespace` (lib/sts/namespaces.rb:5-8) and
-`Mml::Namespace` (mml gem's top-level namespace class) both encode:
-
-```ruby
-uri "http://www.w3.org/1998/Math/MathML"
-prefix_default "mml"
-```
-
-Two classes, same URI/prefix. The current `namespace_scope` workaround on
-`IsoSts::Standard` and `NisoSts::Standard` lists both:
-
-```ruby
-namespace_scope [
-  ::Sts::Namespaces::MathmlNamespace,
-  ::Mml::Namespace,
-  ::Sts::Namespaces::TbxNamespace,
-  ::Lutaml::Xml::W3c::XlinkNamespace,
-]
-```
-
-This is the documented smell noted in memory `mml-gem-integration-failure`
-("namespace_scope duplication is a known smell"). It exists because
-lutaml-model's `namespace_scope` matches by class identity, not by URI.
-
-## Plan
-
-Once A.01 lands upstream and sts-ruby has bumped its lutaml-model dep:
-
-1. Delete `Sts::Namespaces::MathmlNamespace` from `lib/sts/namespaces.rb`.
-2. Replace both `namespace_scope` entries with `::Mml::Namespace` only.
-3. Audit any other references to `MathmlNamespace` (likely only
-   `lib/sts/niso_sts/mml_content.rb:10` — but that whole module is
-   being deleted by C.05).
-
-## Verification
-
-- `grep -rn "MathmlNamespace" lib/` returns nothing
-- TBX round-trip fixtures still preserve `<mml:math>` prefix
-- NISO STS fixtures still preserve `<mml:math>` prefix
-- IsoSts fixtures (V2) still preserve `<mml:math>` prefix
-
-## How to apply
-
-- Coordinate with A.01 — file the BUGREPORT first, then either propose the
-  upstream fix or wait for it
-- When the upstream fix is in a released lutaml-model version, bump
-  sts.gemspec and ship this cleanup as a follow-up PR
-
-See also: TODO.sts-refactor/03-namespace-coupling.md "MathML wrapper"
-discussion (now historical — the wrapper itself was deleted in 9e977a5,
-but the namespace duplication remains).