pubid 2.0.0.pre.alpha.1 → 2.0.0.pre.alpha.2

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

@@ -26,7 +26,7 @@ module Pubid
         # Render the identifier as a string in canonical IHO form.
         # @return [String]
         def to_s
-          letter = type.is_a?(Hash) ? type[:short].to_s : type.to_s
+          letter = self.class.type[:short]
           rendered = "#{publisher} #{letter}-#{code}"
           rendered << " Ap. #{appendix}" if appendix
           rendered << " Part #{part}"    if part

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

@@ -10,10 +10,6 @@ module Pubid
           { key: :bibliographic, title: "Bibliographic Publication",
             short: "B" }
         end
-
-        def type
-          self.class.type
-        end
       end
     end
   end

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

@@ -9,10 +9,6 @@ module Pubid
         def self.type
           { key: :circular_letter, title: "Circular Letter", short: "C" }
         end
-
-        def type
-          self.class.type
-        end
       end
     end
   end

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

@@ -10,10 +10,6 @@ module Pubid
           { key: :miscellaneous, title: "Miscellaneous Publication",
             short: "M" }
         end
-
-        def type
-          self.class.type
-        end
       end
     end
   end

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

@@ -9,10 +9,6 @@ module Pubid
         def self.type
           { key: :publication, title: "Publication", short: "P" }
         end
-
-        def type
-          self.class.type
-        end
       end
     end
   end

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

@@ -9,10 +9,6 @@ module Pubid
         def self.type
           { key: :standard, title: "Standards and Specifications", short: "S" }
         end
-
-        def type
-          self.class.type
-        end
       end
     end
   end

data/lib/pubid/iho/urn_generator.rb

@@ -15,7 +15,7 @@ module Pubid
 
       def generate
         parts = ["urn", "iho"]
-        parts << identifier.type[:short].to_s.downcase
+        parts << identifier.class.type[:short].to_s.downcase
         parts << identifier.code.to_s
         parts << "ap.#{identifier.appendix}"     if identifier.appendix
         parts << "part.#{identifier.part}"       if identifier.part

data/lib/pubid/iso/builder.rb

@@ -125,7 +125,11 @@ module Pubid
               copublisher: value[:copublisher],
             )
           else
-            Pubid::Iso::Components::Publisher.new(publisher: value)
+            # Default copublisher to [] (not nil) so a bare-string publisher
+            # (e.g. a TC document, which skips the copublisher merge) matches
+            # the [] convention used by copublisher-merged parses and by
+            # Identifier.create. Otherwise equality fails on [] vs nil.
+            Pubid::Iso::Components::Publisher.new(publisher: value, copublisher: [])
           end
 
         when :copublishers

data/lib/pubid/iso/identifier.rb

@@ -64,6 +64,267 @@ module Pubid
           Pubid::Iso::Builder.new(Pubid::Iso::Scheme).build(parsed)
         end
       end
