pubid 2.0.0.pre.alpha.12 → 2.0.0.pre.alpha.14

data/lib/pubid/all_parts.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require "pubid"
+module Pubid
+  # Every part of one document, e.g. "ISO 9000 (all parts)".
+  #
+  # The class that includes this module holds part identifiers of one
+  # document in `identifiers`, in natural order and without duplicates. A
+  # member with no part stands for the whole document; it is permitted only
+  # as the sole member.
+  #
+  # A flavor includes it in a subclass of its own `Identifier`, so the
+  # all-parts identifier of a flavor is an identifier of that flavor
+  # (`Pubid::Iso::Identifiers::AllParts < Pubid::Iso::Identifier`). The
+  # subclass names its own suffix or URN; everything else comes from here.
+  # A flavor with no such class uses {Pubid::AllPartsIdentifier}.
+  #
+  # `==` compares the members. `===` compares the document only: the first
+  # member without its part and its edition (see #identity).
+  module AllParts
+    SUFFIX = " (all parts)"
+
+    # The members hold the whole identity, so the hash carries nothing else.
+    # Without the key_value block the serializer reads every inherited
+    # attribute, and the derived #number below would be written too.
+    def self.included(base)
+      base.attribute :identifiers, ::Pubid::Identifier, polymorphic: true,
+                                                        collection: true,
+                                                        initialize_empty: true
+      declare_key_value(base)
+      base.extend(ClassMethods)
+    end
+
+    # lutaml MERGES a subclass block onto the flavor's own block, so the
+    # derived #number below would be written as a top-level key. A no-op
+    # converter keeps it out.
+    def self.declare_key_value(base)
+      base.key_value do
+        map "_type", to: :_type
+        map "identifiers", to: :identifiers
+        map "number", with: { to: :number_to_kv, from: :number_from_kv }
+      end
+    end
+
+    module ClassMethods
+      # lutaml's from_hash builds the object with no attributes and assigns
+      # `identifiers` after #initialize, so it normalizes here too.
+      def from_hash(data, options = {})
+        super.tap do |id|
+          id.send(:normalize_identifiers!) if id.is_a?(::Pubid::AllParts)
+        end
+      end
+    end
+
+    def initialize(attrs = {}, options = {})
+      super
+      normalize_identifiers!
+    end
+
+    # The members hold the number, so it is neither written nor read.
+    def number_to_kv(_model, _doc); end
+
+    def number_from_kv(_model, _value); end
+
+    # @param other [Object] a candidate identifier
+    # @return [Boolean] true when +other+ is any part of the same document,
+    #   in any edition
+    def ===(other)
+      return false unless other.is_a?(::Pubid::Identifier) && identity
+
+      identity === document_of(other)
+    end
+
+    # Another all-parts identifier with +other+ added. The receiver does not
+    # change.
+    # @param other [Pubid::Identifier] a part of the same document, or
+    #   another all-parts identifier of it
+    # @return [Pubid::Identifier] an all-parts identifier of the same class
+    # @raise [ArgumentError] for a different document, an identifier with no
+    #   part, or a part that is already a member
+    def +(other)
+      members = other.is_a?(::Pubid::AllParts) ? other.identifiers : [other]
+      members.each { |member| validate_member!(member) }
+      self.class.new(identifiers: identifiers + members)
+    end
+
+    def to_s(**opts)
+      return "" unless identity
+
+      annotate_plain_render(
+        "#{identity.to_s(**opts.except(:annotated))}#{self.class::SUFFIX}",
+        **opts,
+      )
+    end
+
+    # The all-parts attributes are empty, so the flavor renderers cannot
+    # print it. Only the human form exists yet; `to_mr_string` and `to_slug`
+    # come through here and raise too.
+    def render(format: :human, **opts)
+      return to_s(**opts) if format == :human
+
+      raise NotImplementedError,
+            "an all-parts identifier has no #{format} form yet"
+    end
+
+    def to_urn
+      raise NotImplementedError, "an all-parts identifier has no URN yet"
+    end
+
+    def to_all_parts
+      self
+    end
+
+    def root
+      identifiers.first&.root
+    end
+
+    # The document number, e.g. "9000". The index keys on it.
+    def number
+      identity&.number
+    end
+
+    # True here and false for every other identifier, so a caller that reads
+    # the old flag still works.
+    # rubocop:disable Naming/PredicateMethod
+    def all_parts
+      true
+    end
+    # rubocop:enable Naming/PredicateMethod
+
+    def all_parts?
+      true
+    end
+
+    def base_document
+      identifiers.first&.base_document
+    end
+
+    protected
+
+    # The document: the first member without its part, its subpart and its
+    # edition. #document_of reads it from another all-parts identifier, so it
+    # is protected and not private.
+    # @return [Pubid::Identifier, nil]
+    def identity
+      first = identifiers.first
+      first && document_of(first)
+    end
+
+    private
+
+    # The document of +id+: +id+ without its part and its edition.
+    def document_of(id)
+      return id.identity if id.is_a?(::Pubid::AllParts)
+
+      id.without_parts(*id.class.all_parts_edition_keys)
+    end
+
+    def validate_member!(id)
+      unless id.is_a?(::Pubid::Identifier)
+        raise ArgumentError, "not an identifier: #{id.inspect}"
+      end
+
+      raise ArgumentError, "#{id} is not a part of #{self}" unless self === id
+      raise ArgumentError, "#{id} has no part" unless id.part?
+      return unless identifiers.any? { |member| same_member?(member, id) }
+
+      raise ArgumentError, "#{id} is already a member of #{self}"
+    end
+
+    def same_member?(one, other)
+      one.normalized_copy == other.normalized_copy
+    end
+
+    # Sort, remove duplicates, and drop the whole-document member when a
+    # part is present. `==` and `to_hash` depend on this order.
+    def normalize_identifiers!
+      members = unique_members
+      parts = members.select(&:part?)
+      self.identifiers = sorted(parts.empty? ? members : parts)
+    end
+
+    def unique_members
+      identifiers.each_with_object([]) do |member, acc|
+        acc << member unless acc.any? { |kept| same_member?(kept, member) }
+      end
+    end
+
+    # One member needs no sort, and #to_s raises on an abstract class.
+    def sorted(members)
+      return members if members.size < 2
+
+      members.sort_by { |member| natural_key(member.to_s) }
+    end
+
+    # "ISO 9000-10" sorts after "ISO 9000-2".
+    def natural_key(str)
+      str.split(/(\d+)/).map { |s| s.match?(/\A\d+\z/) ? [0, s.to_i] : [1, s] }
+    end
+  end
+end

