sts 0.6.1 → 0.6.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36f88ede902806ba5a3471e0032a6d9d9543157ab150af32e4b139cc75b77b14
-  data.tar.gz: 93840c45252bb723bc58bb6e78c204075ea94d00a87bb0625a98b16ccfc29bda
+  metadata.gz: 27e3b4850a13bbff3b16e63ad2293589079e4c29b4f25d2fa120a797b9f6ff7c
+  data.tar.gz: 572e19d6b4e428dca7a277d836f73b6121627d094fd1d0e492ef0ba4b82b905c
 SHA512:
-  metadata.gz: 3aad32ee67d2f5ef93f8b4de1b8c7ace1ae073d8cbf6e903f1c9ef0836b9b6ddc7fa5b24cc2157c9bfb431f5860a50944a8f5df3d46ebf1a7444efc0537b37c6
-  data.tar.gz: 7d1aaa5f6c206801500a46b008d72ae194c8c9e0efd148d0e6efc85f72d024d699483510c238fc1342c536957619da4ad7e59e8eb2d0f2f2d9620b133e15c08c
+  metadata.gz: ab688a012341d43a0daa2a2b79d7e68b7e2b10a9e4ee4f30824d357e1c3329721ccfe6fe071e331265ca79de26dc6d9deb54ad269519bc1a6e164f38d76bbd41
+  data.tar.gz: 1cd96829661efa371b501e25dac9f56e5aeb9b6ba3cac72c5de47e1b6d6377c2193eaf29842c36ae68a70321796ceb06079671df81ed848d2805c66256aed3e4

data/.rubocop_todo.yml

@@ -70,6 +70,8 @@ RSpec/DescribeClass:
     - 'spec/elements/new_elements_spec.rb'
     - 'spec/elements/reference_models_spec.rb'
     - 'spec/elements/structural_models_spec.rb'
+    - 'spec/fn_namespace_spec.rb'
+    - 'spec/mathml_version_spec.rb'
     - 'spec/round_trip/reference_docs_spec.rb'
 
 # Offense count: 1

data/TODO.finalize/00-overview.md

@@ -0,0 +1,56 @@
+# sts-ruby + lutaml-model Finalization Plan
+
+**Date**: 2026-07-25
+**Trigger**: User-reported `NoMethodError: paragraph` on `Sts::TbxIsoTml::Fn` nested inside `Sts::NisoSts::Back` (rice.xml e2e).
+**Status**: PR #1 (sts-ruby dedup) in flight; PR #2 (lutaml-model) deferred per downstream maintainer feedback.
+
+## Root Cause Summary
+
+Two layered bugs:
+
+1. **sts-ruby**: `Sts::TbxIsoTml::Fn` (Ruby attr `:p`) and `Sts::NisoSts::Fn` (Ruby attr `:paragraph`) are duplicate `<fn>` classes with conflicting Ruby attribute names. `TbxIsoTml::FnGroup` similarly duplicates `NisoSts::FnGroup`. Six `Fn`/`FnGroup` classes exist across three namespaces; only four are schema-correct.
+2. **lutaml-model**: `Lutaml::Xml::TransformationSupport::ElementBuilder#create_nested_model_element` uses the rule's cached `child_transformation` (keyed on declared `attribute_type`) regardless of the value's actual class. When a caller assigns an unrelated `Serializable` to a typed slot, the wrong transformation is applied silently, producing confusing `NoMethodError`s.
+
+The cache itself is correct (`transformation_key` includes `object_id`). The bug is in the dispatch logic.
+
+## Architecture Decision (PR #1)
+
+`<fn>` and `<fn-group>` are JATS / NISO STS elements (per ISOSTS.xsd and NISO-STS-extended-1.xsd). They are **not** TBX-ISO-TML elements (TBX-ISO-TML is ISO 30042, a terminology model). The presence of `TbxIsoTml::Fn` and `TbxIsoTml::FnGroup` is a misclassification — same pattern as the prior `TbxIsoTml::Math` removal in commit `9e977a5`. Remove them.
+
+Per [[architecture-namespace-independence]]:
+- `IsoSts::*` references use `IsoSts::Fn` / `IsoSts::FnGroup` (independence from NisoSts).
+- `NisoSts::*` references continue to use `NisoSts::Fn` / `NisoSts::FnGroup`.
+- `TbxIsoTml::*` references follow the existing `TbxIsoTml::Bold` / `TbxIsoTml::Italic` precedent (both already use `NisoSts::Fn`): use `NisoSts::Fn` / `NisoSts::FnGroup`. TBX is a shared namespace.
+
+## Decision: Defer PR #2 (lutaml-model)
+
+Downstream metanorma-iso maintainer reviewed the plan and recommended defer:
+> #2 is a real robustness win but introduces a new contract that may break
+> other downstream consumers who've been quietly relying on the current
+> lenient behavior. Worth doing eventually, but urgency drops once #1 lands.
+
+Once #1 lands, the trap cannot be triggered via the original repo's classes. The lenient dispatch remains a robustness gap for future duplicates — see TODO 10 (audit other potential duplicates).
+
+## Execution Order
+
+| # | File | Status |
+|---|---|---|
+| 01 | investigation findings | complete |
+| 02 | delete `TbxIsoTml::Fn` / `TbxIsoTml::FnGroup` | complete |
+| 03 | repoint IsoSts call sites to `IsoSts::Fn` | complete |
+| 04 | repoint TbxIsoTml call sites to `NisoSts::Fn` | complete |
+| 05 | sts-ruby regression specs | complete |
+| 06 | lutaml-model `ElementBuilder` dispatch fix | **deferred** |
+| 07 | lutaml-model specs | **deferred** |
+| 08 | sts-ruby PR | in flight |
+| 09 | lutaml-model PR | **deferred** |
+| 10 | audit other potential duplicates | deferred (future) |
+| 11 | strengthen `anti_patterns_spec.rb` | deferred (future) |
+
+## Principles enforced (PR #1)
+
+- **MECE**: each Fn class lives in exactly one namespace; no parallel hierarchies.
+- **Model-driven**: every `<fn>` reference is a typed `attribute :fn, ::Sts::<Namespace>::Fn`.
+- **OCP**: adding a new host namespace = adding new Fn classes there, not editing existing ones.
+- **DRY**: one class per (namespace, XML element) pair.
+- **No anti-patterns**: no `send`, no `instance_variable_set/get`, no `respond_to?`, no `require_relative` in lib.

