pubid 2.0.20 → 2.0.21

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

data/lib/pubid/iho/builder.rb

@@ -18,18 +18,34 @@ module Pubid
                       part_edition part_year supplement_edition
                       supplement_year annex_edition annex_year
                       appendix_edition appendix_year volume_edition
-                      volume_year].freeze
+                      volume_year
+                      spec spec_sub spec_variant spec_part
+                      spec_section].freeze
       # The independently-publishable components' own editions; the
       # base edition context is mutually exclusive with them (owner
       # ruling on the two publication modes).
       COMPONENT_EDITIONS = %i[part_edition supplement_edition annex_edition
                               appendix_edition volume_edition].freeze
+      # The S-4 anchor: the loose-leaf publication every spec citation
+      # resolves through (bare "B-401" carries it implicitly).
+      S4_TYPE = "S"
+      S4_NUMBER = "4"
+      # A citation letter is one of S-4's lettered Parts; the section
+      # vocabulary (100-600, Part C 100-500) is theirs.
+      SPEC_LETTERS = %w[A B C].freeze
+      # Components an S-4 spec citation cannot carry: the citation is a
+      # leaf of the Part, not a wrappable publication.
+      SPEC_FOREIGN_COMPONENTS = %i[supplement annex appendix
+                                   appendix_subnumber volume issue].freeze
 
       def build(parsed)
         hash = parsed.is_a?(Array) ? parsed.reduce({}, :merge) : parsed
         attrs = stringified_attrs(hash)
+        resolve_spec_citation!(attrs)
+        type = type_letter_from(hash, attrs)
+        assert_spec_anchor!(attrs, type)
         assert_edition_mode!(attrs)
-        klass = Pubid::Iho.identifier_klass_for_type_letter(stringify(hash[:type]))
+        klass = Pubid::Iho.identifier_klass_for_type_letter(type)
         klass.new(**attrs)
       end
 
@@ -39,6 +55,93 @@ module Pubid
 
       private
 
+      # The citation captures resolve onto the model (see the grammar
+      # header): the citation letter folds into `part` (a Part-rule
+      # capture must agree), and the long form's spelled section becomes
+      # the spec alone — beside a citation it only cross-checks the
+      # citation's derived section ("Part B, Section 400, B-401" stores
+      # spec 401; "Part B, Section 500, B-401" is rejected).
+      def resolve_spec_citation!(attrs)
+        letter = attrs.delete(:spec_part)
+        spelled = attrs.delete(:spec_section)
+        attrs[:part] = merge_citation_letter!(attrs[:part], letter) if letter
+        apply_spelled_section!(attrs, spelled)
+        assert_citation_shape!(attrs) if attrs[:spec]
+      end
+
+      def apply_spelled_section!(attrs, spelled)
+        return if spelled.nil?
+        return attrs[:spec] = spelled unless attrs[:spec]
+
+        return if spelled == spec_section_of(attrs[:spec])
+
+        raise ArgumentError,
+              "the spelled section #{spelled} disagrees with the " \
+              "citation #{attrs[:part]}-#{attrs[:spec]}"
+      end
+
+      def spec_section_of(spec)
+        "#{spec[0]}00"
+      end
+
+      def merge_citation_letter!(part, letter)
+        return letter if part.nil? || part == letter
+
+        raise ArgumentError,
+              "the citation letter #{letter} conflicts with part #{part}"
+      end
+
+      def assert_citation_shape!(attrs)
+        assert_citation_letter!(attrs)
+        assert_citation_leaf!(attrs)
+      end
+
+      def assert_citation_letter!(attrs)
+        return if SPEC_LETTERS.include?(attrs[:part])
+
+        raise ArgumentError,
+              "an S-4 spec citation needs a lettered Part (A/B/C), " \
+              "not #{attrs[:part].inspect}"
+      end
+
+      # The citation is a leaf of its Part: it carries no component
+      # edition and none of the wrappable components.
+      def assert_citation_leaf!(attrs)
+        if attrs[:part_edition] || attrs[:part_year]
+          raise ArgumentError,
+                "a spec citation rides the S-4 edition, not a part edition"
+        end
+
+        foreign = attrs.slice(*SPEC_FOREIGN_COMPONENTS).compact.keys
+        return if foreign.empty?
+
+        raise ArgumentError,
+              "an S-4 spec citation is a leaf of its Part and cannot " \
+              "carry #{foreign.join(', ')}"
+      end
+
+      # The series letter: a bare citation branch parse has no series
+      # capture, and its anchor is implicitly the S-4 publication (the
+      # number binds with it).
+      def type_letter_from(hash, attrs)
+        type = stringify(hash[:type])
+        return type if type
+
+        raise ArgumentError, "unknown IHO series" unless attrs[:spec]
+
+        attrs[:number] = S4_NUMBER
+        S4_TYPE
+      end
+
+      def assert_spec_anchor!(attrs, type)
+        return unless attrs[:spec]
+        return if type == S4_TYPE && attrs[:number] == S4_NUMBER
+
+        raise ArgumentError,
+              "an S-4 spec citation requires the S-4 anchor: " \
+              "#{type}-#{attrs[:number]} cannot carry spec #{attrs[:spec]}"
+      end
+
       # The two publication modes are mutually exclusive: an identifier
       # is either within-edition (a base edition its components ride) or
       # separately-published (a component carries its own edition and

