pubid 2.0.4 → 2.0.6

data/lib/pubid/bipm.rb

@@ -6,13 +6,19 @@ module Pubid
     extend Pubid::PrefixesSupport
 
     # Leading tokens a printed BIPM identifier can start with: the 13 committee
-    # acronyms, "Metrologia" (journal), and "BIPM" (the SI Brochure). JCGM is
-    # deliberately excluded — it is owned by the separate Pubid::Jcgm flavor,
-    # so BIPM never emits pubid:jcgm:* rows. French full-name forms that lead
-    # with a type word ("Recommandation 1 du CCL …") are omitted per the
+    # acronyms, "Metrologia" (journal), "BIPM" (the publisher prefix the SI
+    # Brochure / MEP / guide families print), and the two SI-family series
+    # tokens that can lead a reference on their own — "SI Brochure 9e …" and
+    # "SI MEP 10" are printed without the leading BIPM by consumers that strip
+    # it (relaton's Bibliography#search among them), so both spellings must
+    # route. JCGM is deliberately excluded — it is owned by the separate
+    # Pubid::Jcgm flavor, so BIPM never emits pubid:jcgm:* rows. French
+    # full-name forms that lead with a type word ("Recommandation 1 du CCL …")
+    # and the generic French word "Rapport" are omitted per the
     # "exclude ambiguous tokens" policy.
     PREFIXES = %w[
       BIPM Metrologia
+      SI\ Brochure SI\ MEP
       CIPM CGPM JCRB CCTF CCQM CCT CCL CCAUV CCU CCM CCEM CCPR CCRI
     ].freeze
 

data/lib/pubid/bsi/CLAUDE.md

@@ -91,3 +91,7 @@ The general fix (`metanorma__pubid__exclude-recursion-depth` hand-off) promotes
 Verified: `spec/pubid/supplement_date_attributes_spec.rb` exercises the mechanism directly; `spec/pubid/bsi/parse_gaps_spec.rb`, `match_primitives_spec.rb` and `adoption_base_spec.rb`, and `spec/pubid/cen_cenelec/relaton_blockers_spec.rb`'s 10 pinned `:supplement_year` cases, all pass unchanged. Because the new logic only fires when `supplement_date_attributes` is non-empty, every other flavor (including ISO/IEC, which deliberately keep a supplement's year in `date` with no protection — see `lib/pubid/cen_cenelec/CLAUDE.md`) is untouched.
 
 **Open question, not resolved here: `#dated_version_of?`/`#draft_of?` on a bare BSI supplement.** Both compare `exclude(:date, :year[, …])`, which — like every other bare `:date`/`:year` exclusion — now protects a supplement's own date unless `:supplement_year` is also passed. Two standalone `BS 7273-4:2015+A1:2021`/`...+A1:2022` objects were `dated_version_of?` each other before this branch (BSI's old `year`-attribute dodge never protected against `exclude(:year)`) and are not after. **Whether that's the right answer is genuinely unclear and deliberately left open pending feedback** — one reading is that this just makes BSI consistent with CEN/CENELEC, which already behaved this way before this branch (its pre-existing per-flavor `#exclude` override had the same protection); the other is that these two generic relational predicates should be widened to accept a `:supplement_year`-aware exclusion set so they can still recognize two differently-dated editions of the *same supplement* as related. (The predicates switched from `matches?(other, ignore: …)` to the equivalent `exclude(…)` comparison so NIST's asymmetric `#matches?` override no longer breaks them; BSI behavior is unchanged.) Locked (as current behavior, not as a verdict) by `spec/pubid/supplement_date_attributes_spec.rb`.
+
+## The `BSI `-prefixed spelling of the BS series parses (pubid#644)
+
+`BSI BS 5950` used to be a hard parse failure: the strip in `Pubid::Bsi::Identifier.parse` (`strip_bsi_prefix`) only dropped the `BSI ` prefix before PAS/PD/DD/BIP (`BSI_PREFIXED_SERIES`), and `BS` was deliberately absent because **BSI never prints `BSI` in front of its own BS series**. That remains true of the **render** — `to_s(with_publisher: true)` still answers `BS 5950` for a British Standard, and the `BSI` prefix is re-added only for `BSI_PREFIXED_SERIES` — but **external references do cite the series as `BSI BS 5950`**, so the prefixed spelling is now accepted on **parse**: `STRIPPABLE_SERIES = BSI_PREFIXED_SERIES + ["BS"]` drives the strip, and the input normalizes to the canonical `BS 5950` (a normalizing parse — never a byte-exact fixture). Two lists, one line apart, because the parse and render halves of the same question legitimately differ: `BSI_PREFIXED_SERIES` answers "which series does BSI *print* its publisher in front of", `STRIPPABLE_SERIES` answers "which series does an *external* citation print it in front of". Locked by `spec/pubid/router_printed_forms_spec.rb` (routing + canonical render + stable reparse).

