relaton 3.0.0.pre.alpha.16 → 3.0.0.pre.alpha.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83f6b8e1b62e766d9b4fa8f46d68a8d505c4e1534fbe2049f18b36e7cbea29cf
-  data.tar.gz: 7813140bb28511c6396616c40f17ccba333cceccaae64c5e75b2bd8808807ca1
+  metadata.gz: 5e4cd375143aef3a8e9dacfec4c86c06937243afe6a28a50d2960926e9c3396c
+  data.tar.gz: 8f96b7587af7145d05843de68b465263fdd524ad25adfd84fd53970ec97fd4a7
 SHA512:
-  metadata.gz: fbc94c74748bc1e096c03a475bfbe33b9c59438453a788d14e287924b6e0b0eded53d87e9c083effc1814dc4f5b3952e3f7db455271e17f7537de531fe5571b3
-  data.tar.gz: ac81371be2a1c5ca84a49b979098e3a14b15e75442dc1f7f11a43800239148d3e3691d4c6d26e436bead9fc0f9983c9471051a46850950a45e7817e3d196cfae
+  metadata.gz: f74dc77c912c9894872cfae0f04883badc152bf4c0f4e4abf4e2871a8352a1445b89cfb8ef0cac7f9270fd297327823a4c703013fb559bb268a39b0319fc120b
+  data.tar.gz: 9ffb0a15a5cb561f8699ef307c966a470ca96ac2cc97a968161cb7095dedfc5c2f6a5a2db8f59d8e53722776d61f72643ec2b32c8e6ccc50b8e9dd837fdfdbed

data/data/equivalence/adoption-chains.yaml

@@ -0,0 +1,38 @@
+# Cross-SDO equivalence as data: adoption-chain patterns and explicit
+# equivalences the resolver consults on a miss (TODO.sota layer 4).
+#
+# chain patterns: ordered most-specific-first rewrites. A code matching the
+# first group resolves to each rewrite in turn (the canonical form last).
+# The CEN/BSI/DIN/NF adoption ladder: a national adoption cites the EN, the
+# EN cites the ISO — so a miss on "BS EN ISO 1388" falls back through
+# "EN ISO 1388" to "ISO 1388".
+chains:
+- match: '^(?:BS |DIN |NF )?EN (ISO[ /].+)$'
+  resolve:
+  - 'EN \1'
+  - '\1'
+- match: '^(?:BS |DIN |NF )(ISO[ /].+)$'
+  resolve:
+  - '\1'
+- match: '^BS EN (.+)$'
+  resolve:
+  - 'EN \1'
+  - '\1'
+- match: '^DIN EN (.+)$'
+  resolve:
+  - 'EN \1'
+  - '\1'
+- match: '^NF EN (.+)$'
+  resolve:
+  - 'EN \1'
+  - '\1'
+
+# Explicit equivalences: every form in `equivalents` resolves to
+# `canonical` (and the canonical resolves to itself). Used where no pattern
+# expresses the relationship (joint publications, historical adoptions).
+equivalences:
+- canonical: ISO/IEC 17025
+  equivalents:
+  - EN ISO/IEC 17025
+  - BS EN ISO/IEC 17025
+  - DIN EN ISO/IEC 17025

data/lib/relaton/3gpp/CLAUDE.md

