relaton 3.0.0.pre.alpha.1 → 3.0.0.pre.alpha.2

data/lib/relaton/ecma/bibliography.rb

@@ -4,38 +4,76 @@ require "mechanize"
 
 module Relaton
   module Ecma
-    # IETF bibliography module
+    # ECMA bibliography module
     module Bibliography
       ENDPOINT = "https://raw.githubusercontent.com/relaton/relaton-data-ecma/refs/heads/v2/"
 
       class << self
+        # @return [Relaton::Index::Type]
+        def index
+          Relaton::Index.find_or_create(
+            :ECMA, url: "#{ENDPOINT}#{INDEXFILE}.zip", file: "#{INDEXFILE}.yaml",
+            pubid_class: ::Pubid::Ecma::Identifier
+          )
+        end
+
+        #
+        # Search the index for a reference.
         #
-        # Search for a reference on the IETF website.
+        # **The pubid is passed to `Index::Type#search`, not the string.**
+        # `search_candidates` narrows only when the argument is not a `String`,
+        # and a block alone never narrows — so the plain string this used to
+        # pass disabled the binary search however the index was built.
+        # `pubid_class:` on the index alone fixes nothing; both had to change
+        # together.
         #
-        # @param ref [String] the ECMA standard reference to look up (e..g "ECMA-6")
+        # A reference pubid cannot parse finds nothing. There is deliberately no
+        # substring-scan fallback here (the OGC idiom): an ECMA id renders as
+        # `ECMA-262 ed17`, so a substring scan would answer a truncated
+        # reference like `ECMA-26` with every ECMA-26x document — an ambiguous
+        # answer is worse than none. By the same trade-off, a reference must now
+        # parse WHOLE: the old regex was unanchored at the end, so
+        # `ECMA-6 (draft)` silently resolved to ECMA-6 and now does not. See
+        # lib/relaton/ecma/CLAUDE.md for the measured table.
         #
-        # @return [Array<Hash>]
+        # The rows are selected with pubid's subset match `pubid === row`, the
+        # default of `Index::Type#search`. An `edition` or a `volume` that the
+        # reference omits matches any value, so a bare `ECMA-269` reaches the
+        # edition rows. pubid declares `part` strict for ECMA, so a bare
+        # `ECMA-418` does not match `ECMA-418-1`. The class must be identical,
+        # which keeps `ECMA-100` and `ECMA TR/100` apart.
+        #
+        # @param ref [String] the ECMA reference (e.g. "ECMA-6", "ECMA-269 ed3 vol2")
+        #
+        # @return [Array<Hash>] matching index rows
         #
         def search(ref)
-          refparts = parse_ref ref
-          return [] unless refparts
+          pubid = parse_ref ref
+          return [] unless pubid
 
-          index = Relaton::Index.find_or_create :ECMA, url: "#{ENDPOINT}#{INDEXFILE}.zip", id_keys: %i[id ed vol]
-          index.search { |row| match_ref refparts, row }
+          index.search(pubid)
         end
 
+        #
+        # Parse a user reference into a `Pubid::Ecma::Identifier`, or nil.
+        #
+        # `Pubid::Ecma` takes the space form (`ECMA 6`) as well as the hyphen
+        # one, and parses the ` ed<N>` / ` vol<N>` suffixes the old bespoke
+        # regex accepted, so every reference shape the flavor has to handle
+        # parses without normalization here.
+        #
+        # @param ref [String]
+        # @return [Pubid::Ecma::Identifier, nil]
+        #
+        # An unrecognized reference **raises**; like ISO, ETSI and 3GPP we let it
+        # propagate. relaton-cli rescues `Pubid::Errors::Error` and renders
+        # `"..." is not a recognized standards identifier`
+        # (`gems/relaton-cli/lib/relaton/cli/command.rb:324`), and `Db#fetch`
+        # logs it through the `StandardError` arm at `lib/relaton/db.rb:122`.
+        # Rescuing here would collapse "this identifier is malformed" into "no
+        # such document", leaving a caller unable to tell them apart.
         def parse_ref(ref)
