colregs 0.1.1 → 0.2.2

package/docs/adr/0001-name-and-jurisdiction-model.md

@@ -1,7 +1,7 @@
 # ADR 0001 — Package name, and jurisdiction as a dimension
 
 Date: 2026-08-29
-Status: accepted
+Status: accepted; amended 2026-09-05 (licence terms verified, see Amendments)
 
 ## Context
 
@@ -69,8 +69,126 @@ been too narrow. Neither failure was about taste.
   configurations, no prior art as structured data, and the only licence on the
   list that might block outright.
 
+  *Superseded 2026-09-05: the table above is the recalled state and is kept
+  as the record of what was assumed. The verified terms are in Amendments
+  below.*
+
 ## Not decided here
 
 The switching plugin's name and the renderer's name. The plugin needs a
 `signalk-` prefix for app-store discovery regardless; `lamp-wright` and
 `fanali` are both available and both fit the family for the renderer.
+
+## Amendments
+
+### 2026-09-05 — Licence terms verified against the primary sources (Q-3, REQ-PROV-2)
+
+The table in Consequences was recalled, not checked, and said so. Every
+term below except CEVNI was read from the live primary source on
+2026-09-05; CEVNI remains unresolved (item 7). The fetch-by-fetch evidence is in the private state log of that date
+(`state/global/log/2026-09-05-colregs-jurisdiction-licences.md`). This
+amendment supersedes that table. It does not change the decision — name,
+jurisdiction-as-dimension, the work queue — only the licence column and
+what it implies for which instrument supplies the Rules *text*.
+
+| Jurisdiction | Instrument (text source) | Delta | Licence, verified | Attribution to ship (REQ-PROV-3) |
+|---|---|---|---|---|
+| `us/inland` | 33 CFR 83, eCFR | large | 17 U.S.C. §105, public domain | none; credit USCG by custom |
+| `eu/cevni` | CEVNI Rev.6 (UNECE) | largest | **unverified** — unece.org unreachable from the checking host; the UN default terms are personal, non-commercial only. Blocked until written permission is obtained or a national transposition is chosen instead | — |
+| `ca/inland` | Collision Regulations, C.R.C. c.1416, Schedule 1 | moderate | Reproduction of Federal Law Order SI/97-5 | none; accuracy diligence required, and must not be represented as an official version |
+| `de/binnen` | SeeSchStrO (delta) + KVR, Anlage to SeeStrOV (text) | large | §5(1) UrhG, no copyright | none |
+| `uk` | SI 1996/75 (delta) + MSN 1781 (text) | near-zero | OGL v3.0, Crown copyright | "Contains public sector information licensed under the Open Government Licence v3.0." |
+| `au` | Marine Order 30 (Prevention of collisions) 2016, F2016L01187 (delta only; text inherited from `intl`) | near-zero | CC BY 4.0 | "Based on content from the Federal Register of Legislation at [full date of download — filled in when the `au` corpus is retrieved]. For the latest information on Australian Government legislation please go to https://www.legislation.gov.au." |
+
+**What the recall got wrong.** Recorded so the errors are not re-recalled:
+
+1. **AU instrument id.** Marine Order 30 (Prevention of collisions) 2016 is
+   F2016L01187. C2016L01175, the id carried on the board, is a different
+   instrument (a VET provider revocation).
+2. **AU reproduces no Rules text.** The Order "gives effect to" the
+   Convention and defines the International Regulations as the Rules and
+   Annexes "as in force from time to time". CC BY 4.0 clears the Australian
+   delta only; there is no Australian government publication of the Rules
+   to lean on, so `au` inherits its text from `intl` — which the
+   jurisdiction-as-delta model already assumes.
+3. **UK: the SI carries no Rules text either.** Regulation 4(1) of SI
+   1996/75 incorporates Rules 1–36 and Annexes I–III by reference. The text
+   is MSN 1781 (M+F), Crown copyright 2004, published on gov.uk under OGL
+   v3.0. OGL is the right licence; MSN 1781 is the source to cite.
+4. **DE: §5(1) UrhG, not the §5(2) *amtliche Werke* limb.** Both SeeSchStrO
+   and the KVR Anlage are Verordnungen, which §5(1) excludes from copyright
+   outright. The Quellenangabe and Änderungsverbot conditions attach only to
+   §5(2) works and so do not apply. The German Rules text also lives in a
+   separate instrument from SeeSchStrO: the Anlage to §1 SeeStrOV.
+5. **CA carries two conditions** the recall did not: due diligence as to
+   accuracy, and the reproduction "not represented as an official version".
+   The README's not-the-law disclaimer should say so explicitly for `ca`.
+   The canada.ca general terms (non-commercial only) govern non-enactment
+   Crown material and do not displace SI/97-5 for Schedule 1 — but they do
+   mean Transport Canada explanatory prose cannot be lifted on the same
+   footing.
+6. **US: no page states "public domain".** Neither eCFR nor the USCG
+   amalgamated page carries a licence statement, and the Navigation Rules
+   Handbook PDF does not say it despite web summaries claiming so. The basis
+   is 17 U.S.C. §105(a): "Copyright protection under this title is not
+   available for any work of the United States Government".
+7. **CEVNI is unverified, not "unclear".** unece.org, the UN Digital
+   Library and UN iLibrary all refused the checking host, so nothing
+   UNECE-specific was read. What was read is the UN's default position:
+   "All rights reserved", with web-site use limited to "personal,
+   non-commercial use, without any right to resell or redistribute". Ways
+   through: a written permission from UN Publications Rights & Permissions,
+   or a national transposition under an open licence (Germany's BinSchStrO
+   under §5(1) UrhG, or the Netherlands' BPR) — the same corpus by a lawful
+   route, at the cost of being a national delta rather than "CEVNI".
+8. **IMO's own text is closed to this package.** The IMO website terms
+   permit copying and adaptation "for the User's personal, non-commercial
+   purposes" and state that "Reuse of the Materials for commercial purposes
+   is expressly prohibited", with derivatives bound to the same terms. That
+   is incompatible with Apache-2.0 (ADR 0004). The package does not take
+   its text from IMO website materials and must not; the US route it
+   already takes, and the UK, CA and DE routes above, all reach the same
+   Rules text lawfully. Whether IMO holds a copyright in the treaty text
+   itself is the separate, open question below.
+
+**Accepted risk: IMO copyright in the enacted treaty text.** The `intl`
+text is taken from a US Government publication, and §105 covers that
+publication. It does not, by itself, answer whether IMO holds a copyright
+in the underlying 1972 Convention text that survives national enactment.
+The GPO's own caveat — "Government publications may contain copyrighted
+material which was used with permission of the copyright owner" — and
+OGL's exclusion of "third party rights the Information Provider is not
+authorised to license" are exactly that question. No source checked
+answers it; there is no IMO statement either way. The evidence in
+mitigation is practice: four governments publish the full Rules under
+their own terms — the US as a §105 work, the UK as Crown copyright (MSN
+1781, 2004) under OGL, Canada as an enactment under SI/97-5, and Germany
+as an official translation that §5(1) UrhG makes copyright-free. Each of
+those is a state treating the enacted text as its own official work. This
+is recorded as an **accepted risk**, not as settled. Whether to carry it,
+seek an IMO statement, or narrow the package is the maintainer's call and
+is not made here.
+
+**Sources read, 2026-09-05.**
+
+- US: <https://www.ecfr.gov/current/title-33/chapter-I/subchapter-E/part-83>;
+  <https://www.navcen.uscg.gov/navigation-rules-amalgamated>;
+  <https://uscode.house.gov/view.xhtml?req=granuleid:USC-prelim-title17-section105&num=0&edition=prelim>;
+  <https://www.govinfo.gov/about/policies>.
+- UK: <https://www.legislation.gov.uk/uksi/1996/75/contents/made>;
+  <https://assets.publishing.service.gov.uk/government/uploads/system/uploads/attachment_data/file/281965/msn1781.pdf>;
+  <https://www.gov.uk/government/publications/msn-1781-mf-amendment-3-the-merchant-shipping-regulations-1996-colreg>;
+  <https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/>.
+- AU: <https://www.legislation.gov.au/F2016L01187/latest/text>;
+  <https://www.legislation.gov.au/terms-of-use>.
+- DE: <https://www.gesetze-im-internet.de/seeschstro_1971/BJNR006410971.html>;
+  <https://www.gesetze-im-internet.de/seestro_1972/BJNR008160977.html>;
+  <https://www.gesetze-im-internet.de/urhg/__5.html>.
+- CA: <https://laws-lois.justice.gc.ca/eng/regulations/C.R.C.,_c._1416/FullText.html>;
+  <https://laws-lois.justice.gc.ca/eng/regulations/SI-97-5/page-1.html>;
+  <https://www.canada.ca/en/transparency/terms.html>.
+- UN (CEVNI parent terms; UNECE itself unreachable):
+  <https://www.un.org/en/about-us/copyright>;
+  <https://www.un.org/en/about-us/terms-of-use>.
+- IMO: <https://www.imo.org/en/About/Conventions/Pages/COLREG.aspx>;
+  <https://www.imo.org/en/About/Pages/IMO-Website-Terms-and-conditions-of-use.aspx>.

package/docs/adr/0003-language-as-a-dimension.md

@@ -0,0 +1,220 @@
+# ADR 0003 — Language as a dimension, text corpora, and display catalogs
+
+Date: 2026-08-29
+Status: proposed
+
+## Context
+
+COLREGS is not an English-language document with translations. The 1972
+Convention was done in English and French, **both texts equally authentic**,
+with official Spanish and Russian translations deposited alongside the
+original; Arabic and Chinese texts exist because they are IMO official
+languages and the consolidated editions are published in all six. On top of
+that, many states gazette their own translation as legally binding national
+law (Finland via Finlex, Germany, Spain via the BOE, …). A package that
+treats English as the text and everything else as decoration has the legal
+reality backwards. (Each of these claims must still be verified against the
+primary source before the corresponding text lands — REQ-PROV-2 applies to
+languages exactly as it does to jurisdictions; see Q-6/Q-7.)
+
+The current `data/rules.json` already demonstrates the problem. Its text is
+the **USCG amalgamated rendition** of the international rules, with US
+spelling — "maneuver" where the authentic treaty English reads "manoeuvre".
+So the repo today holds a *national-tier, en-US* corpus of the *intl*
+jurisdiction's rules. "Which jurisdiction's rules" and "which text of them"
+are demonstrably independent questions, and the file-format conflates them:
+`text` is a bare string with one file-level source.
+
+Non-legal strings have the same problem one layer down: light names,
+placement prose, and fact-axis labels are inline English inside files the
+requirements call language-neutral.
+
+There is also a downstream motive: SignalK's contributor base is heavily
+non-US (Finland especially), and consumers of this package — the educational
+app in particular — will want localized UI in markets that are maritime
+nations first and English-speaking second. The data model should make a
+community-contributed language a single additive pull request.
+
+## Decision
+
+**Language is a first-class dimension orthogonal to jurisdiction**, tagged
+with BCP 47 codes, structured as three layers:
+
+1. **Structural skeleton (language-neutral).** Paragraph paths, rule
+   numbers, jurisdictions, entry ids, fact values, light ids, relations,
+   predicates, fixtures. None of this ever translates. Translations attach
+   to identifiers; they never replace them.
+
+2. **Rule-text corpora (legal text).** One corpus per
+   (jurisdiction × language × source), keyed by the same paragraph paths as
+   the skeleton, carrying `text` and `rule_title` plus corpus-level
+   provenance. "Corpus" is the term, not "translation": a corpus may be an
+   original text, an official translation, or an independently promulgated
+   national instrument — where one is in fact a translation of another,
+   that is recorded as explicit `translation_of` metadata. `rule_title` is
+   verbatim source material like `text`, not a UI string. Every corpus declares a **status tier**:
+
+   | tier | meaning | examples |
+   |---|---|---|
+   | `authentic` | identified by the governing instrument *itself* as an equally authentic text — the instrument's claim, never this repo's assessment | en and fr per the Convention |
+   | `official` | official translation published or deposited through the instrument's depositary organization | es, ru, ar, zh |
+   | `national` | a state's legally binding published text | USCG amalgamation, Finlex, BOE |
+   | `community` | informational translation, no legal standing | contributed |
+
+   Tier is a property of the *source*, not the language — today's English
+   text is `national` (USCG), and an `authentic` English corpus from the
+   UNTS original can be added later beside it. The tier deliberately ranks
+   *legal authority*; translation provenance (who translated, reviewed,
+   from what) is separate structured metadata on the corpus, not folded
+   into the tier. A corpus holds at most one text per paragraph path.
+   REQ-MODEL-1's verbatim rule applies per corpus: text is verbatim from
+   *its* source at the Unicode level (declared normalization form, no bidi
+   control insertion, no localized numerals or punctuation — REQ-LANG-9);
+   a `community` corpus must record who produced and reviewed it, and
+   machine output without named human review is not accepted.
+
+   **Amendment state, not a temporal model.** COLREGS has been amended
+   repeatedly (Rule 23(c)'s WIG craft arrived in 2001), and national texts
+   consolidate on their own schedules. The package models the *current
+   consolidated state*: the skeleton declares, as data, the amendment state
+   it consolidates, and every corpus declares the amendment state its
+   source reflects (REQ-LANG-10). A mismatch is legitimate but
+   machine-visible — declared staleness, never silence. Historical states
+   are prior package versions, not an in-data version dimension. A
+   renumbering amendment is a major version under REQ-PKG-4 — but it is
+   resolved by *issuing new paragraph paths and deprecating the old ones*
+   (REQ-MODEL-10/11), never by repointing an existing path at different
+   text. Repointing is forbidden outright: no version signal expresses it,
+   so a consumer cannot detect it.
+
+3. **Display catalogs (UI strings, not law).** Per-language message
+   catalogs keyed by stable string keys for the identifier vocabularies:
+   light names, fact-axis value labels, modality labels, image captions.
+   These are what a demo app renders in its UI; they deliberately do *not*
+   share a file with legal corpora, because a UI label needs review for
+   idiom, while legal text needs provenance and verbatimness. Catalog
+   entries are **static strings** — no interpolation, plurals or gender
+   grammar; message composition belongs to the consumer's i18n system
+   (ICU, gettext, whatever), and this package will not grow a homemade
+   one. Catalogs carry lightweight provenance (contributors, reviewers,
+   review date, licence): maritime terminology is load-bearing even in a
+   UI label, and a translation of a public-domain instrument still has a
+   translator holding rights. Maintainer `note` fields inside structural
+   files remain untranslated working documentation — not display strings,
+   not part of the localization surface.
+
+Corpora and catalogs are **additive**: adding a language changes no schema
+and does not edit existing corpora or catalogs (the mirror of REQ-SCOPE-4
+for jurisdictions); required coverage manifests and release documentation
+update as needed.
+Coverage is declared machine-readably — a manifest of which paragraph paths
+each corpus contains — and CI checks every corpus key resolves to a
+skeleton path. Partial corpora are legal and expected; silence never implies
+coverage (the language analogue of REQ-SCOPE-6).
+
+The package declares what exists and **never encodes a fallback policy,
+and never silently substitutes one corpus for another**. Text is only
+addressable inside a corpus, so anything a consumer retrieves is
+attributable; a consumer may assemble a mixed-corpus view (Finnish where it
+exists, English where it doesn't), but a mixed view is never a single
+authoritative edition, and the docs say so. Which language to show, and
+what to do when a paragraph is missing from the chosen corpus, is the
+consumer's call (the spirit of REQ-CONS-3).
+
+### Sketch (illustrative, not binding on filenames)
+
+```text
+data/rules.json                     # skeleton: paths, rule numbers, gaps
+data/text/intl.en-US.uscg.json      # today's text, relabeled for what it is
+data/text/intl.fr.unts.json         # authentic French, when licensed+landed
+data/text/intl.fi.finlex.json       # Finnish national text, contributable
+data/i18n/en.json                   # display catalog
+data/i18n/fi.json
+```
+
+Authoritative metadata lives *inside* each corpus file; the filename is a
+convenience, and CI checks the two agree. Source identity is structured
+(publisher, title, edition, publication/effective dates, URL, retrieved —
+REQ-PROV-6), with rights recorded separately for the source text, the basis
+for redistribution, and the package's own distribution licence. The BCP 47
+tag carries the language of the text and nothing else — `en-US` on the
+USCG corpus means US-spelled English, not "US law" and not "for US users";
+provenance and legal applicability live in the metadata, never in the tag.
+
+## Sequencing
+
+Nothing lands with this ADR. The order later:
+
+1. Split `data/rules.json` into skeleton + the existing text as an
+   `intl / en-US / uscg / national` corpus. Pure refactor, fixtures
+   untouched (they never contained text).
+2. Extract display catalogs for the existing identifier vocabularies (en).
+3. First non-English corpus — chosen by which licence check under Q-6/Q-7
+   clears first, not by market size. French (authentic, UNTS) and Finnish
+   (national, Finlex) are the likely front of the queue.
+4. Community-contribution path documented in README (one corpus file + one
+   catalog file per PR).
+
+## Consequences
+
+- REQ-PROV-2's licence gate applies per corpus. The IMO consolidated
+  six-language editions are sold publications and likely **not**
+  reproducible; national gazettes and the UNTS deposit are the probable
+  lawful sources. This — not translation effort — is the sequencing
+  constraint, recorded as Q-6/Q-7.
+- The README coverage statement (REQ-SCOPE-6) gains a language column:
+  jurisdictions × parts × languages, each with its tier.
+- `data/rules.json` as published today is unaffected until step 1 of the
+  sequencing lands; the split is a breaking change to the published file
+  layout and versions accordingly (REQ-PKG-4).
+- Arabic makes the corpora bidirectional-text-bearing. Plain JSON strings
+  carry RTL text fine; the data layer never inserts or strips bidi control
+  characters (REQ-LANG-9), and rendering direction is a consumer concern
+  that stays out of the data.
+
+## Considered and declined (external review, 2026-08-29)
+
+Two external reviews (PR #4 comments) shaped the revision above. What they
+changed: tag-carries-language-only, tier definitions as legal claims,
+amendment-state declaration, one-text-per-path, static catalogs with
+provenance, Unicode-level verbatimness, structured source identity with the
+three-rights split, no-silent-substitution phrasing, filename/metadata CI
+check. What was declined, and why — recorded so it isn't re-argued:
+
+- **A CI-enforced terminology glossary for translations.** (GATE-5) For legal
+  corpora it contradicts verbatimness: the source says what it says, and
+  if a national text uses inconsistent terms, so does our copy. A glossary
+  as *contributor guidance* for display catalogs may come with the
+  contribution docs; it is not schema and not CI.
+- **ICU MessageFormat / interpolation in catalogs.** This is a data
+  package, not an i18n runtime. Static labels only; a homegrown message
+  system incompatible with real i18n libraries is the failure mode, not
+  the feature.
+- **A package-encoded fallback chain** (e.g. `es-MX → es → en`; GATE-4).
+  Encoding a preferred substitute for legal text is exactly the
+  preference-taking REQ-CONS-3 forbids elsewhere. The stronger, narrower
+  rule replaced it: no silent substitution, full attributability, consumer
+  decides.
+- **Splitting `paragraph_id` from `citation_path`.** (GATE-1) The paragraph
+  path *is* the shared citation across the treaty languages and the
+  harmonised national texts (ADR 0001); a second synthetic id would double
+  every cross-reference for a renumbering event that is rare, already a
+  major version under REQ-PKG-4, and resolvable by deprecation rather than
+  repointing (REQ-MODEL-10). Accepted risk, revisit only when a real
+  renumbering lands — or when Q-8's check of the first national
+  amalgamation shows paragraph paths do not survive it.
+- **A full temporal/legal-version model** (instrument → edition → corpus as
+  first-class layers; GATE-2). The package models current consolidated law;
+  history lives in package versions. The cheap 80% — declared amendment
+  state on skeleton and corpus, machine-visible mismatch — is adopted
+  instead. If a jurisdiction ever requires multiple concurrent editions,
+  that is a new ADR.
+- **`dir: ltr|rtl` metadata per language.** Derivable from the language
+  tag via CLDR by any consumer that needs it; storing it invites drift.
+
+Four of these are declined *for now* rather than on principle, and the
+difference matters: each is recorded in requirements §10 as a timed gate,
+with the event that ends its cheap reversibility and the fact that would
+reopen it. GATE-1 (the `paragraph_id` split) is the one that must be
+re-taken deliberately before 1.0; GATE-3 covers the half-adopted
+legal-status × translation-status split.

package/docs/adr/0004-licence-layering.md

@@ -0,0 +1,78 @@
+# ADR 0004 — Licence layering across the family, and Apache-2.0 here
+
+Date: 2026-08-29
+Status: accepted
+
+## Context
+
+`colregs` shipped 0.1.1 under MIT. `2669e2a` changed the compilation to
+Apache-2.0 with the rationale in the commit body and nowhere else. The
+external review of PR #4 flagged this as the most irreversible change in
+flight and the only one with no record: relicensing is cheap while the
+copyright holder is one person, and stops being cheap at the first merged
+external contribution — which is precisely what the language work exists
+to invite.
+
+This ADR records the decision taken in the 2026-08-29 naming/branding
+session. It is a record of a ruling already made, not a re-argument.
+
+## Decision
+
+Licensing is **layered across the product family**, matched to where the
+novel work lives:
+
+| package | licence | status |
+|---|---|---|
+| `colregs` | Apache-2.0 | landed on `main`, `2669e2a` |
+| `colregs-engine` | Apache-2.0 | repo staked, pre-code |
+| `nav-wright` | AGPL-3.0 | repo staked, pre-code |
+| `searoom` (the app) | AGPL-3.0 | repo seeded |
+
+**Why permissive at the data layer.** The rule text is public law and
+carries no copyright claim here. The fixture file is deliberately a
+cross-implementation contract (REQ-VERIFY-1), so the evaluation logic is
+reimplementable by anyone whatever the engine is licensed as — restricting
+the data or the engine protects almost nothing. Adoption is the point: the
+data package sells the ecosystem. Protection of the novel work — renderer,
+app — lives one layer up under AGPL-3.0, where a sole copyright holder can
+still dual-license store builds.
+
+**Why Apache-2.0 rather than MIT.** Two reasons. The explicit patent grant,
+where MIT's is ambiguous. And ecosystem fit: signalk-server and the
+prominent community plugins are Apache-2.0, and the planned switching
+plugin loads in-process into that Apache-2.0 host, so every layer it
+consumes has to stay permissive regardless. Sampled 2026-08-30, 19 of the
+top 20 SignalK-ecosystem projects by stars are Apache-2.0 — table in
+<https://github.com/mark-brannan/colregs/pull/4#issuecomment-5467185331>.
+
+**npm timing is deliberate.** The change was committed as `chore:` so
+release-please cuts no discrete version for it. npm stays `colregs@0.1.1`
+under MIT until the next release — the i18n work — ships. Published
+artifacts keep the licence they shipped with permanently; the switch
+applies from the next release forward, never retroactively.
+
+## Consequences
+
+- Recorded as **GATE-6** (requirements §10). Closing event: the first
+  merged external contribution. After it, any relicense needs every
+  contributor's consent.
+- Already-published npm versions are irreversibly under their shipped
+  licence. The gate governs future releases only.
+- The gate is **held open deliberately**, by REQ-PROV-7: `CONTRIBUTING.md`
+  states that opening a pull request agrees to a DCO-style certification
+  *and* a licence grant to the maintainer sufficient to relicense. The
+  grant is the part that holds the gate open; a bare DCO certifies origin
+  and grants nothing, so it would not.
+- Honestly: implied assent is weaker than recorded assent. Nothing records
+  that a given contributor read the terms — only that they opened a PR
+  against a repo containing them. That is the cost of keeping the
+  contribution path frictionless while contributors are hypothetical. The
+  upgrade path, if they actually arrive, is a CLA-assistant bot that takes
+  and stores an explicit per-contributor signature.
+- The data-side question is *not* settled by this ADR. REQ-PROV-4 holds
+  code licence and data licence apart, and whether the data wants CC0 or
+  CC BY 4.0 separately is GATE-6's trigger, tracked as Q-9.
+- Maintainer position, on record: external contributors are unlikely short
+  of major success, so this gate is expected to stay open indefinitely. It
+  is recorded anyway — REQ-GATE-1 makes a decline without a named closing
+  event incomplete, and "unlikely" is not a closing event.