pubid 2.0.19 → 2.0.21

data/lib/pubid/iec/identifier.rb

@@ -10,15 +10,15 @@ module Pubid
     # Iso::BundledIdentifier.) Fragment keeps its own stage/edition, so it
     # suppresses a subset inline instead of including this.
     #
-    # number/part/subpart are NOT here, and deliberately so: their maps live on
-    # SingleIdentifier, which the four wrappers do not inherit from, so the
-    # exclusion is structural rather than a denylist that can drift. Only a
-    # converter can be no-opped this way, so a key that needs `with:` for
-    # another reason — year, publisher, copublishers, stage — still lists here.
-    # (`month`/`day`/`undated` are missing from that list and leak a duplicated
-    # top-level key on a wrapper; pre-existing, see lib/pubid/iec/CLAUDE.md.)
+    # number/part/subpart and the date keys (year/month/day/undated) are NOT
+    # here, and deliberately so: their maps live on SingleIdentifier, which
+    # the wrappers do not inherit from, so the exclusion is structural rather
+    # than a denylist that can drift. (The denylist did drift: it once listed
+    # `year` but not `month`/`day`/`undated`, and those three leaked a
+    # duplicated top-level key on every wrapper.) Only publisher,
+    # copublishers and stage stay here, because those maps are still wanted
+    # on the parent block.
     module DelegatedFieldSuppression
-      def year_to_kv(_model, _doc); end
       def publisher_to_kv(_model, _doc); end
       def copublishers_to_kv(_model, _doc); end
       def stage_to_kv(_model, _doc); end
@@ -165,7 +165,7 @@ module Pubid
       key_value do
         map "_type", to: :_type, polymorphic_map: IEC_TYPE_MAP
         # number/part/subpart are NOT mapped here — they live on
-        # SingleIdentifier, the seam that excludes the four delegating wrappers.
+        # SingleIdentifier, the seam that excludes the delegating wrappers.
         # See the comment on that block.
         #
         # stage_iteration is a degenerate Components::Iteration (one :string
@@ -173,13 +173,9 @@ module Pubid
         # ::Pubid::Identifier flattens it to a bare scalar and inflates it back.
         # A plain map is enough; no converter.
         map "stage_iteration", to: :stage_iteration, render_default: false
-        # date serialized flat as year/month/day, nils omitted.
-        map "year", with: { to: :year_to_kv, from: :year_from_kv }
-        map "month", with: { to: :month_to_kv, from: :month_from_kv }
-        map "day", with: { to: :day_to_kv, from: :day_from_kv }
-        # IEC undated reference (e.g. IEC 60050:--). The `false` default is
-        # omitted; only the meaningful `true` round-trips via to_hash.
-        map "undated", with: { to: :undated_to_kv, from: :undated_from_kv }
+        # year/month/day/undated are NOT mapped here either — they live on
+        # SingleIdentifier for the same reason as number/part/subpart: a
+        # wrapper delegates `date` to what it wraps.
         map "edition", to: :edition, render_default: false
         map "languages", to: :languages, render_default: false
         # publisher emitted only when the primary isn't the IEC default;
@@ -195,59 +191,6 @@ module Pubid
         # already drops, so a plain map suffices (the GB spelling).
       end
 
