colregs 0.1.0 → 0.1.1

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

@@ -0,0 +1,76 @@
+# ADR 0001 — Package name, and jurisdiction as a dimension
+
+Date: 2026-08-29
+Status: accepted
+
+## Context
+
+The data package needed a name, and the naming had to fit an existing family:
+`ampacity` and `coastlines` (plain or term-of-art nouns for ready-made data),
+`portolani` (an archaic term of art naming a format), `wire-wright` and
+`coast-wright` (code that derives or draws).
+
+Three candidates were considered.
+
+**`fanali`** — Italian for ships' lanterns. Matched the `portolani` register
+exactly. Rejected: a *fanale* is a lantern, and day shapes are black balls,
+cones and diamonds. Part C's own title is "Lights and Shapes" precisely because
+no single word covers the pair, so the name would have been wrong as soon as
+day shapes landed.
+
+**`navrules`** — the USCG's term. Rejected on reflection: "Navigation Rules" is
+the name of *one country's amalgamation*. It denotes COLREGS plus the US Inland
+Navigational Rules plus 33 CFR 26 and the VTS regs. Naming a multi-jurisdiction
+package after one jurisdiction's compilation is backwards.
+
+**`colregs`** — accepted. It was unclaimed on npm, which for a canonical domain
+term is unusual enough to be worth taking on sight.
+
+## Decision
+
+The package is **`colregs`**, and jurisdiction is a first-class dimension
+(REQ-SCOPE-2) rather than a fork or a later bolt-on.
+
+The name and the data model agree, which is the actual argument:
+
+The national amalgamations are *deltas on COLREGS*, not peer bodies of rules.
+The US Inland Navigational Rules were harmonised with COLREGS in 1980 and share
+its rule numbering — Rule 25 is Rule 25 in both. That is why keying on paragraph
+paths works across jurisdictions at all. COLREGS is the stem every national
+version grows from, so it is the correct name for the trunk, and each
+jurisdiction is a set of overrides hanging off it.
+
+`navrules` would have been actively wrong under this model. `fanali` would have
+been too narrow. Neither failure was about taste.
+
+## Consequences
+
+- The README must state covered jurisdictions explicitly (REQ-SCOPE-6). A name
+  this broad promises more than v1 ships, and the honest fix is disclosure, not
+  a narrower name that would have to change later.
+- `navrules`, `inland-rules`, `33-cfr-83` and `cevni` go in package keywords
+  (REQ-PKG-5) so jurisdiction-specific searches land.
+- Jurisdictions become a work queue rather than a scope question. Ranked by
+  delta-worth-modelling against licence cleanliness, and all licence terms
+  below are **unverified** (Q-3):
+
+  | Jurisdiction | Instrument | Delta | Licence, unverified |
+  |---|---|---|---|
+  | `us/inland` | 33 CFR 83–90 | large | public domain |
+  | `eu/cevni` | CEVNI (UNECE) / RPNR | largest of any | UN copyright — the risk |
+  | `ca/inland` | Collision Regs, C.R.C. c.1416 | moderate | Reproduction of Federal Law Order |
+  | `de/binnen` | SeeSchStrO / BinSchStrO | large | §5 UrhG, *amtliche Werke* |
+  | `uk` | SI 1996/75 | near-zero | OGL v3.0 |
+  | `au` | Marine Order 30 | near-zero | CC BY 4.0 |
+
+  UK and Australia are worth taking *because* their delta is near-zero: they
+  cost almost nothing and let the README name six jurisdictions honestly.
+  CEVNI is the interesting one — genuinely different inland light
+  configurations, no prior art as structured data, and the only licence on the
+  list that might block outright.
+
+## 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.

package/docs/adr/0002-wig-gate-and-jurisdiction-field.md