data/TODO.finalize/01-investigation-findings.md

@@ -0,0 +1,39 @@
+# 01: Investigation Findings — Fn/FnGroup Duplication
+
+**Status**: complete (findings documented for reference)
+
+## Six classes discovered
+
+| Class | File | Ruby attr for `<p>` | Other notable attrs |
+|---|---|---|---|
+| `Sts::IsoSts::Fn` | `lib/sts/iso_sts/fn.rb` | `:paragraph` | fn_type, specific_use, symbol, xml_lang, non_normative_note, non_normative_example |
+| `Sts::IsoSts::FnGroup` | `lib/sts/iso_sts/fn_group.rb` | — | content_type, specific_use, xml_lang, originator, label, title |
+| `Sts::NisoSts::Fn` | `lib/sts/niso_sts/fn.rb` | `:paragraph` | (minimal) |
+| `Sts::NisoSts::FnGroup` | `lib/sts/niso_sts/fn_group.rb` | — | (minimal) |
+| `Sts::TbxIsoTml::Fn` | `lib/sts/tbx_iso_tml/fn.rb` | `:p` ← **outlier** | (minimal) |
+| `Sts::TbxIsoTml::FnGroup` | `lib/sts/tbx_iso_tml/fn_group.rb` | — | (minimal) |
+
+## Call sites (24 total)
+
+### IsoSts (8 sites — all wrong, should be IsoSts::Fn)
+- `lib/sts/iso_sts/{td,bold,paragraph,mixed_citation,sec,th,std,italic}.rb`
+
+### IsoSts (correct — already uses IsoSts::Fn/IsoSts::FnGroup)
+- `lib/sts/iso_sts/{fig,table_wrap_foot,fn_group,app,back,term_sec}.rb`
+
+### TbxIsoTml (4 sites — should be NisoSts::Fn following Bold/Italic pattern)
+- `lib/sts/tbx_iso_tml/{td,th,table_wrap_foot,fn_group}.rb`
+
+### TbxIsoTml (correct — already uses NisoSts::Fn)
+- `lib/sts/tbx_iso_tml/{bold,italic}.rb`
+
+### NisoSts (correct — uses NisoSts::Fn/NisoSts::FnGroup)
+- `lib/sts/niso_sts/{author_notes,source,data_title,named_content,mixed_citation,paragraph,section,back,display_formula,role,reference_standard,contrib,styled_content,toc,boxed_text,fn_group}.rb`
+
+## Verification of root cause
+
+Patch on `Lutaml::Xml::Transformation#apply_standard_rules` showed: when `Sts::TbxIsoTml::Fn` is serialized inside a `Sts::NisoSts::Back` (whose `:fn_group` is typed `NisoSts::FnGroup`), the transformation applied has `model_class = Sts::NisoSts::Fn` (not `TbxIsoTml::Fn`). Its compiled rules include `attribute_name=:paragraph`, which is then `public_send`-ed on the TbxIsoTml::Fn value, raising `NoMethodError`.
+
+The reverse also fails: `NisoSts::Fn` inside `TbxIsoTml::FnGroup` raises `private method 'p' called`.
+
+The cache key in `TransformationRegistry#transformation_key` includes `object_id`, so cache collision is NOT the cause. The bug is in `ElementBuilder#create_nested_model_element` — it reuses `rule.child_transformation` (cached at compile time for the declared `attribute_type`) without consulting `value.class`.

