pubid 2.0.3 → 2.0.5

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.

data/lib/pubid/iho/identifiers/base.rb

@@ -6,10 +6,17 @@ module Pubid
     # every concrete IHO identifier (Identifiers::*) descends from it.
     #
     # IHO identifiers have the form:
-    #   IHO {S|P|M|B|C}-{number}[ Ap. {appendix}][ Part {part}][ Annex {annex}][ Suppl {supplement}][ {version|year|Vol. N [issue]}]
+    #   IHO {S|P|M|B|C}-{number}[ {edition}| Vol. N [(issue)]]
+    #       [ Sup N][ Part X][ Annex A][ Appendix B[-2]] [(2024)]
     #
-    # The leading IHO publisher prefix is optional on input but always
-    # emitted on output.
+    # Every tail component is a first-class semantic component: a typed
+    # attribute, independently addressable, URN-encodable and matchable.
+    # The canonical faces order the edition BEFORE the part
+    # (`IHO S-100 1.0.0 Part 2`), print the supplement as "Sup" and the
+    # appendix as "Appendix" (with the subnumber after a dash), the
+    # volume issue parenthesized (`IHO P-1 Vol. 30 (2)`), and the
+    # with-year qualifier parenthesized (`IHO S-100 5.0.0 Part 2 (2024)`
+    # — the only year face: a periodical year IS a volume).
     class Identifier < ::Pubid::Identifier
       # Parse an IHO identifier string into an identifier object
       # @param identifier [String] The IHO identifier string to parse
@@ -25,32 +32,55 @@ module Pubid
           raise Pubid::Errors::InvalidInputError, Pubid::INPUT_TOO_LONG_MESSAGE
         end
 
-        parsed = Pubid::Parg::Backend.parse(:iho, identifier.strip)
+        parsed = Pubid::Parg::Model.bound(:iho, identifier.strip)
         Builder.build(parsed)
       end
 
       # `number` overrides the generic Components::Code attribute with a plain
-      # string (same pattern as `part` below); it holds the IHO document
-      # number (e.g. "100", "1/21"). Kept as the generic `number` so the
-      # relaton index sorts/binary-searches on it natively via `id.number`.
+      # string (same pattern as the other string components); it holds the IHO
+      # document number (e.g. "100", "1/21" until the slash-chain volume
+      # parse, "158:100"). Kept as the generic `number` so the relaton index
+      # sorts/binary-searches on it natively via `id.number`.
       attribute :number,     :string
       attribute :publisher,  :string, default: "IHO"
-      attribute :appendix,   :string
-      attribute :part,       :string
-      attribute :annex,      :string
-      attribute :supplement, :string
-      attribute :version,    :string
-      # Series identity components (relaton#407): the year-identified
-      # series (B-7, P-5, P-6) and the volume/issue-identified ones
-      # (P-1 and the IHR) carry no a.b.c edition — their trailing
-      # component is a year or a "Vol. N [issue]" pair instead. Plain
-      # scalars, like every other IHO attribute; the grammar's tail
-      # picks exactly one discriminator, so only one of
-      # version/year/volume is ever present, with issue only
-      # alongside volume.
+      # The official IHO edition is the dotted x.y.z (a plain string — the
+      # ~16 string-edition flavors precede this). `IHO S-100 1.0.0` is
+      # edition-specific, `IHO S-100` edition-non-specific; a year beside an
+      # edition is the with-year qualifier, never a year-keyed docidentifier.
+      attribute :edition,    :string
+      # The with-year qualifier on standards (`(2024)` beside an edition) —
+      # the only year component. A periodical year IS a volume: the bare
+      # legacy year input ("IHO P-5 2024") binds into `volume`, so this
+      # attribute never carries a serial locator.
       attribute :year,       :string
+      # Supplement, part, annex, appendix and volume are independently
+      # publishable (owner ruling: "this can happen with any independently
+      # publishable artifacts"), so each carries an optional edition (+ year
+      # qualifier) of its own, mutually exclusive with the base edition
+      # context: `IHO P-6 1.0.0 Vol. 2` (within-edition) vs
+      # `IHO P-6 Vol. 2 1.0.1` (separately-published). The URN attaches
+      # ed- to the node it follows, so one positional slot records both.
+      attribute :supplement, :string
+      attribute :supplement_edition, :string
+      attribute :supplement_year,    :string
+      attribute :part, :string
+      attribute :part_edition, :string
+      attribute :part_year,    :string
+      attribute :annex, :string
+      attribute :annex_edition, :string
+      attribute :annex_year,    :string
+      # The appendix is a letter or a number; a subnumbered appendix
+      # ("Appendix D-2") keeps the letter in `appendix` and the "2" in
+      # `appendix_subnumber` — two independently addressable components,
+      # not one string.
+      attribute :appendix, :string
+      attribute :appendix_subnumber, :string
+      attribute :appendix_edition,   :string
+      attribute :appendix_year,      :string
       attribute :volume,     :string
       attribute :issue,      :string