@@ -0,0 +1,77 @@
+# ADR 0002 — WIG operating-condition gate, and dropping the file-level `jurisdiction` field
+
+Date: 2026-08-29
+Status: accepted
+
+## Context
+
+Two findings came out of PR #2 review (CodeRabbit and a human/agent pass),
+both about predicates not saying what they mean.
+
+### WIG gate
+
+The `23c` entry gated on `wig: true` alone. Rule 23(c) only applies "when
+taking off, landing and in flight near the surface" — a WIG craft cruising
+above the surface is still `wig: true` but not subject to 23(c). The
+condition lived in the entry's prose `notes`, not in `when`, so the predicate
+accepted a case the rule doesn't cover. This is the same failure mode as the
+30(d) fixture bug: the 30(d) entry hung the unconditional 30(a)/(b)
+anchor-light obligation off a `length_m >= 12` gate that only 30(f)'s
+red-light exemption actually carries. In both cases a real-world condition
+was demoted to a `notes` comment instead of encoded in the predicate,
+contradicting the README's own design principle: "a predicate cannot omit a
+case it was never asked about."
+
+### `jurisdiction` field duplication
+
+`data/applicability.json` and `data/rules.json` each carry a *file-level*
+`jurisdiction` field and, separately, every one of their ~140 records repeats
+`"jurisdiction": "intl"` on itself. Nothing tested that the two agreed.
+`data/lights.json` and `data/geometry.json` only have the file-level field —
+no per-record duplication there, because those files aren't record-per-rule
+in the same way.
+
+REQ-MODEL-1 already requires the per-record field: "Where a jurisdiction's
+text differs, both MUST be stored, keyed by jurisdiction" — i.e. two
+paragraph records can share a path and differ only in jurisdiction, which
+only works if the field lives on the record. REQ-MODEL-4 lists `jurisdiction`
+as part of the applicability entry's own tuple, same reason. Nothing in
+`docs/requirements.md` specifies a role for the file-level field; it was
+added as a summary/header, and today it's true only because every record
+still says `intl`.
+
+## Decision
+
+**WIG:** split the single `wig` boolean into two facts in `data/facts.json`:
+`wig` (the vessel is a WIG craft — a permanent characteristic) and
+`wig_near_surface` (the vessel is taking off, landing, or in flight near the
+surface — an operating phase). `23c`'s `when` now requires both. Same
+pattern the data already used for `non_displacement` on 23(b) — a phase
+condition gets its own boolean, not a note.
+
+**`jurisdiction` duplication:** the per-record field is the one REQ-MODEL-1/4
+actually specify and the one that has to hold once `us/inland` entries start
+landing in the same files as `intl` ones (a delta "hangs off" the base per
+ADR 0001, which means mixed jurisdictions in one file is the expected shape,
+not a one-file-per-jurisdiction split). The file-level field can't stay true
+once that happens, so it was dropped from `data/rules.json` and
+`data/applicability.json` rather than kept as a second thing to keep in sync.
+`data/lights.json` and `data/geometry.json` keep their file-level field —
+they have no per-record duplication to drift against, and splitting them
+per-jurisdiction is a decision for whenever a jurisdiction actually changes
+light geometry, not now.
+
+## Consequences
+
+- `fixtures/applicability-fixtures.json` gained a negative WIG fixture
+  (cruising, not near the surface — no 23c) alongside the existing positive
+  one.
+- `data/applicability.json` and `data/rules.json` no longer have a top-level
+  `jurisdiction` key. A reader wanting "what jurisdictions does this file
+  cover" reads the per-record values (currently: `intl`, uniformly) or the
+  README's Coverage table, not a header field that would go stale the moment
+  a delta lands.
+- Same disease, not yet swept: `docs/adr/0002` doesn't do a full audit of
+  every other entry for a note-instead-of-predicate condition. That's a
+  reasonable follow-up if there's evidence of more, not something to
+  speculatively fix here.

package/docs/requirements.md