-      # --- date serialized flat as year/month/day ---
-      def year_to_kv(model, doc)
-        y = model.date&.year
-        return if y.nil? || y.to_s.empty?
-
-        doc.add_child(Lutaml::KeyValue::DataModel::Element.new("year", y.to_s))
-      end
-
-      def year_from_kv(model, value)
-        return if value.nil? || value.to_s.empty?
-
-        (model.date ||= ::Pubid::Components::Date.new).year = value.to_s
-      end
-
-      def month_to_kv(model, doc)
-        m = model.date&.month
-        return if m.nil? || m.to_s.empty?
-
-        doc.add_child(Lutaml::KeyValue::DataModel::Element.new("month", m.to_s))
-      end
-
-      def month_from_kv(model, value)
-        return if value.nil? || value.to_s.empty?
-
-        (model.date ||= ::Pubid::Components::Date.new).month = value.to_s
-      end
-
-      def day_to_kv(model, doc)
-        d = model.date&.day
-        return if d.nil? || d.to_s.empty?
-
-        doc.add_child(Lutaml::KeyValue::DataModel::Element.new("day", d.to_s))
-      end
-
-      def day_from_kv(model, value)
-        return if value.nil? || value.to_s.empty?
-
-        (model.date ||= ::Pubid::Components::Date.new).day = value.to_s
-      end
-
-      # --- date undated flag (IEC undated reference, e.g. IEC 60050:--) ---
-      # The `false` default is omitted; only the meaningful `true` round-trips
-      # via to_hash / from_hash.
-      def undated_to_kv(model, doc)
-        return unless model.date&.undated?
-
-        doc.add_child(Lutaml::KeyValue::DataModel::Element.new("undated", true))
-      end
-
-      def undated_from_kv(model, value)
-        (model.date ||= ::Pubid::Components::Date.new).undated = value.to_s == "true"
-      end
-
       # --- publisher: primary only when non-default; copublishers as a list ---
       def publisher_to_kv(model, doc)
         pub = model.publisher&.body
@@ -326,7 +269,13 @@ module Pubid
         # Apply legacy update_codes normalization first, before any other preprocessing
         normalized = Core::UpdateCodes.apply(string, :iec)
         parsed = Pubid::Parg::Model.bound(:iec, Pubid::Iec::Parser.normalize_input(normalized))
-        Pubid::Iec::Builder.new.build(parsed)
+        id = Pubid::Iec::Builder.new.build(parsed)
+        # A standalone supplement stores its numbers in the layout from_hash
+        # rebuilds only after #ensure_base runs; run it here, so a fresh
+        # parse holds that layout before any reader runs
+        # (SupplementIdentifier#number).
+        id.ensure_base if id.is_a?(SupplementIdentifier)
+        id
       end
 
       # from_hash is the shared polymorphic dispatch on Pubid::Identifier.

data/lib/pubid/iec/identifiers/fragment_identifier.rb

@@ -25,9 +25,9 @@ module Pubid
           map "fragment_number", to: :fragment_number, render_default: false
         end
 
-        # number/part/subpart need no no-op here: their maps live on
-        # SingleIdentifier, which this class does not inherit from.
-        def year_to_kv(_model, _doc); end
+        # number/part/subpart and year/month/day/undated need no no-op here:
+        # their maps live on SingleIdentifier, which this class does not
+        # inherit from.
         def publisher_to_kv(_model, _doc); end
         def copublishers_to_kv(_model, _doc); end
 

data/lib/pubid/iec/identifiers/test_report_form.rb

@@ -11,6 +11,35 @@ module Pubid
         attribute :cispr_identifier, Identifier, polymorphic: true, default: -> {
         }
 