data/lib/pubid/iho/identifiers/base.rb

@@ -8,6 +8,11 @@ module Pubid
     # IHO identifiers have the form:
     #   IHO {S|P|M|B|C}-{number}[ {edition}| Vol. N [(issue)]]
     #       [ Sup N][ Part X][ Annex A][ Appendix B[-2]] [(2024)]
+    # The S-4 loose-leaf publication adds the spec citation
+    #   IHO S-4 [edition] <letter>-<hundreds><seq>[.sub][(variant)]
+    # ("IHO S-4 B-401", the long form "S-4 Part B, Section 400" and the
+    # bare "B-401" all parse to it; `spec` stores the leaf number, the
+    # citation letter rides `part`, the section is a derived reader).
     #
     # Every tail component is a first-class semantic component: a typed
     # attribute, independently addressable, URN-encodable and matchable.
@@ -83,6 +88,15 @@ module Pubid
       attribute :issue,      :string
       attribute :volume_edition, :string
       attribute :volume_year,    :string
+      # The S-4 loose-leaf spec citation (issue #691): `spec` is the leaf
+      # number ("401" of B-401), the citation letter rides `part` (the
+      # builder folds it in), the dotted sub and the parenthesized
+      # variant keep their own components. The SECTION (the hundreds
+      # digit) is never stored — a derived reader — and the `00` slot
+      # (B-400) IS the section-level citation.
+      attribute :spec,         :string
+      attribute :spec_sub,     :string
+      attribute :spec_variant, :string
 
       # Polymorphic type map for lutaml::Model key_value serialization: maps
       # each subclass's polymorphic_name to its class name so `from_hash` can
@@ -122,6 +136,9 @@ module Pubid
         map "volume_edition",     to: :volume_edition
         map "volume_year",        to: :volume_year
         map "issue",              to: :issue
+        map "spec",               to: :spec
+        map "spec_sub",           to: :spec_sub
+        map "spec_variant",       to: :spec_variant
       end
 
       # from_hash is the shared polymorphic dispatch on Pubid::Identifier.
@@ -139,9 +156,40 @@ module Pubid
         args = args.dup
         args << :issue if args.include?(:volume)
         args << :appendix_subnumber if args.include?(:appendix)
+        # The spec citation is the leaf: a reference that omits the spec
+        # nils its sub and variant with it.
+        args.push(:spec_sub, :spec_variant) if args.include?(:spec)
         super
       end
 
+      # The citation letter of an S-4 spec (nil unless the identifier IS
+      # a spec citation): the part carries the letter, the same way the
+      # long form spells it ("Part B" of "B-401").
+      def spec_part
+        spec && part
+      end
+
+      # The section an S-4 spec belongs to: the hundreds digit of the
+      # spec number, zero-padded (B-401 -> "400"; B-400 derives its own
+      # section). DERIVED, never stored, never emitted — the owner
+      # ruling keeps the spec number the leaf.
+      def spec_section
+        return nil unless spec
+
+        "#{spec[0]}00"
+      end
+
+      # True when the spec number is reserved ("NOT CURRENTLY USED") in
+      # the edition's S-4 contents (data/iho/s4-reserved-specs.yaml). An
+      # edition-less reference is reserved when any seeded edition
+      # reserves the number. A reserved citation parses and resolves AS
+      # RESERVED, never invalid (issue #691).
+      def reserved?
+        return false unless spec
+
+        ReservedSpecs.reserved?(edition, part, spec)
+      end
+
       # Render the compact face: the code-adjacent components folded onto
       # the code with separators — the supplement and the part hyphenated
       # (`IHO M-2-2` for `IHO M-2 Sup 2`, `IHO S-5-B` for `IHO S-5 Part B`,
@@ -153,7 +201,10 @@ module Pubid
       def render(format: :human, **opts)
         compact = opts.delete(:compact)
         result = super
-        compact && format == :human ? compact_face(result) : result
+        # A spec citation's canonical face IS the compact form (the
+        # citation is already folded onto the code: "IHO S-4 B-401"), so
+        # the compact flag is a no-op for it.
+        compact && format == :human && !spec ? compact_face(result) : result
       end
 
       # The shared mr_string path reads `edition&.number` (the base

