pubid 2.0.0.pre.alpha.9 → 2.0.0.pre.alpha.11

data/lib/pubid/csa/composite_identifier.rb

@@ -8,35 +8,30 @@ module Pubid
     # collections of other identifiers or package materials.
     #
     # Examples:
-    #   - PackageIdentifier: Base + package materials
-    #   - Future: BundleIdentifier refactor to use composite
+    #   - Package: base + package materials
     #
     # This follows the Composite pattern where an identifier can contain
     # other identifiers or additional metadata as a collection.
-    class CompositeIdentifier < Lutaml::Model::Serializable
-      # The primary/base identifier
-      # Use attr_accessor since it can be any identifier object
-      attr_accessor :base
+    class CompositeIdentifier < Identifier
+      # The primary/base identifier. A real lutaml attribute under the uniform
+      # `base` name, so `#root` walks it and it survives serialization — see
+      # WrapperIdentifier#base for why the type is the cross-flavor
+      # ::Pubid::Identifier.
+      attribute :base, ::Pubid::Identifier, polymorphic: true
 
       # Subclasses MUST implement to_s to define how they render
-      def to_s
+      def to_s(**_opts)
         raise NotImplementedError, "Subclasses must implement to_s method"
       end
 
-      # CSA composites serialise through `to_s`, so MR mirrors that with
-      # ` ` → `.`, `:` → `.`, `/` → `-`, then lowercased (issue #142).
-      def to_mr_string
-        to_s.tr(" ", ".").tr(":", ".").tr("/", "-").downcase
+      # A package peels to the standard it packages — see
+      # WrapperIdentifier#base_document.
+      def base_document
+        base ? base.base_document : self
       end
 
-      def to_slug
-        to_mr_string
-      end
-
-      # CSA composites are not Pubid::Identifier objects, so they do not inherit
-      # #root. They are their own origin for matching purposes.
-      def root
-        self
+      def drop_supplements
+        base || self
       end
     end
   end

data/lib/pubid/csa/identifier.rb

@@ -2,22 +2,38 @@
 
 module Pubid
   module Csa
-    # Common base class for all CSA identifiers. SingleIdentifier (and the
-    # concrete Identifiers::* types through it) descends from it, so every CSA
-    # identifier is `is_a?(Pubid::Csa::Identifier)` natively and gets the shared
-    # polymorphic `from_hash`. (The Wrapper/Composite container models are
-    # separate Lutaml::Model types, not identifiers.)
+    # Common base class for EVERY CSA identifier — the single-document types
+    # through SingleIdentifier, and the container types (WrapperIdentifier,
+    # CompositeIdentifier, Bundled, Combined) directly. So every CSA identifier
+    # is `is_a?(Pubid::Csa::Identifier)` natively and gets the shared
+    # polymorphic `from_hash`, `#root`, `#exclude` and MR rendering. The
+    # containers used to be separate Lutaml::Model types, which is what made
+    # `root.number` raise rather than return the relaton index key.
     class Identifier < ::Pubid::Identifier
       def self.parse(input)
+        unless input.is_a?(String)
+          raise Pubid::Errors::InvalidInputError,
+                Pubid::INPUT_NOT_A_STRING_MESSAGE
+        end
+
         if input.length > Pubid::MAX_INPUT_LENGTH
-          raise ArgumentError, Pubid::INPUT_TOO_LONG_MESSAGE
+          raise Pubid::Errors::InvalidInputError, Pubid::INPUT_TOO_LONG_MESSAGE
         end
 
         # Filter out comments
-        return nil if input.start_with?("#")
+        if input.start_with?("#")
+          raise Pubid::Errors::ParseError.new(
+            "Not a CSA identifier (comment): #{input}",
+            input: input, flavor: "csa",
+          )
+        end
 
-        # Filter out non-standards
-        return nil if input.match?(/^CSA (Communities|Group|Learning|OnDemand|Update)/)
+        # Filter out non-standards (memberships, courses, newsletters)
+        if input.match?(/^CSA (Communities|Group|Learning|OnDemand|Update)/)
+          raise Pubid::Errors::ParseError.new(
+            "Not a CSA standard: #{input}", input: input, flavor: "csa"
+          )
+        end
 
         # Preprocessing: normalize CEI to IEC (French name)
         input = input.gsub("CEI/IEC", "IEC").gsub(/\bCEI\b/, "IEC")
@@ -46,16 +62,14 @@ module Pubid
 
             # Parse normally (will create Bundled or Combined identifier)
             tree = Parser.new.parse(normalized)