+
+      # Factory mirroring pubid 1.x's `Pubid::Iso::Identifier.create` API.
+      #
+      # Accepts 1.x-style primitive kwargs and dispatches to the correct
+      # 2.x `Identifiers::*` subclass via {Pubid::Iso::Scheme}. Coerces
+      # primitives into ISO-specific Component objects.
+      #
+      # Dispatch rules:
+      #   * `type:` (e.g. `:tr`, `:amd`)        → lookup via Scheme
+      #   * else `stage:` (e.g. `"DIS"`, `"AMD"`) → lookup via Scheme
+      #   * else                                → InternationalStandard
+      #
+      # @param type    [Symbol, String, nil] type key (`:is`, `:tr`, `:amd`, …)
+      # @param stage   [String, Symbol, nil] typed-stage abbreviation
+      # @param opts    [Hash] remaining attribute primitives:
+      #   :publisher (String), :number, :part, :subpart, :year, :edition,
+      #   :language
+      # @return [Pubid::Iso::Identifier]
+      def self.create(type: nil, stage: nil, base: nil, **opts)
+        # A bundled directive (e.g. "ISO/IEC DIR 1 + IEC SUP") is stored by the
+        # 1.x index as the base document's fields plus a nested joint_document
+        # (or a supplements array). The 2.x model is a separate
+        # BundledIdentifier; build that so .create round-trips parse.
+        if opts[:joint_document] || opts[:supplements]
+          return build_bundled(type: type, stage: stage, base: base, **opts)
+        end
+
+        klass = resolve_create_class(type: type, stage: stage, base: base)
+        attrs = coerce_create_attrs(opts)
+        ts = resolve_create_typed_stage(klass, stage)
+        if ts
+          # dup the (shared) TYPED_STAGES element before tweaking, and set
+          # original_abbr to the canonical abbr so rendering matches a
+          # parsed identifier (parse records the spelled abbr, e.g. "Amd"
+          # not the upcased short_abbr "AMD").
+          ts = ts.dup
+          ts.original_abbr ||= Array(ts.abbr).first&.to_s
+          attrs[:typed_stage] = ts
+          # Parse fills `type` and `stage` Components derived from
+          # typed_stage; mirror that here so .create round-trips through
+          # Pubid::Identifier#== with a parsed identifier.
+          attrs[:type] ||= ::Pubid::Components::Type.new(
+            name:      ts.name,
+            abbr:      Array(ts.abbr).first.to_s,
+            type_code: ts.type_code&.to_s,
+          )
+          attrs[:stage] ||= ::Pubid::Components::Stage.new(
+            name:              ts.name,
+            stage_code:        ts.stage_code&.to_s,
+            abbr:              Array(ts.abbr).first.to_s,
+            harmonized_stages: Array(ts.harmonized_stages),
+          )
+        end
+        # Build the base_identifier whenever a `base:` is supplied, regardless
+        # of whether the resolved class is registered as a supplement (e.g.
+        # DirectivesSupplement holds a base but is not in
+        # Scheme#supplement_identifiers). Only classes that *require* a base
+        # and were given none raise.
+        if base
+          attrs[:base_identifier] = build_base_identifier(base)
+        elsif supplement_klass?(klass)
+          raise ArgumentError, "#{klass} requires a base: identifier"
+        end
+        # For a DirectivesSupplement the top-level `publisher:` names the
+        # supplement's own publisher ("… ISO SUP"), not the document's — the
+        # document publisher lives on the base. Mirror parse, which records it
+        # as `supplement_publisher`.
+        if klass <= Identifiers::DirectivesSupplement && attrs.key?(:publisher)
+          attrs[:supplement_publisher] = attrs.delete(:publisher)
+          attrs.delete(:copublishers)
+        end
+        klass.new(**attrs)
+      end
+
+      # Build a BundledIdentifier (base document + supplements) from the 1.x
+      # index shape: the top-level fields are the base document, and each
+      # joint_document/supplements entry is a joined supplement.
+      def self.build_bundled(type:, stage:, base:, **opts)
+        raw = opts.delete(:joint_document) || opts.delete(:supplements)
+        entries = raw.is_a?(Array) ? raw : [raw]
+        base_document = create(type: type, stage: stage, base: base, **opts)
+        supplements = entries.map { |j| build_joint_supplement(j) }
+        BundledIdentifier.new(base_document: base_document,
+                              supplements: supplements)
+      end
+
+      # Map a 1.x joint_document hash to a 2.x supplement matching parse. The
+      # index nests the supplement's publisher under joint_document.base.publisher
+      # (e.g. "IEC" for "+ IEC SUP"), while parse records it as the supplement's
+      # own publisher; move it and drop the nested base + empty top publisher.
+      def self.build_joint_supplement(joint)
+        j = joint.transform_keys(&:to_sym)
+        b = (j[:base] || {}).transform_keys(&:to_sym)
+        publisher = b[:publisher].to_s.empty? ? j[:publisher] : b[:publisher]
+        create(
+          type: j[:type],
+          publisher: publisher,
+          copublisher: b[:copublisher] || j[:copublisher],
+          number: (j[:number] unless j[:number].to_s.empty?),
+          year: j[:year],
+        )
+      end
+
+      # Build the base_identifier for a supplement from either an already
+      # constructed identifier or a 1.x-style attribute hash (the nested
+      # `:base` entry in a structured index). Recurses so supplement-of-
+      # supplement chains (e.g. a Corrigendum to an Amendment) build cleanly.
+      def self.build_base_identifier(base)
+        return base if base.is_a?(::Pubid::Identifier)
+
+        create(**base.transform_keys(&:to_sym))
+      end
+
+      # When `stage:` is explicit, look up the matching TypedStage via
+      # Scheme. Otherwise default to the chosen class's "published"
+      # TypedStage (so e.g. TR renders the "/TR" prefix). Returns nil if
+      # neither is available; the renderer then omits the stage prefix.
+      def self.resolve_create_typed_stage(klass, stage)
+        if stage
+          ts = locate_create_typed_stage(stage)
+          ts && retype_stage_for_class(klass, ts)
+        elsif klass.const_defined?(:TYPED_STAGES)
+          klass.const_get(:TYPED_STAGES).find do |ts|
+            ts.stage_code.to_sym == :published
+          end
+        end
+      end
+
+      # Indexes store a supplement's stage as the bare review-stage abbr
+      # ("CD", "WD", "AWI") plus a separate type ("AMD"), so the global lookup
+      # resolves the stage to the IS-typed variant (cdis) rather than the
+      # amendment-typed one (committee_draft_amd). When the resolved stage's
+      # type differs from the class chosen via `type:`, re-pick the equivalent
+      # stage from the class's own TYPED_STAGES. harmonized_stages is the
+      # stable cross-type key (stage_code/abbr diverge between IS and amd:
+      # IS "WD" is :working_draft, the amendment is :wd_amd).
+      def self.retype_stage_for_class(klass, ts)
+        return ts unless klass.const_defined?(:TYPED_STAGES)
+        return ts unless klass.respond_to?(:type) && klass.type
+        return ts if ts.type_code.to_s == klass.type[:key].to_s
+
+        harmonized = Array(ts.harmonized_stages)
+        return ts if harmonized.empty?
+
+        klass.const_get(:TYPED_STAGES).find do |s|
+          (Array(s.harmonized_stages) & harmonized).any?
+        end || ts
+      end
+
+      # Resolve a TypedStage from a create() :stage value. The index may
+      # supply it as an abbreviation ("DIS"), a generic stage_code (:dis),
+      # or a unique per-typed-stage code (:dtr, :fdisp). Try each in turn.
+      def self.locate_create_typed_stage(stage)
+        Scheme.locate_typed_stage_by_abbr(stage.to_s) ||
+          Scheme.locate_typed_stage_by_stage_code(stage) ||
+          Scheme.locate_typed_stage_by_code(stage)
+      end
+
+      def self.resolve_create_class(type:, stage:, base: nil)
+        klass =
+          if type
+            located = locate_klass_by_type_or_short(type)
+            raise ArgumentError, "Unknown ISO type: #{type.inspect}" unless located
+
+            located
+          elsif stage
+            ts = locate_create_typed_stage(stage)
+            ts && Scheme.locate_identifier_klass_by_type_code(ts.type_code)
+          end
+        # A bare `base:` with no type/stage is still a supplement; fall back to
+        # the generic Supplement (which can hold a base) rather than
+        # InternationalStandard (which cannot).
+        klass ||= Identifiers::Supplement if base
+        klass || Identifiers::InternationalStandard
+      end
+
+      # Try direct key lookup, then a case-insensitive key lookup (indexes
+      # store e.g. "DATA" but the registry key is :data), then fall back to
+      # matching the class's :short letter (e.g. type "R" → Recommendation,
+      # whose key is :rec and short is "R"). Indexes and legacy data carry
+      # either the key, an upper-cased key, or the short form.
+      def self.locate_klass_by_type_or_short(type)
+        Scheme.locate_identifier_klass_by_type_code(type) ||
+          Scheme.locate_identifier_klass_by_type_code(type.to_s.downcase) ||
+          Scheme.identifiers.detect { |k| k.type&.dig(:short)&.to_s == type.to_s }
+      end
+
+      def self.supplement_klass?(klass)
+        Array(Scheme.instance.supplement_identifiers).include?(klass)
+      end
+
+      def self.coerce_create_attrs(opts)
+        out = {}
+        if (v = opts[:publisher])
+          # Mirror parse: the publisher carries its copublishers in its own
+          # copublisher list, and each copublisher is also a standalone entry
+          # in the copublishers collection. No copublisher → [] (parity with
+          # parsed plain-ISO identifiers).
+          cops = Array(opts[:copublisher]).map(&:to_s)
+          out[:publisher] = Components::Publisher.new(
+            publisher: v.to_s, copublisher: cops,
+          )
+        end
+        if opts[:copublisher]
+          out[:copublishers] = Array(opts[:copublisher]).map do |c|
+            Components::Publisher.new(publisher: c.to_s)
+          end
+        end
+        %i[number part subpart].each do |k|
+          v = opts[k]
+          out[k] = Components::Code.new(number: v.to_s) unless v.nil?
+        end
+        if (v = opts[:year])
+          out[:date] = ::Pubid::Components::Date.new(year: v.to_s)
+        end
+        if (v = opts[:edition])
+          if v.is_a?(Hash)
+            # 1.x stored a directive org-variant ("ISO/IEC DIR 2 ISO" /
+            # "ISO/IEC DIR 1 IEC:2023") as edition: {publisher:, year:}; parse
+            # models the org as `part` and the year as `date`. Map it so create
+            # round-trips parse.
+            eh = v.transform_keys(&:to_sym)
+            out[:part] ||= Components::Code.new(number: eh[:publisher].to_s) if eh[:publisher]
+            out[:date] ||= ::Pubid::Components::Date.new(year: eh[:year].to_s) if eh[:year]
+          else
+            out[:edition] = ::Pubid::Components::Edition.new(number: v)
+          end
+        end
+        if (v = opts[:language])
+          out[:languages] =
+            [::Pubid::Components::Language.new(code: v.to_s)]
+        end
+        # TcDocument committee fields: the 1.x/index shape is the flat
+        # tctype/tcnumber/… keys, but the 2.x model stores underscored Code
+        # components (mirrors the parser's builder). Without this mapping a
+        # TC document round-trips to a bare "ISO N <num>".
+        { tctype: :tc_type, tcnumber: :tc_number,
+          sctype: :sc_type, scnumber: :sc_number,
+          wgtype: :wg_type, wgnumber: :wg_number }.each do |src, dest|
+          v = opts[src]
+          out[dest] = Components::Code.new(number: v.to_s) unless v.nil?
+        end
+        # Directives subgroup (e.g. "ISO/IEC JTC 1 DIR"): the 1.x/index shape
+        # is dirtype: "JTC", jtc_dir: "DIR", number: "1"; the 2.x model folds
+        # the subgroup into a single `subgroup` Code ("JTC 1") with no
+        # directive number, mirroring parse. Without this, .create drops the
+        # subgroup and collapses the id into a plain "DIR 1".
+        if opts[:dirtype]
+          out[:subgroup] = Components::Code.new(
+            number: [opts[:dirtype], opts[:number]].compact.join(" "),
+          )
+          out.delete(:number)
+        end
+        # TODO(create-shim): 1.x also accepted iteration, amendments,
+        # corrigendums, addendum, month, dir. Add as relaton call sites
+        # require them.
+        out
+      end
+      private_class_method :resolve_create_class, :supplement_klass?,
+                           :resolve_create_typed_stage, :coerce_create_attrs,
+                           :build_bundled, :build_joint_supplement
     end
   end
 end

