relaton 3.0.6 → 3.0.8

data/lib/relaton/cli/util.rb

@@ -0,0 +1,8 @@
+module Relaton
+  module Cli
+    module Util
+      extend Relaton::Bib::Util
+      PROGNAME = "relaton-cli".freeze
+    end
+  end
+end

data/lib/relaton/cli/version.rb

@@ -0,0 +1,11 @@
+# relaton-cli ships in lockstep with the combined `relaton` gem, so its version
+# is that gem's version — the single source of truth in Relaton::VERSION. relaton
+# is a hard runtime dependency, so requiring its lightweight version file always
+# resolves. Don't hardcode a string here; it would silently drift on a bump.
+require "relaton/version"
+
+module Relaton
+  module Cli
+    VERSION = Relaton::VERSION
+  end
+end

data/lib/relaton/cli/xml_convertor.rb

@@ -0,0 +1,47 @@
+require "nokogiri"
+require "relaton/cli/base_convertor"
+
+module Relaton
+  module Cli
+    class XMLConvertor < Relaton::Cli::BaseConvertor
+      def to_yaml
+        convert_and_write(file_content, :to_yaml)
+      end
+
+      # Convert to YAML
+      #
+      # This interface allow us to convert any XML file to YAML.
+      # It only require us to provide a valid XML file and it can
+      # do converstion using default attributes, but it also allow
+      # us to provide custom options to customize this converstion
+      # process.
+      #
+      # @param file [File] The complete path to a XML file
+      # @param options [Hash] Options as hash key, value pairs.
+      #
+      def self.to_yaml(file, options = {})
+        new(file, options).to_yaml
+      end
+
+      private
+
+      def default_ext
+        "yaml"
+      end
+
+      # @param content [Nokogiri::XML::Document]
+      # @return [Hash]
+      def convert_content(content)
+        if %w[bibitem bibdata].include? content.root.name
+          Bibdata.from_xml(content)
+        else
+          Bibcollection.from_xml(content)
+        end
+      end
+
+      def file_content
+        Nokogiri::XML(File.read(file, encoding: "utf-8"))
+      end
+    end
+  end
+end

data/lib/relaton/cli/xml_to_html_renderer.rb