data/TODO.finalize/02-delete-tbxisotml-fn-fngroup.md

@@ -0,0 +1,20 @@
+# 02: Delete `Sts::TbxIsoTml::Fn` and `Sts::TbxIsoTml::FnGroup`
+
+**Status**: pending
+**Blocks**: 03, 04, 05
+
+## Why
+
+`<fn>` and `<fn-group>` are JATS / NISO STS elements. They are not defined by TBX-ISO-TML (ISO 30042). The `TbxIsoTml::Fn` and `TbxIsoTml::FnGroup` classes are misclassified duplicates of `NisoSts::Fn` / `NisoSts::FnGroup` with one schema-breaking difference: the Ruby attribute for `<p>` is `:p` in TbxIsoTml and `:paragraph` in every other namespace. This mismatch is the root cause of the user-reported `NoMethodError`.
+
+## Actions
+
+- [x] Delete `lib/sts/tbx_iso_tml/fn.rb`
+- [x] Delete `lib/sts/tbx_iso_tml/fn_group.rb`
+- [x] Remove `autoload :Fn` and `autoload :FnGroup` from `lib/sts/tbx_iso_tml.rb`
+- [x] Run `bundle exec rspec` — confirm no spec references the deleted constants
+
+## Verification
+
+- `grep -rn "TbxIsoTml::Fn\b\|TbxIsoTml::FnGroup\b" lib/ spec/` returns nothing after steps 03 and 04 complete.
+- `Sts::TbxIsoTml.const_defined?(:Fn)` is `false`.

data/TODO.finalize/03-repoint-isosts-call-sites.md

@@ -0,0 +1,27 @@
+# 03: Repoint IsoSts call sites to `IsoSts::Fn`
+
+**Status**: pending
+**Blocked by**: 02
+
+## Why
+
+Per [[architecture-namespace-independence]], `IsoSts` must be independent of `NisoSts`. The 8 IsoSts files that currently reference `TbxIsoTml::Fn` violate this. They should reference `IsoSts::Fn`, which already exists with the correct ISOSTS schema (5 attributes + label + paragraph + non_normative_note + non_normative_example).
+
+## Actions
+
+For each file, swap `::Sts::TbxIsoTml::Fn` → `::Sts::IsoSts::Fn`:
+
+- [x] `lib/sts/iso_sts/td.rb:28`
+- [x] `lib/sts/iso_sts/bold.rb:25`
+- [x] `lib/sts/iso_sts/paragraph.rb:27`
+- [x] `lib/sts/iso_sts/mixed_citation.rb:22`
+- [x] `lib/sts/iso_sts/sec.rb:37`
+- [x] `lib/sts/iso_sts/th.rb:28`
+- [x] `lib/sts/iso_sts/std.rb:14`
+- [x] `lib/sts/iso_sts/italic.rb:25`
+
+## Verification
+
+- `grep -rn "TbxIsoTml::Fn\b" lib/sts/iso_sts/` returns nothing.
+- `bundle exec rspec spec/iso_sts/` is green.
+- Full suite green (no spec depends on the old typing).

data/TODO.finalize/04-repoint-tbxisotml-call-sites.md

@@ -0,0 +1,24 @@
+# 04: Repoint TbxIsoTml call sites to `NisoSts::Fn`
+
+**Status**: pending
+**Blocked by**: 02
+
+## Why
+
+After step 02 deletes `TbxIsoTml::Fn` / `TbxIsoTml::FnGroup`, the 4 TbxIsoTml files that referenced them must point somewhere. Following the established `TbxIsoTml::Bold` / `TbxIsoTml::Italic` precedent (both already use `NisoSts::Fn`), use `NisoSts::Fn` / `NisoSts::FnGroup`.
+
+TBX-ISO-TML is a shared namespace (per [[architecture-namespace-independence]]: "independence from NisoSts is not independence in general"). `<fn>` inside a TBX table cell is a NISO STS element borrowed into TBX context, so the NISO STS type is the correct reference.
+
+## Actions
+
+- [x] `lib/sts/tbx_iso_tml/td.rb:94` — `::Sts::TbxIsoTml::Fn` → `::Sts::NisoSts::Fn`
+- [x] `lib/sts/tbx_iso_tml/th.rb:95` — same
+- [x] `lib/sts/tbx_iso_tml/table_wrap_foot.rb:7` — `::Sts::TbxIsoTml::FnGroup` → `::Sts::NisoSts::FnGroup`
+- [x] `lib/sts/tbx_iso_tml/table_wrap_foot.rb:13` — `::Sts::TbxIsoTml::Fn` → `::Sts::NisoSts::Fn`
+
+`lib/sts/tbx_iso_tml/fn_group.rb` is deleted in step 02 — no repoint needed.
+
+## Verification
+
+- `grep -rn "TbxIsoTml::Fn\b\|TbxIsoTml::FnGroup\b" lib/sts/tbx_iso_tml/` returns nothing.
+- `bundle exec rspec` green.