data/lib/pubid/iso/parser.rb

@@ -45,7 +45,9 @@ module Pubid
       #             ISO/JTC 1 N 456
       #             ISO/TC 184/SC 4 N 789 (TC and SC only, no WG)
       rule(:tc_document) do
-        prefix_sole_publisher >> str("/") >> tc_type >> space >> tc_number.as(:tc_number) >>
+        # Accept either "ISO/TC 184…" or the lenient space form "ISO TC 184…"
+        # (the latter was valid in pubid 1.x via an optional slash).
+        prefix_sole_publisher >> (str("/") | space) >> tc_type >> space >> tc_number.as(:tc_number) >>
           tc_subcommittee_part.maybe >>
           space >> str("N") >> space? >> digits.as(:number) >>
           (str(":") >> year_digits.as(:year)).maybe
@@ -378,7 +380,7 @@ module Pubid
 
       DIRECTIVES_TYPED_STAGES = Identifiers::Directives::TYPED_STAGES.map(&:abbr).flatten.sort_by(&:length).reverse
       rule(:directives_identifier_no_third) do
-        prefix_with_copublishers >> space >>
+        prefix_with_copublishers >> space? >>
           (directives_publisher_subgroup >> space).maybe >>
           array_to_str(DIRECTIVES_TYPED_STAGES).as(:type_with_stage) >>
           (

data/lib/pubid/iso/scheme.rb

@@ -36,6 +36,12 @@ module Pubid
           instance.locate_typed_stage_by_stage_code(stage_code)
         end
 
+        # @param code [String, Symbol] the per-typed-stage code to find
+        # @return [TypedStage, nil] the matching typed stage
+        def locate_typed_stage_by_code(code)
+          instance.locate_typed_stage_by_code(code)
+        end
+
         # @param harmonized_code [String] the harmonized stage code to find
         # @return [TypedStage, nil] the matching typed stage
         def locate_typed_stage_by_harmonized_code(harmonized_code)

data/lib/pubid/iso/single_identifier.rb

@@ -11,7 +11,8 @@ module Pubid
 
       def build_rendering_context(_renderer, format:, with_edition: false,
                                   lang: :en, lang_single: false,
-                                  stage_format_long: nil, with_date: nil)
+                                  stage_format_long: nil, with_date: nil,
+                                  annotated: false)
         if format == :mr_string
           nil
         elsif lang_single || stage_format_long || !with_date.nil?