@@ -0,0 +1,117 @@
+require "nokogiri"
+require "liquid"
+
+module Relaton::Cli
+  class XmlToHtmlRenderer
+    def initialize(liquid_dir: nil, stylesheet: nil)
+      @liquid_dir = liquid_dir
+      @stylesheet = read_file(stylesheet)
+      init_liquid_template_and_filesystem
+    end
+
+    # @param index_xml [String] Relaton XML
+    # @return [String] HTML
+    def render(index_xml)
+      Liquid::Template
+        .parse(template)
+        .render(build_liquid_document(index_xml))
+    end
+
+    def uri_for_extension(uri, extension)
+      uri&.sub(/\.[^.]+$/, ".#{extension}")
+    end
+
+    # Render HTML
+    #
+    # This interface allow us to convert a Relaton XML to HTML
+    # using the specified liquid template and stylesheets. It
+    # also do some minor clean during this conversion.
+    #
+    # @param file [String] Relaton XML
+    # @param options [Hash]
+    # @return [String] HTML
+    def self.render(file, options)
+      new(**options).render(file)
+    end
+
+    private
+
+    attr_reader :stylesheet, :liquid_dir, :template
+
+    def read_file(file)
+      File.read(file, encoding: "utf-8")
+    end
+
+    # rubocop:disable Metrics/MethodLength
+    # @param source [String] Relaton XML
+    def build_liquid_document(source)
+      bibcollection = build_bibcollection(source)
+      hash_to_liquid(
+        depth: 2,
+        css: stylesheet,
+        title: bibcollection.title,
+        date: DateTime.now.to_s,
+        author: bibcollection.author,
+        documents: document_items(bibcollection)
+      )
+    end
+
+    def init_liquid_template_and_filesystem
+      file_system = Liquid::LocalFileSystem.new(liquid_dir)
+      @template = read_file(file_system.full_path("index"))
+
+      Liquid::Template.file_system = file_system
+    end
+
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+    # TODO: This should be recursive, but it's not
+    # @param hash [Hash]
+    # @option hash [Integer] :dept
+    # @option hash [String] :css path to stylesheet file
+    # @option hash [String] :title
+    # @option hash [String] :author
+    # @option hash [Array<Hash>] :documents
+    #
+    # @return [Hash]
+    def hash_to_liquid(hash)
+      hash.map do |key, value|
+        case key
+        when "title"
+          if value.is_a?(Array)
+            title = value.detect { |t| t["type"] == "main" } || value.first
+            v = title ? title["content"] : nil
+          elsif value.is_a?(Hash) then v = value["content"]
+          else v = value
+          end
+        when "docidentifier"
+          did = if value.is_a?(Array)
+                  value.detect { |d| (d["id"] || d["content"]).to_s !~ /^(http|https):\/\// } ||
+                    value.first
+                else value
+                end
+          v = did
+        else v = value
+        end
+        [key.to_s, empty2nil(v)]
+      end.to_h
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
+    def empty2nil(value)
+      value unless value.is_a?(String) && value.empty? && !value.nil?
+    end
+
+    # @param source [String] Relaton XML
+    # @return [Relaton::Bibcollection]
+    def build_bibcollection(source)
+      Relaton::Bibcollection.from_xml(Nokogiri::XML(source))
+    end
+
+    # @param bibcollection [Relaton::Bibcollection]
+    # @return [Array<Hash>]
+    def document_items(bibcollection)
+      bibcollection.to_h["root"]["items"].map { |item| hash_to_liquid(item) }
+    end
+  end
+end

data/lib/relaton/cli/yaml_convertor.rb

@@ -0,0 +1,102 @@
+require "yaml"
+require "relaton/cli/base_convertor"
+require "relaton/bib"
+
+module Relaton
+  module Cli
+    class YAMLConvertor < Relaton::Cli::BaseConvertor
+      def to_xml
+        if writable
+          convert_and_write(file_content, :to_xml)
+        else
+          convert_content(file_content).to_xml date_format: :full, bibdata: true
+        end
+      end
+
+      class << self
+        # Convert to XML
+        #
+        # This interface allow us to convert any YAML file to XML.
+        # It only require us to provide a valid YAML file and it can
+        # do converstion using default attributes, but it also allow
+        # us to provide custom options to customize this converstion
+        # process.
+        #
+        # @param file [File] The complete path to a YAML file
+        # @param options [Hash] Options as hash key, value pairs.
+        #
+        def to_xml(file, options = {})
+          new(file, options).to_xml
+        end
+
+        # @param content [Hash] document in YAML format
+        # @return [RelatonBib::BibliographicItem,
+        #   RelatonIso::IsoBiblioraphicItem]
+        def convert_single_file(content)
+          flavor = content.dig("ext", "flavor") || doctype(content["docidentifier"])
+          if (processor = Relaton::Db::Registry.instance.by_type(flavor))
+            begin
+              processor.from_yaml content.to_yaml
+            rescue RuntimeError
+              Relaton::Bib::Item.from_yaml(content.to_yaml)
+            end
+          else
+            Relaton::Bib::Item.from_yaml(content.to_yaml)
+          end
+        end
+
+        private
+
+        # @param content [Hash]
+        # @return [String]
+        def doctype(docid)
+          did = docid.is_a?(Array) ? docid.fetch(0) : docid
+          return unless did
+
+          did["type"] || did.fetch("content")&.match(/^\w+/)&.to_s
+        end
+      end
+
+      private
+
+      def default_ext
+        "rxl"
+      end
+
+      def file_content
+        date_to_string(YAML.load_file(file))
+      end
+
+      def date_to_string(obj)
+        if obj.is_a? Hash
+          obj.reduce({}) do |memo, (k, v)|
+            memo[k] = date_to_string(v)
+            memo
+          end
+        elsif obj.is_a? Array
+          obj.reduce([]) { |memo, v| memo << date_to_string(v) }
+        else
+          obj.is_a?(Date) ? obj.to_s : obj
+        end
+      end
+
+      def convert_collection(content)
+        if content.has_key?("root")
+          content["root"]["items"] = content["root"]["items"].map do |i|
+            # RelatonBib::HashConverter::hash_to_bib(i)
+            self.class.convert_single_file(i)
+          end
+          Relaton::Bibcollection.new(content["root"])
+        end
+      end
+
+      def xml_content(_raw_file)
+        convert_content(file_content).to_xml(date_format: :full, bibdata: true)
+      end
+
+      def convert_content(content)
+        convert_collection(content) || self.class.convert_single_file(content)
+      end
+    end
+  end
+end

data/lib/relaton/cli.rb

@@ -0,0 +1,113 @@
+require "fileutils"
+require "thor"
+require "thor/hollaback"
+require_relative "cli/version"
+require_relative "cli/util"
+require_relative "cli/command"
+
+module Relaton
+  def self.db(dir = nil)
+    Cli.relaton dir
+  end
+
+  module Cli
+    class RelatonDb
+      include Singleton
+
+      DBCONF = "#{Dir.home}/.relaton/dbpath".freeze
+
+      # @param dir [String, nil]
+      # @return [Relaton::Db]
+      def db(dir)
+        if dir
+          FileUtils.mkdir_p File.dirname(DBCONF)
+          File.write DBCONF, dir, encoding: "UTF-8"
+          @db = Relaton::Db.new dir, nil
+        else
+          @db ||= Relaton::Db.new dbpath, nil
+        end
+      end
+
+      private
+
+      # @return [String] path to DB
+      def dbpath
+        if File.exist?(DBCONF)
+          File.read(DBCONF, encoding: "UTF-8")
+        else "#{Dir.home}/.relaton/cache"
+        end
+      end
+    end
+
+    class << self
+      def version
+        require "relaton/bib"
+        registry = Relaton::Db::Registry.instance
+        # Every flavor now ships inside the single `relaton` gem, so they all
+        # report Relaton::VERSION rather than a separate gem version.
+        puts "CLI => #{Relaton::Cli::VERSION}"
+        puts "relaton => #{Relaton::VERSION}"
+        puts "relaton-bib => #{Relaton::VERSION}"
+        registry.processors.each_key do |k|
+          name = k.to_s.sub("_", "-")
+          puts "#{name} => #{Relaton::VERSION}"
+        end
+      end
+
+      def start(arguments)
+        Relaton::Cli::Command.start(arguments)
+      end
+
+      # Relaton
+      #
+      # Based on current setup, we need to initiate a Db instance to
+      # register all of it's supported processor backends. To make it
+      # easier we have added it as a class method so we can use this
+      # whenever necessary.
+      #
+      # @param dir [String, nil]
+      # @return [Relaton::Db]
+      def relaton(dir)
+        RelatonDb.instance.db dir
+      end
+
+      # @param content [Nokogiri::XML::Document]
+      # @return [RelatonBib::BibliographicItem,
+      #   RelatonIsoBib::IsoBibliongraphicItem]
+      def parse_xml(doc)
+        doc.remove_namespaces! if doc.respond_to?(:remove_namespaces!)
+        if (proc = Cli.processor(doc))
+          proc.from_xml(doc.to_s)
+        else
+          Relaton::Bib::Item.from_xml(doc.to_s) rescue nil
+        end
+      end
+
+      # @param doc [Nokogiri::XML::Element]
+      # @return [RelatonIso::Processor, RelatonIec::Processor,
+      #   RelatonNist::Processor, RelatonIetf::Processot,
+      #   RelatonItu::Processor, RelatonGb::Processor,
+      #   RelatonOgc::Processor, RelatonCalconnect::Processor]
+      def processor(doc)
+        docid = doc.at "docidentifier"
+        proc = get_proc docid
+        return proc if proc
+
+        Relaton::Db::Registry.instance.by_type(docid&.text&.match(/^\w+/)&.to_s)
+      end
+
+      private
+
+      # @param doc [Nokogiri::XML::Element]
+      # @return [RelatonIso::Processor, RelatonIec::Processor,
+      #   RelatonNist::Processor, RelatonIetf::Processot,
+      #   RelatonItu::Processor, RelatonGb::Processor,
+      #   RelatonOgc::Processor, RelatonCalconnect::Processor]
+      def get_proc(docid)
+        return unless docid && docid[:type]
+
+        Relaton::Db::Registry.instance.by_type(docid[:type])
+      end
+    end
+  end
+end

data/lib/relaton/doi/CLAUDE.md

@@ -38,7 +38,7 @@ Key classes in `lib/relaton/doi/`:
 - **RSpec** with `expect` syntax only (monkey patching disabled)
 - **VCR** cassettes in `spec/vcr_cassettes/` record Crossref HTTP responses and are never auto-rerecorded (see root `CLAUDE.md`). Because Crossref rate-limits, **re-record this suite alone** — under parallel `rake spec` it answers 429 and the empty body gets recorded as if it were data.
 - **XML fixtures** in `spec/fixtures/` — expected output XML files. The `read_fixture` helper auto-substitutes today's date into `<fetched>` tags.
-- **equivalent-xml** gem for XML comparison in integration tests
+- **canon** gem for XML comparison in integration tests
 - Integration tests in `spec/relaton/doi_spec.rb` cover 40+ document types via VCR cassettes
 - Unit tests in `spec/relaton/doi/parser_spec.rb` test Parser methods directly with hash inputs
 

data/lib/relaton/element_finder.rb

@@ -0,0 +1,29 @@
+module Relaton
+  module ElementFinder
+    attr_reader :document
+
+    def find_text(xpath, element = nil)
+      find(xpath, element)&.text
+    end
+
+    def find_html(xpath, element = nil)
+      find(xpath, element)&.inner_html
+    end
+
+    def find(xpath, element = nil)
+      (element || document).at(apply_namespace(xpath))
+    end
+
+    def find_xpath(xpath, element = nil)
+      element&.xpath(apply_namespace(xpath))
+    end
+
+    def apply_namespace(xpath)
+      xpath
+        .gsub(%r{/([a-zA-Z])}, "/xmlns:\\1")
+        .gsub(%r{::([a-zA-Z])}, "::xmlns:\\1")
+        .gsub(%r{\[([a-zA-Z][a-z0-9A-Z@/]* ?=)}, "[xmlns:\\1")
+        .gsub(%r{\[([a-zA-Z][a-z0-9A-Z@/]*\])}, "[xmlns:\\1")
+    end
+  end
+end

data/lib/relaton/gb/CLAUDE.md

@@ -44,4 +44,4 @@ GB parses identifiers with `Pubid::Gb::Identifier`. It publishes no index, so it
 
 ## Testing
 
-RSpec with WebMock + VCR (cassettes in `spec/vcr_cassettes/`). Network is blocked via WebMock. SimpleCov and equivalent-xml are loaded via `spec/support/`. No index fixture — GB is scraped, not indexed; `spec/fixtures/` holds XML/YAML round-trip data.
+RSpec with WebMock + VCR (cassettes in `spec/vcr_cassettes/`). Network is blocked via WebMock. SimpleCov and canon are loaded via `spec/support/`. No index fixture — GB is scraped, not indexed; `spec/fixtures/` holds XML/YAML round-trip data.

data/lib/relaton/ietf/CLAUDE.md

@@ -375,7 +375,7 @@ and the affected files come through with their real characters —
 - **An oracle for `read_bibxml` must read binary.** The method is byte-verbatim (`File.binread`), so comparing it against `File.read(path, encoding: "UTF-8")` compares two different strings **on Windows only**: Ruby opens a file in text mode there and collapses CRLF to LF. The repo declares no `.gitattributes` and the GitHub Windows runner image defaults to `core.autocrlf=true`, so a fixture stored with LF is checked out CRLF — which failed all three `windows-latest` jobs while every Linux and macOS job passed. Use `File.read(path, mode: "rb", encoding: "UTF-8")`. macOS cannot reproduce this by checking the fixture out as CRLF, because its text-mode read does not translate; emulate Windows explicitly with `File.read(path, encoding: "UTF-8", universal_newline: true)`. The two `keeps CRLF line endings verbatim` examples pin the contract with `binwrite` temp files, independent of the checkout — one per branch, since the CP1252 repair rebuilds the string run by run and is where a line ending is likeliest to be lost. Note that a byte-equality oracle alone cannot catch a dropped `force_encoding`: `rfc.xml` is pure ASCII, and Ruby compares two ASCII-only strings as equal across encodings, so the example asserts `encoding` separately.
 - **Schema validation** via `ruby-jing` against the shared RNG grammars in the repo-root `grammar/` (`Jing.new "../../grammar/relaton-ietf-compile.rng"`, relative to the suite's CWD `spec/ietf/`)
 - **Shared examples** for org/person parsing in `bibxml_parser_spec.rb` (`parse_org`, `parse_person`)
-- **`equivalent-xml`** gem used for XML comparison (`be_equivalent_to` matcher)
+- **`canon`** gem used for XML comparison (`be_equivalent_to` matcher)
 
 ## RuboCop
 

data/lib/relaton/iho/CLAUDE.md

@@ -55,11 +55,11 @@ In `item.rb`, `require_relative "relation"` is placed **after** the `Item` class
 
 `Bibliography.search`/`.get` fetches YAML from the relaton-data-iho GitHub repo via `Relaton::Index`, then deserializes into model objects.
 
-**Editions and series.** The pubid `version` is the edition (`IHO B-12 3.0.0`; the grammar takes `a.b.c` only). A reference with no version answers with the **latest** edition: `recency_key` compares the segments as integers (`2.10.0` after `2.9.0`). It used to be `min_by` on the string, which returned the oldest.
+**Editions and series (the pubid 2.0.5 component model, relaton#440).** The pubid attribute is `edition` (dotted `a.b.c`, `IHO B-12 3.0.0`; the pre-440 name `version` is gone). A reference with no edition answers with the **latest**: `recency_key` compares the segments as integers (`2.10.0` after `2.9.0`). It used to be `min_by` on the string, which returned the oldest.
 
-**Series are identified by year or volume, not an edition (relaton#407).** B-7, P-5 and P-6 carry a `year` (`IHO P-5 2024`), the IHR (P-1) a `volume` with an optional `issue` (`IHO P-1 Vol. 30 (2)`) — plain scalars added by pubid#635, mutually exclusive with `version` (the grammar's tail picks exactly one). The same `recency_key` orders each kind numerically, so a bare series query answers with the latest year/volume/issue. Matching (`pubid_match?`) treats a component the query omits as a wildcard: `IHO P-1 Vol. 30` matches any issue of volume 30. The comparison runs through pubid's `#exclude` — excluding `:volume` nils the `issue` with it (the pair is one scalar cluster) — the way BIPM's `stem_keys` does. The subdivisions (part/appendix/annex/supplement) stay strict: this flavor cannot use the `===` subset match, because pubid does not declare `subset_strict` for IHO's subdivisions and a nil `part` would read as "any part" (`IHO S-100` would answer with a part row).
+**Serial locators are volumes (relaton#440 unified the year locators of relaton#407).** The yearbook year IS a volume: `IHO P-5 Vol. 2020` is canonical, the bare-year faces (`P-5 2020`, `P-5/2020`) parse as legacy aliases into the same `volume`, and the IHR is `P-1 Vol. 30` with `Issue 1` (no parens) or the short slash form `P-1/30`. A bare series query answers with the latest volume/issue. **Components can publish separately and carry their own edition:** `IHO S-66 Suppl 1 2.0.0` gives `supplement_edition`, `S-100 Part S-102 1.0.0` gives `part_edition`, annexes likewise — and the publication years in parens (`S-52 Annex A 4.0.3 (2021)`) are `*_year` metadata, not identity: a stated year pins the record, an omitted one wildcards. Matching (`pubid_match?`) treats a discriminator the query omits as a wildcard: `IHO P-1 Vol. 30` matches any issue of volume 30. The comparison runs through pubid's `#exclude` — excluding `:volume` nils the `issue`, excluding an `:appendix` nils its `appendix_subnumber` (scalar clusters) — the way BIPM's `stem_keys` does. The subdivisions (part/appendix/annex/supplement) stay strict: this flavor cannot use the `===` subset match, because pubid does not declare `subset_strict` for IHO's subdivisions and a nil `part` would read as "any part" (`IHO S-100` would answer with a part row).
 
-**The edition reaches the index only through the committed row.** A record prints `B-12` and keeps its edition in `edition:`, so `relaton index` cannot read a version from the docid. `MachineIndex#refine` (relaton-cli) takes the committed `index-v3.yaml` row when it adds only a key in `REFINABLE_KEYS` to the parse — `version`/`edition`/`volume`/`year`/`issue` (relaton#407 added the year/issue pair for the series rows). Before that, the Pages index (generated 2026-10-29) had no `version` in any of its 325 rows, so every versioned reference answered not-found (relaton-data-iho#20). The suite did not see it: `spec/fixtures/index-v3.zip` is the committed index, which has versions. The suite's fixture currently carries the **re-keyed** series rows (year/volume) ahead of the data repo: the placeholder `1.0.0` rows for p-1/p-1-2x/p-5/p-6/b-7 are replaced by `year`/`volume` rows — refresh the fixture from the live published zip once relaton-data-iho re-keys, and reconcile any file-name drift then.
+**The edition reaches the index only through the committed row.** A record prints `B-12` and keeps its edition in `edition:`, so `relaton index` cannot read a version from the docid. `MachineIndex#refine` (relaton-cli) takes the committed `index-v3.yaml` row when it adds only a key in `REFINABLE_KEYS` to the parse — `version`/`edition`/`volume`/`year`/`issue` (relaton#407 added the year/issue pair for the series rows). Before that, the Pages index (generated 2026-10-29) had no `version` in any of its 325 rows, so every versioned reference answered not-found (relaton-data-iho#20). The suite did not see it: `spec/fixtures/index-v3.zip` is the committed index, which has versions. The suite's fixture carries the #48-era re-keyed series rows migrated to the #440 keys (`version`→`edition`/`<component>_edition`, year locators→`volume`; `support/migrate_index_fixture.rb` did the one-shot migration) — refresh the fixture from the live published zip once relaton-data-iho round 2 republishes, and reconcile any file-name drift then.
 
 ### Test Infrastructure
 

data/lib/relaton/iho/bibliography.rb

@@ -96,31 +96,37 @@ module Relaton
           )
         end
 
-        # The sort key for the latest record in a bucket (relaton#407). Each
-        # IHO identity carries exactly one trailing discriminator — a dotted
-        # `version` (an edition, `B-12 3.0.0`), a series `year` (`P-5 2024`)
-        # or a series `volume` with its `issue` (`P-1 Vol. 30 (2)`) — and the
-        # key orders by that component, numerically: version segments compare
-        # as integers (2.10.0 is later than 2.9.0), as do year, volume and
-        # issue. A row with no discriminator at all is the oldest. Rows in
-        # one bucket share the discriminator kind once the data is keyed;
-        # while kinds coexist the array compare is deterministic, and a
-        # year's bare [2024] beats a placeholder edition's [1, 0, 0].
+        # The sort key for the latest record in a bucket (relaton#407,
+        # reshaped by relaton#440's component model). Volume-locator series
+        # (P-1, P-5) carry a `volume` with an optional `issue` — the
+        # yearbook year IS a volume (`P-5 Vol. 2020`; the bare-year faces
+        # of the #48 re-key parse as legacy aliases), so the year locators
+        # fold into the volume ordering. Edition-keyed products carry a
+        # dotted `edition` (`B-12 3.0.0`), and a component published
+        # separately carries its own edition (`S-66 Suppl 1 2.0.0` →
+        # `supplement_edition`). Every component compares numerically
+        # segment by segment (2.10.0 after 2.9.0); a row with no
+        # discriminator at all is the oldest.
         def recency_key(id)
-          if id.year
-            [id.year.to_i]
-          elsif id.volume
+          if id.volume
             [id.volume.to_i, id.issue.to_i]
           else
-            id.version.to_s.split(".").map(&:to_i)
+            ed = id.edition || id.supplement_edition || id.part_edition ||
+              id.annex_edition || id.appendix_edition || id.volume_edition
+            ed.to_s.split(".").map(&:to_i)
           end
         end
 
-        # The components that make an IHO document the one it is beyond the
-        # series and subdivisions: the edition (`version`), or — for the
-        # series identified by year or volume instead (B-7, P-1, P-5, P-6;
-        # relaton#407) — the `year` or the `volume`/`issue` pair.
-        DISCRIMINATOR_KEYS = %i[version year volume issue].freeze
+        # The identity components beyond the series and subdivisions
+        # (relaton#440): the base `edition` — or the component-level
+        # edition when the component publishes separately — plus the
+        # volume/issue pair. The publication years (`year`, `*_year`) are
+        # metadata, not identity: a stated year pins the record, an
+        # omitted one wildcards it.
+        DISCRIMINATOR_KEYS = %i[
+          edition volume issue
+          supplement_edition part_edition annex_edition appendix_edition volume_edition
+        ].freeze
 
         # Both `row_id` and `query` are Pubid::Iho::Identifiers::* instances.
         # Class identity pins the series (S/P/M/B/C). Subdivision keys
@@ -132,21 +138,29 @@ module Relaton
         # so `IHO S-100` would answer with a part row.
         #
         # The discriminator keys stay nil-tolerant: an unqualified `IHO B-11`
-        # finds the latest edition, an unqualified `IHO P-5` the latest year,
-        # and `IHO P-1 Vol. 30` any issue of that volume — while a stated
-        # component must match exactly. The comparison runs through pubid's
-        # `#exclude` (the primitive `matches?` is built on), so the rules the
-        # flavor declares there ride along: excluding `:volume` nils the
-        # `issue` with it. `stem_keys` in the BIPM flavor is the same shape.
+        # finds the latest edition, an unqualified `IHO P-5` the latest
+        # volume (the yearbook year — relaton#440 folded the year
+        # locators in), and `IHO P-1 Vol. 30` any issue of that volume —
+        # while a stated component must match exactly. The comparison runs
+        # through pubid's `#exclude` (the primitive `matches?` is built
+        # on), so the rules the flavor declares there ride along: excluding
+        # `:volume` nils the `issue` with it, and excluding an appendix
+        # nils its subnumber — the scalar clusters are one unit. `stem_keys`
+        # in the BIPM flavor is the same shape.
         def pubid_match?(row_id, query)
           row_id.class == query.class &&
             row_id.exclude(*wildcards(query)) == query.exclude(*wildcards(query))
         end
 
         # The discriminators the query leaves unset: wildcards for the
-        # search, significant whenever the query states one.
+        # search, significant whenever the query states one — plus the
+        # publication years, which are stated-metadata: pinned when the
+        # query carries them, wildcarded when it does not.
         def wildcards(query)
-          DISCRIMINATOR_KEYS.select { |key| query.public_send(key).nil? }
+          keys = DISCRIMINATOR_KEYS + %i[
+            year supplement_year part_year annex_year appendix_year volume_year
+          ]
+          keys.select { |key| query.public_send(key).nil? }
         end
       end
     end

data/lib/relaton/iho/processor.rb

@@ -26,9 +26,10 @@ module Relaton
       end
 
       # An IHO record prints `B-12` and keeps its edition in `edition`, so
-      # the edition goes on the key as the version (relaton#408).
+      # the edition goes on the key (relaton#408). The component model
+      # (relaton#440) renamed the pubid attribute `version` -> `edition`.
       def item_cache_key(pubid, item)
-        with_components pubid, version: item.edition&.content
+        with_components pubid, edition: item.edition&.content
       end
 
       # @param xml [String]

data/lib/relaton/nist/CLAUDE.md

@@ -69,7 +69,8 @@ All data models inherit from `Lutaml::Model::Serializable` and use declarative a
   - **`#write_file` serializes before it indexes**, so a record that fails to serialize leaves no index row naming a file that was never written. That is how a `Bib::Date` in `Scraper.fetch_dates` hid: `Nist::ItemData` takes `Nist::Date`, and YAML serialization rejects the parent class (the same strictness as the docidentifier note below).
 - `ModsParser` — maps MODS XML (via `loc_mods`) to `ItemData`
 - `Scraper` — fetches items from GitHub YAML or CSRC JSON
-- `PubsExport` — singleton; caches CSRC pubs-export zip with thread-safe daily updates
+- `PubsExport` — singleton; caches CSRC pubs-export zip with thread-safe daily updates. The cache file is `#datafile`, under `Relaton::Index.config.storage_dir` (default `Dir.home`; the `DATAFILE` constant is only that default).
+  - **A read-only file system must not stop a search (relaton-nist#57).** When the cache write fails, `#fetch_data` keeps the downloaded zip in `@buffer`, and `#unzip` reads it with `Zip::File.open_buffer`. In rubyzip 3, `open_buffer` returns the buffer, not the block value, so collect the rows in a local. The cache write goes to a temp file and is renamed into place (`#write_datafile`), so a failed write never leaves a truncated zip that later processes read as fresh. `HitCollection#search` also rescues the local-cache errors in `LOCAL_DATA_ERRORS` from `from_json` (`#from_json_or_empty`), logs a warning, and continues with `from_ga`. Do not widen that list to `SystemCallError`: `Errno::ECONNREFUSED` is one, and a CSRC outage would then answer "not found" from the index, which `Relaton::Db` can cache. Specs assert the warning with `output(...).to_stderr_from_any_process`. A `receive(:warn)` stub on `Util` is never hit: `Kernel#warn` is private, the stub stays private, and the explicit-receiver call goes to `method_missing`.
 
 ### Pubid-backed docidentifier
 
@@ -115,6 +116,15 @@ NIST-specific gotchas (why this isn't a straight copy of IEC/CCSDS):
   numbered editions/revisions (`e2`, `r5`). Dates that ride the `update`
   component (some NBS supplements) are left intact — `update` also encodes
   non-date update codes (`/Upd2`), so stripping it would corrupt identity.
+- **The item's `edition` comes from the DOI (relaton-nist#56).**
+  `ModsParser#parse_edition` sets `<edition number="N">N</edition>` only for a
+  numbered `e<N>` edition in the DOI (`NBS.CIRC.111e2` → 2, `11e2.1915` → 2):
+  250 of the 20,392 live MODS records. An `e<year>` edition is a date, and an
+  `r<N>` revision is not an edition, so both stay without one. The MODS
+  `<edition>` element is prose (`New version`, `Erratum`), never a number. The
+  issue's "edition 0 → 1" rule came from the old Crossref feed; it is kept for
+  a DOI `e0` (none in the live data). A DOI pubid cannot parse gives no
+  edition, not an error.
 - **No `(all parts)` marker in `content`.** `content` is live-derived from
   `@pubid`, so `to_all_parts!` freezes the already-stripped rendering into
   `@raw_content` before wrapping `@pubid` in pubid's `AllParts` — matching

data/lib/relaton/nist/README.adoc

@@ -311,7 +311,13 @@ Relaton::Nist::Item.from_yaml File.read("spec/fixtures/item.yaml")
 
 === Fetching data
 
-On a search, the CSRC data sources are fetched and stored in the user's cache.
+On a search, the CSRC data sources are fetched and stored in the user's cache,
+`~/.relaton/nist/pubs-export.zip`. The cache follows
+`Relaton::Index.config.storage_dir`, so one setting moves it together with the
+index cache. When the cache cannot be written (for example on a read-only file
+system such as AWS Lambda), the data stays in memory for the process. When the
+CSRC data cannot be used at all, the search continues with the
+`relaton-data-nist` index.
 
 This gem uses the https://github.com/usnistgov/NIST-Tech-Pubs/releases/download/May2024/allrecords-MODS.xml dataset as NIST-Tech-Pubs data source.