-          %r{^ECMA[-\s]
-            (?<id>(?:\d[\d-]*|\w+/\d+))
-            (?:\sed(?<ed>[\d.]+))?
-            (?:\svol(?<vol>\d+))?
-          }x.match ref
-        end
-
-        def match_ref(refparts, row) # rubocop:disable Metrics/AbcSize
-          row[:id][:id].match?(/^ECMA[-\s]#{refparts[:id]}/) &&
-            (refparts[:ed].nil? || row[:id][:ed] == refparts[:ed]) &&
-            (refparts[:vol].nil? || row[:id][:vol] == refparts[:vol])
+          ::Pubid::Ecma::Identifier.parse ref.to_s.strip
         end
 
         # @param code [String] the ECMA standard Code to look up (e..g "ECMA-6")
@@ -47,20 +85,50 @@ module Relaton
           result = fetch_doc(code)
           if result
             Util.info "Found: `#{result.docidentifier.first.content}`", key: code
-            # item
           else
             Util.info "Not found.", key: code
           end
           result
         end
 
-        def compare_edition_volume(aaa, bbb)
-          comp = bbb[:id][:ed] <=> aaa[:id][:ed]
-          comp.zero? ? aaa[:id][:vol] <=> bbb[:id][:vol] : comp
+        private
+
+        #
+        # The index row for a reference: latest edition, then lowest volume.
+        #
+        # That is the selection order the bespoke `compare_edition_volume` +
+        # `min` implemented, kept deliberately — but the edition is now compared
+        # segment-wise as INTEGERS. Comparing the rendered strings made "9" beat
+        # "17" and "5" beat "5.1", so 5 of the 421 document families returned an
+        # older document than the reference asked for: ECMA-262 answered ed9
+        # (2018-06) where ed17 (2026-06) exists, ECMA-74 ed9 (2005-12) where
+        # ed22 (2025-12) exists, and likewise 402, 328 and 109.
+        #
+        # `r[:file]` breaks the tie, because the index sort is not stable.
+        #
+        # @param ref [String]
+        # @return [Hash, nil]
+        #
+        def best_match(ref)
+          search(ref).max_by { |r| [edition_key(r[:id].edition), -r[:id].volume.to_i, r[:file]] }
+        end
+
+        #
+        # Order key for an ECMA edition: its dot-separated segments as integers.
+        #
+        # `[]` for an absent edition, which therefore sorts below every present
+        # one — right for the 64 edition-less rows (mementos, a few reports),
+        # none of which shares a document with an edition-bearing row.
+        #
+        # @param edition [String, nil]
+        # @return [Array<Integer>]
+        #
+        def edition_key(edition)
+          edition.to_s.split(".").map(&:to_i)
         end
 
-        def fetch_doc(code) # rubocop:disable Metrics/AbcSize
-          row = search(code).min { |a, b| compare_edition_volume a, b }
+        def fetch_doc(code)
+          row = best_match code
           return unless row
 
           url = "#{ENDPOINT}#{row[:file]}"

data/lib/relaton/ecma/data_fetcher.rb

@@ -18,7 +18,12 @@ module Relaton
       SOURCES = %w[standards technical-reports mementos].freeze
 
       def index
-        @index ||= Relaton::Index.find_or_create :ecma, file: "#{INDEXFILE}.yaml"
+        # `pubid_class:` on the producer too: FileIO#save only calls `to_hash`
+        # for instances of it, so without it the crawl writes v1-shaped rows
+        # under a v2 name, silently.
+        @index ||= Relaton::Index.find_or_create(
+          :ecma, file: "#{INDEXFILE}.yaml", pubid_class: ::Pubid::Ecma::Identifier
+        )
       end
 
       def log_error(msg)
@@ -31,30 +36,84 @@ module Relaton
 
       # @param bib [Relaton::Ecma::ItemData]
       def write_file(bib)
-        file = filename bib
+        # Two distinct ids can sanitize to one filename, in which case the
+        # second document used to be dropped outright. Give it a path of its
+        # own; a genuine duplicate (same id) still resolves to one path and is
+        # still skipped.
+        file = unique_output_file filename_id(bib)
+        # A reserved path only ever belongs to one id, so a hit here is the same
+        # document again. Checked FIRST: a disambiguated path stays != filename
+        # forever, so gating this on that comparison would make a repeat of a
+        # disambiguated id skip the skip and overwrite its own file.
         if @files.include? file
           Util.warn "Duplicate file #{file}"
-        else
-          @files << file
-          File.write file, serialize(bib), encoding: "UTF-8"
-          index.add_or_update index_id(bib), file
+          return
         end
+
+        Util.warn "Duplicate file #{filename bib}; writing #{file} instead" if file != filename(bib)
+        @files << file
+        File.write file, serialize(bib), encoding: "UTF-8"
+        add_to_index bib, file
+      end
+
+      #
+      # Index the document, or record why it could not be indexed.
+      #
+      # An id pubid cannot rebuild is recorded in `@errors` — the inherited
+      # `report_errors` logs a String value as the message, and its GhIssue
+      # channel opens a GitHub issue at the end of the crawl — and the row is
+      # skipped rather than indexed unparsed: `Relaton::Index` rejects the WHOLE
+      # index if a single row fails to deserialize, and its sort calls
+      # `.root.number` on every id. The data file is already written by the
+      # caller, so the document is unindexed, never lost. (The 3GPP/W3C shape.)
+      #
+      # @param bib [Relaton::Ecma::ItemData]
+      # @param file [String] path the document was written to
+      #
+      def add_to_index(bib, file)
+        id = index_id bib
+        return index.add_or_update(id, file) if id
+
+        docid = bib.docidentifier[0]&.content || file
+        @errors[docid.to_s] = "Unparseable primary id `#{docid}` was not indexed (#{file})"
       end
 
       def filename(bib)
+        output_file filename_id(bib)
+      end
+
+      # The docid the filename is derived from.
+      def filename_id(bib)
         id = bib.docidentifier[0].content
         id += " #{bib.edition.content}" if bib.edition
         locality = locality_with_volume bib
         id += " #{locality.reference_from}" if locality
-        output_file id
+        id
       end
 
+      #
+      # The index key: a `Pubid::Ecma::Identifier` carrying the number, the
+      # edition and the volume.
+      #
+      # Built from the MODEL, never from a rendered string — the same three
+      # fields `#filename_id` reads — so the crawl cannot lose a component to a
+      # parse or to a render default. The base identifier is the docidentifier's
+      # own pubid, **duplicated** first: `edition` and `volume` are index
+      # metadata, and every `ECMA-269` volume file carries the bare
+      # `docidentifier: ECMA-269`, so setting them on the shared object would
+      # promote the document's own printed id to the index form.
+      #
+      # @param bib [Relaton::Ecma::ItemData]
+      # @return [Pubid::Ecma::Identifier, nil] nil if pubid rejects the docid
+      #
       def index_id(bib)
-        { id: bib.docidentifier[0].content }.tap do |i|
-          i[:ed] = bib.edition.content if bib.edition
-          locality = locality_with_volume bib
-          i[:vol] = locality.reference_from if locality
-        end
+        pubid = bib.docidentifier[0]&.pubid&.dup
+        return unless pubid
+
+        pubid.edition = bib.edition.content if bib.edition
+        locality = locality_with_volume bib
+        pubid.volume = locality.reference_from if locality
+        pubid
       end
 
       def locality_with_volume(bib)

data/lib/relaton/ecma/docidentifier.rb

@@ -0,0 +1,124 @@
+module Relaton
+  module Ecma
+    # Structured ECMA document identifier. The docid string is the BARE printed
+    # form ("ECMA-269", "ECMA TR/101", "ECMA MEM/2021"), and it is parsed into a
+    # `Pubid::Ecma::Identifier` kept in `@pubid` while the lutaml `content`
+    # attribute stays a plain string for serialization.
+    #
+    # Parsing is **soft**: `content=` lazily requires pubid and rescues
+    # `LoadError`/`StandardError`, so a missing pubid gem or non-ECMA content
+    # leaves `@pubid` nil rather than raising.
+    #
+    # ## Why this class exists, and the one rule that is ECMA-specific
+    #
+    # `Pubid::Ecma::Identifier#to_s` renders the edition and the volume **by
+    # default** — `"ECMA-269 ed3 vol2"`. That default is deliberate on the pubid
+    # side: `Relaton::Index::Type#add_or_update` keys on a bare `id.to_s`, and
+    # 740 of the 804 published rows carry an edition, so without it 383 rows
+    # collapse onto another row's key and vanish from the index.
+    #
+    # A **document's own** docidentifier is the opposite. Every `ECMA-269`
+    # volume file in `relaton-data-ecma` carries `docidentifier: ECMA-269` and
+    # the same title — the edition and the volume are index metadata, not part
+    # of the printed id. So `refresh_content!` must opt OUT of both, or a
+    # mutation would silently promote the stored content to the index form.
+    #
+    # This is the mirror image of `Relaton::ThreeGpp::Docidentifier`, whose
+    # `refresh_content!` must pass `with_publisher: true` because ITS pubid
+    # defaults to the index rendering and its stored content is the fuller one.
+    # The two look contradictory only until you notice each one re-renders what
+    # its own stored `content` already holds.
+    class Docidentifier < Bib::Docidentifier
+      attr_reader :pubid
+
+      # Capture the inherited (LocalizedMarkedUpString) content setter before
+      # overriding #content=, so #refresh_content! can write the re-rendered
+      # string back WITHOUT re-parsing (a re-parse would rebuild @pubid from the
+      # string and discard in-place mutations).
+      alias_method :store_content, :content=
+
+      def initialize(attrs = {}, options = {})
+        pubid = attrs.is_a?(Hash) ? attrs.delete(:pubid) : nil
+        attrs[:content] ||= render(pubid) if pubid
+        super
+        @pubid = pubid if pubid
+      end
+
+      def content=(value)
+        super
+        return unless value
+
+        @pubid = begin
+          require "pubid"
+          ::Pubid::Ecma::Identifier.parse(value.to_s)
+        rescue LoadError, StandardError
+          nil
+        end
+      end
+
+      # `Pubid::Ecma::Identifier` models number/part/subpart/edition/volume, so
+      # the mapping is:
+      #
+      # - **`remove_date!` → clears `edition`.** ECMA has no date component;
+      #   `edition` is its version discriminator, so clearing it yields the
+      #   version-agnostic ("most recent") reference. It is invisible in the
+      #   rendered bare form, which never carried the edition to begin with —
+      #   but the identifier really does change, and a consumer reading
+      #   `#pubid` sees it.
+      # - **`remove_part!` → clears `part`/`subpart`.** Real here:
+      #   "ECMA-418-1" -> "ECMA-418".
+      # - **`to_all_parts!` → both, then wraps `@pubid` in pubid's `AllParts`.**
+      #   `content` stays the plain stripped id — ECMA's own renderer has no
+      #   "(all parts)" marker, and `content` is cached from the pre-wrap
+      #   pubid on purpose. `#pubid` itself, read directly, now answers
+      #   `all_parts? == true` and renders WITH pubid's generic marker
+      #   (`#to_s`), since it's the wrapper.
+      #
+      # All three no-op safely when `@pubid` is nil, so `Bib::ItemData`'s
+      # `#to_all_parts` / `#to_most_recent_reference` never raise on ECMA items.
+
+      def remove_part!
+        clear_attrs! :part
+      end
+
+      def remove_date!
+        clear_attrs! :edition
+      end
+
+      def to_all_parts!
+        return if !@pubid || @pubid.all_parts?
+
+        # `#exclude` (no args) rebuilds a full independent copy — `remove_part!`
+        # / `remove_date!` mutate `@pubid` in place, so a bare reference here
+        # would lose the original part/edition to that mutation too.
+        original = @pubid.exclude
+        remove_part!
+        remove_date!
+        @pubid = original.to_all_parts
+      end
+
+      private
+
+      def clear_attrs!(*attrs)
+        return unless @pubid
+
+        cleared = attrs.select { |attr| @pubid.respond_to?("#{attr}=") }
+        return if cleared.empty?
+
+        cleared.each { |attr| @pubid.public_send("#{attr}=", nil) }
+        @pubid.subpart = nil if attrs.include?(:part) && @pubid.respond_to?(:subpart=)
+        refresh_content!
+      end
+
+      def refresh_content!
+        store_content(render(@pubid)) if @pubid
+      end
+
+      # The bare document form. See the class comment for why both flags are
+      # opted out of, and why 3GPP's twin does the opposite.
+      def render(pubid)
+        pubid.to_s(with_edition: false, with_volume: false)
+      end
+    end
+  end
+end

data/lib/relaton/ecma/item.rb

@@ -1,3 +1,4 @@
+require_relative "docidentifier"
 require_relative "ext"
 
 module Relaton
@@ -5,6 +6,7 @@ module Relaton
     class Item < Bib::Item
       model ItemData
 
+      attribute :docidentifier, Docidentifier, collection: true, initialize_empty: true
       attribute :ext, Ext
     end
   end

data/lib/relaton/ecma/memento_parser.rb

@@ -21,7 +21,7 @@ module Relaton
 
       private
 
-      # @return [Array<Relaton::Bib::Docidentifier>]
+      # @return [Array<Relaton::Ecma::Docidentifier>]
       def fetch_docidentifier
         code = "ECMA MEM/#{@hit.at('div[1]//p').text}"
         docid = super(code)

data/lib/relaton/ecma/page_fetcher.rb

@@ -1,6 +1,8 @@
 module Relaton
   module Ecma
     class PageFetcher
+      RETRIES = 3
+
       def initialize
         @agent = Mechanize.new
         @agent.user_agent_alias = Mechanize::AGENT_ALIASES.keys[rand(21)]
@@ -9,18 +11,28 @@ module Relaton
       #
       # Get page with retries
       #
+      # A failed fetch must raise, not fall out of the loop. `RETRIES.times`
+      # returns its receiver, so the exhausted loop used to hand the caller the
+      # Integer 3 as if it were a page, and `StandardParser#fetch_title`
+      # reported the transport error as `undefined method 'xpath' for an
+      # instance of Integer`. `DataFetcher#html_index` already rescues per hit,
+      # so one unreachable page is skipped with a readable message.
+      #
       # @param [String] url url to fetch
       #
       # @return [Mechanize::Page] document
+      # @raise [Relaton::RequestError] after RETRIES attempts
       #
       def get(url)
-        3.times do |n|
+        error = nil
+        RETRIES.times do |n|
           sleep n
-          doc = @agent.get url
-          return doc
+          return @agent.get url
         rescue StandardError => e
+          error = e
           Util.error e.message
         end
+        raise Relaton::RequestError, "Could not access #{url}: #{error.message}"
       end
     end
   end

data/lib/relaton/ecma/parser_common.rb

@@ -14,11 +14,11 @@ module Relaton
         [Bib::Contributor.new(organization: org, role: [role])]
       end
 
-      # @return [Array<Relaton::Bib::Docidentifier>]
+      # @return [Array<Relaton::Ecma::Docidentifier>]
       def fetch_docidentifier(id = nil)
         return [] if id.nil? || id.empty?
 
-        [Bib::Docidentifier.new(type: "ECMA", content: id, primary: true)]
+        [Docidentifier.new(type: "ECMA", content: id, primary: true)]
       end
 
       def fetch_ext

data/lib/relaton/ecma/processor.rb

@@ -9,6 +9,7 @@ module Relaton
         @defaultprefix = /^ECMA(-|\s)/
         @idtype = "ECMA"
         @datasets = %w[ecma-standards]
+        @pubid_flavor = :Ecma
       end
 
       # @param code [String]
@@ -59,7 +60,9 @@ module Relaton
       #
       def remove_index_file
         require_relative "../ecma"
-        Relaton::Index.find_or_create(:ECMA, url: true, file: "#{INDEXFILE}.yaml").remove_file
+        Relaton::Index.find_or_create(
+          :ECMA, url: true, file: "#{INDEXFILE}.yaml"
+        ).remove_file
       end
     end
   end

data/lib/relaton/ecma/standard_parser.rb

@@ -26,7 +26,7 @@ module Relaton
         @translation_source ||= parse_translation_source
       end
 
-      # @return [Array<Relaton::Bib::Docidentifier>]
+      # @return [Array<Relaton::Ecma::Docidentifier>]
       def fetch_docidentifier
         result = super(@hit.text)
         @errors[:standard_docidentifier] &&= result.empty?
@@ -83,7 +83,7 @@ module Relaton
           ref, ed, date, vol = edition_parser.edition_id_parts rel.at("span").text
           next if ed.nil? || ed.empty?
 
-          docid = Bib::Docidentifier.new(type: "ECMA", content: ref, primary: true)
+          docid = Docidentifier.new(type: "ECMA", content: ref, primary: true)
           source = rel.xpath("span/a").map { |l| Bib::Uri.new type: "pdf", content: l[:href] }
           edition = Bib::Edition.new content: ed
           extent = edition_parser.create_extent(vol)

data/lib/relaton/ecma.rb

@@ -1,3 +1,8 @@
+# Not lazy: DataFetcher names ::Pubid::Ecma::Identifier as the index
+# `pubid_class:`, and Docidentifier parses every docid through it.
+# (The IANA/IHO/IALA/OGC form; spec/relaton/lazy_loading_spec.rb guards that
+# this file is not itself loaded when a Db is built.)
+require "pubid"
 require "relaton/index"
 require "relaton/bib"
 require_relative "version"
@@ -10,7 +15,11 @@ require_relative "ecma/bibliography"
 
 module Relaton
   module Ecma
-    INDEXFILE = "index-v1"
+    # The one index this flavor builds and reads: pubid-keyed rows
+    # (`_type: pubid:ecma:*`), via `pubid_class: ::Pubid::Ecma::Identifier`.
+    # `relaton-data-ecma`'s crawler derives the legacy `index-v1` from these
+    # rows for released consumers, so it is not produced or read here.
+    INDEXFILE = "index-v2".freeze
 
     # Returns hash of XML reammar
     # @return [String]

data/lib/relaton/etsi/bibliography.rb

@@ -9,8 +9,15 @@ module Relaton
       # @param text [String]
       # @return [Relaton::Etsi::ItemData, nil]
       def search(text) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
-        index = Relaton::Index.find_or_create :etsi, url: "#{SOURCE}index-v1.zip", file: INDEX_FILE
-        row = index.search(text).min_by { |r| r[:id] }
+        # An unrecognized reference raises Pubid::Errors::ParseError; like
+        # ISO we let it propagate — the CLI turns it into a friendly message
+        # and API callers rescue it themselves. Valid partial refs parse with
+        # the omitted refinements (version/date/part) left blank.
+        pubid = ::Pubid::Etsi.parse text
+
+        index = Relaton::Index.find_or_create :etsi, url: "#{SOURCE}#{INDEXFILE}.zip", file: "#{INDEXFILE}.yaml",
+                                                     pubid_class: ::Pubid::Etsi::Identifier
+        row = best_match(index, pubid)
         return unless row
 
         url = "#{SOURCE}#{row[:file]}"
@@ -24,6 +31,64 @@ module Relaton
         raise Relaton::RequestError, e.message
       end
 
+      # Match the reference against the index and return the most recent edition.
+      #
+      # The rows are selected with pubid's subset match `pubid === row`. A
+      # version or a date that the reference omits matches any value, so a
+      # bare `ETSI GS ZSM 012` matches every edition, while a fully-qualified
+      # ref matches only that edition. The class must be identical, so a base
+      # reference such as `ETSI ETR 310` does not reach its amendment or
+      # corrigendum (`ETR 310/C1`).
+      # The pubid — not a String — is passed to `index.search` so the index
+      # narrows candidates by number via binary search; each row's `:id` is
+      # already a Pubid::Etsi identifier (deserialized via `pubid_class`).
+      # `max_by` on `edition_key` picks the latest edition among the matches.
+      #
+      # pubid declares `parts` strict for ETSI, so a part-less reference asks
+      # for every part by matching each row **without its parts** (see
+      # #comparable). `#to_all_parts` cannot serve here: a
+      # `Pubid::AllPartsIdentifier` compares the document alone, so it also
+      # drops the version and the date, and
+      # `ETSI GR ZSM 011 V1.1.1 (2023-02)` would answer with V2.1.1.
+      #
+      # @param index [Relaton::Index::Type]
+      # @param pubid [::Pubid::Etsi::Identifier]
+      # @return [Hash, nil] the winning index row (`{ id:, file: }`)
+      def best_match(index, pubid)
+        all_parts = pubid.code&.parts.to_a.empty?
+        index.search(pubid) { |row| pubid === comparable(row[:id], all_parts) }
+             .max_by { |row| edition_key(row[:id]) }
+      end
+
+      # The row as the reference sees it: without its parts when the reference
+      # names none, unchanged otherwise. `#exclude` returns a copy, so the
+      # cached index id is untouched.
+      #
+      # @param id [::Pubid::Etsi::Identifier]
+      # @param all_parts [Boolean] the reference names no part
+      # @return [::Pubid::Etsi::Identifier]
+      def comparable(id, all_parts)
+        all_parts ? id.exclude(:part, :subpart, :parts) : id
+      end
+
+      # Sort key for one edition: the version numbers, then the publication date.
+      #
+      # ETSI versions are not zero-padded, so a comparison of the rendered id
+      # orders `V9.0.0` above `V19.0.0` and `ed.9` above `ed.11`, and a bare
+      # reference then resolves to an old edition. `Pubid::Etsi::Identifier` is
+      # not `Comparable` and its `<=>` returns nil, so the key comes from the
+      # parsed components: `version.version` holds the bare numbers (`"19.0.0"`,
+      # or `"9"` for the `ed.9` form) and `date` renders as `yyyy-mm`. Both
+      # delegate to `base` on a corrigendum/amendment id, so every row shape
+      # keys the same way. A missing version or date gives `[]` / `""`, which
+      # sort below any real value — hence the `.to_s` outside each `&.` chain.
+      #
+      # @param id [::Pubid::Etsi::Identifier]
+      # @return [Array(Array<Integer>, String)]
+      def edition_key(id)
+        [(id.version&.version).to_s.split(".").map(&:to_i), id.date.to_s]
+      end
+
       # @param ref [String] the ETSI standard Code to look up
       # @param year [String, nil] year
       # @param opts [Hash] options