@@ -19,17 +20,19 @@ module Pubid
             with_language_code: lang_single ? :single : :none,
             stage_format_long: stage_format_long || false,
             with_date: with_date.nil? || with_date,
+            annotated: annotated,
           )
         else
-          detect_rendering_context
+          detect_rendering_context(annotated: annotated)
         end
       end
 
-      def detect_rendering_context
+      def detect_rendering_context(annotated: false)
         Rendering::RenderingContext.new(
           with_language_code: detect_language_code_format,
           stage_format_long: detect_stage_format_long,
           with_date: true,
+          annotated: annotated,
         )
       end
 

data/lib/pubid/iso/urn_generator.rb

@@ -78,9 +78,10 @@ module Pubid
         part_comp = part_component
         parts << part_comp if part_comp
 
-        # Stage (only for non-published documents)
+        # Stage (only for non-published documents); an all-parts series
+        # reference carries no specific stage.
         stage_comp = stage_component
-        parts << stage_comp if stage_comp
+        parts << stage_comp if stage_comp && !identifier.all_parts
 
         # Year (for published documents and when edition is present)
         year_comp = year_component
@@ -94,6 +95,9 @@ module Pubid
         lang_comp = language_component
         parts << lang_comp if lang_comp
 
+        # Series suffix for all-parts identifiers (compact, no padding)
+        parts << "ser" if identifier.all_parts
+
         parts.join(":")
       end
 