data/TODO.finalize/05-sts-regression-specs.md

@@ -0,0 +1,27 @@
+# 05: Add sts-ruby regression specs
+
+**Status**: pending
+**Blocked by**: 02, 03, 04
+
+## Why
+
+Round-tripping alone cannot catch this class of bug — the wrong-type assignment only fails when nested two levels deep, and a future contributor could re-introduce `TbxIsoTml::Fn` thinking it is a reasonable place for a TBX footnote. Specs must assert:
+
+1. The deleted constants stay deleted.
+2. Each call site uses the correct namespace's Fn.
+3. The original bug repro (NisoSts::Back wrapping TbxIsoTml-style Fn usage) no longer raises — but this is now impossible to express directly because TbxIsoTml::Fn is gone. Instead, assert that a NisoSts::Back → NisoSts::FnGroup → NisoSts::Fn serialization round-trips, and the original error message ("undefined method 'paragraph'") cannot occur.
+
+## Actions
+
+- [x] Add `spec/fn_namespace_spec.rb` asserting:
+  - `Sts::TbxIsoTml.const_defined?(:Fn)` is `false`
+  - `Sts::TbxIsoTml.const_defined?(:FnGroup)` is `false`
+  - `lib/sts/iso_sts/**/*.rb` files reference `IsoSts::Fn` / `IsoSts::FnGroup`, never `TbxIsoTml::Fn`
+  - `lib/sts/tbx_iso_tml/**/*.rb` files reference `NisoSts::Fn` / `NisoSts::FnGroup`, never `TbxIsoTml::Fn`
+  - Cross-namespace `Fn`/`FnGroup` instantiation and round-trip works through `NisoSts::Back → NisoSts::FnGroup → NisoSts::Fn`
+- [x] Run full suite, confirm green.
+
+## Verification
+
+- New spec file passes (14+ examples).
+- Full suite: 2300+ examples, 0 failures.

data/TODO.finalize/06-lutaml-model-element-builder-fix.md

@@ -0,0 +1,45 @@
+# 06: lutaml-model `ElementBuilder#create_nested_model_element` dispatch fix
+
+**Status**: DEFERRED (per downstream maintainer feedback 2026-07-25)
+**Repo**: `lutaml/lutaml-model`
+**File**: `lib/lutaml/xml/transformation/element_builder.rb`
+
+## Why deferred
+
+The downstream metanorma-iso maintainer (who originally reported the bug) reviewed the proposed two-PR plan and recommended:
+
+> Defer #2. The fix is a real robustness win but introduces a new contract
+> ("declared type must match value class") that may break other downstream
+> consumers who've been quietly relying on the current lenient behavior. Worth
+> doing eventually, but the urgency drops once #1 lands — without the
+> duplicate classes there's no easy way to trigger the trap.
+
+## Original analysis (kept for future reference)
+
+Currently `create_nested_model_element` reuses `rule.child_transformation` (compiled for the declared `attribute_type`) for any value that is not a declared subtype. When a caller assigns an unrelated `Lutaml::Model::Serialize` to a typed slot, the wrong transformation is applied to the value, producing confusing `NoMethodError`s on whichever Ruby attribute name differs.
+
+The cache itself is fine — `transformation_key` includes `object_id`. The dispatch logic is the bug.
+
+## When to revisit
+
+- Track upstream consumers: if a second case of cross-class assignment emerges (e.g., another gem duplicates a Serializable with different Ruby attribute names), the urgency rises.
+- Pair with a proper audit of existing polymorphic specs to ensure the lenient dispatch wouldn't break tests.
+- Consider an opt-in flag (`strict_type_check: true`) before flipping default behavior.
+
+## Sketch of the fix (when revisited)
+
+In `lib/lutaml/xml/transformation/element_builder.rb#create_nested_model_element`:
+
+```ruby
+dispatch_on_value_class = union || is_polymorphic ||
+  (value.is_a?(Lutaml::Model::Serialize) && value.class != rule.attribute_type)
+
+child_transformation = if dispatch_on_value_class
+                         value.class.transformation_for(:xml, register)
+                       else
+                         rule.child_transformation ||
+                           rule.attribute_type.transformation_for(:xml, register)
+                       end
+```
+
+This subsumes the existing `is_polymorphic_subtype` check (subtypes already have `value.class != rule.attribute_type`).

data/TODO.finalize/07-lutaml-model-specs.md

