sts 0.6.2 → 0.6.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 572accdd400693b1c1320ea6891f5be801f3917d64d98058f6da1b30c92436c2
-  data.tar.gz: 3bd1daa1cd5335c796c21732e7034b5bfb23f522bdd1d9e7db85df32f07bcf2a
+  metadata.gz: c758f04c86a04df1adb4bc66d09aac7f31477d8ce6879bb9cd8935d86a7ae616
+  data.tar.gz: 56893d54b3e2193926f95a8a988d0a12dc73b31a85d9223e90edfe46adf80b07
 SHA512:
-  metadata.gz: ebf47f3e1a2d0e4b95ccc6cba35d3e749cec5393847f21c420346a031e366ea3f33d9e2f641cc2a03fea4598b57a278d1539c3dcb777b9a1882e9bf45aa0711a
-  data.tar.gz: 73b5f522a8d2177c58ac7ecb1d618d2c5e270dddac0113383ee567eb32cabb2022c70f1d0559bde2b5c5d613f72dd0608905fde0549fadc4a35e280b2d26fb46
+  metadata.gz: e2444f3c73074bd001445a89a5712854e112b429180b7a96feff1e01e303dfd5791a7ab6e81eb27498ba859078a8a647793a8e40276ec6e2cab2d90c9b7a4517
+  data.tar.gz: d3b0d7c1ba7721b108ae509b5847e1a21917d4cc5507581d7581af2d71a0f742d16b316fc53a3d8c263b11816ee074a6b5a17547b9773dd3f99e472959db9069

data/.rubocop_todo.yml

@@ -70,6 +70,7 @@ 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'
 

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

@@ -19,7 +19,7 @@
 |---|------|----------|----------|--------------|
 | 01 | `01-mathml-delegation.md` | Anti-Pattern Fix | DONE | — |
 | 02 | `02-type-resolution.md` | Anti-Pattern Fix | DONE | — |
-| 03 | `03-namespace-coupling.md` | Architecture | IN PROGRESS (63→20 refs) | 01, 02 |
+| 03 | `03-namespace-coupling.md` | Architecture | IN PROGRESS (63→16 refs) | 01, 02 |
 | 04 | `04-register-versioning.md` | Architecture | HIGH | 01, 02 |
 | 05 | `05-missing-elements.md` | Feature Gap | MOSTLY DONE | 04 |
 | 06 | `06-missing-attributes.md` | Feature Gap | DONE | 04 |
@@ -166,27 +166,39 @@ grep -r "method_missing|respond_to_missing|Object.const_get|\.send" lib/
 - ~~Expand StringName usage (in contrib, element-citation, related-article — NISO STS 1.2)~~ → DONE: added to name-alternatives; already in person-group and mixed-citation
 
 ### 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.
+- `03-namespace-coupling.md` — IN PROGRESS: 63→16 IsoSts→NisoSts references
+  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.
+1. Finish `03` — the 16 remaining refs split evenly between seven recursive
+   roots and five child-bearing roots. The first 15 high-reuse dependency
+   leaves are now modelled, reducing the unresolved closures to 78–84
+   not-yet-modelled ISOSTS elements before existing IsoSts boundaries. The
+   remaining work still needs an architecture decision for the recursive
+   content core.
+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

@@ -3,7 +3,7 @@
 **Priority**: HIGH
 **Category**: Architecture
 **Estimated Effort**: High