@@ -228,6 +232,9 @@ module Pubid
           end
         end
 
+        # Series suffix for all-parts identifiers (compact, no padding)
+        parts << "ser" if identifier.all_parts
+
         parts.join(":")
       end
 
@@ -326,7 +333,14 @@ module Pubid
         end
 
         # Format as stage-XX.XX
-        stage_part = "stage-#{harmonized_code}"
+        # An iterated PRF (Proof) stage (e.g. "PRF TR 17716.2") renders as the
+        # symbolic "draft" stage in the URN rather than its harmonized numeric
+        # code; a plain PRF without an iteration keeps the harmonized code.
+        stage_part = if stage_code.to_s == "prf" && identifier.stage_iteration
+                       "stage-draft"
+                     else
+                       "stage-#{harmonized_code}"
+                     end
 
         # For base identifiers (not supplements), include iteration in stage code
         # For supplements, iteration goes in the version part (v1.2)

data/lib/pubid/iso/urn_parser.rb

@@ -71,6 +71,15 @@ module Pubid
 
         parts = urn.sub("urn:iso:std:", "").split(":")
 
+        # Series suffix: a trailing "ser" marks an all-parts identifier. Strip
+        # it before component parsing so it is not misread as a language or
+        # supplement token (which previously rendered as "(SER)").
+        all_parts = false
+        if parts.last == "ser"
+          parts.pop
+          all_parts = true
+        end
+
         # Parse publisher(s) - first part
         publishers = parse_publisher(parts.shift)
 