@@ -0,0 +1,12 @@
+# 07: lutaml-model specs for cross-class dispatch
+
+**Status**: DEFERRED (follows step 06)
+
+See step 06 for the deferral rationale. When 06 is revisited, the specs described below should accompany it.
+
+## Originally planned specs
+
+- Cross-class dispatch: parent declares `attribute :child, ParentClass`; caller assigns `OtherSerializable.new` (not a subtype). Serialization uses `OtherSerializable`'s mapping rules.
+- Round-trip preserved: parsing the serialized XML yields an instance whose attributes match the original.
+- Declared-type fast path unchanged: assigning a `ParentClass` instance uses the cached `child_transformation`.
+- Subtype polymorphism (existing `is_polymorphic_subtype` behaviour) still works.

data/TODO.finalize/08-sts-ruby-pr.md

@@ -0,0 +1,20 @@
+# 08: Open sts-ruby PR
+
+**Status**: pending
+**Blocked by**: 02, 03, 04, 05
+
+## Actions
+
+- [x] Branch `fix/remove-tbxisotml-fn-duplicate` off latest `main`.
+- [x] Commit steps 02–05 with a clear message.
+- [x] Push, open PR against `metanorma/sts-ruby`.
+- [x] PR body via `--body-file` (contains backticks — never inline).
+
+## PR description points
+
+- Root cause: duplicate `<fn>` classes across namespaces with conflicting Ruby attr names.
+- Why TbxIsoTml loses its Fn/FnGroup: `<fn>` is not a TBX-ISO-TML element.
+- Why IsoSts keeps its own: namespace independence (per ADR 2026-05-07).
+- Why TbxIsoTml call sites use NisoSts::Fn: matches existing Bold/Italic pattern; TBX is shared.
+- Behaviour change: callers that construct IsoSts documents using `TbxIsoTml::Fn` must now use `IsoSts::Fn` (drop-in: same `:paragraph` Ruby attr).
+- References TODO.finalize/00-overview.md.

data/TODO.finalize/09-lutaml-model-pr.md

@@ -0,0 +1,5 @@
+# 09: Open lutaml-model PR
+
+**Status**: DEFERRED (follows step 06)
+
+See step 06. No PR to file at this time.

data/TODO.finalize/10-audit-other-duplicates.md

@@ -0,0 +1,29 @@
+# 10: Audit other potential duplicates (deferred)
+
+**Status**: deferred — track for future investigation
+**Priority**: medium
+
+## Why
+
+The Fn/FnGroup duplication suggests `TbxIsoTml` may contain other JATS / NISO STS elements misclassified as TBX. Each duplicate is a potential version-mismatch footgun. A one-time audit would surface them.
+
+## Suspects to investigate
+
+Cross-reference each `TbxIsoTml::*` class against the TBX-ISO-TML (ISO 30042) element list. Anything NOT in TBX-ISO-TML is a misfit. Likely candidates:
+
+- `TbxIsoTml::Xref` — `<xref>` is a JATS element
+- `TbxIsoTml::TableWrap` — `<table-wrap>` is JATS / NISO STS
+- `TbxIsoTml::Table`, `TbxIsoTml::Thead`, `TbxIsoTml::Tbody`, `TbxIsoTml::Tfoot`, `TbxIsoTml::Tr`, `TbxIsoTml::Th`, `TbxIsoTml::Td`, `TbxIsoTml::Col`, `TbxIsoTml::Colgroup` — XHTML table model, not TBX
+- `TbxIsoTml::Caption` — `<caption>` is JATS
+- `TbxIsoTml::FnGroup` (deleted in step 02)
+- `TbxIsoTml::List` (if present) — `<list>` is JATS
+
+True TBX-ISO-TML elements (must stay): `TermEntry`, `Tig`, `Term`, `TermInformationGroup`, `EntailedTerm`, `Descrip`, `DescripGrp`, `Note` (TBX-spec note, not JATS note), `Definition`, `Source`, `LangSet`, `SubjectField`, `PartOfSpeech`, etc.
+
+## Verification approach for each suspect
+
+1. Check ISO 30042 / TBX-INFO documentation for the element name.
+2. If NOT in TBX-ISO-TML: should not exist in `Sts::TbxIsoTml::*`.
+3. Decide: delete (if no semantic difference from the JATS / NISO STS equivalent) or move to the correct namespace.
+
+This is **not** in scope for the current PR series. Track as a follow-up.

data/TODO.finalize/11-strengthen-anti-patterns-spec.md