data/lib/pubid/all_parts_identifier.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "pubid"
+module Pubid
+  # The all-parts identifier of a flavor that has no class of its own.
+  # A flavor that prints "(all parts)" or has a series URN gives its own
+  # class instead: see {Pubid::AllParts} and `Identifier.all_parts_class`.
+  class AllPartsIdentifier < Identifier
+    include AllParts
+
+    # This class belongs to no flavor, so its name carries no flavor segment
+    # and {TypeResolver} resolves it directly.
+    def self.polymorphic_name
+      return super unless self == ::Pubid::AllPartsIdentifier
+
+      "pubid:all-parts"
+    end
+  end
+end

data/lib/pubid/amca/CLAUDE.md

@@ -0,0 +1,47 @@
+# AMCA flavor notes
+
+AMCA index key and MR slug.
+
+These notes were part of the root `CLAUDE.md`. Read them before you change `lib/pubid/amca/` or `spec/pubid/amca/`. The root file keeps the cross-flavor contract that every flavor obeys.
+
+## From the root note "AMCA / ASME / ASTM index key (`root.number`): three flavors, three different shapes"
+
+**(1) AMCA — flat `:string` columns on the leaves, and a latent `==` bug fixed with them.** `code` is deleted and each of the three leaves declares `attribute :number, :string`. An earlier draft kept the inherited `Components::Code` instead (AMCA's own `Components::Code` resolved to `Pubid::Components::Code` — there is no `lib/pubid/amca/components/code.rb` — so nothing needed retyping, the CSA case); that works too, and the serialized bytes are identical either way, but the flat string matches the other flavors here and lets the custom `key_value` converters go entirely. **The converters were what hid a real bug.** `year` was declared `Components::Date`, yet the builder assigns a String and lutaml does not cast it — so the **parse** path held a String while **from_hash** produced a `Components::Date`. `to_hash` and `to_s` agreed, because `year_to_kv` normalised both shapes to a scalar, so the relaton index gate (`from_hash(to_hash) == to_hash`) passed — while **`parse(x) == from_hash(parse(x).to_hash)` was false for every AMCA id**, breaking `#matches?`, which is built on `==`. `year` is now `:string` too, both `with:` converters are gone (every mapped attribute is a plain scalar, and the canonical `to_hash` already drops empty and default values), and a spec asserts round-trip **equality**, not just hash equality — the stronger check that would have caught it. **Lesson: a `with:` converter that normalises two possible runtime shapes is a signal that the attribute type is wrong, not a fix.** The serialized key moved `code` → `number` (no consumer). **AMCA's `Publication` and `Interpretation` also lost hand-written keyword `initialize` methods** that assigned ivars directly and bypassed lutaml — costing them their `_type` (so `from_hash` could not route back), their `publisher` default, and the serialization of `revision`/`interpretation_code`, which were `attr_reader`s `to_hash` dropped. Both are now ordinary lutaml attributes; the builder already called `new(**attributes)` exactly as it does for `Standard`, which never had the problem. This is the AIEE/IRE/NESC migration applied again.
+
+## Revision, rendering and URN (hand-off `asme-bpvc-and-amca-residue`)
+
+**The publication revision never reached the object.** The grammar captured only `01` of `Rev. 01-23`, and `Builder#build_publication` read it under `parsed[:revision]`, where the grammar did not put it. The grammar now captures the whole `01-23` as `:revision`, so `revision`, `to_hash`, `to_s` and the URN (`rev.01-23`) carry it.
+
+**The renderer lost text.** It printed `AMCA Publication 211 -22` (a space before the year), `AMCA 99 – JW` (no `Interp`), and `(2010)` for `(R2010)`. Every parseable AMCA fixture id now renders as it was written, except the real normalizations (`ANSI/AMCA 220-21` → `ANSI/AMCA Standard 220-21`).
+
+**Every AMCA URN held a Ruby Hash.** `urn_type` interpolated the `type` metadata Hash (`copub.amca:{key: :publication, ...}`); it now reads `type[:key]`, the source `mr_type` reads. The URN also carries the interpretation code (`interp.jw`), so the interpretations of one standard no longer share a URN. `UrnParser` reads every token back (type, copublisher, interpretation code, revision, reaffirmation), so all 50 parseable fixture ids come back `==` from their URN; before, it rebuilt a bare `AMCA <number>-<year>` Standard.
+
+**Not fixed, pre-existing:** `AMCA 204 – 1` and `ANSI/AMCA Standard 210-25 / ASHRAE 51-25` do not parse. `ANSI/AMCA 210-16 /ASHRAE 51-16` parses but silently drops `/ASHRAE 51-16`, because `additional_copublisher` has no capture. The `suffix` rule of `standard_identifier` has no capture either, so `suffix` is never set on a `Standard`.
+
+## `all_parts_edition_keys`: Publication's `revision`, then the shared `reaffirmed`
+
+`Identifier.all_parts_edition_keys` defaults to `%i[date year edition
+version]`. A first pass fixed `Identifiers::Publication#revision` (the
+`Rev. 01-23` token), a separate discriminator that list never covered, so
+`"AMCA Publication 211-22 (Rev. 01-23)".to_all_parts` did not collapse
+onto another revision of the same publication under `#to_all_parts`/`#===`.
+Fixed with `Identifiers::Publication.all_parts_edition_keys` (`super +
+%i[revision]`), declared on `Publication` itself rather than the shared
+`Pubid::Amca::Identifier` base — `Standard`/`Interpretation` don't carry
+`revision`.
+
+Code review of that same change found a second, wider gap it had missed:
+`reaffirmed` (the `"(R2010)"` year) is declared on the shared
+`Pubid::Amca::Identifier` base (`identifiers/base.rb`), not on
+`Publication`, and `Renderer#render_base` reads it for **every** leaf —
+`Standard` as well as `Publication` — so `"AMCA 210-16 (R2010)"` failed to
+collapse onto `"AMCA 210-16 (R2015)"` even though neither is a
+`Publication`. Fixed on the shared base itself:
+`Pubid::Amca::Identifier.all_parts_edition_keys` is `super +
+%i[reaffirmed]`; `Publication`'s own override chains through `super` and
+picks it up automatically. **Lesson**: a discriminator declared on a
+shared base needs the override on that base, not repeated per leaf — and,
+per the IEEE entry above, finding one missed attribute is not proof the
+audit is complete. Not part of the original hand-off's audit list (which
+didn't cover AMCA); found during code review of the OGC/3GPP/NIST fix.
+Locked by `spec/pubid/all_parts_edition_keys_audit_spec.rb`.

data/lib/pubid/amca/builder.rb

@@ -154,11 +154,7 @@ module Pubid
 
         # Extract revision (Rev. 01-23)
         if parsed[:revision]
-          revision_data = parsed[:revision]
-          if revision_data && revision_data[:revision_year]
-            attributes[:revision] =
-              extract_value(revision_data[:revision_year])
-          end
+          attributes[:revision] = extract_value(parsed[:revision])
         end
 
         Identifiers::Publication.new(**attributes)
@@ -174,3 +170,5 @@ module Pubid
     end
   end
 end
+
+Pubid::Amca::Builder.prepend(Pubid::Builder::AllPartsWrap)

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

@@ -17,7 +17,7 @@ module Pubid
           raise Pubid::Errors::InvalidInputError, Pubid::INPUT_TOO_LONG_MESSAGE
         end
 
-        parsed = Parser.parse(identifier)
+        parsed = Pubid::Parg::Backend.parse(:amca, identifier)
         Builder.build(parsed)
       end
 
@@ -87,6 +87,16 @@ module Pubid
       def mr_year
         year&.to_s
       end
+
+      # `reaffirmed` (the "(R2010)" year, read by Renderer#render_base — used
+      # for Standard as well as Publication) is a discriminator the default
+      # %i[date year edition version] list misses, shared by every leaf that
+      # inherits this class. Declared here, not per-leaf, so Standard's own
+      # reaffirmations collapse too; Publication's revision (see
+      # publication.rb) is layered on top via `super`.
+      def self.all_parts_edition_keys
+        super + %i[reaffirmed]
+      end
     end
   end
 end

data/lib/pubid/amca/identifiers/publication.rb

@@ -28,6 +28,19 @@ module Pubid
         def self.type
           { key: :publication, title: "Publication", short: nil }
         end
+
+        # `revision` is Publication's edition/version discriminator and is
+        # not in the default %i[date year edition version] list, so
+        # #to_all_parts/#=== failed to collapse two revisions of the same
+        # publication (e.g. "AMCA Publication 211-22 (Rev. 01-23)" vs
+        # "... (Rev. 02-23)"). Declared here, not on the shared
+        # Pubid::Amca::Identifier base, because `revision` is
+        # Publication-only — Standard and Interpretation don't carry it.
+        # `super` also picks up `reaffirmed`, added on the shared base
+        # (identifiers/base.rb) since Standard carries that one too.
+        def self.all_parts_edition_keys
+          super + %i[revision]
+        end
       end
     end
   end

data/lib/pubid/amca/parser.rb

@@ -62,7 +62,8 @@ module Pubid
 
       # Publication revision (Rev. 01-23)
       rule(:revision) do
-        lparen >> str("Rev") >> dot.maybe >> space >> digits.as(:revision_year) >> dash >> digits >> rparen
+        lparen >> str("Rev") >> dot.maybe >> space >>
+          (digits >> dash >> digits).as(:revision) >> rparen
       end
 
       # Interpretation code (JW, KB, RG, AW, AH, or just a number)

data/lib/pubid/amca/renderer.rb

@@ -29,53 +29,42 @@ module Pubid
       private
 
       def render_base(id)
-        parts = []
-        parts << id.copublisher if id.copublisher
         t = id.class.respond_to?(:type) ? id.class.type : nil
-        if t.is_a?(Hash) && t[:title]
-          parts << t[:title].to_s
-        end
-        parts << id.number.to_s
-        parts << "-#{id.year}" if id.year
-
-        result = parts.compact.join(" ")
-
-        if id.copublisher&.include?("/") && id.year
-          type_title = t.is_a?(Hash) ? t[:title].to_s : ""
-          result = "#{id.copublisher} #{type_title} #{id.number}-#{id.year}"
-        end
-
-        result += " (#{id.reaffirmed})" if id.reaffirmed
-
+        title = t[:title].to_s if t.is_a?(Hash) && t[:title]
+        result = document(id, title)
+        result += " (R#{id.reaffirmed})" if id.reaffirmed
         result
       end
 
+      # The revision and the reaffirmation are separate optional groups in
+      # the grammar, so either or both can appear.
       def render_publication(id)
-        parts = []
-        parts << id.copublisher if id.copublisher
-        parts << "Publication"
-        parts << id.number.to_s
-        parts << "-#{id.year}" if id.year
-        parts << " (Rev. #{id.revision})" if id.revision
-        parts << " (#{id.reaffirmed})" if id.reaffirmed && !id.revision
-
-        parts.join(" ").squeeze(" ")
+        result = document(id, "Publication")
+        result += " (Rev. #{id.revision})" if id.revision
+        result += " (R#{id.reaffirmed})" if id.reaffirmed
+        result
       end
 
       def render_interpretation(id)
-        parts = []
-        parts << id.copublisher if id.copublisher
-        parts << id.number.to_s
+        result = [id.copublisher, id.number.to_s].compact.join(" ")
 
         if id.interpretation_code
-          parts << "– #{id.interpretation_code}"
+          result += " #{id.interpretation_code} Interp"
         elsif id.year
-          parts << "-#{id.year}"
+          result += " – #{id.year}"
+        else
+          result += " Interp"
         end
 
-        parts << " #{id.suffix}" if id.suffix
+        result += " #{id.suffix}" if id.suffix
+        result
+      end
 
-        parts.join(" ").squeeze(" ")
+      # "AMCA Standard 803-02": the year joins the number with a bare dash.
+      def document(id, title)
+        result = [id.copublisher, title, id.number.to_s].compact.join(" ")
+        result += "-#{id.year}" if id.year
+        result
       end
     end
   end

data/lib/pubid/amca/urn_generator.rb

@@ -27,9 +27,26 @@ module Pubid
         "copub.#{identifier.copublisher.to_s.downcase}" if identifier.copublisher
       end
 
+      # Identity-bearing: "AMCA 99 JW Interp" and "AMCA 99 KB Interp" are
+      # different documents.
+      def urn_interpretation
+        return nil unless identifier.respond_to?(:interpretation_code)
+
+        code = identifier.interpretation_code
+        "interp.#{code.downcase}" if code
+      end
+
+      def urn_revision
+        revision = identifier.revision if identifier.respond_to?(:revision)
+        "rev.#{revision}" if revision
+      end
+
+      # `type` is a metadata Hash; interpolating it put a Ruby Hash literal
+      # into every AMCA URN. The key is the source Identifier#mr_type reads.
       def urn_type
-        (identifier.class.respond_to?(:type) ? identifier.class.type : nil)
-          &.to_s&.downcase
+        return nil unless identifier.class.respond_to?(:type)
+
+        identifier.class.type[:key]&.to_s
       end
 
       def generate
@@ -37,6 +54,8 @@ module Pubid
         parts << urn_number if urn_number
         parts << urn_year if urn_year
         parts << urn_suffix if urn_suffix
+        parts << urn_interpretation if urn_interpretation
+        parts << urn_revision if urn_revision
         parts << urn_reaffirmed if urn_reaffirmed
         parts << urn_copublisher if urn_copublisher
 

data/lib/pubid/amca/urn_parser.rb

@@ -5,23 +5,49 @@ module Pubid
     # Parses AMCA URNs back into identifiers.
     #
     # UrnGenerator emits:
-    #   urn:amca:{number}:{year}[:{copub.publisher}[:{other tokens}]]
+    #   urn:amca:{number}[:{year}][:{keyed tokens}][:{type}]
     #
-    # The current generator can leak the Type Hash literal into the URN
-    # (e.g., `copub.amca:{:key => :standard, ...}`). This parser filters
-    # any token containing `{` so round-trip works for the common case.
+    # The keyed tokens are `interp.<code>`, `rev.<revision>`,
+    # `reaff.<year>` and `copub.<publisher>`; the type is the key of the
+    # identifier class. The parser rebuilds the printed form from them and
+    # parses that, so the identifier comes back as the same class.
     #
     # Examples:
-    # - urn:amca:210:08              → AMCA 210-08
+    # - urn:amca:210:08                             → AMCA 210-08
+    # - urn:amca:211:22:rev.01-23:copub.amca:publication
+    #                            → AMCA Publication 211-22 (Rev. 01-23)
+    # - urn:amca:99:interp.jw:copub.amca:interpretation → AMCA 99 JW Interp
     class UrnParser < Pubid::UrnParser::Base
+      TYPE_TITLES = {
+        "standard" => "Standard",
+        "publication" => "Publication",
+      }.freeze
+
       def parse_urn(urn)
-        body = strip_namespace(urn)
-        parts = split_parts(body).reject { |p| p.include?("{") }
+        number, *rest = split_parts(strip_namespace(urn))
+        year = rest.shift if rest.first&.match?(/\A\d+\z/)
+        keyed = rest.grep(/\./).to_h { |token| token.split(".", 2) }
+        type = (rest - keyed.map { |k, v| "#{k}.#{v}" }).last
+
+        flavor_parse(printed(number, year, keyed, type))
+      end
+
+      private
 
-        number, year = parts
-        text = "AMCA #{number}"
+      def printed(number, year, keyed, type)
+        publisher = keyed.fetch("copub", "amca").upcase
+        return interpretation(publisher, number, keyed) if type == "interpretation"
+
+        text = [publisher, TYPE_TITLES[type], number].compact.join(" ")
         text += "-#{year}" if year
-        flavor_parse(text)
+        text += " (Rev. #{keyed['rev']})" if keyed["rev"]
+        text += " (R#{keyed['reaff']})" if keyed["reaff"]
+        text
+      end
+
+      def interpretation(publisher, number, keyed)
+        code = keyed["interp"]&.upcase
+        [publisher, number, code, "Interp"].compact.join(" ")
       end
     end
   end

data/lib/pubid/ansi/builder.rb

@@ -45,6 +45,10 @@ module Pubid
           value.to_s.split(",").map do |lang|
             Components::Language.new(code: lang.strip)
           end
+        when :all_parts
+          # The shared Grammar marks the tree; the prepended AllPartsWrap
+          # routes the wrap, so the marker itself carries no component.
+          nil
         else
           raise ArgumentError, "Unknown parameter type: #{type}"
         end
@@ -52,3 +56,5 @@ module Pubid
     end
   end
 end
+
+Pubid::Ansi::Builder.prepend(Pubid::Builder::AllPartsWrap)

data/lib/pubid/ansi/identifier.rb

@@ -23,7 +23,7 @@ module Pubid
           raise Pubid::Errors::InvalidInputError, Pubid::INPUT_TOO_LONG_MESSAGE
         end
 
-        parsed = Pubid::Ansi::Parser.new.parse(string)
+        parsed = Pubid::Parg::Backend.parse(:ansi, string)
         Pubid::Ansi::Builder.new.build(parsed)
       end
     end

data/lib/pubid/api/CLAUDE.md

@@ -0,0 +1,23 @@
+# API flavor notes
+
+API rendering repairs and the `number` retype residue.
+
+These notes were part of the root `CLAUDE.md`. Read them before you change `lib/pubid/api/` or `spec/pubid/api/`. The root file keeps the cross-flavor contract that every flavor obeys.
+
+## From the root note "`number`/`part`/`subpart` retyped to `:string` — tranche 1 of 3 (ansi, api, bsi, cen_cenelec, idf, jcgm)"
+
+**The six flavors have no fixture net of their own**: every one of their `fixtures_spec.rb` files reports **0 examples** (the `../../../fixtures` glob has one `..` too many; api and idf also use an uppercase directory — hand-off `ten-dead-fixture-specs`), and ANSI's sole assertion is `expect(fixtures.size).to be > 0`. Fixing those globs would drag in unrelated stale-fixture failures, so the new spec's corpus sweep reads the same files directly — the ashrae/csa/etsi/oiml precedent. **One pre-existing defect repaired in passing**: `API COS 1-07/RP 75, 4th edition` put a raw `Parslet::Slice` into `root.number` (the hand-off warned it would look like a migration failure); `Api::Builder#cast` now returns `value.to_s`, so it is a real String. **One severe API defect repaired here — the ONLY deliberate `to_s` change in this branch.** `Pubid::Api::Identifier.parse("API RP 500").to_s` was `"API"`: **163 of API's 193 corpus ids rendered as the bare publisher**, and since `to_s` is the document number *and* the output filename, all 163 collapsed onto one another. Two independent **dead reads**, both found by pulling on the `code` thread this retype exposed: (1) `Api::Renderer#code_portion` read an `id.code` attribute that **nothing ever assigns** — the parser emits no `:code` key and `Builder#cast` never sets one — while the number the builder does populate sits in `number`; (2) the type token was gated on `id.class.attributes.key?(:type_string)`, but `type_string` is a plain **method** on each leaf, never a lutaml attribute, so that guard was always false. The fix is two reads (`number`, and `respond_to?(:type_string)`), plus deleting the `code` attribute and the three dead `code_portion` methods (`SingleIdentifier`'s and `Mpms`'s were never called at all — the renderer has its own). **`render_mpms` never consulted `code_portion`, which is exactly why MPMS was the one form that always rendered correctly.** Byte-exact `to_s` goes from **29/193 to 190/193**, and the 3 residuals are precisely the normalizing parses the generated fixtures already mark `!input!rendered`. **The strongest evidence that this restores intent rather than inventing output: regenerating the fixtures (`rake "validation:classify[api]"`) changed exactly ONE line** — a stale `!… !API` corrected to `!… !API 75-07`. The corpus had recorded the correct renderings all along; the code had drifted away from them silently, because API's `fixtures_spec.rb` matches no files and reports 0 examples and its other specs are `respond_to?(:parse)` stubs. Re-adding a `code` attribute would silently reopen the defect, so `spec/pubid/api/rendering_gaps_spec.rb` asserts it is absent from the whole hierarchy. **Note `maybe(:code)` in `urn_generator/base.rb#urn_number` is safe** — `maybe` guards on `attributes.key?`, so the removed attribute simply never matches. Measured over the corpus, the repair is **purely additive**: of 193 ids, 163 grew and **0 shrank**, and every new rendering *extends* the old one (`to_urn`, `to_hash` and `root.number` are untouched) — the ASHRAE invariant, which is stronger than byte-identity for a fix. **An MR gap this branch pinned was closed mid-flight by PR #354, and the pin is what caught it** — a worked example of why these "assert the CURRENT behaviour" blocks earn their place. When written, all **30** MPMS ids slugged to the bare `"api"` because MPMS kept its locator in a `chapter` attribute and had no `number` at all. #354 then moved the chapter into the inherited `number` (it *is* the document number) and this branch retyped that `number` to `:string`; **composed, they close the collapse** — 0 ids now slug to bare `"api"`, and `API MPMS CH 12.2` keys `"12"` as a String. Merging `main` turned the pin red exactly as designed, and it was rewritten to assert the repair. **A narrower gap remains and is re-pinned**: the MR slug is built from `number` alone, so the sections of one chapter still share it (`CH 14.4` and `CH 14.6` both → `api.14`, 11 colliding slugs corpus-wide, and `to_slug` is a filename). Closing that needs an `Mpms#mr_number_with_part` appending section/subsection (the BIPM/OIML shape). **Merge note for whoever does tranche 2/3**: #354's `Builder#handle_key` routes the MPMS `:chapter` parse key into the `number` *attribute*, and `assign_attributes` hands `handle_key` the **already-cast** value — so the `cast` arm must be `when :number, :chapter then value.to_s`, not a `Components::Code`, or MPMS silently regains a boxed number. (hand-off: retype-number-to-string; remaining: tranche 2 = CSA, tranche 3 = ISO and NIST on separate branches, then flip `identifier.rb:136-138` and delete the leaf `:string` redeclarations and the twelve tripwire blocks.)
+
+## From the root note "Parse-failure error contract — uniform across every flavor"
+
+**`Identifier.parse` was the one public parse in the gem that could return `nil`.** `lib/pubid/api/identifier.rb` opened with
+
+```ruby
+return nil if input.start_with?("#")   # "Filter out comments"
+```
+
+a **fixture-file concern living in a public API**. A caller passing a `#`-leading string got `nil` back and discovered it as a `NoMethodError` on `.to_s`, far from the cause. `lib/pubid/csa/identifier.rb` even carried a comment noting that every flavor "but `api`" honoured the raise-or-return-an-identifier contract, so this was known and unfixed.
+
+Deleting it cost nothing: **both** API fixture loaders already reject `#` lines themselves (`spec/pubid/api/fixtures_spec.rb`, `spec/pubid/api/root_number_spec.rb`), so nothing depended on the nil. A comment line is not an identifier and now raises `Parslet::ParseFailed` like any other unparseable string. The `rescue Parslet::ParseFailed => e; raise e` that followed it was a no-op and went too, and API gained the input guards it had never had (it was one of the 14 flavors an over-long string reached the parser in).
+
+**Rule this illustrates:** a filter that exists for *how the test corpus is stored* belongs in the corpus loader, never in `parse`.

data/lib/pubid/api/builder.rb

@@ -56,3 +56,5 @@ module Pubid
     end
   end
 end
+
+Pubid::Api::Builder.prepend(Pubid::Builder::AllPartsWrap)

data/lib/pubid/api/identifier.rb

@@ -34,7 +34,7 @@ module Pubid
         # this was the one public parse in the gem that could return nil, which
         # a caller reading `id.to_s` sees as a NoMethodError far from the cause.
         # Both API fixture loaders already drop `#` lines themselves.
-        tree = Parser.new.parse(input)
+        tree = Pubid::Parg::Backend.parse(:api, Api::Parser.normalize_input(input))
         Builder.new.build(tree)
       end
     end

data/lib/pubid/api/parser.rb

@@ -129,11 +129,15 @@ module Pubid
 
       root(:identifier)
 
-      # Preprocessing to normalize common typos
-      def parse(input)
+      # Pre-parse ingestion normalization (R2): every parse path feeds
+      # the grammar the same normalized string.
+      def self.normalize_input(input)
         # Normalize MPMP typo to MPMS
-        normalized = input.gsub("API MPMP", "API MPMS")
-        super(normalized)
+        input.gsub("API MPMP", "API MPMS")
+      end
+
+      def parse(input)
+        super(self.class.normalize_input(input))
       end
     end
   end