-**Status**: Partially done — 63 → 20 references (GitHub issue #40)
+**Status**: Partially done — 63 → 16 references (GitHub issue #40)
 
 ## Problem
 
@@ -12,49 +12,63 @@ independent of NisoSts (ADR 2026-05-07): ISOSTS is frozen legacy, NISO STS
 evolves, so coupling them violates OCP.
 
 PR #31 reduced this from 157 to 63 references. Issue #40 reduced it further,
-from 63 to 20.
+from 63 to 16.
 
-## 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
+## Done in issue #40 — 47 refs removed, 46 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`,
   `Volume`, `Issue`, `Fpage`, `Lpage`, `PageRange`. 16 refs.
 - **`WiNumber` added** — ISOSTS gives `wi-number` an `@id`; it was typed as a
   plain string, silently discarding that `@id`.
+- **`Publisher` closure added** — `Publisher`, `PublisherName`, `PublisherLoc`,
+  and `Email` are modelled from ISOSTS.xsd; `PublisherLoc` reuses the existing
+  IsoSts `ExtLink` and `Uri` boundary models. All four retain the
+  project-mandated `@id` model surface. 1 ref.
+- **15 reusable dependency leaves added** — `Abbrev`, `Annotation`, `Country`,
+  `Day`, `Etal`, `Fax`, `InlineGraphic`, `Institution`, `MilestoneEnd`,
+  `MilestoneStart`, `Month`, `Num`, `ObjectId`, `Phone`, and `Season` are
+  modelled from ISOSTS.xsd and close entirely on existing IsoSts types. They
+  remove no direct reference yet, but establish the first shared dependency
+  layer for the remaining recursive roots.
+- **3 Niso-only child refs deleted** — `std-meta` from `Front` and
+  `editing-instruction` from `Body` and `Sec`. Neither element exists in
+  ISOSTS.xsd, so adding IsoSts equivalents would incorrectly expand the schema.
 
 ### Why classes and not plain `:string`
 
@@ -65,20 +79,23 @@ round-trip. For a scalar, `render_empty: :empty` recovers it; for a collection
 to `[]`, destroying the information at parse time before any render option
 applies. Content-only classes round-trip every case.
 
-## Remaining — 20 refs
+## Remaining — 16 refs
 
-**11 refs to 9 deep roots**: `MetadataStd`, `ElementCitation`, `PersonGroup`,
-`Collab`, `Source`, `DispQuote`, `EditingInstruction`, `TermDisplay`,
-`BoxedText`. Each reaches the same ~152-class mutually-recursive core
-(`Section` → `Paragraph` → `DispQuote` → `Paragraph`). `DispQuote` has 3 direct
-children but pulls all 152. No incremental path — needs its own decision.
+**8 refs to 7 recursive roots**: `ElementCitation`, `PersonGroup`, `Collab`,
+`Source`, `DispQuote`, `TermDisplay`, and `BoxedText`. Each reaches the same
+78–79-element mutually-recursive core before existing IsoSts boundaries
+(`sec` → `p` → `disp-quote` → `p`). No direct one-file path remains.
 
-**9 refs whose ISOSTS content models have real children**, closure not measured:
-`attrib` (:1082), `term-head` (:4308), `article-title`, `license` → `license-p`
-(:51), `publisher` → `publisher-loc`, `custom-meta-group` → `custom-meta`.
-`attrib` and `term-head` are **not** trivial leaves in ISOSTS despite what the
-NisoSts models suggest; `license-p` reaches `array`/`alternatives`, so these may
-not be cheap. Measure before planning.
+**8 refs to 5 child-bearing roots**, now measured after the first dependency
+layer: `attrib` (:1082) reaches 78 not-yet-modelled ISOSTS elements before
+existing IsoSts boundaries, `term-head` (:4308) reaches 79, `article-title`
+reaches 78, `license` → `license-p` (:51) reaches 84, and
+`custom-meta-group` → `custom-meta` reaches 82. They converge on the same
+recursive content core as the deep roots, so none is another bounded model
+batch. `publisher` was the only exception: its four-element closure
+(`publisher`, `publisher-name`, `publisher-loc`, `email`) is complete.
+The Niso `Attrib` class is only 17 lines because it omits all 37 ISOSTS child
+types; copying it would silently drop valid ISO content rather than decouple it.
 
 ## Rejected: three-tier `Sts::Base` hierarchy
 
@@ -113,7 +130,8 @@ 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`
-3. Autoload registry 1:1 with the directory (112/112)
+1. `grep -rho "Sts::NisoSts::" lib/sts/iso_sts/ | wc -l` → `16`
+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 (131/131)
 4. `bundle exec rspec` green; `bundle exec rubocop` clean

data/lib/sts/iso_sts/abbrev.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Sts
+  module IsoSts
+    class Abbrev < Lutaml::Model::Serializable
+      attribute :id, :string
+      attribute :content_type, :string
+      attribute :specific_use, :string
+      attribute :alt, :string
+      attribute :xml_lang, :string
+      attribute :xlink_type, :string
+      attribute :xlink_href, :string
+      attribute :xlink_role, :string
+      attribute :xlink_title, :string
+      attribute :xlink_show, :string
+      attribute :xlink_actuate, :string
+      attribute :content, :string, collection: true
+      attribute :def, ::Sts::IsoSts::Def, collection: true
+
+      xml do
+        element "abbrev"
+        mixed_content
+
+        map_attribute "id", to: :id
+        map_attribute "content-type", to: :content_type
+        map_attribute "specific-use", to: :specific_use
+        map_attribute "alt", to: :alt
+        map_attribute "xml:lang", to: :xml_lang
+        map_attribute "xlink:type", to: :xlink_type
+        map_attribute "xlink:href", to: :xlink_href
+        map_attribute "xlink:role", to: :xlink_role
+        map_attribute "xlink:title", to: :xlink_title
+        map_attribute "xlink:show", to: :xlink_show
+        map_attribute "xlink:actuate", to: :xlink_actuate
+
+        map_content to: :content
+        map_element "def", to: :def
+      end
+    end
+  end
+end