@@ -0,0 +1,24 @@
+# 11: Strengthen `anti_patterns_spec.rb` (deferred)
+
+**Status**: deferred — track for future improvement
+**Priority**: low
+
+## Why
+
+The current `spec/anti_patterns_spec.rb` checks for `method_missing`, `respond_to_missing?`, `Object.const_get`, `.send(` — but misses several global-rule patterns. The MathML hack file (`lib/sts/iso_sts/mathml2/math.rb`, since deleted in TODO 02 of the prior audit) had `instance_variable_set`, `respond_to?(:read)`, and hand-rolled `to_xml` — none would have been caught.
+
+## Add checks for
+
+- [ ] `instance_variable_set` / `instance_variable_get` (forbidden by global rule)
+- [ ] `respond_to?` for type-checking (allowed only inside test infrastructure or explicit adapter negotiation — define an allowlist)
+- [ ] Hand-rolled serialization methods on `Lutaml::Model::Serializable` subclasses: `def to_h`, `def to_hash`, `def from_h`, `def from_hash`, `def to_json`, `def from_json`, `def to_xml`, `def from_xml`, `def serialize`, `def deserialize`
+- [ ] `require_relative` anywhere in `lib/` (autoloads only — global rule)
+- [ ] `double(` in specs (global rule)
+
+## Implementation notes
+
+- The existing pattern (file-by-file source scan) extends naturally — add new `it` blocks per check.
+- Some checks may need an allowlist (e.g., `respond_to?` for IO vs String detection at gem boundaries). Document the allowlist inline.
+- Run after every lib change, not just at PR time.
+
+This is **not** in scope for the current PR series. Track as a follow-up.

data/TODO.sts-refactor/00-overview.md

@@ -167,26 +167,35 @@ grep -r "method_missing|respond_to_missing|Object.const_get|\.send" lib/
 
 ### Architectural Items (High Effort)
 - `03-namespace-coupling.md` — IN PROGRESS: 63→20 IsoSts→NisoSts references
