relaton 3.0.0.pre.alpha.17 → 3.0.0.pre.alpha.18

data/lib/relaton/gb/README.adoc

@@ -0,0 +1,169 @@
+= Relaton::Gb
+
+Relaton::Gb is a Ruby gem that searches and fetches Chinese GB standards.
+The standards scraped form:
+
+* GB standards - http://www.std.gov.cn/gb/search
+* Social organization standards - http://www.ttbz.org.cn
+* Sector standards - http://www.std.gov.cn/hb
+
+NOTE: Unlike the ISO website, the GB websites require the year of publication to be included in the search.
+So a standard will not be found successfully through this gem unless the year is included in its document
+identifier: for example, not `CN(GB/T 1.1)`, but `CN(GB/T 1.1-2009)`.
+
+== Usage
+
+=== Search document
+
+[source,ruby]
+----
+require 'relaton/gb'
+=> true
+
+hit_collection = Relaton::Gb::Bibliography.search "GB/T 20223-2006"
+[relaton-gb] INFO: (GB/T 20223-2006) Fetching from openstd.samr.gov.cn ...
+=> <Relaton::Gb::HitCollection:0x00000000001350 @ref= @fetched=false>
+
+hit_collection.first
+=> <Relaton::Gb::Hit:0x00000000001850 @fullIdentifier="" @docref="GB/T 20223-2006">
+----
+
+=== Scrape document form collection
+
+[source,ruby]
+----
+hit_collection.first.item
+=> #<Relaton::Gb::ItemData:0x000000012913b968
+
+hit_collection.first.item.title.first
+=> #<Relaton::Bib::Title:0x00000001290f2bc8
+    @content="棉短绒",
+    @format=nil,
+    @language="zh",
+    @locale=nil,
+    @script="Hans",
+    @type="title-main">
+
+hit_collection.first.item.ext.gbtype
+=> #<Relaton::Gb::GbType:0x00000001259687c0
+    @mandate=["recommended"],
+    @prefix="GB_national",
+    @scope=["national"],
+    @topic=["other"]>
+
+hit_collection.first.item.ext.ccs
+=> [#<Relaton::Gb::CCS:0x000000012913f608 @code="B32">]
+
+hit_collection.first.item.date
+=> [#<Relaton::Bib::Date:0x0000000129111dc0
+    @at=#<Relaton::Bib::StringDate::Value:0x00000001291111e0 @value="2006-03-10">,
+    @from=nil,
+    @text=nil,
+    @to=nil,
+    @type=["published"]>]
+
+hit_collection.first.item.date.first.at.to_s
+=> "2006-03-10"
+
+hit_collection.first.item.date.first.at.to_date
+=> #<Date: 2006-03-10 ((2453805j,0s,0n),+0s,2299161j)>
+----
+
+=== Get document by identifier
+
+[source,ruby]
+----
+Relaton::Gb::Bibliography.get "GB/T 20223-2006"
+[relaton-gb] INFO: (GB/T 20223-2006) Fetching from openstd.samr.gov.cn ...
+[relaton-gb] INFO: (GB/T 20223-2006) Found: `GB/T 20223-2006`
+=> #<Relaton::Gb::ItemData:0x0000000129dd16a0
+----
+
+=== Get document by identifier and year
+
+[source,ruby]
+----
+Relaton::Gb::Bibliography.get "GB/T 20223", "2006"
+[relaton-gb] INFO: (GB/T 20223-2006) Fetching from openstd.samr.gov.cn ...
+[relaton-gb] INFO: (GB/T 20223-2006) Found: `GB/T 20223-2006`
+=> #<Relaton::Gb::ItemData:0x00000001299ffdd8
+----
+
+=== Create bibliographic item from YAML
+[source,ruby]
+----
+
+Relaton::Gb::Item.from_yaml File.read('spec/fixtures/item.yaml')
+=> #<Relaton::Gb::ItemData:0x00000001292d85c8
+----
+
+=== Serialization
+
+[source,ruby]
+----
+hit_collection.first.item.to_xml
+=> "<bibitem id="GBT202232006" type="standard" schema-version="v1.5.6">
+      <fetched>2026-01-26</fetched>
+      <title language="zh" script="Hans" type="title-main">棉短绒</title>
+      <title language="zh" script="Hans" type="main">棉短绒</title>
+      <title language="en" script="Latn" type="title-main">Cotton linter</title>
+      <title language="en" script="Latn" type="main">Cotton linter</title>
+      <uri type="src">http://openstd.samr.gov.cn/bzgk/gb/newGbInfo?hcno=083B48FA72DBD3B9BDE74507BC31736A</uri>
+      <docidentifier type="Chinese Standard" primary="true">GB/T 20223-2006</docidentifier>
+      ...
+    </bibitem>"
+----
+
+With `bibdata: true` option XML output is wrapped with `bibdata` element and `ext` element added.
+
+[source,ruby]
+----
+hit_collection.first.item.to_xml bibdata: true
+=> "<bibdata type="standard" schema-version="v1.5.6">
+      <fetched>2026-01-26</fetched>
+      <title language="zh" script="Hans" type="title-main">棉短绒</title>
+      <title language="zh" script="Hans" type="main">棉短绒</title>
+      <title language="en" script="Latn" type="title-main">Cotton linter</title>
+      <title language="en" script="Latn" type="main">Cotton linter</title>
+      <uri type="src">http://openstd.samr.gov.cn/bzgk/gb/newGbInfo?hcno=083B48FA72DBD3B9BDE74507BC31736A</uri>
+      <docidentifier type="Chinese Standard" primary="true">GB/T 20223-2006</docidentifier>
+      ...
+      <ext schema-version="v1.1.2">
+        <doctype>standard</doctype>
+        ...
+      </ext>
+    </bibdata>"
+----
+
+=== Typed source links
+
+Each GB document has `src` type source link.
+
+[source,ruby]
+----
+hit_collection.first.item.source
+=> #<Relaton::Bib::Uri:0x0000000129112bf8
+    @content="http://openstd.samr.gov.cn/bzgk/gb/newGbInfo?hcno=083B48FA72DBD3B9BDE74507BC31736A",
+    @language=nil,
+    @locale=nil,
+    @script=nil,
+    @type="src">
+----
+
+=== Logging
+
+Relaton::Gb uses the relaton-logger gem for logging. By default, it logs to STDOUT. To change the log levels and add other loggers, read the https://github.com/relaton/relaton-logger#usage[relaton-logger] documentation.
+
+== Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+== Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/gdbib.
+
+== License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/relaton/gost/CLAUDE.md

@@ -0,0 +1,100 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with the
+`Relaton::Gost` flavor.
+
+## Project Overview
+
+`Relaton::Gost` retrieves **GOST** standards — the interstate/national standards of the
+former-Soviet space (Государственный стандарт), published by Rosstandart and the
+Euro-Asian Council for Standardization (EASC/МГС). It is **index-backed** (no scraping):
+it searches a pre-built **pubid-structured** index via `Relaton::Index` and fetches
+per-document YAML from the `relaton/relaton-data-gost` GitHub repo. The model layer mirrors
+the `Relaton::Easc` sibling; the pubid-backed retrieval mirrors `Relaton::Oiml`.
+
+## Architecture
+
+Namespace: `Relaton::Gost`. Retrieval flow:
+
+1. **Bibliography** (`bibliography.rb`) — `get(code, year, opts)` parses the citation with
+   `Pubid::Gost.parse`, looks it up in the **pubid-structured** index, fetches the matching
+   `row[:file]` YAML over `Net::HTTP` (`Item.from_yaml`, raising `Relaton::RequestError` on
+   non-200), and stamps `fetched`. `search` picks the **latest edition** (`max_by { year }`)
+   among number-matched candidates; `get` then strips the year for an **undated** citation via
+   `to_most_recent_reference` (so `GOST 1.0` renders undated but resolves the newest edition),
+   while a dated citation (`GOST 1.0-92`) or explicit `year` pins that edition. Mirrors
+   `lib/relaton/oiml/bibliography.rb`.
+2. **Index** — `Relaton::Index.find_or_create(:gost, url: "#{ENDPOINT}index-v2.zip",
+   file: "index-v2.yaml", pubid_class: ::Pubid::Gost::Identifier)`. Each row's `:id` is a
+   `_type: pubid:gost:{interstate,national}-standard` hash that `Relaton::Index` rebuilds into
+   a `Pubid::Gost` identifier via `from_hash`; passing the parsed pubid to `#search` lets it
+   binary-search candidates by number (see `Bibliography#rows`). `INDEXFILE =
+   "index-v2"` is in `lib/relaton/gost.rb`.
+3. **Item / ItemData / Ext** (`item.rb`, `item_data.rb`, `ext.rb`) — `Item` extends
+   `Bib::Item`, re-declares `ext` to the typed `Gost::Ext` and `docidentifier` to the pubid
+   `Gost::Docidentifier`. `Ext`'s GOST fields (`urn`, `webpage`, `ics_code`, `developer`,
+   `keywords` [collection], `pages`, `designation_original`) round-trip natively through YAML
+   **and** XML (mapped in both `xml` and `key_value`). (The live dataset uses `urn`/`webpage`/
+   `ics_code`/`pages`/`designation_original`; `developer`/`keywords` are declared but unused.)
+4. **Doctype** (`doctype.rb`) — `TYPES = %w[interstate national preliminary methodological]`
+   (GOST, GOST R, PST, OD categories). Carried in the inherited `content` attribute.
+5. **Docidentifier** (`docidentifier.rb`) — wraps a `Pubid::Gost` identifier (`attr_reader
+   :pubid`); `content=` re-parses to keep `@pubid` in sync, and `remove_date!` nil-s the pubid
+   `year` and re-renders `content` (GOST carries the edition as `year`, not `date`) so
+   `to_most_recent_reference` yields `GOST R 34.12`. Mirrors `Oiml::Docidentifier`.
+6. **Processor** (`processor.rb`) — registry integration; `@short = :relaton_gost`,
+   `@prefix = "GOST"`, `@idtype = "GOST"`, and `@defaultprefix = %r{^(?:GOST|ГОСТ)\b}` so **both
+   the Latin `GOST` and Cyrillic `ГОСТ` surface forms route here** (the `\b` stops it swallowing
+   longer tokens). `remove_index_file` passes `url: true` and `file:` only — the delete never
+   reads the index, so it needs no `pubid_class` (see `lib/relaton/index/CLAUDE.md`). Every method touching a
+   flavor constant lazy-`require_relative`s `../gost` first (the lazy-registry invariant;
+   `spec/relaton/lazy_loading_spec.rb` guards it).
+
+There are no scrapers — everything comes from the curated index + GitHub YAML.
+
+## Pubid
+
+The flavor is **pubid-backed** via `Pubid::Gost` (metanorma/pubid#108), on the `pubid` `main`
+branch the root `Gemfile` already pins (for JCGM). `Bibliography#rows` selects a dated
+citation with `index.search(query, exact: true)` (pubid `==`) and an undated one with the
+default subset match `query === row`: the omitted year matches any value, so it matches every
+edition sharing subtype + number. `===` requires the same class, so interstate and national
+stay distinct, and `1.1` does not match `1.10`. pubid declares `copublisher` strict for GOST
+(pubid#408), so an omitted copublisher means "none". Measured over the full
+`relaton-data-gost` index (37,508 rows): `===` and the old `matches?(…, ignore: [:year])` agree
+on all 94,279 pairs. The
+`relaton-data-gost` `index-v2.yaml` was built with this **same** pubid, so the rows deserialize
+(a mismatched pubid would make `Relaton::Index` reject the whole index — cf. the root
+`CLAUDE.md` JCGM note). The pinned release `2.0.0.pre.alpha.13` carries `Pubid::Gost` and
+`subset_strict`; any lower pin must too.
+
+## Dataset
+
+`relaton/relaton-data-gost` is the live data repo behind `ENDPOINT` (a real pubid-structured
+`index-v2.yaml` + `data/*.yaml`). The specs run fully offline against a small committed subset
+(see Testing).
+
+## Testing
+
+`spec/gost/` — self-contained, run via `bundle exec rake spec:gost` (or `cd spec/gost &&
+bundle exec rspec -I . .`). Coverage:
+
+- `ext_spec.rb`, `item_spec.rb` — YAML round-trip of the typed ext fields.
+- `bibliography_spec.rb` — retrieval against real records copied from `relaton-data-gost`:
+  the pubid-structured index fixture `fixtures/index-v2.zip` is pre-loaded into the
+  `Relaton::Index` pool in `before(:suite)` (with `pubid_class`), and `fixtures/data/*.yaml`
+  are served by WebMock (`support/webmock.rb`) — **no live network**. Covers dated/undated/
+  Cyrillic lookups, undated→latest-edition, year-pinning, not-found (`nil`), and non-200
+  (`Relaton::RequestError`). Fixture docs: interstate `GOST 1.0` (editions 2015 + 92) and
+  national `GOST R 34.12-2015`.
+- `processor_spec.rb` — processor shape + Latin/Cyrillic prefix routing.
+
+To refresh the fixture, copy the wanted rows from `relaton-data-gost/index-v2.yaml` into
+`fixtures/index-v2.yaml`, re-zip it to `fixtures/index-v2.zip`, and copy the matching
+`data/*.yaml` files.
+
+There is **no RelaxNG grammar** for GOST and no XML-schema validation spec: the metanorma
+document model (`metanorma-model-iso/grammars/`) defines no GOST grammar, so there is nothing
+to copy into `grammar/` and nothing to validate `to_xml` against. This matches the sibling
+`easc` flavor (also grammar-less). If an official GOST grammar is ever added upstream, copy the
+`<flavor>{,-compile}.rng` pair into `grammar/` and add a Jing-validation spec then.

data/lib/relaton/iala/CLAUDE.md

@@ -0,0 +1,97 @@
+# CLAUDE.md
+
+## Architecture
+
+**Pubid-backed docidentifier.** `Relaton::Iala::Docidentifier`
+(`docidentifier.rb`, `< Bib::Docidentifier`) parses its `content` into a
+`Pubid::Iala::Identifier` kept in `@pubid`, while the lutaml `content` attribute
+stays a plain string for serialization. Parsing is **soft**: `content=` lazily
+`require "pubid"` + `require "pubid/iala"` (pubid core must load first for
+`Pubid::PrefixesSupport`) and rescues `LoadError`/`StandardError`, so a missing
+pubid gem or non-IALA/unparseable content leaves `@pubid` nil rather than raising.
+
+It implements the base class's abstract `remove_part!` / `remove_date!` /
+`to_all_parts!` by mutating the pubid and re-rendering via `refresh_content!`
+(which writes through the aliased `store_content` — the inherited string setter —
+so in-place mutations aren't clobbered by a re-parse). IALA's identifier models
+only `publisher`/`number`/`edition`/`language`, so the mapping is IALA-specific:
+
+- **`remove_date!` → clears `edition`.** IALA carries no date component; `edition`
+  is its version discriminator, so this yields the version-agnostic ("most
+  recent") reference, e.g. `IALA S1070 Ed 2.0` → `IALA S1070`.
+- **`remove_part!` → clears the (unused) `part`/`subpart` attributes.** A no-op
+  for the rendered string today: IALA folds any subpart inline into `number`
+  (e.g. `0103-1`), so the part is not a separable component. Implemented anyway
+  so it never raises, and it starts working automatically if pubid-iala ever
+  models `part` separately.
+- **`to_all_parts!` → `remove_part!` + `remove_date!`, then wraps `@pubid` in
+  pubid's `AllParts`.** `content` stays the edition-stripped string — IALA'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. Mirrors `lib/relaton/iec/model/docidentifier.rb`.
+
+All three no-op safely when `@pubid` is nil, so `Bib::ItemData#to_all_parts` /
+`#to_most_recent_reference` never raise on IALA items.
+
+**Index (`index-v2`, pubid-keyed).** `INDEXFILE` is the pubid-backed
+`index-v2` published by `relaton-data-iala`: 701 rows of
+`_type: pubid:iala:*` with `number`/`edition`/`language`. The consumer
+(`Bibliography#index`) passes
+`pubid_class: ::Pubid::Iala::Identifier` — that is what makes `Relaton::Index`
+deserialize the rows into identifiers, sort them by `id.root.number`, and let
+`Type#search` bsearch. Omitting it leaves the rows as raw hashes and
+`FileIO#sorted` false, so every lookup scans all 701 rows, silently. That was
+the state before this flavor adopted the W3C pattern; the data repo already
+published a pubid-shaped `index-v2`, only the consumer was unwired.
+`Processor#remove_index_file` passes `url: true` and `file:` only: the delete
+never reads the index (see `lib/relaton/index/CLAUDE.md`).
+
+`Bibliography#best_match` follows the ETSI/W3C idiom:
+
+- **Pass the pubid, not the string.** `Type#search_candidates` narrows only when
+  the argument is not a `String`, so passing the reference text — which this
+  flavor used to do — disables the binary search however the index was built.
+- **Selection is pubid's asymmetric subset match** (`Pubid::SubsetMatch`):
+  `pubid === r[:id]`, the reference on the left. A component the reference omits
+  matches any value, so a bare `IALA M0001` finds the `Ed 9.0 (E)` row, while
+  `IALA R0106 Ed 2.1 (F)` reaches only its own. `edition` and `language` are
+  IALA's only optional components.
+- **The document type is never a wildcard.** It is the identifier's class, and
+  `===` requires the same class. 17 of the 309 index numbers are shared by two
+  types (`R1001` and `C1001` are different documents), so they stay apart. An
+  `Annex` row carries its base identifier, which `===` compares with its own
+  subset match.
+- **Newest edition wins, deterministically.** Editions are dotted versions and
+  must be compared segment-by-segment as integers: `"10.0"` is newer than
+  `"9.0"` but loses as a string. No published edition has a segment above 9
+  today, so this is latent — the same bug already fixed for ETSI. Ties break on
+  the edition text and then the file path, because the index sort is not stable.
+  Among rows of one edition the language-neutral record wins: it is the base
+  document, the others are translations.
+- **An unparseable reference raises.** `parse_ref` lets
+  `Pubid::Errors::ParseError` propagate, and the full-scan substring fallback is
+  gone with it: a substring match answered an ambiguous reference with whichever
+  row sorted first, instead of telling the caller the reference is not an
+  identifier.
+
+`require "pubid"` sits in `lib/relaton/iala.rb` (the IANA/IHO form), so pubid
+loads with the flavor. `Processor#remove_index_file` names no pubid class, so the
+cold `Db#clear` path that `spec/relaton/lazy_loading_spec.rb` guards does not
+depend on it. `Docidentifier` keeps its own
+lazy, `LoadError`-rescuing require: it is reached by deserialization, which must
+not depend on the flavor entry file having been loaded.
+
+## Testing
+
+- `bundle exec rake spec:iala` — run the IALA suite.
+- Specs live in `spec/iala/relaton/iala/` and run self-contained (see the root
+  `CLAUDE.md` Testing section).
+- `spec/iala/fixtures/index-v2.zip` is a 19-row curated subset of the published
+  index, copied row-for-row so the stored shapes stay verbatim. It covers the
+  matching rules above: a multi-edition document (`R0101`, editions `2` and
+  `3.0`), a four-language document (`R0106`), a number shared by two types
+  (`R1001` / `C1001`), a sub-part folded into the number (`C0103-1`), and the
+  language-neutral/translation split. `spec/iala/support/webmock.rb` seeds it
+  into the `Relaton::Index` pool **with `pubid_class:`** — without that the
+  suite would pass while exercising something the runtime never does.

data/lib/relaton/iana/CLAUDE.md

@@ -0,0 +1,105 @@
+# CLAUDE.md
+
+## Development
+
+- `bundle install` — install dependencies
+- `bundle exec rake spec:iana` — run this flavor's tests
+  (rubocop is configured via the root `.rubocop.yml` but is not in the bundle)
+
+## What this flavor is
+
+IANA entries are protocol **registries**, not numbered standards. An identifier
+is a hierarchical registry slug capped at one "/":
+
+```
+IANA _6lowpan-parameters
+IANA _6lowpan-parameters/lowpan_nhc
+```
+
+`Parser#docnumber` builds the bare slug (`registry[/sub-registry]`) by joining a
+nested registry's XML `id` to its parent's; `Core::DataFetcher#output_file`
+turns that into the document filename (`data/_6lowpan-parameters-lowpan_nhc.yaml`).
+
+`output_file` collapses `/` and `-` to the same character, so two distinct
+registries can want one file — `rpki/signed-objects` and `rpki-signed-objects`
+do, the only such pair in the 3405 published rows. `save_doc` therefore writes
+through `Core::DataFetcher#unique_output_file`, which hands the second one a
+digest-suffixed path instead of overwriting the first; the warning stays so the
+clash is visible in the crawl log. Before that fix the corpus had 3405 index
+rows over 3404 files, and one id resolved to the wrong document.
+
+## Index (`index-v2`, pubid-keyed)
+
+`INDEXFILE = "index-v2"` (`lib/relaton/iana.rb`). Rows carry
+`Pubid::Iana::Identifiers::Registry` identifiers, serialized as:
+
+```yaml
+- :id:
+    _type: pubid:iana:registry
+    sub_registry: lowpan_nhc      # absent for a top-level registry
+    number: _6lowpan-parameters
+  :file: data/_6lowpan-parameters-lowpan_nhc.yaml
+```
+
+`number` holds the **top-level** slug — not a document number, because an IANA
+identifier has none (digits only ever appear glued inside a slug token:
+`sip-parameters/sip-parameters-13`, `idna-tables-11.0.0`). It is the index key:
+`Relaton::Index::Type#candidates_by_number` bsearches on `id.root.number.to_s`,
+so a registry and all of its sub-registries share one bucket (655 buckets over
+the 3405 published rows; median 3, max 73 — `pcep`) and `Bibliography#pubid_match?`
+separates them. `registry` is a **derived reader** over `number`, so it is not a
+serialized key.
+
+The pair that must stay in step, both passing
+`pubid_class: ::Pubid::Iana::Identifier`:
+
+| role | file |
+|---|---|
+| producer | `data_fetcher.rb` — `#index` + the guarded `#add_to_index` |
+| consumer | `bibliography.rb` — `#index`, `#parse_ref`, `#pubid_match?` |
+
+`processor.rb#remove_index_file` passes `url: true` and `file:` only: the delete
+never reads the index (see `lib/relaton/index/CLAUDE.md`).
+
+`#add_to_index` rescues and warns rather than raising: `Relaton::Index` rejects
+the **whole** index if one row fails to deserialize, so an unparseable slug has
+to be skipped at write time instead of aborting the crawl.
+
+### Why a stale index is loud, not silent
+
+A row serialized before `number` existed (`{_type, registry, sub_registry}`)
+deserializes with `number` **nil and no error at all**: lutaml ignores unknown
+keys, and `Index::FileIO#id_supported?` skips its `to_hash`/`from_hash`
+validation for a concrete subclass — which every IANA id is. pubid therefore
+fails at *render* time instead: `Identifier#require_number!` raises
+`ArgumentError` ("… regenerate the index") from `to_s`, `to_urn` and
+`to_mr_string`. **If you see that error the index is stale — rebuild it, don't
+work around it.** `spec/iana/relaton/iana_spec.rb`'s "the pubid index-v2
+fixture" block is the tripwire for the fixture.
+
+### Migration note (v1 → v2)
+
+`index-v1` was keyed on the bare slug string, so `Index::Type#search` matched by
+**substring** and `min_by { |i| i[:id] }` picked the shortest hit — `IANA rpki`
+also matched `rpki/signed-objects`. v2 matches the identifier exactly, so a
+partial reference no longer resolves.
+
+This flavor no longer produces `index-v1`. `relaton-data-iana`'s own
+`crawler.rb` derives it from `index-v2` (a plain YAML transform:
+`sub_registry ? "#{number}/#{sub_registry}" : number`) so released gem lines
+keep resolving.
+
+## Testing
+
+- **Framework:** RSpec with VCR cassettes and WebMock.
+- **Index fixture:** `spec/iana/fixtures/index-v2.zip` (all 3405 published rows)
+  is deserialized through `pubid_class` once per process and **re-seeded into
+  the `Relaton::Index` pool before every example** — see
+  `spec/iana/support/webmock.rb` for why (the producer-side `find_or_create`
+  evicts it otherwise). Its `actual?` override claims only the consumer
+  (`url:`) lookup.
+- **VCR cassettes:** `spec/iana/vcr_cassettes/` — index downloads are ignored by
+  VCR (`support/vcr.rb`), since the fixture answers them.
+- The XML round-trip specs validate against `grammar/relaton-iana-compile.rng`
+  with Jing, which needs a **Java runtime**; without one they fail with
+  `Jing::ExecutionError`, unrelated to any code change.

data/lib/relaton/iana/README.adoc

@@ -0,0 +1,107 @@
+= Relaton::Iana
+
+Relaton::Iana is a Ruby gem that implements the https://github.com/metanorma/metanorma-model-iso#iso-bibliographic-item[IsoBibliographicItem model].
+
+You can use it to retrieve metadata of IANA Standards and access such metadata through the `Realaton::Iana::ItemData` object.
+
+== Usage
+
+=== Search for a standard using keywords
+
+[source,ruby]
+----
+require 'relaton/iana'
+=> true
+
+item = Relaton::Iana::Bibliography.get "IANA service-names-port-numbers"
+[relaton-iana] INFO: (IANA service-names-port-numbers) Fetching from Relaton repository ...
+[relaton-iana] INFO: (IANA service-names-port-numbers) Found: `IANA service-names-port-numbers`
+=> #<Relaton::Iana::ItemData:0x0000000110a8ed80
+...
+----
+
+=== XML serialization
+
+[source,ruby]
+----
+item.to_xml
+=> "<bibitem id="IANAservicenamesportnumbers" type="standard" schema-version="v1.5.6">
+      <fetched>2026-01-27</fetched>
+      <title language="en" script="Latn">Service Name and Transport Protocol Port Number Registry</title>
+      <uri type="self">https://www.iana.org/assignments/service-names-port-numbers</uri>
+      <docidentifier type="IANA" primary="true">IANA service-names-port-numbers</docidentifier>
+      ...
+    </bibitem>"
+----
+
+=== Typed links
+
+Each IANA document has `src` type source link.
+
+[source,ruby]
+----
+item.source.first.type
+=> "src"
+
+item.source.first.content
+=> "https://www.iana.org/assignments/service-names-port-numbers"
+----
+
+=== Create bibliographic item from XML
+[source,ruby]
+----
+Relaton::Iana::Item.from_xml File.read('spec/fixtures/auto-response-parameters.xml')
+=> #<Relaton::Iana::ItemData:0x0000000124776198
+...
+----
+
+=== Create bibliographic item from YAML
+[source,ruby]
+----
+Relaton::Iana::Item.from_yaml File.read('spec/fixtures/item.yaml')
+=> #<Relaton::Iana::ItemData:0x0000000124e1c588
+...
+----
+
+=== Fetch data
+
+There is an IANA dataset https://github.com/ietf-ribose/iana-registries which can be converted into RelatonXML/BibXML/BibYAML formats.
+
+The method `Relaton::Iana::DataFetcher.fetch(output: "data", format: "yaml")` converts all the documents from the dataset and saves them to the `./data` folder in YAML format.
+Arguments:
+
+- `output` - folder to save documents (default './data').
+- `format` - the format in which the documents are saved. Possible formats are: `yaml`, `xml`, `bibxml` (default `yaml`).
+
+[source,ruby]
+----
+Relaton::Iana::DataFetcher.fetch
+Started at: 2021-11-19 13:32:05 +0100
+Stopped at: 2021-11-19 13:34:40 +0100
+Done in: 155 sec.
+=> nil
+----
+
+This method uses GitHub search API to fetch the documents. The search API has a https://docs.github.com/en/rest/reference/search#rate-limit[rate limitaion] of 30 requests per minute for authenticated users and 10 requests per minute for unauthenticated users. Usually, the rate limit is not reached because the search API is used only for the file list fetching. But if you run the method multiple times in a short period, the rate limit may be reached. In this case, the method will wait until the rate limit is reset.
+
+You can use a personal access token (PTA) to increase the rate limit. To do this, add your PTA to the `GITHUB_TOKEN` environment variable.
+
+=== Logging
+
+Relaton::Iana uses the relaton-logger gem for logging. By default, it logs to STDOUT. To change the log levels and add other loggers, read the https://github.com/relaton/relaton-logger#usage[relaton-logger] documentation.
+
+== Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+The index test fixture is `spec/iana/fixtures/index-v2.zip` — the pubid-keyed `index-v2` published by the https://github.com/relaton/relaton-data-iana[relaton-data-iana] repository (branch `v2`). To refresh it, download the live `index-v2.zip` and replace the fixture.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+== Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/relaton/relaton_w3c.
+
+== License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/relaton/iec/CLAUDE.md

@@ -0,0 +1,13 @@
+# CLAUDE.md
+
+## Development
+
+- `bundle install` — install dependencies
+- `bundle exec rake spec` — run tests
+- `bundle exec rubocop` — lint
+
+## Testing
+
+- **Framework:** RSpec with VCR cassettes and WebMock
+- **Index fixture:** `spec/fixtures/index-v2.zip` is pre-loaded into `Relaton::Index` pool in `before(:suite)` (configured in `spec/support/webmock.rb`). Run `rake spec:update_index` to refresh from relaton-data-iec. The fixture is the lean pubid-v2 `to_hash` index (`_type`-tagged rows); rows are deserialized via `Pubid::Iec::Identifier.from_hash` and validated by round-trip in relaton-index (no `id_keys` allowlist).
+- **VCR cassettes:** `spec/vcr_cassettes/` — index download requests are ignored by VCR (handled by fixture).