+      attribute :volume_edition, :string
+      attribute :volume_year,    :string
 
       # Polymorphic type map for lutaml::Model key_value serialization: maps
       # each subclass's polymorphic_name to its class name so `from_hash` can
@@ -71,31 +101,98 @@ module Pubid
       key_value do
         map "_type",      to: :_type, polymorphic_map: IHO_TYPE_MAP
         map "number",     to: :number
-        map "appendix",   to: :appendix
-        map "part",       to: :part
-        map "annex",      to: :annex
-        map "supplement", to: :supplement
-        map "version",    to: :version
+        map "edition",    to: :edition
         map "year",       to: :year
-        map "volume",     to: :volume
-        map "issue",      to: :issue
+        map "supplement",         to: :supplement
+        map "supplement_edition", to: :supplement_edition
+        map "supplement_year",    to: :supplement_year
+        map "part",               to: :part
+        map "part_edition",       to: :part_edition
+        map "part_year",          to: :part_year
+        map "annex",              to: :annex
+        map "annex_edition",      to: :annex_edition
+        map "annex_year",         to: :annex_year
+        map "appendix",           to: :appendix
+        map "appendix_subnumber", to: :appendix_subnumber
+        map "appendix_edition",   to: :appendix_edition
+        map "appendix_year",      to: :appendix_year
+        map "volume",             to: :volume
+        map "volume_edition",     to: :volume_edition
+        map "volume_year",        to: :volume_year
+        map "issue",              to: :issue
       end
 
       # from_hash is the shared polymorphic dispatch on Pubid::Identifier.
-      # IHO_TYPE_MAP remains as the key_value polymorphic_map.
-
-      # The volume/issue pair is a scalar cluster: a reference that omits
-      # the issue must still match a hit that carries one ("P-1 Vol. 30"
-      # vs "P-1 Vol. 30 (2)"), so excluding the volume nils the issue
-      # with it — the same additive-alias shape the base applies to
-      # :year -> :date. A lone scalar :year needs no override here: the
-      # base nils a declared :year directly (the additive :year -> :date
-      # alias nils whichever name the flavor declares).
+      # IHO_TYPE_MAP remains the key_value polymorphic_map.
+
+      # The volume/issue and appendix/subnumber pairs are scalar clusters:
+      # a reference that omits the finer component must still match a hit
+      # that carries one ("P-1 Vol. 30" vs "P-1 Vol. 30 (2)"), so excluding
+      # the coarser component nils the finer one with it — the same
+      # additive-alias shape the base applies to :year -> :date. A lone
+      # scalar :year needs no override here: the base nils a declared :year
+      # directly (the additive :year -> :date alias nils whichever name the
+      # flavor declares).
       def exclude(*args)
+        args = args.dup
         args << :issue if args.include?(:volume)
+        args << :appendix_subnumber if args.include?(:appendix)
         super
       end
-    end
 
+      # Render the compact face: the code-adjacent components folded onto
+      # the code with separators — the supplement and the part hyphenated
+      # (`IHO M-2-2` for `IHO M-2 Sup 2`, `IHO S-5-B` for `IHO S-5 Part B`,
+      # `IHO S-100-1` for `IHO S-100 Part 1`) and the volume as the slash
+      # chain (`IHO P-5/2024` for `IHO P-5 Vol. 2024`). The canonical
+      # render stays expanded; compact is opt-in. The legacy faces (glued
+      # lettered bases, Suppl, bare years) parse but are never rendered in
+      # any form.
+      def render(format: :human, **opts)
+        compact = opts.delete(:compact)
+        result = super
+        compact && format == :human ? compact_face(result) : result
+      end
+
+      # The shared mr_string path reads `edition&.number` (the base
+      # declares edition as Components::Edition); IHO's edition is a plain
+      # string, so the segment is built from it directly.
+      def mr_edition
+        return nil unless edition
+
+        "ed#{edition}"
+      end
+
+      private
+
+      # Fold " Sup N" / " Part X" / " Vol. N" into the code as "-N" /
+      # "-X" / "/N", keeping everything else in place (the edition
+      # follows the compact code, as in the legacy "S-5A 1.0.2" print
+      # order). The issue keeps its parenthesized print.
+      def compact_face(rendered)
+        result = rendered.sub(/\A#{publisher} #{base_code}(?= |$)/,
+                              "#{publisher} #{compact_code}")
+        folded_segments.each { |segment| result = result.sub(segment, "") }
+        result
+      end
+
+      def base_code
+        "#{self.class.type[:short]}-#{number}"
+      end
+
+      def compact_code
+        code = base_code.dup
+        code << "-#{supplement}" if supplement
+        code << "-#{part}" if part
+        code << "/#{volume}" if volume
+        code
+      end
+
+      def folded_segments
+        [supplement && " Sup #{supplement}",
+         part && " Part #{part}",
+         volume && " Vol. #{volume}"].compact
+      end
+    end
   end
 end