-  remaining (issue #40). Source of truth is `ISOSTS.xsd`, NOT the NisoSts
-  models — they disagree on nearly every element.
+  remaining (issue #40). ISOSTS.xsd governs content models and all non-`@id`
+  attributes; the `@id` follows the 86948b9 convention.
 - `04-register-versioning.md` — Version the models via lutaml-model Registers
 - `11-duplicate-models.md` — 44 overlapping element resolution (depends on 03)
 
-### Known bugs — schema conformance (separate from 03)
+### Schema conformance — dropped ISOSTS attributes
 The 2026-05-07 "@id added to all models (XSD-verified)" pass verified against
-the **NISO** XSD and applied the result to IsoSts. ISOSTS disagrees:
-- **16 IsoSts models silently drop ISOSTS attributes that exist** — real data
-  loss. `sub`/`sup` lose `arrange`+`specific-use`; `ext-link` loses 5 xlink
-  attrs; `mixed-citation` loses 6; `graphic`, `copyright-*`, `edition`,
-  `title`, `label`, `uri`, `named-content`, `underline`, `meta-date`, `body`
-  lose others.
-- **25 IsoSts models carry an `@id` ISOSTS does not define** — harmless (never
-  populated on parse, never emitted on serialise), but dead surface.
+the **NISO** XSD and applied the result to IsoSts.
+- **Fixed — dropped ISOSTS attributes restored.** 15 IsoSts models were
+  silently dropping ISOSTS attributes present in real documents (data loss):
+  `sub`/`sup` (`arrange`+`specific-use`), `ext-link`/`mixed-citation`/`uri`/
+  `named-content` (`xlink:*`), `graphic` (`xlink:*`+`originator`), `copyright-*`,
+  `edition`, `title`, `label`, `underline`, `body`. This change adds them and
+  fixes `sec`/`standard`/`term-sec`, which mapped `xml:lang` under the wrong XML
+  name. (`meta-date` was NOT lossy — it already maps `type`.)
+- **Not a bug — the conventional `@id`.** IsoSts models carry an `@id` that
+  ISOSTS does not itself define; this is the deliberate 86948b9 convention
+  (NISO-XSD-verified), not dead surface.
+- **Remaining follow-up (separate change).** 7 spurious attributes on 5 models
+  (model carries an attr ISOSTS does not define: `graphic` `type`, `body`/`back`
+  `content-type`, `content-language`/`language` extras), and the 6 classes left
+  without `@id` in 86948b9 (`monospace`, `sc`, `strike`, `underline`, `uri`,
+  `standard_ref`).
 
 ## Next Action
 Two independent tracks:
 1. Finish `03` — the 20 remaining refs split into 11 deep-root refs (each
    reaching a ~152-class recursive core) and 9 child-bearing refs whose closure
    is unmeasured. Both need sizing before planning.
-2. File and fix the 16 lossy models above — real data loss, unrelated to
-   decoupling.
+2. The remaining schema-conformance follow-up above — the 7 spurious attributes
+   on 5 models and the 6 classes without `@id`. (The dropped-attribute data loss
+   is now fixed.)

data/TODO.sts-refactor/03-namespace-coupling.md

@@ -14,41 +14,42 @@ evolves, so coupling them violates OCP.
 PR #31 reduced this from 157 to 63 references. Issue #40 reduced it further,
 from 63 to 20.
 
-## Source of truth: ISOSTS.xsd, NOT the NisoSts models
+## Content models from ISOSTS.xsd; `@id` from the 86948b9 convention
 
-The obvious approach — duplicate each NisoSts class into IsoSts — produces
-**schema-incorrect models**. The NisoSts models disagree with
-`reference-docs/isosts-v1/xsd/ISOSTS.xsd` on nearly every element:
+IsoSts models carry `@id` following the compatibility convention established in
+86948b9 (NISO-XSD-verified). ISOSTS.xsd governs element content
+models and all non-`@id` attributes; it is not an authority that forbids the
+conventional `@id`. So the two schemas can legitimately differ per element:
 
-| Element | ISOSTS says | NisoSts model |
+| Element | ISOSTS content/attrs | NisoSts model |
 |---|---|---|
-| `year` (:948) | `content-type`, `specific-use`, `xml:lang` — no `@id` | `@id` only |
-| `doc-type` (:6378) | `type="xs:string"` — no attributes at all | `@id` + content |
+| `doc-type` (:6378) | `type="xs:string"` | `@id` + content |
 | `ics` (:6373) | `type="xs:string"` | `@id` + `ics-desc` child |
 | `fpage` | `content-type`, `seq`, `specific-use`, `xml:lang`; no children | `@id` + bold/italic |
 | `license` (:51) | `license-type`, `specific-use`, `xml:lang` | `@id`, `xlink:href` |
-| `ruby` | **not an ISOSTS element** | exists (NISO only) |
 
 `feature_doc.xml` declares `<!DOCTYPE standard SYSTEM ".../ISOSTS.dtd">`, and
 the ISOSTS DTD agrees with ISOSTS.xsd (both derive `bold`, `sub` etc. from the
-JATS 0.4 modules). ISOSTS.xsd is a faithful conversion and is the authority.
+JATS 0.4 modules) on content models.
 
 **Round-tripping does not prove correctness.** A model that invents or drops an
 attribute still parses and serialises symmetrically, so the suite stays green
 while the model is wrong. Assert the exact attribute set per element instead.
 
-Attribute lists must be **generated** from the XSD, never hand-read: `version`
-on `tex-math` and `specific-use` on `pub-id` sit after long `xs:enumeration`
-blocks and are invisible to a truncated read.
+Non-`@id` attribute lists must be **generated** from the XSD, never hand-read:
+`version` on `tex-math` and `specific-use` on `pub-id` sit after long
+`xs:enumeration` blocks and are invisible to a truncated read.
 
 ## Done in issue #40 — 43 refs removed, 27 classes added
 
 - **14 `xs:string` elements** (`originator`, `doc-type`, `doc-number`,
   `part-number`, `version`, `suppl-type`, `suppl-number`, `suppl-version`,
   `urn`, `sdo`, `proj-id`, `release-version`, `ics`, `secretariat`) — modelled
-  as content-only IsoSts classes with no attributes. 23 refs.
+  as content IsoSts classes that also carry the conventional `@id` (86948b9);
+  `secretariat` is content plus `@id`, not content-only. 23 refs.
 - **3 `permissions` refs** repointed to the existing `IsoSts::Permissions`.
-- **`ruby` deleted** from `StyledContent` — ISOSTS defines no such element.
+- **`ruby` deleted** from `StyledContent` — ISOSTS's `styled-content` content
+  model omits `<ruby>` (NISO permits it transitively via the emphasis group).
   Behaviour change: `<ruby>` in `<styled-content>` no longer round-trips.
 - **13 element classes** modelled from ISOSTS.xsd: `Year`, `PubDate`,
   `ReleaseVersionId`, `IsProof`, `AltText`, `LongDesc`, `TexMath`, `PubId`,
@@ -114,6 +115,7 @@ reaches `TbxIsoTml`/MathML. Those are shared namespaces, outside this ADR.
 ## Verification
 
 1. `grep -rho "Sts::NisoSts::" lib/sts/iso_sts/ | wc -l` → `20`
-2. Every attribute on an IsoSts model traces to a line in `ISOSTS.xsd`
+2. Every *non-`@id`* attribute on an IsoSts model traces to a line in
+   `ISOSTS.xsd`; `@id` follows the 86948b9 convention
 3. Autoload registry 1:1 with the directory (112/112)
 4. `bundle exec rspec` green; `bundle exec rubocop` clean

data/lib/sts/iso_sts/body.rb

@@ -5,6 +5,7 @@ module Sts
     class Body < Lutaml::Model::Serializable
       attribute :id, :string
       attribute :content_type, :string
+      attribute :specific_use, :string
       attribute :paragraph, ::Sts::IsoSts::Paragraph, collection: true
       attribute :sec, ::Sts::IsoSts::Sec, collection: true
       attribute :term_sec, ::Sts::IsoSts::TermSec, collection: true
@@ -31,6 +32,7 @@ module Sts
 
         map_attribute "id", to: :id
         map_attribute "content-type", to: :content_type
+        map_attribute "specific-use", to: :specific_use
 
         map_element "p", to: :paragraph
         map_element "sec", to: :sec

data/lib/sts/iso_sts/bold.rb

@@ -22,7 +22,7 @@ module Sts
       attribute :sc, ::Sts::IsoSts::Sc, collection: true
       attribute :strike, ::Sts::IsoSts::Strike, collection: true
       attribute :underline, ::Sts::IsoSts::Underline, collection: true
-      attribute :fn, ::Sts::TbxIsoTml::Fn, collection: true
+      attribute :fn, ::Sts::IsoSts::Fn, collection: true
 
       xml do
         element "bold"

data/lib/sts/iso_sts/copyright_holder.rb

@@ -4,6 +4,9 @@ module Sts
   module IsoSts
     class CopyrightHolder < Lutaml::Model::Serializable
       attribute :id, :string
+      attribute :content_type, :string
+      attribute :specific_use, :string
+      attribute :xml_lang, :string
       attribute :content, :string, collection: true
       attribute :sub, ::Sts::IsoSts::Sub
       attribute :sup, ::Sts::IsoSts::Sup
@@ -11,6 +14,9 @@ module Sts
       xml do
         element "copyright-holder"
         map_attribute "id", to: :id
+        map_attribute "content-type", to: :content_type
+        map_attribute "specific-use", to: :specific_use
+        map_attribute "xml:lang", to: :xml_lang
         mixed_content
 
         map_content to: :content

data/lib/sts/iso_sts/copyright_statement.rb

@@ -4,6 +4,9 @@ module Sts
   module IsoSts
     class CopyrightStatement < Lutaml::Model::Serializable
       attribute :id, :string
+      attribute :content_type, :string
+      attribute :specific_use, :string
+      attribute :xml_lang, :string
       attribute :content, :string, collection: true
       attribute :bold, ::Sts::IsoSts::Bold
       attribute :italic, ::Sts::IsoSts::Italic
@@ -13,6 +16,9 @@ module Sts
       xml do
         element "copyright-statement"
         map_attribute "id", to: :id
+        map_attribute "content-type", to: :content_type
+        map_attribute "specific-use", to: :specific_use
+        map_attribute "xml:lang", to: :xml_lang
         mixed_content
 
         map_content to: :content

data/lib/sts/iso_sts/copyright_year.rb

@@ -4,12 +4,16 @@ module Sts
   module IsoSts
     class CopyrightYear < Lutaml::Model::Serializable
       attribute :id, :string
+      attribute :content_type, :string
+      attribute :specific_use, :string
       attribute :content, :string
 
       xml do
         element "copyright-year"
 
         map_attribute "id", to: :id
+        map_attribute "content-type", to: :content_type
+        map_attribute "specific-use", to: :specific_use
 
         map_content to: :content
       end

data/lib/sts/iso_sts/disp_formula.rb

@@ -9,7 +9,7 @@ module Sts
       attribute :xml_lang, :string
       attribute :originator, :string
       attribute :label, ::Sts::IsoSts::Label
-      attribute :math, Mml::V3::Math
+      attribute :math, Mml::V2::Math
       attribute :bold, ::Sts::IsoSts::Bold
       attribute :italic, ::Sts::IsoSts::Italic
       attribute :non_normative_note, ::Sts::IsoSts::NonNormativeNote

data/lib/sts/iso_sts/doc_number.rb

@@ -2,14 +2,17 @@
 
 module Sts
   module IsoSts
-    # ISOSTS declares <doc-number> as type="xs:string" -- no attributes.
+    # ISOSTS declares <doc-number> as type="xs:string". The @id follows the
+    # NisoSts convention established in 86948b9, not ISOSTS itself.
     class DocNumber < Lutaml::Model::Serializable
       attribute :content, :string
+      attribute :id, :string
 
       xml do
         element "doc-number"
 
         map_content to: :content
+        map_attribute "id", to: :id
       end
     end
   end

data/lib/sts/iso_sts/doc_type.rb

@@ -2,14 +2,17 @@
 
 module Sts
   module IsoSts
-    # ISOSTS declares <doc-type> as type="xs:string" -- no attributes.
+    # ISOSTS declares <doc-type> as type="xs:string". The @id follows the
+    # NisoSts convention established in 86948b9, not ISOSTS itself.
     class DocType < Lutaml::Model::Serializable
       attribute :content, :string
+      attribute :id, :string
 
       xml do
         element "doc-type"
 
         map_content to: :content
+        map_attribute "id", to: :id
       end
     end
   end

data/lib/sts/iso_sts/edition.rb

@@ -4,10 +4,16 @@ module Sts
   module IsoSts
     class Edition < Lutaml::Model::Serializable
       attribute :id, :string
+      attribute :content_type, :string
+      attribute :specific_use, :string
+      attribute :xml_lang, :string
       attribute :content, :string, collection: true
       xml do
         element "edition"
         map_attribute "id", to: :id
+        map_attribute "content-type", to: :content_type
+        map_attribute "specific-use", to: :specific_use
+        map_attribute "xml:lang", to: :xml_lang
         mixed_content
 
         map_content to: :content