-            result = Builder.new.build(tree)
+            result = build!(tree, input)
 
             # Apply CAN/CSA- prefix to the appropriate parts
-            if result
-              set_publisher_prefix(result, "CAN/CSA-")
+            set_publisher_prefix(result, "CAN/CSA-")
 
-              # Handle reaffirmation if present
-              if (wrapped_input =~ /\(R(\d{4})\)/) && result.class.attributes.key?(:reaffirmation)
-                result.reaffirmation = $1
-              end
+            # Handle reaffirmation if present
+            if (wrapped_input =~ /\(R(\d{4})\)/) && result.class.attributes.key?(:reaffirmation)
+              result.reaffirmation = $1
             end
 
             return result
@@ -91,8 +105,7 @@ module Pubid
           wrapped_input = wrapped_input.sub(/^CSA-/, "CSA ")
 
           # Parse the wrapped identifier recursively
-          wrapped_identifier = parse(wrapped_input)
-          return nil unless wrapped_identifier
+          base = parse(wrapped_input)
 
           # NOTE: Series identifiers should be wrapped in CanadianAdopted when
           # they have CAN/CSA- prefix. The Series will handle rendering correctly.
@@ -101,32 +114,35 @@ module Pubid
           # Set publisher prefix on wrapped identifier
           # For Series identifiers with CAN/ wrapper, use full "CAN/CSA-" prefix
           # For other identifiers, use the detected original_prefix ("CSA-" or "CSA")
-          if wrapped_identifier.class.attributes.key?(:publisher_prefix)
-            if is_can_csa && wrapped_identifier.is_a?(Identifiers::Series)
+          if base.class.attributes.key?(:publisher_prefix)
+            if is_can_csa && base.is_a?(Identifiers::Series)
               # Series gets full "CAN/CSA-" prefix for proper rendering
-              wrapped_identifier.publisher_prefix = "CAN/CSA-"
+              base.publisher_prefix = "CAN/CSA-"
             elsif original_prefix
-              # For Combined identifiers, set on first identifier
-              if wrapped_identifier.is_a?(Identifiers::Combined) && wrapped_identifier.first
-                wrapped_identifier.first.publisher_prefix = original_prefix if wrapped_identifier.first.class.attributes.key?(:publisher_prefix)
+              # For Combined identifiers, set on the primary designation
+              if base.is_a?(Identifiers::Combined) && base.identifiers&.first
+                primary = base.identifiers.first
+                if primary.class.attributes.key?(:publisher_prefix)
+                  primary.publisher_prefix = original_prefix
+                end
               else
                 # For non-Combined identifiers, set directly
-                wrapped_identifier.publisher_prefix = original_prefix
+                base.publisher_prefix = original_prefix
               end
             end
           end
 
-          # Set reaffirmation on wrapped_identifier if it has the attribute
-          if wrapped_identifier.class.attributes.key?(:reaffirmation) && reaffirm_year
-            wrapped_identifier.reaffirmation = reaffirm_year
-            if wrapped_identifier.class.attributes.key?(:original_reaffirmation_4digit)
-              wrapped_identifier.original_reaffirmation_4digit = reaffirmation_was_4digit
+          # Set reaffirmation on base if it has the attribute
+          if base.class.attributes.key?(:reaffirmation) && reaffirm_year
+            base.reaffirmation = reaffirm_year
+            if base.class.attributes.key?(:original_reaffirmation_4digit)
+              base.original_reaffirmation_4digit = reaffirmation_was_4digit
             end
           end
 
           # Create CanadianAdoptedIdentifier wrapper
           result = Identifiers::CanadianAdopted.new
-          result.wrapped_identifier = wrapped_identifier
+          result.base = base
           result.reaffirmation = reaffirm_year if reaffirm_year
 
           return result
@@ -157,44 +173,43 @@ module Pubid
           end
 
           # Parse the wrapped identifier recursively
-          wrapped_identifier = parse(wrapped_input)
-          return nil unless wrapped_identifier
+          base = parse(wrapped_input)
 
           # Set year_format for dash format identifiers (preserve original 2-digit year)
-          if has_dash_year && wrapped_identifier.class.attributes.key?(:year_format)
-            wrapped_identifier.year_format = "dash"
+          if has_dash_year && base.class.attributes.key?(:year_format)
+            base.year_format = "dash"
             # Mark original year as 2-digit so renderer converts back (1986 → 86)