data/lib/pubid/iho/pubid_urn_schema.rb

@@ -13,10 +13,11 @@ module Pubid
     # edition/year right after it — supplement, part, annex, appendix (the
     # two-level Appendix D-2 keeps the subnumber as its own atom), volume
     # (the unified locator, yearbook volumes included: `vol-2024`), issue.
-    # Letters stay case-preserved (`part-A`). The legacy `y.` yearbook
-    # marker is decodable in the official URN parser, never emitted here:
-    # a periodical has no `year-` atom value, its volume carries the year.
-    # The official urn:mrn:iho:… form stays on #to_urn.
+    # The S-4 spec citation sits inside its part (`spec-`, `specsub-`,
+    # `specvar-`). Letters stay case-preserved (`part-A`). The legacy
+    # `y.` yearbook marker is decodable in the official URN parser, never
+    # emitted here: a periodical has no `year-` atom value, its volume
+    # carries the year. The official urn:mrn:iho:… form stays on #to_urn.
     PubidUrnSchema = Pubid::PubidUrn.define("iho") do
       atom "edition", "ed"
       atom "year", "year"
@@ -26,6 +27,12 @@ module Pubid
       atom "part", "part"
       atom "part_edition", "parted"
       atom "part_year", "party"
+      # The S-4 loose-leaf spec citation (issue #691): a child of the
+      # part (the citation letter rides `part-`); the section is
+      # derivable from the spec's hundreds digit — never an atom.
+      atom "spec", "spec"
+      atom "spec_sub", "specsub"
+      atom "spec_variant", "specvar"
       atom "annex", "annex"
       atom "annex_edition", "anned"
       atom "annex_year", "annyear"

data/lib/pubid/iho/renderer.rb

@@ -19,6 +19,13 @@ module Pubid
     #                                   beside an edition is the date
     #                                   qualifier on standards,
     #                                   parenthesized — the only year face
+    #   "IHO S-4 B-401"                 the S-4 spec citation (the long
+    #                                   form "S-4 Part B, Section 400"
+    #                                   parses to the same identity and
+    #                                   renders compact: the citation
+    #                                   replaces the Part face; the
+    #                                   section is derivable, never
+    #                                   printed)
     #
     # The renderer is registered as the `:human` format in the IHO format
     # registry and invoked via `render(format: :human)`; the compact face
@@ -32,12 +39,17 @@ module Pubid
       # edition (+ parenthesized year) right after it; the appendix joins
       # its subnumber; the issue rides parenthesized after its volume;
       # the base year prints only as the parenthesized with-year
-      # qualifier.
+      # qualifier. The S-4 spec citation face (" B-401") sits where the
+      # Part face sits — it REPLACES the Part face when a spec is
+      # present (the citation letter is the part), printing
+      # "<letter>-<number>" with the dotted sub and the parenthesized
+      # variant folded on.
       FACES = [
         [:edition, " %s"],
         [:supplement, " Sup %s"], [:supplement_edition, " %s"],
         [:supplement_year, " (%s)"],
         [:part, " Part %s"], [:part_edition, " %s"], [:part_year, " (%s)"],
+        [:spec, " %s"],
         [:annex, " Annex %s"], [:annex_edition, " %s"], [:annex_year, " (%s)"],
         [:appendix, " Appendix %s"], [:appendix_subnumber, "-%s"],
         [:appendix_edition, " %s"], [:appendix_year, " (%s)"],
@@ -50,11 +62,36 @@ module Pubid
         id = @id
         rendered = "#{id.publisher} #{id.class.type[:short]}-#{id.number}"
         FACES.each do |component, face|
-          value = id.public_send(component)
+          value = face_value(id, component)
           rendered << (face % value) if value
         end
         rendered
       end
+
+      private
+
+      # nil = the face does not print. The citation face replaces the
+      # Part face (same containment slot: the citation letter IS the
+      # part), and it prints only on a spec citation.
+      def face_value(id, component)
+        if component == :spec
+          return nil unless id.spec
+
+          return spec_citation(id)
+        end
+        return nil if component == :part && id.spec
+
+        id.public_send(component)
+      end
+
+      # "B-401", "B-122.1", "B-521(I)", "B-351.1(I)" — the citation the
+      # S-4 contents and cross-references print.
+      def spec_citation(id)
+        citation = "#{id.part}-#{id.spec}"
+        citation << ".#{id.spec_sub}" if id.spec_sub
+        citation << "(#{id.spec_variant})" if id.spec_variant
+        citation
+      end
     end
   end
 end