+        # The embedded CISPR document is part of the form's identity, so it
+        # serializes under its own key (issue #687 — before it, a
+        # CISPR-bearing TRF hashed to just its publisher and year and never
+        # matched after a from_hash round trip). The converter shape is
+        # VapIdentifier#base_to_kv / #base_from_kv: the nested identifier
+        # carries its own polymorphic `_type`, so to_hash embeds the nested
+        # hash and from_hash dispatches back through the type map.
+        key_value do
+          map "cispr_identifier",
+              with: { to: :cispr_identifier_to_kv,
+                      from: :cispr_identifier_from_kv }
+        end
+
+        def cispr_identifier_to_kv(model, doc)
+          cispr = model.cispr_identifier
+          return unless cispr
+
+          doc.add_child(
+            Lutaml::KeyValue::DataModel::Element.new("cispr_identifier",
+                                                     cispr.to_hash),
+          )
+        end
+
+        def cispr_identifier_from_kv(model, value)
+          if value
+            model.cispr_identifier = ::Pubid::Iec::Identifier.from_hash(value)
+          end
+        end
+
         # TRF has type abbreviation for parsing
         TYPED_STAGES = [
           Pubid::Components::TypedStage.new(

data/lib/pubid/iec/identifiers/working_document.rb

@@ -11,12 +11,28 @@ module Pubid
       #   Working Document: "100/3705(F)/FDIS"
       class WorkingDocument < Base
         attribute :technical_committee, :string, default: -> {}
-        attribute :wd_number, :string, default: -> {}
         attribute :wd_language, :string, default: -> {}
         attribute :wd_stage, :string, default: -> {}
         attribute :wp_stage, :string, default: -> {}
         attribute :wp_type, :string, default: -> {}
 
+        # The working document's identity attributes are plain strings, so no
+        # converter is needed: lutaml writes the scalar, and
+        # ::Pubid::Identifier#to_hash drops a nil (the `-> {}` defaults are
+        # nil). This is the serialization that issue #687 restored — before
+        # it, `to_hash` was `{"_type" => "pubid:iec:working-document"}` alone,
+        # all 2,318 working documents shared one hash and one URN
+        # (`urn:pubid:iec:wd`), and no row of this class ever matched after a
+        # from_hash round trip.
+        key_value do
+          map "technical_committee", to: :technical_committee,
+                                     render_default: false
+          map "wd_language", to: :wd_language, render_default: false
+          map "wd_stage", to: :wd_stage, render_default: false
+          map "wp_stage", to: :wp_stage, render_default: false
+          map "wp_type", to: :wp_type, render_default: false
+        end
+
         # Working documents have no TYPED_STAGES - they use PROJECT_STAGES only
         TYPED_STAGES = [].freeze
 
@@ -29,14 +45,15 @@ module Pubid
         end
 
         # A working document prints its committee, number, language and stage —
-        # `1/2457(F)/FDIS` — and none of those is the `number` the shared token
-        # table looks for, so it had no annotatable token. `wd_stage` is the
-        # printed stage token ("FDIS"); the derived `#stage` reader covers only
-        # the PWI/PNW work-programme form and is nil here.
+        # `1/2457(F)/FDIS` — and the document number is the inherited
+        # `number` (issue #687: it used to sit in a parallel `wd_number`
+        # attribute that nothing serialized). `wd_stage` is the printed stage
+        # token ("FDIS"); the derived `#stage` reader covers only the PWI/PNW
+        # work-programme form and is nil here.
         def annotation_tokens
           super + [
             [:technical_committee, "docnumber"],
-            [:wd_number, "docnumber"],
+            [:number, "docnumber"],
             [:wd_language, "language"],
             [:wd_stage, "stage"],
             [:wp_stage, "stage"],

data/lib/pubid/iec/pubid_urn_schema.rb

@@ -16,13 +16,15 @@ module Pubid
     # published URNs are unchanged. `database` was a string atom before any
     # URN carried it — the corpus holds only `true`, so it is a bool.
     #
-    # Known identity gaps the URN inherits, because it carries exactly what
-    # to_hash carries (pinned in lib/pubid/iec/CLAUDE.md): a WorkingDocument
-    # serializes only `_type`, and a TestReportForm's CISPR document sits in
-    # the unserialized `cispr_identifier` — such rows emit type-only URNs
-    # (`urn:pubid:iec:wd`) and are one hash, so they are not a collision.
-    # Mapping them is a wire-format change and stays the separate decision
-    # it already was. The official RFC 5141-style urn:iec:std: form stays
+    # The identity gaps this schema used to inherit are closed (issue #687):
+    # the working document's committee/number/language/stage and work-programme
+    # stage/type serialize (`tc-`, `wdlang-`, `wdstage-`, `wpstage-`,
+    # `wptype-`, with the document number in the positional core), and a
+    # TestReportForm's CISPR document rides `cispr-` as a nested id — so a
+    # working document URNs per document instead of the shared type-only
+    # `urn:pubid:iec:wd` it used to be. The new atoms sit after `vap-` and
+    # before `lang-`, per the invariant below, so every landed URN encodes
+    # identically. The official RFC 5141-style urn:iec:std: form stays
     # on #to_urn.
     PubidUrnSchema = Pubid::PubidUrn.define("iec") do
       atom "publisher", "pub"
@@ -41,6 +43,12 @@ module Pubid
       atom "sheet_number", "sheet"
       atom "sheet_year", "sheetyear"
       atom "vap", "vap", kind: :list
+      atom "technical_committee", "tc"
+      atom "wd_language", "wdlang"
+      atom "wd_stage", "wdstage"
+      atom "wp_stage", "wpstage"
+      atom "wp_type", "wptype"
+      atom "cispr_identifier", "cispr", kind: :id
       atom "languages.*.code", "lang"
       atom "identifiers", "ids", kind: :ids
 

data/lib/pubid/iec/renderer.rb

@@ -208,8 +208,10 @@ module Pubid
           # International Standard, so rendering would not be a fixed point.
           parts = []
           parts << id.wp_stage
-          if id.wp_type && !id.wp_type.strip.empty?
-            parts << " #{id.wp_type.strip}"
+          if id.wp_type && !id.wp_type.empty?
+            # wp_type is stripped at the construction site (Builder#cast),
+            # so the stored value is what renders.
+            parts << " #{id.wp_type}"
           end
 
           if id.number
@@ -226,8 +228,10 @@ module Pubid
         parts = []
         parts << id.technical_committee if id.technical_committee
 
-        if id.wd_number
-          num_part = id.wd_number.to_s
+        # The working document's own number is the inherited `number`
+        # (issue #687).
+        if id.number
+          num_part = id.number.to_s
           num_part += "(#{id.wd_language})" if id.wd_language
           parts << num_part
         end

data/lib/pubid/iec/single_identifier.rb

@@ -22,15 +22,80 @@ module Pubid
       # their own (Identifiers::Base and SupplementIdentifier).
       #
       # That is a structural exclusion, not a denylist of no-op converters that
-      # a later key can be forgotten from — which is how `month`/`day` came to
-      # leak (see DelegatedFieldSuppression).
+      # a later key can be forgotten from. The date keys live here for the
+      # same reason: the wrappers delegate `date` too, and when the date maps
+      # sat on Iec::Identifier the denylist no-opped `year` but not
+      # `month`/`day`/`undated`, so `IEC CA 01:2025-10 CSV` emitted a second,
+      # top-level "month" beside the one inside "base".
       #
-      # The values are plain strings, so no converter is needed: lutaml writes
-      # the scalar, and ::Pubid::Identifier#to_hash drops a nil.
+      # number/part/subpart are plain strings, so no converter is needed:
+      # lutaml writes the scalar, and ::Pubid::Identifier#to_hash drops a nil.
+      # The date keys keep converters, because they split one `date`
+      # attribute across four keys.
       key_value do
         map "number", to: :number
         map "part", to: :part
         map "subpart", to: :subpart
+        # date serialized flat as year/month/day, nils omitted.
+        map "year", with: { to: :year_to_kv, from: :year_from_kv }
+        map "month", with: { to: :month_to_kv, from: :month_from_kv }
+        map "day", with: { to: :day_to_kv, from: :day_from_kv }
+        # IEC undated reference (e.g. IEC 60050:--). The `false` default is
+        # omitted; only the meaningful `true` round-trips via to_hash.
+        map "undated", with: { to: :undated_to_kv, from: :undated_from_kv }
+      end
+
+      # --- date serialized flat as year/month/day ---
+      def year_to_kv(model, doc)
+        y = model.date&.year
+        return if y.nil? || y.to_s.empty?
+
+        doc.add_child(Lutaml::KeyValue::DataModel::Element.new("year", y.to_s))
+      end
+
+      def year_from_kv(model, value)
+        return if value.nil? || value.to_s.empty?
+
+        (model.date ||= ::Pubid::Components::Date.new).year = value.to_s
+      end
+
+      def month_to_kv(model, doc)
+        m = model.date&.month
+        return if m.nil? || m.to_s.empty?
+
+        doc.add_child(Lutaml::KeyValue::DataModel::Element.new("month", m.to_s))
+      end
+
+      def month_from_kv(model, value)
+        return if value.nil? || value.to_s.empty?
+
+        (model.date ||= ::Pubid::Components::Date.new).month = value.to_s
+      end
+
+      def day_to_kv(model, doc)
+        d = model.date&.day
+        return if d.nil? || d.to_s.empty?
+
+        doc.add_child(Lutaml::KeyValue::DataModel::Element.new("day", d.to_s))
+      end
+
+      def day_from_kv(model, value)
+        return if value.nil? || value.to_s.empty?
+
+        (model.date ||= ::Pubid::Components::Date.new).day = value.to_s
+      end
+
+      # --- date undated flag (IEC undated reference, e.g. IEC 60050:--) ---
+      # The `false` default is omitted; only the meaningful `true` round-trips
+      # via to_hash / from_hash.
+      def undated_to_kv(model, doc)
+        return unless model.date&.undated?
+
+        doc.add_child(Lutaml::KeyValue::DataModel::Element.new("undated", true))
+      end
+
+      def undated_from_kv(model, value)
+        (model.date ||= ::Pubid::Components::Date.new).undated = value.to_s == "true"
       end
 
       # Generate URN for this identifier

data/lib/pubid/iec/supplement_identifier.rb

@@ -33,26 +33,11 @@ module Pubid
       def base_from_kv(model, value)
         return unless value
 
-        base = ::Pubid::Iec::Identifier.from_hash(value)
-        model.base = base
-
-        # A base of the exact SingleIdentifier class is the synthetic self-base
-        # of a standalone supplement ("IEC/FDAM 60038-1"); a real attached base
-        # is always a concrete type (InternationalStandard, etc.). Re-engage the
-        # synthetic-base state so the supplement renders in standalone form
-        # (publisher/TYPE base-number-supp-number) instead of attached form.
-        if base.instance_of?(::Pubid::Iec::SingleIdentifier)
-          model.mark_synthetic_standalone!
-        end
-      end
-
-      # Re-engage the standalone synthetic-base state on a deserialized
-      # supplement. At this point `number` already holds the supplement number
-      # (set from the "number" key before "base"), so preserve it as the
-      # supplement number and flag the synthetic base.
-      def mark_synthetic_standalone!
-        @synthetic_base = true
-        @supplement_number = @number
+        # A bare SingleIdentifier here is the synthetic base of a standalone
+        # supplement; #synthetic_base? reads that class, so nothing else needs
+        # restoring. "number" already holds the supplement number, which is
+        # what ensure_base stores on the parse path too.
+        model.base = ::Pubid::Iec::Identifier.from_hash(value)
       end
 
       # Override base getter to ensure it's always created for standalone supplements
@@ -60,29 +45,21 @@ module Pubid
         @base || ensure_base
       end
 
-      # Override number getter to trigger swap for standalone supplements
+      # A standalone supplement holds the grammar's layout (base number in
+      # `number`, supplement number in `part`) until #ensure_base moves it.
+      # Not every construction path goes through one builder branch ("IEC FDAM
+      # 60038-1" does not, nor a hand-built Amendment), so these readers make
+      # the move before they answer: the result never depends on which reader
+      # ran first, and #exclude, which copies through the readers, copies the
+      # moved layout. They only TRIGGER the move; they return the stored value.
       def number
-        # Guard against recursion in ensure_base
-        return @number if @ensuring_base
-
-        # For standalone supplements, trigger base creation first
-        ensure_base if @synthetic_base.nil? && publisher && part
-
-        if @synthetic_base
-          @supplement_number || @number
-        else
-          super
-        end
+        settle_standalone_layout
+        super
       end
 
-      # Override part getter for standalone supplements (part becomes nil after swap)
       def part
-        # For standalone supplements with synthetic base, part is nil (moved to number)
-        if @synthetic_base
-          nil
-        else
-          super
-        end
+        settle_standalone_layout
+        super
       end
 
       # Delegate publisher and copublishers to base whenever there is
@@ -102,59 +79,52 @@ module Pubid
         base ? base.copublishers : @copublishers
       end
 
-      # Ensure we have a base for standalone supplements
-      # Creates a synthetic base identifier from supplement attributes if needed
-      # Returns the base
+      # Synthesise the base of a supplement that names none, and return it.
+      #
+      # A standalone supplement ("IEC/FDAM 60038-1") arrives from the grammar
+      # with the BASE number in `number` and the SUPPLEMENT number in `part`.
+      # This moves the base number onto a bare SingleIdentifier base and stores
+      # the supplement number in `number`, so the attributes hold what they
+      # mean — the layout `from_hash` rebuilds from the serialized hash. A
+      # supplement with no part (a bare "+AMD1:2008" in a consolidation,
+      # "IEC/AMD 1:2017") gets a self-base whose number equals its own; its
+      # `number` is left as it is.
+      #
+      # The base deliberately gets NO typed_stage. A stage without a code is
+      # not serialized, so `from_hash` cannot restore one, and a stage set
+      # here alone made `parse != from_hash(to_hash)` — `==` compares `base`
+      # (`lib/pubid/iec/CLAUDE.md`).
       def ensure_base
         return @base if @base
 
-        # Guard flag to prevent recursion in number getter
+        # publisher/copublishers read through `base`; this guard makes them
+        # read the supplement's own value while the base is being built.
         @ensuring_base = true
+        return nil unless publisher && (@number || @part)
 
-        # For standalone supplements like "IEC/FDAM 60038-1"
-        # The supplement number is in the `part` attribute, while `number` is the base number
-        # We need to create a synthetic base and use part as the supplement number
-        return nil unless publisher && (number || part)
-
-        # Capture original values BEFORE marking as synthetic
-        # (otherwise our getters will return swapped values)
-        base_number = number
-        supplement_number = part
-
-        # NOW mark that this is a synthetic base (after capturing values)
-        @synthetic_base = true
-
-        # Use SingleIdentifier which has typed_stage attribute
         base = SingleIdentifier.new
         base.publisher = publisher
-        base.number = base_number if base_number
-        base.part = nil # Base doesn't have part - part is the supplement number
-        base.subpart = subpart if subpart
+        base.number = @number if @number
+        base.subpart = @subpart if @subpart
         base.date = date if date
 
-        # Create typed_stage for the base - use "IS" (International Standard) type
-        # not the supplement type
-        base.typed_stage = Pubid::Components::TypedStage.new(
-          abbr: ["IS"],
-          type_code: :is,
-          stage_code: :undated,
-        )
+        if @part
+          @number = @part
+          @part = nil
+        end
 
         @base = base
-
-        # Store the supplement number for getter override
-        # The original number is the base number (moved to base)
-        # The original part is the supplement number (what we want to return)
-        @supplement_number = supplement_number
-
-        @base
       ensure
         @ensuring_base = false
       end
 
-      # Check if this supplement has a synthetic base (created for standalone format)
+      # True when the base is the bare SingleIdentifier that #ensure_base (or
+      # from_hash) synthesised for a standalone supplement; a real attached
+      # base is always a concrete type (InternationalStandard, SheetIdentifier
+      # …). Read from the base itself, so it survives #exclude, which copies
+      # `base` into a new object.
       def synthetic_base?
-        @synthetic_base ||= false
+        base.instance_of?(::Pubid::Iec::SingleIdentifier)
       end
 
       def to_s(**opts)
@@ -173,6 +143,12 @@ module Pubid
 
         segments.join(".")
       end
+
+      private
+
+      def settle_standalone_layout
+        ensure_base if @base.nil? && @part && !@ensuring_base
+      end
     end
   end
 end

data/lib/pubid/iho/CLAUDE.md

@@ -96,6 +96,58 @@ The compact face (`compact: true`) folds the code-adjacent components
 onto the code: supplement and part hyphenated, volume as the slash
 chain — `IHO M-2-2`, `IHO S-100-2 5.0.0`, `IHO P-5/2024`.
 
+## S-4 loose-leaf sections and specs (owner rulings, 2026-11-11)
+
+The S-4 loose-leaf publication (Parts A/B/C → Sections 100-600, Part C
+100-500 → Regulations/Specifications cited `<letter>-<hundreds><seq>`)
+is modeled ONE COMPONENT DEEP, not two tiers: the spec number IS the
+leaf. `B-401` binds the letter into `part` ("B") and the number into
+`spec` ("401"); the SECTION (the hundreds digit) is DERIVED —
+`#spec_section` (`B-401` → `"400"`) — never stored, never emitted, and
+the `00` slot (B-400) IS the section-level citation, so `S-4 Part B,
+Section 400` ≡ `IHO S-4 B-400` (one identity, two spellings).
+
+| component    | attribute    | canonical face      | parse-only forms                    |
+|--------------|--------------|---------------------|-------------------------------------|
+| spec         | `spec`       | `B-401` (with part) | the spelled section (", Section 400") |
+| spec sub     | `spec_sub`   | `.1`                | —                                   |
+| spec variant | `spec_variant` | `(I)`             | —                                   |
+
+- **Faces**: canonical compact `IHO S-4 B-401` (dated:
+  `IHO S-4 4.10.0 B-401` — the edition precedes the citation, as it
+  precedes the part). The citation face REPLACES the Part face in the
+  renderer (`compact: true` is a no-op on it — it is already compact).
+  Subs and variants combine (`B-351.1(I)` is in the 4.9.0 text).
+- **Three forms parse to one identity**: the anchored citation, the
+  LONG form `S-4 Part B, Section 400[, B-401]` (normalizing parse; the
+  spelled section becomes `spec` alone, and beside a citation it only
+  cross-checks the citation's derived section — "Section 500, B-401"
+  raises) and the BARE `B-401` (implicit S-4 anchor; B only — bare
+  C-x stays the Circular Letter series, and the 3-digit `[1-6]xx`
+  shape keeps the B Bibliographic series (B-12) on the main branch).
+  `IHO B-401` (publisher + bare) parses to the spec too.
+- **The anchor is load-bearing**: a spec citation requires the S-4
+  anchor (series S number 4 — the builder raises otherwise), a
+  lettered Part (A/B/C, not a numbered part), and no component
+  editions or S-4-foreign components (supplement/annex/appendix/
+  volume/issue); the citation letter must agree with a Part-rule
+  capture.
+- **Reserved numbers** (`B-170`, `B-230`, `B-305`, `B-323` — "NOT
+  CURRENTLY USED" in the Ed 4.9.0 and 4.10.0 contents) parse and
+  resolve AS RESERVED, never invalid: `#reserved?` answers from
+  `data/iho/s4-reserved-specs.yaml` (edition-keyed, provenance in the
+  file; an edition-less reference is reserved when ANY seeded edition
+  reserves the number). `lib/pubid/iho/reserved_specs.rb` is the
+  loader (`Pubid::Iho::ReservedSpecs`).
+- **URN atoms**: the citation is a child of its part — the letter rides
+  the existing `part-` atom (case preserved: `part-B`, never the
+  lowercase `part-b` sketch), then `spec-`, `specsub-`, `specvar-`
+  (the `appsub-` naming convention; the `:sub-1`/`:variant-i` in the
+  ruling's sketch are these atoms). `urn:iho:s:4:ed-4.10.0:part-B:
+  spec-401`; the section is not emitted. No `ed-`/`year-` after a
+  spec node (UrnParseError — the spec rides its publication's
+  edition); `specsub-`/`specvar-` only after `spec-`.
+
 ## Identity semantics
 
 - The components are identity-bearing in `==`/`matches?`; a bare