-            if wrapped_identifier.class.attributes.key?(:original_year_4digit)
-              wrapped_identifier.original_year_4digit = false
+            if base.class.attributes.key?(:original_year_4digit)
+              base.original_year_4digit = false
             end
           end
 
           # Check if this is a Series identifier - return it directly with CAN3- prefix
           # Series identifiers are complete identifier types and handle the prefix themselves
           # They don't need to be wrapped in CanadianAdopted
-          if wrapped_identifier.is_a?(Identifiers::Series)
-            wrapped_identifier.publisher_prefix = "CAN3-"
-            wrapped_identifier.reaffirmation = reaffirm_year if reaffirm_year
-            wrapped_identifier.original_reaffirmation_4digit = reaffirmation_was_4digit
-            return wrapped_identifier
+          if base.is_a?(Identifiers::Series)
+            base.publisher_prefix = "CAN3-"
+            base.reaffirmation = reaffirm_year if reaffirm_year
+            base.original_reaffirmation_4digit = reaffirmation_was_4digit
+            return base
           end
 
           # Set CAN3- as publisher prefix on wrapped identifier
-          if wrapped_identifier.class.attributes.key?(:publisher_prefix)
-            wrapped_identifier.publisher_prefix = "CAN3-"
+          if base.class.attributes.key?(:publisher_prefix)
+            base.publisher_prefix = "CAN3-"
           end
 
-          # Set reaffirmation on wrapped_identifier if it has the attribute
-          if wrapped_identifier.class.attributes.key?(:reaffirmation) && reaffirm_year
-            wrapped_identifier.reaffirmation = reaffirm_year
-            if wrapped_identifier.class.attributes.key?(:original_reaffirmation_4digit)
-              wrapped_identifier.original_reaffirmation_4digit = reaffirmation_was_4digit
+          # Set reaffirmation on base if it has the attribute
+          if base.class.attributes.key?(:reaffirmation) && reaffirm_year
+            base.reaffirmation = reaffirm_year
+            if base.class.attributes.key?(:original_reaffirmation_4digit)
+              base.original_reaffirmation_4digit = reaffirmation_was_4digit
             end
           end
 
           # Create CanadianAdoptedIdentifier wrapper
           result = Identifiers::CanadianAdopted.new
-          result.wrapped_identifier = wrapped_identifier
+          result.base = base
           result.reaffirmation = reaffirm_year if reaffirm_year
 
           return result
@@ -250,13 +265,20 @@ module Pubid
             "/Amd #{amendment_num}#{separator}#{amend_full_year}"
           end
 
-          # Parse with appropriate flavor parser
-          wrapped_identifier = parse_external_standard(wrapped_input)
-          return nil unless wrapped_identifier
+          # Parse with appropriate flavor parser. The helper probes several
+          # flavors and reports failure with nil; the public contract is a
+          # raise, so translate here.
+          base = parse_external_standard(wrapped_input)
+          unless base
+            raise Pubid::Errors::ParseError.new(
+              "Unparseable adopted standard: #{input}",
+              input: input, flavor: "csa",
+            )
+          end
 
           # Create CsaAdoptedIdentifier wrapper
           result = Identifiers::CsaAdopted.new
-          result.wrapped_identifier = wrapped_identifier
+          result.base = base
           result.reaffirmation = reaffirm_year if reaffirm_year
 
           return result
@@ -337,12 +359,9 @@ module Pubid
               break if token.match?(/^PACKAGE$/i)
 
               test_input = base_input.empty? ? token : "#{base_input} #{token}"
-              parsed = parse(test_input)
-              if parsed
-                base_input = test_input
-              else
-                break
-              end
+              break unless try_parse(test_input)
+
+              base_input = test_input
             end
 
             # Extract materials as everything between base and PACKAGE
@@ -354,9 +373,16 @@ module Pubid
             end
           end
 
-          # Parse base identifier recursively
-          base = base_input ? parse(base_input) : nil
-          return nil unless base
+          # Parse the base identifier recursively. An unparseable base is a
+          # failed package, not a nil.
+          if base_input.nil? || base_input.empty?
+            raise Pubid::Errors::ParseError.new(
+              "Unparseable package base: #{input}",
+              input: input, flavor: "csa",
+            )
+          end
+
+          base = parse(base_input)
 
           # Create PackageIdentifier
           result = Identifiers::Package.new
@@ -393,39 +419,61 @@ module Pubid
         normalized = normalized.gsub("CAN3-", "CSA ")
 
         tree = Parser.new.parse(normalized)