@@ -0,0 +1,187 @@
+# CLAUDE.md
+
+## Architecture
+
+**Pubid-backed docidentifier.** `Relaton::ThreeGpp::Docidentifier`
+(`docidentifier.rb`, `< Bib::Docidentifier`) parses its `content` into a
+`Pubid::Tgpp::Identifier` kept in `@pubid`, while the lutaml `content`
+attribute stays a plain **string** — `ItemData#create_id` calls
+`docid.content.sub(...)`, so the ISO `Type::Pubid` route (which makes `content`
+return an object) would break it. Parsing is **soft**: `content=` lazily
+`require "pubid"` and rescues `LoadError`/`StandardError`, so a missing pubid
+gem or non-3GPP content leaves `@pubid` nil rather than raising.
+
+Before this class existed, 3GPP inherited `Bib::Docidentifier`, whose
+`remove_part!` / `remove_date!` / `to_all_parts!` each raise
+`NotImplementedError` — and `Bib::ItemData` broadcasts all three to every
+docidentifier, so `#to_all_parts` and `#to_most_recent_reference` **raised on
+every 3GPP item**. The mapping is 3GPP-specific:
+
+- **`remove_part!` → clears `parts`.** A real, separable component here
+  (unlike IALA's, which is a no-op): `TS 29.198-04-1` → `TS 29.198`. `parts`
+  is a collection, so it is emptied rather than nil'd — `Identifier#code`
+  renders through `parts.map`.
+- **`remove_date!` → clears `release` AND `version`.** 3GPP carries no date;
+  those two are its version discriminators — the same pair that
+  `Bibliography#best_match` lets a reference omit — so clearing both yields the
+  version-agnostic ("most recent") reference `TS 23.207`.
+- **`to_all_parts!` → both, then wraps `@pubid` in pubid's `AllParts`.**
+  `content` stays the plain stripped id — the Tgpp 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 `ItemData#to_all_parts` and
+`#to_most_recent_reference` never raise.
+
+**The `with_publisher` trap.** `Pubid::Tgpp::Identifier#to_s` defaults to
+**omitting** the `3GPP ` token — deliberately, so it reproduces the index id
+(`TS 23.207:REL-4/4.0.0`). The stored docidentifier `content` *keeps* the
+prefix (`Parser#parse_docid` builds `"3GPP #{number}"`), while `docnumber` does
+not. So `Docidentifier#refresh_content!` renders
+`to_s(with_publisher: true)`; without it every mutation would silently strip
+the prefix. This is the one place 3GPP diverges from the IALA template, whose
+`refresh_content!` is a bare `to_s`.
+
+**Index (`index-v2`, pubid-keyed).** `INDEXFILE` is the pubid-backed
+`index-v2`: 88,464 rows of `_type: pubid:3gpp:{technical-specification,
+technical-report}` with `number`/`suffix`/`parts`/`release`/`version`. The
+consumer (`Bibliography#index`) and the producer (`DataFetcher#index`) pass
+`pubid_class: ::Pubid::Tgpp::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 on the **producer** side writes v1-shaped
+rows under a v2 name, silently (`FileIO#save` only calls `to_hash` when the
+value is an instance of `pubid_class`); omitting it on the **consumer** side
+leaves the rows raw hashes with `FileIO#sorted` false, so every lookup scans
+all 88,464 rows. Measured on the live corpus: 3,767 number buckets, largest
+979; a `TS 23.207` lookup narrows to **37 of 88,464**.
+`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/IALA 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. `pubid_class:` alone fixes nothing; both had to change together.
+- **Select with the subset match.** `best_match` calls `index.search(pubid)`
+  with no block, so `Index::Type#search` selects with pubid's `pubid === row`.
+  `release` and `version` are 3GPP's only optional components: one that the
+  reference omits matches any value, so a bare `3GPP TS 23.207` finds the
+  `REL-19/19.0.0` row. Measured over the full `relaton-data-3gpp` index
+  (88,464 rows): `===` and the old `matches?(…, ignore: %i[release version])`
+  agree on all 31,305,864 pairs.
+- **`suffix` and `parts` are strict.** They are part of the document code
+  (`TS 29.198-04-1`, `TR 00.01U`), not qualifiers, so pubid declares them
+  `subset_strict` for 3GPP (pubid#408): `TS 29.198` does not match
+  `TS 29.198-04-1`, and `TR 00.01` does not match `TR 00.01U`.
+- **Neither is the document type.** It is the identifier's class, and `===`
+  requires the same class, so `TS 23.207` and `TR 23.207` never match. (No
+  document code in the corpus is actually carried by both types — measured
+  over all 88,464 rows — so the specs pin this with a negative lookup rather
+  than a fixture pair.)
+- **A part-less row must deserialize with `parts == []`.** A parsed identifier
+  has always had `parts == []`; one deserialized from an index row used to
+  have `parts == nil`. With `parts` strict, nil and empty are the same value,
+  but the old attribute-wise `matches?` made every part-less row silently fail
+  to match its own reference — 366 of the 387 fixture rows. Fixed upstream in
+  pubid (`242ad5b`). If part-less lookups ever start returning nil again,
+  check the installed pubid before the flavor.
+- **An unrecognized reference raises.** Like ISO and ETSI, the parse error
+  propagates out of `search`, so relaton-cli renders `"…" is not a recognized
+  standards identifier` (`gems/relaton-cli/lib/relaton/cli/command.rb:324`,
+  `subcommand_collection.rb:134`) and API callers rescue it themselves. The
+  parse happens **outside** the method-level rescue, whose list is transport
+  errors only, so it is never relabelled as a `Relaton::RequestError`.
+
+### Ordering: highest version wins
+
+`min_by { |r| r[:id] }` compared raw strings, so `3GPP TS 23.207` (37 rows)
+returned `REL-10/10.0.0` because `"1" < "4"` — neither the newest nor the
+oldest, just whichever sorted first as text. The key is now the version,
+compared **segment by segment as integers** (`19.0.0` beats `4.0.0`; `5.10.0`
+beats `5.9.0`, which a text comparison gets backwards).
+
+Scored against each document's own `date[0].at` over 870 documents in 59
+multi-row groups:
+
+| Key | Picks the newest published document |
+|---|---|
+| version segments, numeric | 51/59 — **86%** |
+| release rank, then version | 51/59 — **86%** |
+| the old `min_by { r[:id] }` | 1/59 — **2%** |
+
+**Do not add a release key on top.** The two candidate keys picked the same row
+in all 59 sampled groups and disagree on only **9 of 3,982** multi-row groups
+corpus-wide (99.77% identical) — all draft TRs carried into a later release at
+a lower version, e.g. `TR 23.873`, where the release answer is not clearly
+better. The cost would be a hand-maintained 27-token table whose order is
+**non-monotonic**: the chronological sequence is `Ph1, Ph2, REL-96, REL-97,
+REL-98, REL-99, Release 2000, UMTS, REL-4 … REL-21`, so every numeric read of
+the token puts REL-99 above REL-19.
+
+Ties break on the rendered id and then the file path, because the index sort is
+not stable.
+
+**Known limit — do not try to "fix" the ordering back.** "Newest release" and
+"newest publication" are different documents in ~8% of groups, because 3GPP
+keeps revising old releases:
+
+```
+TS 04.08   newest published: REL-98/7.21.0  2004-01-05
+           highest release:  REL-99/8.0.0   2000-06-30
+```
+
+A version key returns the second. No key computable from the identifier alone
+returns the first: index rows carry only `{id, file}` and `Pubid::Tgpp` has no
+date attribute. Closing that gap would need a pubid attribute, an index schema
+change and a crawler change.
+
+**Producer side.** `DataFetcher#save_doc` indexes
+`docidentifier.detect(&:primary).pubid` through `#index_primary` — the pubid is
+already parsed on the model, so nothing re-parses `docnumber`, and
+`pubid.to_s` (no publisher token) reproduces the old string key byte-for-byte,
+so the index key did not move. `docnumber` still names the output file. An id
+pubid cannot rebuild is recorded in `@errors` (the inherited `report_errors`
+logs a String value as the message) and the row is **skipped** rather than
+indexed unparsed — `Relaton::Index` rejects the whole index on one bad row. The
+data file is still written, so the document is unindexed, never lost.
+
+`require "pubid"` sits in `lib/relaton/3gpp.rb` (the IANA/IHO/IALA 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. `Processor` also sets
+`@pubid_flavor = :Tgpp`, so `Core::Processor#prefixes` reads
+`Pubid::Tgpp.prefixes` (`["3GPP"]`).
+
+## Testing
+
+- `bundle exec rake spec:3gpp` — run the 3GPP suite.
+- Specs live in `spec/3gpp/relaton/3gpp/` and run self-contained (see the root
+  `CLAUDE.md` Testing section).
+- **Index fixture.** `spec/3gpp/fixtures/index-v2.zip` is a curated subset of
+  the published index — never the full 88,464 rows, and never hand-written.
+  `bundle exec rake spec:update_index_3gpp` regenerates it;
+  `tasks/index_fixture_3gpp.rb` names each document group and the rule it pins
+  (`TS 23.207` version ordering, `TS 05.05` legacy release tokens, `TS 04.08`
+  the known limit, `TS 29.198-04-1` parts, `TR 00.01U` suffix, `TS 29.215` the
+  release-less row). Rows are copied **verbatim** from `relaton-data-3gpp`'s
+  published `index-v2.zip`, so the stored shapes are exactly what `DataFetcher`
+  writes and what the runtime deserializes. `#build` refuses a v1 source
+  outright — string ids under the v2 name would give a fixture
+  `Relaton::Index` rejects wholesale — so the failure names its cause instead
+  of surfacing as an unrelated deserialization error.
+
+  Re-cutting always produces a different **binary** even when the rows are
+  unchanged, because a zip stores mtimes. Compare the rows, not the file: if
+  the row set is identical, there is nothing to commit.
+- `spec/3gpp/support/webmock.rb` seeds the fixture into the `Relaton::Index`
+  pool **with `pubid_class:`** — without it the suite would pass while
+  exercising something the runtime never does. It re-seeds in `before(:each)`,
+  not only `before(:suite)`, because `DataFetcher#index` asks for the same type
+  with `file:` but no `url:` and `Pool#type` then replaces the entry.
+  `Pool#type` upcases its key, so `Bibliography`'s `"3GPP"` and
+  `DataFetcher`'s `"3gpp"` are the same pooled entry, `:"3GPP"`.
+- **VCR cassettes:** `spec/3gpp/vcr_cassettes/`. Index downloads are ignored by
+  VCR (matched as `index-v\d+\.zip`, so the next `INDEXFILE` bump does not
+  start recording them) and served from the fixture instead.

data/lib/relaton/3gpp/README.adoc

@@ -0,0 +1,149 @@
+= Relaton3gpp
+
+Relaton3gpp 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 W3C Standards from https://w3.org, and access such metadata through the `W3cBibliographicItem` object.
+
+== Usage
+
+=== Search for a standard using keywords
+
+[source,ruby]
+----
+require "relaton_3gpp"
+=> true
+
+item = Relaton3gpp::Bibliography.get "3GPP TR 00.01U:UMTS/3.0.0"
+[relaton-3gpp] (3GPP TR 00.01U:UMTS/3.0.0) Fetching repository ...
+[relaton-3gpp] (3GPP TR 00.01U:UMTS/3.0.0) Found: `3GPP TR 00.01U:UMTS/3.0.0`
+=> #<Relaton3gpp::BibliographicItem:0x00007f92d94264e0
+...
+----
+
+=== XML serialization
+
+[source,ruby]
+----
+item.to_xml
+=> "<bibitem id="3GPPTR00.01U-UMTS/3.0.0" type="standard" schema-version="v1.2.1">
+      <fetched>2022-12-02</fetched>
+      <title type="main" format="text/plain">Work programme for the standardization of Universal Mobile Telecommunications System (UMTS)</title>
+      <uri type="src">http://www.3gpp.org/ftp/Specs/archive/00_series/00.01U/0001U-300.zip</uri>
+      <docidentifier type="3GPP" primary="true">3GPP TR 00.01U:UMTS/3.0.0</docidentifier>
+      <docnumber>TR 00.01U:UMTS/3.0.0</docnumber>
+      ...
+    </bibitem>"
+----
+
+With argument `bibdata: true` it outputs XML wrapped by `bibdata` element and adds flavor `ext` element.
+
+[source,ruby]
+----
+item.to_xml bibdata: true
+=> "<bibdata type="standard" schema-version="v1.2.1">
+      <fetched>2022-12-02</fetched>
+      <title type="main" format="text/plain">Work programme for the standardization of Universal Mobile Telecommunications System (UMTS)</title>
+      <uri type="src">http://www.3gpp.org/ftp/Specs/archive/00_series/00.01U/0001U-300.zip</uri>
+      <docidentifier type="3GPP" primary="true">3GPP TR 00.01U:UMTS/3.0.0</docidentifier>
+      <docnumber>TR 00.01U:UMTS/3.0.0</docnumber>
+      ...
+        <ext schema-version="v1.0.4">
+          <doctype>TR</doctype>
+          <editorialgroup>
+            <technical-committee type="prime">SMG5</technical-committee>
+          </editorialgroup>
+          <radiotechnology>3G</radiotechnology>
+          <release>
+            <version2G>3</version2G>
+            <version3G>3</version3G>
+            <defunct>true</defunct>
+            <freeze-meeting>SMG-28</freeze-meeting>
+            <freeze-stage1-meeting>SMG-28</freeze-stage1-meeting>
+            <freeze-stage2-meeting>SMG-28</freeze-stage2-meeting>
+            <freeze-stage3-meeting>SMG-28</freeze-stage3-meeting>
+            <close-meeting>SP-28</close-meeting>
+            <project-end>1999-02-12</project-end>
+          </release>
+        </ext>
+      </ext>
+    </bibdata>"
+----
+
+=== Typed links
+
+Some 3GPP documents have `src` type link.
+
+[source,ruby]
+----
+item.link.first.type
+=> "src"
+
+item.link.first.content
+==> #<Addressable::URI:0x320 URI:http://www.3gpp.org/ftp/Specs/archive/00_series/00.01U/0001U-300.zip>
+----
+
+=== Create bibliographic item from XML
+[source,ruby]
+----
+Relaton3gpp::XMLParser.from_xml File.read('spec/fixtures/bibdata.xml')
+=> #<Relaton3gpp::BibliographicItem:0x00007fcf5f21af30
+...
+----
+
+=== Create bibliographic item from YAML
+[source,ruby]
+----
+hash = YAML.load_file 'spec/fixtures/bib.yaml'
+=> {"schema-version"=>"v1.2.1",
+ "id"=>"3GPPTR00.01U-UMTS/3.0.0",
+...
+
+bib_hash = Relaton3gpp::HashConverter.hash_to_bib hash
+=> {:"schema-version"=>"v1.2.1",
+ :id=>"3GPPTR00.01U-UMTS/3.0.0",
+...
+
+Relaton3gpp::BibliographicItem.new(**bib_hash)
+=> #<Relaton3gpp::BibliographicItem:0x00007f92d953cbe0
+...
+----
+
+=== Fetch data
+
+There is a 3GPP dataset ftp://www.3gpp.org/Information/Databases/[latest *.csv] which can be converted into RelatonXML/BibXML/BibYAML formats.
+
+The method `Relaton3GPP::DataFetcher.fetch(output: "data", format: "yaml")` converts all the documents from the dataset and save them to the `./data` folder in YAML format.
+Arguments:
+
+- `source` - a data source name. Possible values are: `status-smg-3GPP` and `status-smg-3GPP-force`. The first one only downloads a dataset if it's updated. The second one forces this gem to download the latest dataset.
+- `output` - folder to save documents (default './data').
+- `format` - a format in which the documents are saved. Possible formats are: `yaml`, `xml`, `bibxml` (default `yaml`).
+
+[source,ruby]
+----
+Relaton3GPP::DataFetcher.fetch "status-smg-3GPP" output: "data", format: "yaml"
+Started at: 2021-12-10 19:58:46 +0100
+Stopped at: 2021-12-10 20:08:03 +0100
+Done in: 557 sec.
+=> nil
+----
+
+=== Logging
+
+Relaton3gpp 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 update the index test fixture (used by tests), run `rake spec:update_index_3gpp`. This downloads the published index from the https://github.com/relaton/relaton-data-3gpp[relaton-data-3gpp] repository, keeps a curated subset of it, and writes `spec/3gpp/fixtures/index-v2.zip`. The full index has ~88,000 rows, so the fixture is deliberately a subset; `tasks/index_fixture_3gpp.rb` documents which document groups it keeps and why.
+
+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 the created tag, 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_3gpp.
+
+== License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/relaton/adobe/CLAUDE.md

@@ -0,0 +1,104 @@
+# CLAUDE.md
+
+Dev notes for the `Relaton::Adobe` flavor. Excluded from the packaged gem via
+the gemspec `files` glob (dev docs only). See the root `CLAUDE.md` for the
+cross-flavor conventions.
+
+## What Adobe is
+
+`Relaton::Adobe` covers Adobe technical publications: **font tech notes** (the
+`adobe-type-tools/font-tech-notes` repo, numbered `ATN<NNNN>` / "Adobe Technical
+Note #<number>") and **named publications** cited by PDF-Association standards
+(Adobe Glyph List, PostScript Language, the Adobe-Japan1/GB1/CNS1/Korea1/KR-9
+character collections, etc.). Records live in the `relaton-data-adobe` data repo.
+
+The flavor mirrors the shape of `Relaton::Iala` — a thin model layer over
+`Relaton::Bib` plus a `Bibliography` retrieval front-end.
+
+## Two doctypes
+
+`Doctype::TYPES` (`doctype.rb`) is `%w[tech-note publication]`, carried in the
+inherited `content` attribute:
+
+- **`tech-note`** — numbered notes; `tech_note_number` + `source_repo_path` set.
+- **`publication`** — slug-keyed named publications; `publication_slug` set.
+
+## Typed Ext (`ext.rb`)
+
+`Relaton::Adobe::Ext < Bib::Ext` adds Adobe-specific structured metadata so it
+round-trips natively through **both** XML and YAML (no per-repo merge hacks):
+`urn`, `webpage`, `tech_note_number`, `source_repo_path`, `publication_slug`.
+Each is declared in both the `xml` and `key_value` mapping blocks. The elements
+land directly under `<ext>` (alongside the inherited `doctype`/`flavor`); the
+RelaxNG grammar (`grammar/relaton-adobe.rng`) extends `BibDataExtensionType`
+(`combine="interleave"`) with the five optional elements and restricts
+`DocumentType` to the two doctypes. `spec/adobe/relaton/adobe/xml_spec.rb`
+Jing-validates the produced XML against it.
+
+## Docidentifier (pubid-backed, mirrors OIML)
+
+`Relaton::Adobe::Docidentifier < Bib::Docidentifier` **soft-parses** its `content`
+into a `Pubid::Adobe` identifier held in `@pubid` (a `TechNote` or `Publication`),
+exactly like `Relaton::Oiml::Docidentifier`:
+
+- `content=` runs `::Pubid::Adobe.parse` and rescues — a non-canonical string
+  (e.g. a title-cased `"Adobe Glyph List"`, vs the canonical
+  `"Adobe Publication adobe-glyph-list"`) leaves `@pubid` nil while the plain
+  `content` string still round-trips.
+- The base class's abstract `remove_part!` / `remove_date!` / `to_all_parts!`
+  (which otherwise raise `NotImplementedError`) are implemented as **safe no-ops**
+  over the pubid: Adobe identifiers carry no part/date/all-parts component, so
+  these keep `Bib::ItemData#to_most_recent_reference` / `#to_all_parts` from
+  raising and never change the rendered `content`.
+
+`require "pubid"` (in `adobe.rb`) exposes `Pubid::Adobe`. pubid is already a
+gemspec dependency (shared with iso/oiml/…), so no new dep was added.
+
+## Retrieval flow (pubid-backed, mirrors OIML)
+
+`Processor#get` (`processor.rb`) → `Bibliography.get` → `Bibliography.search`
+(`bibliography.rb`), modelled on `lib/relaton/oiml/bibliography.rb`:
+
+1. Parse the reference with `::Pubid::Adobe.parse` (`pubid_for`); an unparseable
+   ref is a **graceful miss** (logged, returns nil) rather than a raised Parslet
+   error — it only reached here because it matched the flavor prefix regex.
+2. Look up in the `relaton-data-adobe` `index-v2` via
+   `Relaton::Index.find_or_create(:adobe, …, pubid_class: ::Pubid::Adobe::Identifier)`,
+   so each row's `:id` is a `Pubid::Adobe` identifier. **Tech notes narrow by
+   number** (binary search); **publications have no number**, so `search(nil)`
+   scans and the block filters. `pubid_match?` compares `row_id.to_s == query.to_s`
+   — the human render is a stable identity key (drops a tech note's filename
+   slug so `ATN5014` matches a slug-carrying record; includes a publication's
+   slug+version). Unlike OIML there is **no edition-year selection** — each
+   reference maps to a single record.
+3. `Net::HTTP.get_response` for the row's `:file` under `ENDPOINT`
+   (`raw.githubusercontent.com/relaton/relaton-data-adobe/main/`).
+4. `Relaton::Adobe::Item.from_yaml` → an `ItemData`, date-stamped via `fetched=`.
+
+Network/HTTP errors become `Relaton::RequestError`. **Do not** delegate `get`
+back into `Relaton::Db#fetch` — that both mis-arities (`Db#fetch` is 1..3 args)
+and re-enters the dispatcher, so it can never resolve.
+
+The `Processor` registers `short = :relaton_adobe`, `prefix = "Adobe"`,
+`defaultprefix = /^(?:Adobe|ATN)/` so both `Adobe Technical Note #5014` and
+`ATN5014` route here.
+
+## Status / follow-ups
+
+- `Pubid::Adobe` (identifier flavor: `TechNote` + `Publication`, prefixes
+  `["Adobe", "ATN"]`) is on pubid `main`, the version this repo pins, and is now
+  wired into both `Docidentifier` and `Bibliography`.
+- `relaton-data-adobe` (dataset) is not yet published; retrieval is wired and
+  unit-tested offline (webmock + a stubbed pubid-class index), but a live
+  end-to-end fetch waits on the data repo. When it lands, confirm rows serialize
+  as `_type: pubid:adobe:{tech-note,publication}` (the `ADOBE_TYPE_MAP` pubid
+  deserializes via `pubid_class`).
+
+## Testing
+
+- `bundle exec rake spec:adobe` — run the Adobe suite.
+- Specs live in `spec/adobe/relaton/adobe/` and run self-contained (see the root
+  `CLAUDE.md` Testing section). `xml_spec.rb` covers schema validation;
+  `docidentifier_spec.rb` covers pubid parsing + the mutation hooks;
+  `bibliography_spec.rb` covers the offline retrieval path (tech-note narrowing,
+  publication scan, ATN-alias identity, graceful miss).

data/lib/relaton/bib/CLAUDE.md

@@ -0,0 +1,130 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+RelatonBib is a Ruby gem that implements the [BibliographicItem model](https://github.com/metanorma/relaton-models#bibliography-uml-models) for bibliographic reference management. It's part of the Relaton ecosystem and serves as the base library for other Relaton gems.
+
+## Common Commands
+
+```bash
+# Install dependencies
+bundle install
+
+# Run all tests
+bundle exec rake spec
+
+# Run a single test file
+bundle exec rspec spec/relaton_bib/bibliographic_item_spec.rb
+
+# Run a specific test by line number
+bundle exec rspec spec/relaton_bib/bibliographic_item_spec.rb:42
+
+# Run linting
+bundle exec rubocop
+
+# Auto-fix linting issues
+bundle exec rubocop -a
+
+# Interactive console
+bin/console
+```
+
+## Architecture
+
+### Serialization Layer (lutaml-model)
+
+The codebase uses [lutaml-model](https://github.com/lutaml/lutaml-model) for serialization. Each model class in `lib/relaton/bib/model/` inherits from `Lutaml::Model::Serializable` and declares attributes with XML/YAML/JSON mappings.
+
+### Core Classes
+
+**`Relaton::Bib::Item`** ([lib/relaton/bib/model/item.rb](lib/relaton/bib/model/item.rb)) - The main serialization class defining all bibliographic attributes and their XML mappings. Uses `ItemData` as its underlying model.
+
+**`Relaton::Bib::ItemData`** ([lib/relaton/bib/item_data.rb](lib/relaton/bib/item_data.rb)) - The data container class that holds bibliographic data and provides conversion methods (`to_xml`, `to_yaml`, `to_bibtex`, `to_rfcxml`). This separation allows the same data to be serialized differently (bibitem vs bibdata).
+
+**`Relaton::Bib::Bibitem`** and **`Relaton::Bib::Bibdata`** - Variants of `Item` with different XML root elements and attributes (bibitem excludes `ext`, bibdata excludes `id`).
+
+### Component Models
+
+Each bibliographic attribute has its own class in `lib/relaton/bib/model/`:
+
+- `Title`, `LocalizedString`, `LocalizedMarkedUpString` - text with language/script
+- `Contributor`, `Person`, `Organization` - contributors and affiliations
+- `Docidentifier` - document IDs (DOI, ISBN, etc.)
+- `Date` - publication dates with custom `StringDate` type
+- `Relation` - related documents (circular reference with Item)
+- `Ext` - extension data (doctype, ICS codes, structured identifiers)
+
+### Sanitizing marked-up content
+
+**`Relaton::Bib::Sanitizer`** ([lib/relaton/bib/sanitizer.rb](lib/relaton/bib/sanitizer.rb))
+strips markup outside the basicdoc set. `LocalizedMarkedUpString#content=` calls it on
+assignment, so every `Title`, `Abstract`, `Note`, `Formattedref` and `Docidentifier` in
+every flavor passes through it. Two properties are load-bearing:
+
+- **It does not give up on an undeclared namespace prefix.** Third-party markup prefixes
+  its elements — Crossref returns JATS as `<jats:p><jats:italic>x</jats:italic></jats:p>`,
+  sometimes with an `xlink:` prefix on an attribute — and Relaton never declares the prefix.
+  Nokogiri reports an undeclared prefix as a parse error, so the old
+  `return content if fragment.errors.any?` returned exactly the markup that most needed
+  sanitizing. The undeclared prefix then reached the bibdata XML, relaton-render's
+  `sanitise_citations_input_string` returned nil, and isodoc raised
+  `NoMethodError: undefined method '[]' for nil` (metanorma-pdfa#99). `parse_with_prefixes`
+  now declares each prefix on a wrapper element, parses, and removes **only the wrapper's
+  own** declarations, matched by identity rather than by URI — `remove_namespaces!` would
+  also strip a namespace the content declares itself, such as the MathML `xmlns` inside an
+  opaque `<stem>`. `wrapper_name` renames the wrapper while the content contains it, so the
+  content cannot close it early — in **one** scan (`NS_WRAPPER_RX`), because growing the
+  name and re-testing with `include?` is quadratic, the same trap the root `CLAUDE.md`
+  records for relaton-cli's `strip_tags`. An undeclared prefix inside `<stem>` goes as well
+  (`<mml:math>` → `<math>`): an undeclared prefix in the output is the failure being fixed.
+  Un-prefixing an attribute renames it, so `drop_attribute_namespaces` **drops** a prefixed
+  attribute whose plain name the element already carries — keeping both would emit
+  `target="a" target="b"`, which Nokogiri rejects as `Attribute target redefined`, and that
+  is the very unparseable output this path exists to prevent. Test the collision with
+  `plain_attribute?`, not `Node#attribute`, which matches on the name alone and so finds the
+  prefixed attribute itself. The guard for genuinely malformed input stays — unbalanced tags,
+  a stray `<`, and text that only looks like a prefixed tag are all returned untouched.
+- **It does not indent.** `SAVE_OPTS` drops Nokogiri's `FORMAT` default, so
+  `sanitize("<p><em>x</em></p>")` returns the input rather than `"<p>\n  <em>x</em>\n</p>"`.
+  Don't reintroduce a bare `to_xml`.
+
+### Parsing
+
+- **`HashParserV1`** ([lib/relaton/bib/hash_parser_v1.rb](lib/relaton/bib/hash_parser_v1.rb)) - Converts legacy Hash/YAML format to `ItemData`
+- **`Converter::BibXml`** ([lib/relaton/bib/converter/bibxml.rb](lib/relaton/bib/converter/bibxml.rb)) - Parses RFC BibXML format via `Relaton::Bib::Converter::BibXml.to_item`
+- **lutaml-model native** - `Item.from_xml`, `Item.from_yaml`, `Item.from_json` handle current format
+
+### Rendering
+
+- **`Renderer::BibtexBuilder`** - Converts `ItemData` to BibTeX format
+- **`Converter::BibXml`** - Converts `ItemData` to RFC XML format via `Relaton::Bib::Converter::BibXml.to_xml`
+- **lutaml-model native** - `to_xml`, `to_yaml`, `to_json` via the serialization classes
+
+### Usage Pattern
+
+```ruby
+# Parse from YAML
+item = Relaton::Bib::Item.from_yaml(yaml_string)
+
+# Parse from XML
+item = Relaton::Bib::Bibitem.from_xml(xml_string)
+item = Relaton::Bib::Bibdata.from_xml(xml_string)
+
+# Parse from RFC XML
+item = Relaton::Bib::Converter::BibXml.to_item(xml_string)
+
+# Convert to different formats (returns string)
+item.to_xml                    # as <bibitem>
+item.to_xml(bibdata: true)     # as <bibdata>
+item.to_yaml
+item.to_bibtex
+item.to_rfcxml
+```
+
+## Code Style
+
+- Follows Ribose OSS Ruby style guide (inherited via `.rubocop.yml`)
+- Target Ruby version: 3.1+
+- Uses YARD documentation comments