data/lib/pubid/bsi/single_identifier.rb

@@ -37,7 +37,16 @@ module Pubid
       # itself and is never preceded by it.
       BSI_PREFIXED_SERIES = %w[PAS PD DD BIP].freeze
 
-      BSI_PREFIX = /\ABSI\s+(?=(?:#{BSI_PREFIXED_SERIES.join('|')})\b)/
+      # Series tokens whose `BSI `-prefixed spelling parses (the strip below
+      # drops the prefix before the baked grammar runs). That is the
+      # BSI_PREFIXED_SERIES plus `BS`: `BS` is never PRINTED with the prefix
+      # by BSI itself, but external references do cite the British Standard
+      # series as `BSI BS 5950` (pubid#644), so the prefixed spelling is
+      # accepted on parse and normalizes to the canonical `BS 5950`. Render
+      # never re-adds the prefix for `BS` — only BSI_PREFIXED_SERIES does.
+      STRIPPABLE_SERIES = (BSI_PREFIXED_SERIES + %w[BS]).freeze
+
+      BSI_PREFIX = /\ABSI\s+(?=(?:#{STRIPPABLE_SERIES.join('|')})\b)/
 
       # `BSI PAS 2031:2019` is the external spelling of `PAS 2031:2019`. The
       # prefix is not part of the identity, so it is dropped before the baked

data/lib/pubid/ieee/builder.rb

@@ -1812,7 +1812,12 @@ module Pubid
         # Optional attributes (excluding part/subpart since they're in code)
         extract_optional(parsed, attributes, :edition)
         extract_optional(parsed, attributes, :revision)
-        extract_optional(parsed, attributes, :rev_sep)
+# A printed separator before the revision is notation residue: once the
+# revision is repositioned to the canonical face (and every corpus
+# expectation for these variants renders it absent), carrying rev_sep
+# would make the variant hash differ from its canonical equivalent.
+# Keep it only for a bare "Rev" with no number.
+extract_optional(parsed, attributes, :rev_sep) unless attributes[:revision] =~ /\A\d/
         attributes[:rev_bare] = true if parsed[:rev_bare]
 
         # Month/day - always extract if present (but not if already extracted from year)

data/lib/pubid/ietf/CLAUDE.md

@@ -5,3 +5,5 @@ IETF readiness for the unified relaton index.
 These notes were part of the root `CLAUDE.md`. Read them before you change `lib/pubid/ietf/` or `spec/pubid/ietf/`. The root file keeps the cross-flavor contract that every flavor obeys.
 
 - **IETF readiness for the unified relaton index (`relaton-data-ietf`)**: relaton is collapsing RFCs, the RFC sub-series (BCP/STD/FYI) and Internet-Drafts into **one** index keyed on the structured pubid hash (`pubid_class: ::Pubid::Ietf::Identifier`). That index is **all-or-nothing** — `Relaton::Index::FileIO#deserialize_id` raises on the *first* unparseable row and `#load_index` then rejects the whole index — so one bad id out of 176,862 means no consumer resolves *any* IETF reference. Four changes, all verified against the published corpora (`relaton-data-{rfcs,rfcsubseries,ids}`, branch `v2`). **(1) `draft_rest` accepts `.` and `A-Z`** (`match['a-zA-Z0-9+_.\-']`): exactly 50 of the 166,740 published draft ids failed without them (21 dotted `draft-ietf-pilc-2.5g3g-12`, 29 uppercase `draft-chapin-clnp-ISO8473-00`, 0 both), and a character census confirms the class now covers the corpus **exactly** — the only chars outside `[a-z0-9-]` anywhere in it are `. _ +` and `A-Z`. Widening is safe because the top-level alternation is keyed on the leading token (`RFC`/`BCP|STD|FYI`/`draft-`), so a wider draft tail can never make another branch match; `Builder#split_draft_version` needed no change (it inspects only the last three characters). The set stays **closed** — a space, `/` or `&` in a slug is crawler junk and still fails (pinned by negative examples). **(2) Zero-padded ids parse, grammar-level**: `rfc-index.xml` writes sub-series membership as `<is-also><doc-id>STD0066</doc-id></is-also>` (369 padded doc-ids) and RFCs as `RFC0001`, and relaton#109 forbids relaton normalizing them itself. The space is `.maybe` on both the `rfc` and `subseries` rules and `Builder#unpad` strips the pad (`/\A0+(?=\d)/`, a look-ahead so an all-zero number keeps its last digit), so `STD0066`/`STD 0066`/`STD66` all render the canonical `STD 66`. `unpad` is applied unconditionally, so the **spaced** padded form is normalized too — `RFC 0001` previously parsed and rendered back verbatim, and now renders `RFC 1` with a correspondingly changed hash and URN. That is deliberate (one canonical spelling per document) and has **zero** effect on the published corpora, which contain no padded row. **This is a normalizing parse, so the padded spellings must NEVER go into the byte-exact `spec/fixtures/ietf/identifiers/pass/`** — they live in `spec/pubid/ietf/zero_padded_spec.rb`, the BIPM `CIPM/2005-06(REV)` precedent. **(3) The Internet-Draft slug moved from `name` into `number`, and `series` became derived**: relaton bsearches on `id.root.number.to_s`, so with the slug in `name` all 166,740 drafts keyed to `""` and the narrowing bought nothing (with the slug: 43,564 buckets, median 2, worst 101). `name` is **dropped entirely** (no alias); the slug — leading `draft-` included — is the key, deliberately shared by a draft's unversioned aggregator row and every one of its versions so a document and its variants cluster. `series` is likewise **not stored**: `_type: pubid:ietf:std` already encodes it, so `Bcp`/`Std`/`Fyi` expose a `SERIES` constant + a plain `#series` reader (safe — `::Pubid::Identifier` declares no `series` attribute and nothing generic reads `.series`) and `build_subseries` stops passing it. The whole serialized vocabulary is now **three keys**: `_type` + `number` always, `version` only on a versioned draft — a sub-series row (`{_type, number}`) has the same shape as an RFC's. **The attributes live on the five LEAVES, not the shared `Pubid::Ietf::Identifier`**, via the `Identifiers::Serialization` mixin (`number` + the `key_value` block; `InternetDraft` merges its own `version` mapping on top — lutaml combines a mixin-installed block with a second in-class one, the ITU precedent). This is the IEEE `number` determinism landmine: a `:string` redefinition of the parent's `Components::Code number` on a class the leaves *inherit* from resolves nondeterministically under multi-flavor load. It was invisible while drafts left `number` nil; it is load-bearing now. The base deliberately carries **no** `key_value` block — one there would be inherited-and-merged by every leaf. `spec/pubid/ietf/root_number_spec.rb` is the tripwire (asserts `number` is a `String`, the exact keys, the exact `to_hash` key sets) and **must run under the full `rake` suite** to mean anything. **(4) Round-trip is validated here because relaton structurally cannot**: `FileIO#id_supported?` **skips** its `to_hash`/`from_hash` check whenever the object is a concrete subclass (`return true unless obj.instance_of?(@pubid_class)`), and *every* IETF id is a subclass — so a lossy round-trip would pass validation silently and produce wrong lookups. Three layers: `fixtures_spec.rb` is now **zero-failure** (was a 90% threshold — wrong for an all-or-nothing index) and checks `to_s` byte-exactness, `from_hash(to_hash)` fidelity in both `to_s` and `to_hash`, **and** a non-empty `root.number` for every fixture line; the fixtures grew to ~2,500 lines (the complete 365-row sub-series corpus, a 139-id structural edge set, a deterministic 1-in-84 draft sample — each file's header records the regeneration command); and `spec/pubid/ietf/corpus_round_trip_spec.rb` runs the same four checks over all 176,862 published ids, **opt-in** via `PUBID_IETF_CORPUS=<dir with the three relaton-data checkouts> bundle exec rake test:corpus_ietf` (self-skips otherwise; ~100s; verified 0 failures). **relaton note — the indexes must be regenerated, there is no alias**: `name` and `series` are gone as serialized keys, so a pre-`number` row (`{_type, name, version}`) deserializes with **`number` nil** and no error at all — lutaml ignores unknown keys, and relaton's subclass skip means `id_supported?` won't catch it either, leaving every draft keyed under `""`. Rendering is therefore the loud failure: `Renderer#require_number!` raises `ArgumentError` on a nil/empty `number` rather than returning `nil` or `"-02"`, and the renderer's sub-series arm is an explicit `when Bcp, Std, Fyi` with an `else raise` instead of a catch-all (a bare `Pubid::Ietf::Identifier` has no `series` reader). Pinned by the "legacy `name`-shaped hash" block in `root_number_spec.rb`. **Pre-existing bug fixed in passing**: `UrnParser`'s bare `Errors::ParseError` does not resolve — `Errors` lives under `Pubid::UrnParser` (the module), which is neither in the lexical scope of `Pubid::Ietf::UrnParser` nor an ancestor of `Base` — so an invalid URN raised `NameError` instead, and the spec's `raise_error(StandardError)` accepted it. Now fully qualified as `Pubid::UrnParser::Errors::ParseError` (the adobe/easc/gost/iala convention) with the spec asserting that exact class. **`Pubid::Iec::UrnParser` has the identical bug and is untouched here.** Also: `Identifier.parse` gained the inline `MAX_INPUT_LENGTH` guard — relaton reaches that class-level funnel directly through `pubid_class:`, bypassing `Pubid::Ietf.parse` — and IETF was added to the three cross-flavor tables it was missing from (`identifier_roundtrip_spec`, `uniform_identifier_handle_spec`, `redos_guard_spec`), which is what exercises the leaf `number` under real multi-flavor load. (hand-off: ietf-index-readiness.)
+
+- **`IETF` is a prefix (pubid#644)**: `PREFIXES` gained the publisher token itself. `strip_prefix` (`lib/pubid/ietf/identifiers/base.rb`) already parsed the external spellings `IETF RFC 8341` / `IETF I-D draft-…`, and `to_s(with_publisher: true)` prints that same `IETF `-prefixed form — but without "IETF" in the prefix table the flavor had **no claim** on the string, and the router's non-exact fallback (`IETF RFC 2119` normalizes to the canonical `RFC 2119`) is reserved for prefix owners. So `Pubid.parse("IETF RFC 2119")` raised while `Pubid::Ietf.parse` succeeded. With the prefix registered, the router routes it (fallback path) and the `with_publisher: true` render reproduces the input byte for byte. Bare `RFC 2119` keeps routing exactly as before (exact round trip). Locked by `spec/pubid/router_printed_forms_spec.rb`.

data/lib/pubid/ietf.rb

@@ -11,8 +11,11 @@ module Pubid
     extend Pubid::PrefixesSupport
 
     # Leading tokens a printed IETF id can begin with. "draft" covers the
-    # "draft-<slug>" Internet-Draft form. No joint/co-publication prefixes.
-    PREFIXES = ["RFC", "BCP", "STD", "FYI", "draft"].freeze
+    # "draft-<slug>" Internet-Draft form. "IETF" covers the external
+    # publisher-prefixed spelling ("IETF RFC 2119", "IETF I-D draft-…") that
+    # the flavor's own strip_prefix parses and `to_s(with_publisher: true)`
+    # prints back. No joint/co-publication prefixes.
+    PREFIXES = ["IETF", "RFC", "BCP", "STD", "FYI", "draft"].freeze
 
     autoload :Builder, "#{__dir__}/ietf/builder"
     autoload :Identifier, "#{__dir__}/ietf/identifiers/base"

data/lib/pubid/iho/CLAUDE.md

@@ -1,98 +1,174 @@
 # IHO flavor notes
 
 IHO (International Hydrographic Organization) identifiers: the
-S/P/M/B/C letter series, their parg-driven parse, and the series
-components introduced for relaton/relaton#407.
+S/P/M/B/C letter series, their parg-driven parse, and the full
+component model (edition, supplement, part, annex, appendix +
+subnumber, volume, issue, with-year qualifier) from the owner rulings
+of 2026-11-03.
 
 Read this before you change `lib/pubid/iho/` or `spec/pubid/iho/`. The
 root `CLAUDE.md` keeps the cross-flavor contract that every flavor
 obeys.
 
-## Parsing runs on the parg artifact
+## Parsing runs on the parg artifact, through typed bindings
 
 There is no `parser.rb` and no Parslet anywhere in this flavor: parse
-goes `Pubid::Parg::Backend.parse(:iho, ...)` over the baked artifact
-`data/parg/iho.json`. The artifact is baked from the flavor grammar
-source `grammars/iho.parg` in the pubid-grammar repository (commit
-840b2b1d "Retire the last live Parslet parsers" ports the original
-13-rule Parslet grammar byte-identically).
-
-**Drift warning:** the artifact on this branch carries the
-relaton/relaton#407 tail rules (year / volume / issue), while the
-checked-in `grammars/iho.parg` in pubid-grammar still has only the
-version tail. Until the updated grammar source lands in pubid-grammar,
-the artifact is ahead of its source and not reproducible from it —
-the same artifact-ahead-of-source state the root notes describe under
-grammar-artifact drift. Do not re-bake from the stale source, and do
-not hand-edit the artifact; land the grammar first.
-
-## Series components (relaton/relaton#407)
-
-The B-7, P-1, P-5, P-6 series are continuously updated publications
-whose trailing component is not an a.b.c edition: P-5/P-6 (and B-7)
-are identified by **year**, P-1 (the International Hydrographic
-Review) by **volume** with an optional **issue**. The grammar tail
-picks exactly one discriminator, so only one of `version` / `year` /
-`volume` is ever present, with `issue` only beside a volume:
-
-- `IHO P-5 2024` — year is a plain `:string` scalar, 19xx/20xx only
-  (`IHO P-5 1850` and the two-segment `IHO B-12 3.0` reject).
-- `IHO P-1 Vol. 30 (2)` — volume/issue scalars; `Issue 2` is an input
-  alias whose canonical print is `(2)`.
-- `IHO S-44 5.0.0` — the dotted `version` stays for the edition-bearing
-  series and legacy `1.0.0` placeholder rows.
-
-All three are ordinary lutaml attributes mapped through the flavor's
-`key_value` block — no converters, no hand-rolled serialization.
-
-**Identity semantics:** the components are identity-bearing in `==` /
-`matches?`; a bare reference (`IHO P-5`) leaves all four nil and
-wildcards the series (`spec/pubid/partial_ref_spec.rb` locks the
-omitted-key set). The volume/issue pair is a scalar **cluster**:
-`exclude(:volume)` nils the issue with it, so a reference that omits
-the issue still matches a hit that carries one — the same
-additive-alias shape the base applies to `:year -> :date`. A lone
-scalar `:year` needs no override; the base nils a declared `:year`
-directly.
-
-**`all_parts_edition_keys` needs no override:** the default
-`%i[date year edition version]` already covers `:year` and `version`,
-and volume/issue only ride part-less ids, which cannot join
-`AllParts` (`validate_member!` demands a `part`). The audit case in
-`spec/pubid/all_parts_edition_keys_audit_spec.rb` covers the
-version-bearing S-series collapse.
-
-**URN conventions:** only the dotted `version` is an untagged
-segment. A year is tagged `y.N` (`urn:iho:p:5:y.2024`); a volume is a
-`vol.N` segment with an optional `issue.N` segment after it
-(`urn:iho:p:1:vol.30:issue.2`). The URN parser walks the tagged
-segments as a run and hands the rebuilt text back through the flavor
-parse, so a URN round-trip exercises the same grammar as a string.
-**The number is not escaped and can hold a colon** (`IHO S-158:100`
-gives `urn:iho:s:158:100`), so the parser joins every untagged segment
-that is not an a.b.c version back into the number. That is why the
-year must carry a tag: with the bare year that pubid 2.0.2 emitted,
-`IHO S-158:2024` and `IHO S-158 2024` both gave `urn:iho:s:158:2024`,
-and no colon number round-tripped at all. A 2.0.2 year URN such as
-`urn:iho:p:5:2024` now decodes as the number `5:2024`; it was emitted
-only by 2.0.2. A tagged segment with an unknown tag raises
-`Pubid::Errors::UrnParseError`.
+goes `Pubid::Parg::Model.bound(:iho, ...)` — the artifact's
+`bindings identifier` block delivers every component as an
+attribute-named scalar, and `Builder` only dispatches the series
+letter to its concrete class and pads one grammar-level alias (the
+S-100 `v1`/`v5.1` shorthand fills `edition` as `1.0.0`/`5.1.0`). The
+artifact is baked from `grammars/iho.parg` in pubid-grammar; the
+vendored twin `data/parg/iho.parg` is the embedded source's provenance
+copy and must move together with `data/parg/iho.json` (the ISO
+pattern).
+
+**Bake pin:** the artifact must be baked at parsanol 1.3.126 (the
+grammar repo's `scripts/bake-one.rb` forces the gem version and
+verifies the `compiler_version` stamp). 1.3.127 is broken fleet-wide
+(parsanol-ruby#434 — its loud-loss check matches the binding PATH
+instead of the CAPTURE name), so both repos pin below it: the grammar
+repo's CI moved 1.3.121 → 1.3.126 with the component-model PR.
+
+## The component model (owner rulings, 2026-11-03)
+
+Every component is a FIRST-CLASS SEMANTIC component: a typed `:string`
+attribute, independently addressable, URN-encodable and matchable —
+never a string suffix. All of them live flat on `Pubid::Iho::Identifier`
+(mapped through the flavor `key_value` block, no converters):
+
+| component   | attribute          | canonical face    | parse-only aliases           |
+|-------------|--------------------|-------------------|------------------------------|
+| edition     | `edition`          | `1.0.0` (bare)    | `v1`/`v5.1` (padded)         |
+| supplement  | `supplement`       | `Sup 1`           | `Suppl 1`                    |
+| part        | `part`             | `Part A`/`Part 1`/`Part S-102` | `S-5-B`, `S-100-1`, `S-158-S-102` (compact) |
+| annex       | `annex`            | `Annex A`         | —                            |
+| appendix    | `appendix`         | `Appendix D`      | `App`, `Ap.`                 |
+| subnumber   | `appendix_subnumber` | `-2` (joined)   | —                            |
+| volume      | `volume`           | `Vol. 30`/`Vol. 2024` | `/21` (slash chain), bare `2024` |
+| issue       | `issue`            | `(2)`             | `Issue 2`                    |
+| year (qualifier) | `year`        | `(2024)`          | —                            |
+| component edition | `<kind>_edition` (+ `<kind>_year`) | `<kind> x.y.z (2024)` | —     |
+
+- **Two main syntaxes:** `IHO S-100 1.0.0` (dated = edition-specific)
+  and `IHO S-100` (undated = edition-non-specific). The official IHO
+  edition is the dotted x.y.z WITHOUT a year; a year beside an edition
+  is the with-year qualifier, never a year-keyed docidentifier. The
+  canonical part face is edition-before-part: `IHO S-100 1.0.0 Part 2`.
+- **The part's compact face is hyphenated** (`IHO S-5-B`,
+  `IHO S-100-1`) — it parses AND renders via `to_s(compact: true)`.
+  Gluing without a separator is disallowed as a form: it cannot extend
+  to numbered parts unambiguously (`S-1001`). The four lettered glued
+  bases in the records (S-5A, S-5B, S-8A, S-8B) are LEGACY parse-only
+  aliases, never rendered; the owner rules later whether to reject
+  them. The dash-digit suffix that used to join the number (`P-6-3` as
+  number "6-3") is now the part component.
+- **One serial locator: the volume.** P-1 and P-6 are volume-keyed;
+  the yearbook year IS a volume (`IHO P-5 Vol. 2024`, short
+  `IHO P-5/2024`). The bare year (`IHO P-5 2024`) is a legacy alias
+  that binds INTO `volume` — `year` never carries a serial locator.
+- **The with-year qualifier** (`IHO S-100 5.0.0 Part 2 (2024)`) is the
+  only base `year` face, always parenthesized beside an edition.
+- **Component-edition duality** (owner: "this can happen with any
+  independently publishable artifacts"): supplement, part, annex,
+  appendix and volume each carry an optional `<kind>_edition` (+
+  `<kind>_year`) of their own, MUTUALLY EXCLUSIVE with the base edition
+  context — within-edition (`IHO P-6 1.0.0 Vol. 2`, the component rides
+  the base's edition) vs separately-published (`IHO P-6 Vol. 2 1.0.1`,
+  `IHO S-98 Part A 1.0.0`, `IHO S-158 Part S-102 0.2.0`; the base is
+  cited edition-less). The builder raises when both appear. Every
+  trailing edition now follows a component, so the historical
+  edition-last spellings reinterpret as component editions.
+- **Series-reference parts**: a check standard applied to another IHO
+  series cites it as its part — `IHO S-158 0.2.0 Part S-102`, compact
+  `IHO S-158-S-102` (the part value vocabulary is letter | number |
+  `[SPMBC]-<digits>`). The wild glued `S-158-102` stays a plain number
+  part: the syntax cannot distinguish it from `S-100-1` = Part 1, and
+  normalizing it needs an IHO series table (owner call pending).
+- **Supplement canonical face is `Sup`** (the M-2 spelling — why save
+  two characters when Annex and Appendix stay full-length); `Suppl`
+  (the S-66 wild spelling) is the parse-only alias, never rendered.
+- **Appendix canonical face is `Appendix`**; the subnumber keeps its
+  own component (`Appendix D` + `appendix_subnumber` "2" render joined
+  as `Appendix D-2`).
+
+The compact face (`compact: true`) folds the code-adjacent components
+onto the code: supplement and part hyphenated, volume as the slash
+chain — `IHO M-2-2`, `IHO S-100-2 5.0.0`, `IHO P-5/2024`.
+
+## Identity semantics
+
+- The components are identity-bearing in `==`/`matches?`; a bare
+  reference (`IHO P-5`) leaves them all nil and wildcards the series
+  (`spec/pubid/partial_ref_spec.rb` locks the omitted-key set:
+  edition/year/volume/issue).
+- Scalar **clusters**: `exclude(:volume)` nils `issue` with it, and
+  `exclude(:appendix)` nils `appendix_subnumber` — a reference that
+  omits the finer component still matches a hit that carries one (the
+  base's additive `:year -> :date` alias shape).
+- `all_parts_edition_keys` needs no override: the default
+  `%i[date year edition version]` already covers `:year` and
+  `:edition`.
+
+## URN scheme — positional, containment-ordered
+
+The URN mirrors the containment tree, one semantic atom per segment;
+the segment grammar table lives in the grammar header
+(`grammars/iho.parg`) and is implemented by
+`urn_generator.rb`/`urn_parser.rb`:
+
+    urn:iho:<type>:<number>[:ed-<x.y.z>][:sup-<n>][:part-<X>]
+      [:annex-<A>][:appendix-<B>][:<sub>][:vol-<n>][:issue-<n>]
+      [:year-<yyyy>]
+
+- Markers are the lowercased face tokens (`ed-` follows ISO's
+  RFC 5141 precedent); letters are case-preserved.
+- `ed-` and `year-` are POSITIONAL: the edition attaches to the node it
+  follows — the base when no component precedes it, else that
+  component's own edition (`vol-2:ed-1.0.1` = separately-published
+  volume). A `year-` belongs to a component only when it follows that
+  component's own edition; otherwise it is the base with-year
+  qualifier.
+- Containment: part ⊃ annex ⊃ appendix ⊃ subnumber (bare digit atom,
+  only directly after its appendix); vol ⊃ issue.
+- The number occupies every leading bare segment up to the first
+  marker, so a colon number (`S-158:100` → `urn:iho:s:158:100`)
+  round-trips without escaping. A colon number and a volume stay
+  distinct because the volume is marker-tagged (`urn:iho:s:158:2024`
+  vs `urn:iho:s:158:vol-2024` — the #637 hazard, kept under the
+  positional scheme).
+- The yearbook year emits as the volume (`urn:iho:p:5:vol-2024`);
+  `year-` exists only for the standards qualifier.
+- The parser validates every marker value against its own pattern and
+  rejects unknown/reordered/duplicate/junk segments with
+  `Pubid::Errors::UrnParseError` (the ISO urn_parser strictness); it
+  builds through `Builder.build` from the decoded attributes, so URN
+  decode and string parse share one construction path.
+
+**Breaking URN migrations this scheme carries** (legacy forms stay
+decodable, never emitted): the dotted keys (`part.4a`, `suppl.1`,
+`ap.A`, `annex.A`, `vol.30`, `issue.2`, `appendix.D-2`) and the bare
+a.b.c edition segment move to the marker segments; the #635/#637
+`y.2024` tag decodes into the **volume** (`urn:iho:p:5:y.2024` now
+re-emits as `urn:iho:p:5:vol-2024`). relaton-data-iho needs a re-crawl
+(it is already legacy pre-pubid-2 shape); the frozen testsuite corpus
+rows are re-frozen in the coupled corpus round.
 
 ## Fixtures run through the classify pipeline
 
 `spec/fixtures/iho/identifiers/full/identifiers.txt` is the input
-corpus; `rake "validation:classify[iho]"` regenerates `pass/` and
-`fail/` from it (the classifier deletes pass/fail first — never edit
-them by hand, edit `full/` and reclassify). Before the relaton#407
-branch the pass files were hand-curated with **no** `full/` tree, the
-OASIS hazard: a classify run would have wiped 131 entries and rebuilt
-nothing. The classifier's per-flavor class detection has an `iho`
-case, so fail entries land in a named class file.
+corpus (seeded from the hand-curated pass files, the #407 serial
+forms and the component-model matrix off the IHO publications
+spreadsheet); `rake "validation:classify[iho]"` regenerates `pass/`
+and `fail/` from it (the classifier deletes pass/fail first — never
+edit them by hand, edit `full/` and reclassify). The normalizing
+parses (Suppl→Sup, Ap.→Appendix, glued→expanded, bare year→Vol.,
+v-shorthand→dotted) are recorded as `!input!rendered` entries.
 
 ## relaton-side follow-ups (not this repo)
 
-relaton/relaton#407 items 3-4 stay open on the relaton side:
-`Relaton::Iho::Bibliography#pubid_match?`/`version_key` need the new
-component, relaton-cli's `MachineIndex::REFINABLE_KEYS` needs
-`year`/`volume` beside `version`/`edition`, and the pubid pin bumps
-in step with the relaton-data-iho re-key.
+`Relaton::Iho::Bibliography#pubid_match?`/`version_key` need the
+edition rename (the serialized key moved `version` → `edition`) and
+the volume unification; relaton-cli's `MachineIndex::REFINABLE_KEYS`
+needs `edition`/`volume` beside the retired `version`/`year` keys; the
+pubid pin moves in step with the relaton-data-iho re-key.

data/lib/pubid/iho/builder.rb

@@ -2,25 +2,35 @@
 
 module Pubid
   module Iho
-    # Build IHO identifier objects from the parg artifact parse tree.
+    # Build IHO identifier objects from the grammar's typed bound map.
+    #
+    # Parse goes through {Pubid::Parg::Model.bound} — the artifact's
+    # `bindings identifier` block delivers every component as an
+    # attribute-named scalar (type, number, part, annex, appendix,
+    # appendix_subnumber, supplement, edition, edition_shorthand, year,
+    # volume, issue) — so the builder only dispatches the series letter
+    # to its concrete class and resolves the one grammar-level alias:
+    # the S-100 "v1"/"v5.1" edition shorthand pads to the official
+    # dotted x.y.z edition ("1" -> "1.0.0", "5.1" -> "5.1.0").
     class Builder
+      ATTRIBUTES = %i[number appendix appendix_subnumber part annex
+                      supplement year volume issue
+                      part_edition part_year supplement_edition
+                      supplement_year annex_edition annex_year
+                      appendix_edition appendix_year volume_edition
+                      volume_year].freeze
+      # The independently-publishable components' own editions; the
+      # base edition context is mutually exclusive with them (owner
+      # ruling on the two publication modes).
+      COMPONENT_EDITIONS = %i[part_edition supplement_edition annex_edition
+                              appendix_edition volume_edition].freeze
+
       def build(parsed)
         hash = parsed.is_a?(Array) ? parsed.reduce({}, :merge) : parsed
-        type_letter = stringify(hash[:type])
-
-        attrs = {
-          number: stringify(hash[:number]),
-          appendix: stringify(hash[:appendix]),
-          part: stringify(hash[:part]),
-          annex: stringify(hash[:annex]),
-          supplement: stringify(hash[:supplement]),
-          version: stringify(hash[:version]),
-          year: stringify(hash[:year]),
-          volume: stringify(hash[:volume]),
-          issue: stringify(hash[:issue]),
-        }.compact
-
-        Pubid::Iho.identifier_klass_for_type_letter(type_letter).new(**attrs)
+        attrs = stringified_attrs(hash)
+        assert_edition_mode!(attrs)
+        klass = Pubid::Iho.identifier_klass_for_type_letter(stringify(hash[:type]))
+        klass.new(**attrs)
       end
 
       def self.build(parsed)
@@ -29,6 +39,41 @@ module Pubid
 
       private
 
+      # The two publication modes are mutually exclusive: an identifier
+      # is either within-edition (a base edition its components ride) or
+      # separately-published (a component carries its own edition and
+      # the base is cited edition-less).
+      def assert_edition_mode!(attrs)
+        return unless attrs[:edition]
+        return unless COMPONENT_EDITIONS.any? { |key| attrs[key] }
+
+        owned = attrs.slice(*COMPONENT_EDITIONS).compact.keys.join(", ")
+        raise ArgumentError,
+              "a base edition and a component edition are mutually " \
+              "exclusive: #{owned} cannot ride edition #{attrs[:edition]}"
+      end
+
+      def stringified_attrs(hash)
+        attrs = ATTRIBUTES.to_h { |key| [key, stringify(hash[key])] }
+        attrs[:edition] = edition_from(hash[:edition], hash[:edition_shorthand])
+        attrs.compact
+      end
+
+      # The official IHO edition is the dotted x.y.z; the "v1"/"v5.1"
+      # shorthand is a parse-only alias that fills the same attribute.
+      def edition_from(edition, shorthand)
+        return stringify(edition) if edition
+
+        pad_edition_shorthand(shorthand)
+      end
+
+      def pad_edition_shorthand(shorthand)
+        return nil if shorthand.nil?
+
+        major, minor = stringify(shorthand).split(".")
+        "#{major}.#{minor || '0'}.0"
+      end
+
       def stringify(value)
         return nil if value.nil?
 

data/lib/pubid/iho/identifier.rb

@@ -3,5 +3,5 @@
 # The IHO flavor base class is Pubid::Iho::Identifier — a real Pubid::Identifier
 # subclass that every concrete IHO identifier descends from, so `is_a?` identity
 # and the shared polymorphic `from_hash` work natively (no facade needed). Its
-# body and `.parse` live in identifiers/base.rb; this file just ensures it is loaded when a consumer
-# references Pubid::Iho::Identifier directly.
+# body and `.parse` live in identifiers/base.rb; this file just ensures
+# it is loaded when a consumer references Pubid::Iho::Identifier directly.