@@ -0,0 +1,221 @@
+# colregs — design requirements
+
+Status: **draft**, seeded 2026-08-29. This is the source of truth for what the
+package must do. Coding sessions work against these IDs; tests cite them.
+
+Requirement IDs are stable and never reused. If a requirement is dropped it is
+struck through and kept, not deleted — a spec whose IDs shift silently cannot
+be cited by a test.
+
+Language: **MUST** / **SHOULD** / **MAY** in the RFC 2119 sense.
+
+---
+
+## 1. Purpose
+
+Publish the international collision regulations, and the national amalgamations
+derived from them, as language-neutral data that more than one implementation
+can consume and verify against.
+
+Two named consumers shape the design:
+
+- **an educational app** — wants every rule, including those with no switchable
+  output, plus imagery and prose;
+- **a switching plugin** — wants only the subset a boat can actually act on,
+  evaluated against live vessel state.
+
+Neither consumer lives in this repo.
+
+### Non-goals
+
+- **No inference.** The package does not decide what a vessel *is doing*.
+  Deriving `making_way`, propulsion or activity from sensor data belongs to a
+  separate consumer. This package is a pure function of a fact record.
+- **No runtime.** Data and fixtures only; no evaluator ships here.
+- **No advice.** The package states what the rules require. It does not tell a
+  mariner what to do, and carries no claim of fitness for navigation.
+
+---
+
+## 2. Definitions
+
+| Term | Meaning |
+|---|---|
+| **paragraph path** | The citation unit: `27(a)(i)`, `25(d)(ii)`. Not the rule number. |
+| **fact record** | A set of facts about one vessel at one moment; the input. |
+| **entry** | One applicability record: predicate → lights/refs → modality → citation. |
+| **modality** | `shall` / `may` / `shall-if-practicable`. |
+| **jurisdiction** | A body of rules: `intl`, `us/inland`, `ca/inland`, … |
+| **delta** | A jurisdiction's departures from the international text. |
+
+---
+
+## 3. Scope and jurisdictions
+
+- **REQ-SCOPE-1** — The package MUST model the international regulations
+  (COLREGS 72) as its base body of rules.
+- **REQ-SCOPE-2** — Jurisdiction MUST be a first-class dimension on every
+  applicability entry and every rule-text record, expressed as
+  `<country-or-body>/<waters>` with `intl` as the reserved base value.
+  Examples: `intl`, `us/inland`, `us/great-lakes`, `us/western-rivers`,
+  `ca/inland`, `de/binnen`, `eu/cevni`.
+- **REQ-SCOPE-3** — A jurisdiction MUST be expressible as a *delta*: entries
+  absent from a jurisdiction's data inherit from `intl`. A jurisdiction MUST
+  NOT require restating the whole body of rules.
+- **REQ-SCOPE-4** — Adding a jurisdiction MUST be additive. It MUST NOT require
+  a schema change or edits to existing `intl` entries.
+- **REQ-SCOPE-5** — Geography that gates a rule (Great Lakes, Western Rivers,
+  a designated special anchorage area) MUST be an ordinary fact read by a
+  predicate, NOT a jurisdiction value of its own where the rule is a
+  conditional inside a wider jurisdiction.
+- **REQ-SCOPE-6** — Every release MUST state, in the README, exactly which
+  jurisdictions and which rule parts it contains. Silence MUST NOT imply
+  coverage.
+
+### 3.1 Rule parts
+
+Part C (Rules 20–31, lights and shapes) is v1. The structure MUST accommodate
+the rest without redesign.
+
+- **REQ-PART-1** — Part C lights MUST be complete for `intl` before any other
+  part or jurisdiction is added.
+- **REQ-PART-2** — Day shapes MUST use the same entry model as lights, differing
+  only in the fixture vocabulary they emit.
+- **REQ-PART-3** — Sound and light signals (Part D, Rules 32–37) SHOULD be
+  representable by the same entry model. Where they are not — signals are
+  event-triggered rather than state-derived — the divergence MUST be recorded
+  as an ADR before any Part D data is written.
+- **REQ-PART-4** — Steering and sailing rules (Part B) are OUT of v1 scope and
+  MAY never be modelled; they govern conduct between two vessels, not the
+  appearance of one, and the fact record is single-vessel by construction.
+
+---
+
+## 4. Data model
+
+Four layers, each independently addressable.
+
+- **REQ-MODEL-1** — **Rule text**, verbatim, keyed by paragraph path. Text MUST
+  NOT be paraphrased, summarised or reflowed. Where a jurisdiction's text
+  differs, both MUST be stored, keyed by jurisdiction.
+- **REQ-MODEL-2** — **Light definitions** (Rule 21) MUST carry colour, arc of
+  visibility in degrees, and range by length band (Rule 22). Jurisdictions MAY
+  add definitions (e.g. the US special flashing light, Inland 21(g)).
+- **REQ-MODEL-3** — **Facts**: the input vocabulary. Three orthogonal axes MUST
+  be used, never a single flattened status enum:
+  - `propulsion` ∈ power / sail / oars
+  - `activity` ∈ none / fishing / trawling / towing / pushing / being-towed /
+    nuc / ram / cbd / mine / pilot / diving
+  - `position` ∈ underway / anchored / aground / moored
+  plus `making_way` as a boolean refining `position=underway`, and numeric and
+  boolean facts (`length_m`, `tow_length_m`, `max_speed_kn`, `composite_unit`,
+  and the education-only facts).
+- **REQ-MODEL-4** — **Applicability entries**: `when` (predicate over facts) →
+  lights or refs → modality → citation → jurisdiction. Every entry MUST have a
+  stable id derived from its paragraph path (`25b`, `25d1`).
+- **REQ-MODEL-5** — Gates MUST be expressed as predicates over facts
+  (`length_m < 7`), never as pre-enumerated tuples or configuration counts. Any
+  count of "configurations" is an output of evaluation, never an input to the
+  data.
+- **REQ-MODEL-6** — Entries MUST compose. Multiple entries applying to one fact
+  record is the normal case, not an error (Rule 28 is "in addition to" Rule 23).
+- **REQ-MODEL-7** — Three relations MUST be supported:
+  - `includes` — import another entry's **lights only**, never its predicate;
+  - `in_lieu_of` — legal alternatives for the same fact record;
+  - `excludes` — mutual exclusion, including across rules.
+- **REQ-MODEL-8** — Alternatives MUST be first-class. Where the rules permit a
+  choice, the data MUST express all lawful options with their differing
+  modalities and gates, and MUST NOT pick one.
+- **REQ-MODEL-9** — A decode table from SignalK `navigation.state` to the three
+  axes MUST ship with the package. Its lossy cases MUST be enumerated in data,
+  not prose — at minimum, the flat enum cannot express fishing-at-anchor.
+
+---
+
+## 5. Provenance and licensing
+
+- **REQ-PROV-1** — Every text and image asset MUST record its source, the date
+  retrieved, and its licence or public-domain basis.
+- **REQ-PROV-2** — A jurisdiction MUST NOT be added until its reproduction terms
+  have been checked against the primary source and recorded. Recalled or assumed
+  terms are not sufficient.
+- **REQ-PROV-3** — Where a licence requires attribution (e.g. OGL, CC BY), the
+  attribution text MUST ship in the package, not only in the repo.
+- **REQ-PROV-4** — Code licence and data licence MUST be stated separately. The
+  code licence does not cover third-party scans.
+- **REQ-PROV-5** — Images MUST be addressable as data: an image record per file,
+  naming what it illustrates by entry id or paragraph path. Unexplained filename
+  prefixes are a provenance defect.
+
+---
+
+## 6. Verification
+
+- **REQ-VERIFY-1** — Fixtures MUST pair fact records with the entries that apply,
+  and MUST be consumable by an implementation in any language.
+- **REQ-VERIFY-2** — A **drift test** MUST cross-check the forward direction
+  (fact record → lights) against a reverse direction (observed lights →
+  candidate fact records), so the two cannot silently disagree.
+- **REQ-VERIFY-3** — Every applicability entry MUST be covered by at least one
+  fixture that exercises it, and at least one that excludes it.
+- **REQ-VERIFY-4** — Every `in_lieu_of` and `excludes` relation MUST have a
+  fixture demonstrating it.
+- **REQ-VERIFY-5** — Predicates MUST be tested at their boundaries. Every numeric
+  gate MUST have fixtures immediately either side of the threshold.
+- **REQ-VERIFY-6** — CI MUST fail on a fixture that references an entry id, a
+  light definition or a paragraph path that does not exist.
+
+---
+
+## 7. Packaging
+
+- **REQ-PKG-1** — Zero runtime dependencies.
+- **REQ-PKG-2** — Data MUST be consumable without a JavaScript runtime: plain
+  JSON, no code-carrying formats.
+- **REQ-PKG-3** — The published package MUST contain data, images, fixtures and
+  provenance, and MUST NOT contain build tooling or source scans.
+- **REQ-PKG-4** — Breaking changes to entry ids, fact vocabulary or relation
+  semantics MUST be a major version.
+- **REQ-PKG-5** — Package keywords MUST include the terms a searcher would
+  actually use for each covered jurisdiction (`colregs`, `navrules`,
+  `inland-rules`, `33-cfr-83`, `cevni`).
+
+---
+
+## 8. Consumer contracts
+
+- **REQ-CONS-1** — The switching subset MUST be derivable from the data by
+  filtering, not by a separate hand-maintained list. A consumer MUST be able to
+  select actuable entries mechanically.
+- **REQ-CONS-2** — Education-only facts MUST be marked as such in the fact
+  vocabulary, so a switching consumer can assert it never reads them.
+- **REQ-CONS-3** — Final selection among lawful alternatives belongs to the
+  consumer (for switching, the vessel's fixture map). The package MUST NOT
+  encode a preference.
+- **REQ-CONS-4** — The package MUST NOT assume a SignalK consumer beyond the
+  optional decode table of REQ-MODEL-9.
+
+---
+
+## 9. Open questions
+
+Tracked here until resolved; each becomes an ADR.
+
+- **Q-1** — Do Part D sound signals fit the entry model, or do they need an
+  event dimension? Blocks REQ-PART-3.
+- **Q-2** — Are the USCG scans the educational payload, or a stopgap until
+  light geometry is rendered from data? Affects how hard REQ-PROV-5 is pushed.
+- **Q-3** — Jurisdiction licence terms are **unverified**: US public domain,
+  UK OGL v3.0, AU CC BY 4.0, DE §5 UrhG *amtliche Werke*, CA Reproduction of
+  Federal Law Order, EU/UNECE CEVNI unclear. REQ-PROV-2 blocks each until
+  checked against the primary source. CEVNI is the one most likely to fail.
+- **Q-4** — Two upstream SignalK spec asks are outstanding and independent of
+  this package: a making-way indicator, and `design.maxSpeed`.
+- **Q-5** — REQ-VERIFY-5 asks for boundary fixtures on every numeric gate.
+  Three gates (`23a2`, `26b-mast`, `30c`'s `length_m` thresholds) live only in
+  `modality_by`, not in the entry's `when` — they flip `shall` to `may`, not
+  which entries apply. The fixture format only asserts applying entry ids, not
+  expected modality, so there is no way to fixture these three without
+  extending the schema to carry expected modality per entry. Not done
+  speculatively; blocks a clean REQ-VERIFY-5 pass on these three gates until
+  decided.