pubid 2.0.20 → 2.0.22

data/lib/pubid/iec/supplement_identifier.rb

@@ -4,6 +4,11 @@ module Pubid
   module Iec
     # Identifier that represents a supplement to a base identifier.
     class SupplementIdentifier < SingleIdentifier
+      # The supplement number a legacy standalone face implies when its
+      # type token carries none ("IEC/DCOR 60038-1" is Corrigendum 1 of
+      # 60038-1); the owner's no-number rule.
+      LEGACY_STANDALONE_SUPPLEMENT_NUMBER = "1"
+
       attribute :base, Identifier, polymorphic: true
 
       # Serialize the supplemented document under "base". The supplement's own
@@ -22,8 +27,9 @@ module Pubid
         # (e.g. a bare "+AMD1:2008" nested in a consolidation): a fake doc whose
         # number equals the supplement's own. It renders nothing and the getter
         # recreates it identically on load, so don't persist it. A standalone
-        # supplement ("IEC/FDAM 60038-1") instead moves the real base number into
-        # the synthetic base (base.number != own number), which must be kept.
+        # supplement in the legacy prefix face ("IEC/DCOR 60038-1") instead
+        # holds the real base designation (base.number != own number), which
+        # must be kept.
         return if model.synthetic_base? && base.number.to_s == model.number.to_s
 
         doc.add_child(Lutaml::KeyValue::DataModel::Element.new("base",
@@ -33,26 +39,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 +51,22 @@ module Pubid
         @base || ensure_base
       end
 
-      # Override number getter to trigger swap for standalone supplements
+      # A standalone supplement written in the legacy prefix face holds the
+      # grammar's layout (the whole base designation on itself) until
+      # #ensure_base moves it. Not every construction path goes through one
+      # builder branch ("IEC DCOR 60038-1" reaches the typed branch, a
+      # hand-built Amendment none), 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 +86,75 @@ 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 written in the legacy prefix face ("IEC/DCOR
+      # 60038-1", "IEC/DISH 60038-1") arrives from the grammar with the BASE
+      # designation stored on itself — the base number in `number`, the base
+      # part (and subpart) in `part`/`subpart`. That layout is the grammar's
+      # bound shape, not the identity: the face names a supplement OF that
+      # designation, so the designation moves WHOLE onto a concrete
+      # InternationalStandard base (publisher, copublishers and the date go
+      # with it — old notation prints the base's year, and a draft
+      # supplement carries no publication date of its own) and the
+      # supplement keeps a number of its own, defaulting to 1 — the
+      # no-number rule (an unnumbered draft face means
+      # Amendment/Corrigendum/Interpretation-Sheet 1; owner ruling
+      # 2026-11-12, reversing #693's part-to-number move, which stole the
+      # base's part for the supplement). The concrete base is what makes the
+      # decode hash-match (and equal) the modern on-base parse of the same
+      # document: `parse("IEC/DCOR 60038-1") == parse("IEC 60038-1/DCOR1")`.
+      #
+      # A supplement with no part (a true standalone like "IEC/AMD 1:2017",
+      # or a bare "+AMD1:2008" in a consolidation) keeps its own number and
+      # gets a synthetic self-base whose number equals it; its date stays
+      # its own.
+      #
+      # 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
-
-        # 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.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,
-        )
+        return nil unless publisher && (@number || @part)
+
+        if @part
+          base = Identifiers::InternationalStandard.new
+          base.publisher = publisher
+          base.copublishers = copublishers if copublishers&.any?
+          base.number = @number
+          base.part = @part
+          base.subpart = @subpart if @subpart
+          base.date = date if date
+          @number = LEGACY_STANDALONE_SUPPLEMENT_NUMBER
+          @part = nil
+          @date = nil
+        else
+          base = SingleIdentifier.new
+          base.publisher = publisher
+          base.number = @number if @number
+          base.date = date if date
+        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. A legacy prefix face's designation moves
+      # onto a CONCRETE InternationalStandard instead (see #ensure_base), so
+      # it renders in the attached, modern form and hash-matches the modern
+      # on-base parse of the same document.
       def synthetic_base?
-        @synthetic_base ||= false
+        base.instance_of?(::Pubid::Iec::SingleIdentifier)
       end
 
       def to_s(**opts)
@@ -173,6 +173,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
@@ -182,4 +234,5 @@ component with its own edition/year right after it (`sup-`, `part-`,
 `parted-`, `appendix-`, `appsub-`, `vol-`, `issue-` …). Case is preserved
 (`part-A`); the yearbook year is a volume (`vol-2024`, no `year-` value —
 the legacy `y.` marker stays decodable in the official URN parser, never
-emitted). The official `urn:mrn:iho:…` form stays on `#to_urn`.
+emitted). The positional `urn:iho:` form of `UrnGenerator` stays on
+`#to_urn` — pubid emits no `urn:mrn:iho:…` URN.

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,12 @@ 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 positional urn:iho:… form of UrnGenerator
+    # stays on #to_urn — pubid emits no urn:mrn:iho:… URN.
     PubidUrnSchema = Pubid::PubidUrn.define("iho") do
       atom "edition", "ed"
       atom "year", "year"
@@ -26,6 +28,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

data/lib/pubid/iho/reserved_specs.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Pubid
+  module Iho
+    # The S-4 reserved specification registry
+    # (data/iho/s4-reserved-specs.yaml): the "NOT CURRENTLY USED"
+    # numbers, edition-keyed (owner rulings of 2026-11-11, issue #691).
+    # {Reserved?} answers from this table — a reserved number parses and
+    # resolves AS RESERVED, never invalid.
+    module ReservedSpecs
+      DATA_PATH =
+        File.expand_path("../../../data/iho/s4-reserved-specs.yaml", __dir__)
+
+      class << self
+        # True when the part-lettered spec number is reserved in the
+        # given S-4 edition. An edition-less reference is reserved when
+        # ANY seeded edition reserves the number: the number is out of
+        # circulation in every edition that names it.
+        def reserved?(edition, part, spec)
+          return false unless part && spec
+
+          if edition
+            specs_for(edition, part).include?(spec)
+          else
+            registry.values.any? do |parts|
+              specs_for_parts(parts, part).include?(spec)
+            end
+          end
+        end
+
+        # The edition-keyed registry: edition => part letter => spec
+        # numbers.
+        def registry
+          @registry ||=
+            (YAML.safe_load_file(DATA_PATH) || {}).transform_values do |parts|
+              parts.transform_values { |specs| Array(specs) }
+            end
+        end
+
+        private
+
+        def specs_for(edition, part)
+          specs_for_parts(registry.fetch(edition, {}), part)
+        end
+
+        def specs_for_parts(parts, part)
+          parts.fetch(part, [])
+        end
+      end
+    end
+  end
+end