-        result = Builder.new.build(tree)
+        result = build!(tree, input)
 
         # Set publisher prefix if detected
-        if result && publisher_prefix
-          set_publisher_prefix(result, publisher_prefix)
-        end
+        set_publisher_prefix(result, publisher_prefix) if publisher_prefix
 
         # Set year format if detected as dash and not already set
-        if result && has_dash_year && result.year_format.nil?
-          result.year_format = "dash"
-        end
+        result.year_format = "dash" if has_dash_year && result.year_format.nil?
 
         result
       rescue Parslet::ParseFailed => e
         raise e
       end
 
+      # Build a parse tree into an identifier, or fail loudly.
+      #
+      # Builder#build can return nil for a tree it recognises but cannot map
+      # to a class. `parse` must return an identifier or raise — every flavor
+      # but `api` already honours that — because a nil surfaces in the caller
+      # as a NoMethodError far from the input that caused it, rather than as a
+      # catchable parse failure.
+      def self.build!(tree, input)
+        built = Builder.new.build(tree)
+        return built if built
+
+        raise Pubid::Errors::ParseError.new(
+          "Unparseable CSA identifier: #{input}",
+          input: input, flavor: "csa",
+        )
+      end
+
+      # Probe whether a string parses. The package base scan walks
+      # progressively longer prefixes and keeps the longest that succeeds, so
+      # it is the one caller that genuinely wants a nil rather than a raise.
+      def self.try_parse(input)
+        parse(input)
+      rescue Parslet::ParseFailed, ArgumentError
+        nil
+      end
+
       def self.set_publisher_prefix(obj, prefix)
         # Set on main object if it has the attribute
         if obj.class.attributes.key?(:publisher_prefix)
           obj.publisher_prefix = prefix
         end
 
-        # Set on combined identifier parts
+        # Set on combined identifier parts. The primary designation always
+        # takes the prefix; a trailing one only when it printed a publisher of
+        # its own (a bare continuation must stay bare).
         if obj.is_a?(Identifiers::Combined)
-          if obj.first&.class&.attributes&.key?(:publisher_prefix)
-            obj.first.publisher_prefix = prefix
-          end
-          if obj.second && obj.second.class.attributes.key?(:has_publisher) && obj.second.has_publisher && obj.second.class.attributes.key?(:publisher_prefix)
-            obj.second.publisher_prefix = prefix
-          end
-          if obj.third && obj.third.class.attributes.key?(:has_publisher) && obj.third.has_publisher && obj.third.class.attributes.key?(:publisher_prefix)
-            obj.third.publisher_prefix = prefix
+          Array(obj.identifiers).each_with_index do |part, index|
+            next unless part.class.attributes.key?(:publisher_prefix)
+            next if index.positive? &&
+              !(part.class.attributes.key?(:has_publisher) && part.has_publisher)
+
+            part.publisher_prefix = prefix
           end
         end
 
@@ -489,15 +537,29 @@ module Pubid
       end
 
       # CSA encodes its identity across many shape-specific attributes
-      # (`publisher_prefix`, `code`, `no_number`, `series`, `series_prefix`,
+      # (`publisher_prefix`, `number`, `no_number`, `series`, `series_prefix`,
       # `package`, `reaffirmation`, `year` with prefix/format/French markers,
       # etc.) that the generic MrString renderer doesn't know about. The
       # CSA `to_s` already round-trips losslessly through the CSA parser, so
       # MR mirrors it: ` ` → `.`, `:` → `.` (so the year never looks like
       # another code segment), `/` → `-` (CAN/CSA- prefix), then lowercased
       # to match the all-lowercase MR convention (issue #142).
+      #
+      # Those three are the SEMANTIC mappings — they carry CSA's segment
+      # structure. Everything else is then neutralised by CHARSET, not by an
+      # enumerated escape list, so a character that appears in a future
+      # reference cannot leak into what `to_slug` hands a filesystem. CSA
+      # references really do carry `(`, `)`, `,`, `&` and `+` today
+      # (`CSA C22.2 NO. 100:14 (R2024)`, `… Code, Handbook & Training
+      # Package`, `… + A1:15`), and the old `tr` chain let all of them
+      # through — 601 of 816 slugs were not filename-safe. The BIPM `mr_slug`
+      # precedent.
       def to_mr_string
-        to_s.tr(" ", ".").tr(":", ".").tr("/", "-").downcase
+        to_s
+          .downcase
+          .tr(" ", ".").tr(":", ".").tr("/", "-")
+          .gsub(/[^a-z0-9._-]+/, "-")
+          .gsub(/\A[-.]+|[-.]+\z/, "")
       end
 
       def to_slug