@@ -212,7 +221,8 @@ module Pubid
 
         # Build the identifier hash
         build_identifier(publishers, number, part, subpart, type_code, stage_code, stage_iteration,
-                         harmonized_stage_code, stage_from_abbr, year, edition, languages, supplements)
+                         harmonized_stage_code, stage_from_abbr, year, edition, languages, supplements,
+                         all_parts)
       end
 
       private
@@ -302,7 +312,8 @@ module Pubid
 
       # Build identifier from parsed components
       def build_identifier(publishers, number, part, subpart, type_code, stage_code, stage_iteration,
-                         harmonized_stage_code, stage_from_abbr, year, edition, languages, supplements)
+                         harmonized_stage_code, stage_from_abbr, year, edition, languages, supplements,
+                         all_parts = false)
         # Start with base document hash
         base_hash = {
           publisher: publishers.first,
@@ -414,6 +425,9 @@ typed_stage
           }
         end
 
+        # all_parts belongs on the outermost identifier (after any supplement wrapping)
+        base_hash[:all_parts] = true if all_parts
+
         # Build the final identifier
         builder = Pubid::Iso::Builder.new(Pubid::Iso::Scheme.new)
         builder.build(base_hash)

data/lib/pubid/itu/identifier.rb

@@ -17,37 +17,102 @@ module Pubid
         raise "Failed to parse ITU identifier '#{identifier}': #{e.message}"
       end
 
-      # Factory mirroring v1's Pubid::Itu::Identifier.create API. The v1 form
-      # accepts a `type:` discriminator plus attribute kwargs; this v2
-      # implementation supports the subset needed by metanorma-itu PR #497:
-      #   * type: :annex — builds Identifiers::Annex
-      #   * series: "OB" (with no type:) — builds Identifiers::SpecialPublication
+      # Factory mirroring pubid 1.x's `Pubid::Itu::Identifier.create` API.
+      # Dispatch on `:type`:
+      #   * nil → Recommendation (or SpecialPublication for series "OB")
+      #   * :recommendation     → Identifiers::Recommendation
+      #   * :annex              → Identifiers::Annex
+      #   * :special_publication → Identifiers::SpecialPublication
+      #
+      # Component-typed kwargs are accepted as primitives and coerced:
+      #   * sector: "T"   → Components::Sector.new(sector: "T")
+      #   * series: "X"   → Components::Series.new(series: "X")
+      #   * number: "509" → Components::Code.new(number: "509")
+      #   * year: "2020"  → Pubid::Components::Date.new(year: "2020")
+      TYPE_KEY_TO_KLASS = {
+        recommendation:      "Recommendation",
+        annex:               "Annex",
+        special_publication: "SpecialPublication",
+      }.freeze
+
       def self.create(type: nil, **kwargs)