data/lib/pubid/csa/identifiers/bundled.rb

@@ -5,23 +5,33 @@ require "lutaml/model"
 module Pubid
   module Csa
     module Identifiers
-      class Bundled < Lutaml::Model::Serializable
-        attribute :base, Standard
-        attribute :bundled_with, Standard, collection: true
+      class Bundled < Identifier
+        # The consolidated base document and the amendments bundled with it.
+        # Both are typed cross-flavor and polymorphic — see
+        # WrapperIdentifier#base — because a bundle's base is routinely a Cec,
+        # which is not a Standard subclass. #root is inherited: it walks
+        # `base` to the origin document.
+        attribute :base, ::Pubid::Identifier, polymorphic: true
+        attribute :bundled_with, ::Pubid::Identifier, polymorphic: true,
+                                                      collection: true
         attribute :reaffirmation, :string
         attribute :original_reaffirmation_4digit, :boolean, default: -> {
           false
         }
         attribute :year_format, :string # Add for compatibility with identifier.rb
 
-        # CSA bundles are not Pubid::Identifier objects, so they do not inherit
-        # #root. They are their own origin for matching purposes.
-        def root
-          self
+        # A bundle is a base document consolidated with its amendments, so
+        # both matching primitives peel to that base.
+        def base_document
+          base ? base.base_document : self
         end
 
-        def to_s
-          # For Cec identifiers, use normalized form (code instead of cec_part + NO.)
+        def drop_supplements
+          base || self
+        end
+
+        def to_s(**opts)
+          # For Cec identifiers, use normalized form (number instead of cec_part + NO.)
           # This is used for "normalized form" rendering in bundled identifiers
           if base.is_a?(Cec)
             # Render base with normalized code format
@@ -37,7 +47,7 @@ module Pubid
                              end
                            end
             base_str = (needs_space ? "#{prefix} " : prefix) +
-              base.code.value.to_s + # Use normalized code (e.g., "C22.2-1")
+              base.number.value.to_s + # Normalized code (e.g. "C22.2-1")
               ":#{year_display}"
             parts = [base_str]
           else
@@ -50,7 +60,7 @@ module Pubid
             bundled_with.each do |bundled|
               # For Cec identifiers, use normalized code format
               if bundled.is_a?(Cec)
-                bundled_part = bundled.code.value.to_s # Normalized code (e.g., "C22.2-2")
+                bundled_part = bundled.number.value.to_s # e.g. "C22.2-2"
                 if bundled.year
                   # Use dash if year_format is dash, otherwise colon
                   separator = bundled.year_format == "dash" ? "-" : ":"
@@ -68,7 +78,7 @@ module Pubid
               else
                 # Standard rendering for other identifier types
                 bundled_part = ""
-                bundled_part += bundled.code.to_s if bundled.code
+                bundled_part += bundled.number.to_s if bundled.number
 
                 if bundled.year
                   # Use dash if year_format is dash, otherwise colon
@@ -123,7 +133,7 @@ module Pubid
                       end
           end
 
-          result
+          annotate_plain_render(result, **opts)
         end
       end
     end

data/lib/pubid/csa/identifiers/canadian_adopted.rb

@@ -12,40 +12,40 @@ module Pubid
       #
       # This is a wrapper pattern where:
       #   - CAN/ indicates Canadian adoption
-      #   - The wrapped_identifier is the actual CSA standard being adopted
+      #   - The base is the actual CSA standard being adopted
       #
       # This is semantically different from a string prefix because:
       #   - CAN/ wraps an entire identifier (which may itself be complex)
       #   - The wrapped identifier is recursively parsed as a full CSA identifier
       #   - Proper object composition, not string manipulation
       class CanadianAdopted < WrapperIdentifier
-        def to_s
+        def to_s(**opts)
           # For CAN3- identifiers, don't add CAN/ prefix (CAN3- is already complete)
           # For Series with CAN/CSA- prefix, don't add CAN/ (it's already complete)
           # For CAN/CSA- identifiers, CAN/ wraps CSA- part
-          if wrapped_identifier.class.attributes.key?(:publisher_prefix) && wrapped_identifier.publisher_prefix
-            prefix = wrapped_identifier.publisher_prefix
+          if base.class.attributes.key?(:publisher_prefix) && base.publisher_prefix
+            prefix = base.publisher_prefix
             # CAN3- is standalone, just render wrapped identifier
             # CAN/CSA- is already complete for Series identifiers
-            if prefix == "CAN3-" || (prefix == "CAN/CSA-" && wrapped_identifier.is_a?(Identifiers::Series))
-              result = wrapped_identifier.to_s
+            if prefix == "CAN3-" || (prefix == "CAN/CSA-" && base.is_a?(Identifiers::Series))
+              result = base.to_s
             else
               # For other cases, prepend CAN/ prefix
-              result = "CAN/#{wrapped_identifier}"
+              result = "CAN/#{base}"
             end
           else
             # No publisher_prefix, prepend CAN/
-            result = "CAN/#{wrapped_identifier}"
+            result = "CAN/#{base}"
           end
-          # Only add reaffirmation from wrapper if wrapped_identifier doesn't have one
+          # Only add reaffirmation from wrapper if base doesn't have one
           # (to avoid duplicates - Identifier.parse sets it on both)
-          if reaffirmation && !(wrapped_identifier.class.attributes.key?(:reaffirmation) && wrapped_identifier.reaffirmation)
+          if reaffirmation && !(base.class.attributes.key?(:reaffirmation) && base.reaffirmation)
             # Determine if space is needed before reaffirmation
             # Space needed if year is 2-digit and reaffirmation is 4-digit (original format)
             # No space if both year and reaffirmation are 2-digit
             # Check original_year_4digit flag - if false, year was originally 2-digit
-            year_was_2digit = wrapped_identifier.class.attributes.key?(:original_year_4digit) &&
-              !wrapped_identifier.original_year_4digit
+            year_was_2digit = base.class.attributes.key?(:original_year_4digit) &&
+              !base.original_year_4digit
             # Check original_reaffirmation_4digit flag
             reaffirmation_was_4digit = original_reaffirmation_4digit
 
@@ -74,7 +74,7 @@ module Pubid
               result += "(R#{reaffirmation_str})"
             end
           end
-          result
+          annotate_plain_render(result, **opts)
         end
       end
     end

data/lib/pubid/csa/identifiers/cec.rb

@@ -13,12 +13,52 @@ module Pubid
         attribute :cec_part, Components::Code      # C22.2, C22.3, C22.4, C22.6
         attribute :no_number, Components::Code     # Number after NO.
 
-        # Combined code attribute for compatibility
-        # Returns cec_part + "-" + no_number (e.g., "C22.2-1")
-        def code
+        # `CSA C22.2 NO. 286:23` stores the joined "C22.2-286" in `number`, which
+        # appears nowhere in the printed form; the two halves it does print live
+        # in `cec_part` and `no_number`. Naming them gives the identifier its
+        # docnumber spans back.
+        def annotation_tokens
+          super + [
+            [:publisher_prefix, "publisher"],
+            [:cec_part, "docnumber"],
+            [:no_number, "docnumber"],
+          ]
+        end
+
+        # Merged with SingleIdentifier's block (lutaml combines an inherited
+        # key_value block with a subclass one), so this adds only the half of
+        # the code that Cec keeps separately.
+        key_value do
+          map "cec_part",
+              with: { to: :cec_part_to_kv, from: :cec_part_from_kv }
+        end
+
+        def cec_part_to_kv(model, doc)
+          emit_kv(doc, "cec_part", model.cec_part)
+        end
+
+        def cec_part_from_kv(model, value)
+          model.cec_part = Components::Code.new(value: value.to_s)
+        end
+
+        # The document code, synthesised from its two halves:
+        # cec_part + "-" + no_number (e.g. "C22.2-1"). This is the index key.
+        #
+        # It shadows the reader lutaml generates for the inherited `number`
+        # attribute, which is safe because Cec declares no `number` of its own
+        # — the ITU precedent (itu/identifiers/base.rb). `cec_part` and
+        # `no_number` are themselves serialized, so from_hash reproduces the
+        # synthesised value.
+        #
+        # Deliberately NOT memoised: `@number` is the very ivar lutaml uses to
+        # store the inherited attribute, so caching there would both discard a
+        # value assigned through the generated writer and go stale if
+        # `cec_part`/`no_number` were reassigned — and `number` is the relaton
+        # index key. The concatenation is trivial, so there is nothing to save.
+        def number
           return nil unless cec_part && no_number
 
-          @code ||= Components::Code.new(value: "#{cec_part.value}-#{no_number.value}")
+          Components::Code.new(value: "#{cec_part.value}-#{no_number.value}")
         end
       end
     end