-        case type
-        when :annex
-          Identifiers::Annex.new(**kwargs)
-        when nil
-          if kwargs[:series].to_s == "OB"
-            create_special_publication(**kwargs)
-          else
-            raise ArgumentError,
-                  "Identifier.create without :type requires series: 'OB'"
-          end
-        else
-          raise ArgumentError,
-                "Unsupported type for Identifier.create: #{type.inspect}"
+        # Backward-compat: nil type + series "OB" → SpecialPublication.
+        if type.nil? && kwargs[:series].to_s == "OB"
+          return create_special_publication(**kwargs)
         end
+
+        klass = resolve_create_class(type)
+        klass.new(**coerce_create_attrs(kwargs, klass: klass))
+      end
+
+      def self.resolve_create_class(type)
+        return Identifiers::Recommendation if type.nil?
+
+        klass_name = TYPE_KEY_TO_KLASS[type.to_sym]
+        raise ArgumentError, "Unknown ITU type: #{type.inspect}" unless klass_name
+
+        Identifiers.const_get(klass_name)
       end
 
+      # Backward-compat helper retained for the OB-series shortcut.
       def self.create_special_publication(number:, series: "OB", date: nil,
-language: nil)
+                                          language: nil)
         Identifiers::SpecialPublication.new(
-          series: Components::Series.new(series: series.to_s),
-          code: Components::Code.new(number: number.to_s),
-          date: date,
+          series:   Components::Series.new(series: series.to_s),
+          code:     Components::Code.new(number: number.to_s),
+          date:     date,
           language: language&.to_s,
         )
       end
+
+      def self.coerce_create_attrs(opts, klass: nil)
+        attrs = {}
+        if (v = opts[:sector])
+          attrs[:sector] = if v.is_a?(Components::Sector)
+                             v
+                           else
+                             Components::Sector.new(sector: v.to_s.upcase)
+                           end
+        end
+        if (v = opts[:series])
+          attrs[:series] = if v.is_a?(Components::Series)
+                             v
+                           else
+                             Components::Series.new(series: v.to_s)
+                           end
+        end
+        if opts[:number] || opts[:code]
+          code_value = opts[:code]
+          if code_value.is_a?(Components::Code)
+            attrs[:code] = code_value
+          else
+            attrs[:code] = Components::Code.new(
+              number:    (opts[:number] || code_value).to_s,
+              subseries: opts[:subseries]&.to_s,
+              parts:     opts[:parts] ? Array(opts[:parts]).map(&:to_s) : nil,
+            )
+          end
+        end
+        if (v = opts[:year])
+          attrs[:date] = Pubid::Components::Date.new(year: v.to_s)
+        end
+        attrs[:date] = opts[:date] if opts[:date].is_a?(Pubid::Components::Date)
+        attrs[:language] = opts[:language].to_s if opts[:language]
+
+        # Pass through any subclass-specific kwarg the chosen class
+        # declares (e.g. Annex#base) — preserves callers that already pass
+        # an explicit attribute that our coercion table doesn't cover.
+        if klass
+          consumed = %i[sector series number code subseries parts year date
+                        language]
+          opts.each do |k, v|
+            next if consumed.include?(k) || attrs.key?(k)
+            attrs[k] = v if klass.attributes.key?(k)
+          end
+        end
+        attrs
+      end
+      private_class_method :resolve_create_class, :coerce_create_attrs
     end
   end
 end