colregs 0.1.0

package/LICENSE

@@ -0,0 +1,34 @@
+MIT License
+
+Copyright (c) 2026 Mark Brannan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING OUT OF
+OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+The MIT licence above covers this compilation: the JSON structure, the
+predicates, the fixtures and the tests.
+
+The rule text in `data/rules.json` and the diagrams in `images/NRHB_*.png` are
+works of the United States Government and are not subject to copyright in the
+United States (17 U.S.C. 105). The `*arc.gif` files have unverified
+provenance — see PROVENANCE.md.
+
+This package is not authoritative and is not endorsed by the US Coast Guard.
+Navigate by the published rules.

package/PROVENANCE.md

@@ -0,0 +1,65 @@
+# Provenance
+
+Everything in this package is transcribed or copied from US Government
+publications. Nothing here is authoritative: consult the published rules.
+
+## Rule text — `data/rules.json`
+
+- **Source:** USCG Navigation Center, *Navigation Rules, International —
+  Inland* (amalgamated), <https://www.navcen.uscg.gov/navigation-rules-amalgamated>
+- **Retrieved:** 2026-08-29
+- **Scope:** the **International** text only. The amalgamated page marks
+  inland-only inserts and international-only variants inline; inland text was
+  removed and international variants kept. Nothing was paraphrased.
+- **Rights:** a work of the US Government, not subject to copyright in the
+  United States (17 U.S.C. 105).
+- **Known hole:** Rule 24(g)(i) is absent from the source page. Rather than
+  reconstruct it from memory, `rules.json` records it under `gaps` and the
+  paragraph is omitted. 24(g) covers inconspicuous, partly submerged tows and
+  is outside the applicability table in this release.
+
+## Diagrams — `images/NRHB_*.png`
+
+- **Source:** the same USCG page, at
+  `https://www.navcen.uscg.gov/sites/default/files/images/navrules/<name>`
+- **Retrieved:** 2026-08-29 — fetched from the live USCG server, not scanned
+  from the PDF handbook and not recovered from an archive.
+- **Rights:** US Government work, public domain (17 U.S.C. 105).
+- Per-file URL, byte count, SHA-256 and pixel dimensions are recorded in
+  `data/images.json`, along with the USCG's own caption text and the
+  paragraphs and applicability entries each image illustrates.
+
+Two of the 38 (`NRHB_25_b.png`, `NRHB_27_ei.png`) are served by the USCG but
+not linked from the page; they were fetched by name. Two more
+(`NRHB_23_e.png`, `NRHB_24_j.png`) illustrate Great Lakes and Western Rivers
+paragraphs and are unmapped in this international-only release — they are kept
+because the inland ruleset will want them.
+
+### The `NR_*` / `NRHB_*` prefix question, resolved
+
+`mark-brannan/signalk-auto-nav-lights` carried images under two prefixes with
+no provenance recorded. `NR_25_b.png` and `NR_27_ei.png` are the same two
+diagrams the USCG now serves as `NRHB_25_b.png` and `NRHB_27_ei.png` — an
+older filename for the same images, not a different source. This package uses
+the current USCG names throughout.
+
+## Arc diagrams — `images/*arc.gif` — **unresolved**
+
+`mastheadarc.gif`, `portarc.gif`, `stbdarc.gif`, `sternarc.gif` and
+`towingarc.gif` were carried over from `signalk-auto-nav-lights`. They are
+believed to be USCG illustrations, but the page that served them no longer
+exists and no archived original has been located, so their provenance and
+rights are **unverified**. `data/images.json` marks them
+`"provenance_status": "unresolved"`.
+
+They are decorative here: the arcs themselves are data, in `data/lights.json`
+under each light's `arc`. If provenance cannot be established, delete the GIFs;
+nothing in the package depends on them.
+
+## SignalK paths
+
+`data/facts.json` records which SignalK path, if any, publishes each fact.
+Verified 2026-08-29 against the installed `@signalk/signalk-schema`
+(`schemas/groups/navigation.json`, `schemas/groups/design.json`). The
+`navigation.state` enum values in the decode table are copied verbatim from
+that schema, spelling included.

package/README.md

@@ -0,0 +1,50 @@
+# colregs
+
+The international collision regulations, and the national amalgamations derived
+from them, as language-neutral JSON — with the provenance to check every line
+against its source and fixtures a second implementation can verify against.
+
+Data only. No runtime, no dependencies, no inference.
+
+> **Status: pre-release.** Nothing here is complete, and nothing here is fit for
+> navigation. See [`docs/requirements.md`](docs/requirements.md) for what it is
+> meant to become.
+
+## Coverage
+
+| | |
+|---|---|
+| **Rules** | Part C, lights (Rules 20–31). Day shapes and Part D signals are not here. |
+| **Jurisdictions** | `intl` only. US Inland, Canada and the rest are modelled for but not present. |
+| **Conditions** | Night. |
+
+Coverage is stated because silence must not imply it (REQ-SCOPE-6).
+
+## Design
+
+This repo is requirements-first. Coding sessions work against numbered
+requirements and cite them; decisions that shaped the design are recorded as
+ADRs rather than argued again.
+
+- [`docs/requirements.md`](docs/requirements.md) — the source of truth
+- [`docs/adr/`](docs/adr/) — decisions, with the reasoning that produced them
+
+Three ideas carry most of the design:
+
+**The paragraph is the unit.** Rule text, citations and composition all key on
+the paragraph path — `27(a)(i)`, not "Rule 27". Citation unit and composition
+unit turn out to be the same thing.
+
+**Predicates, not enumerations.** Gates are `length_m < 7`, never a pre-built
+list of configurations. Enumerated tables are where prior art silently loses
+rules; a predicate cannot omit a case it was never asked about.
+
+**Alternatives are first-class.** COLREGS routinely permits a choice — a
+tricolor *in lieu of* separate sidelights, a torch *in lieu of* either. The data
+carries every lawful option with its modality and gate, and picks none of them.
+Selection belongs to the consumer.
+
+## Licence
+
+Code and fixtures: see `LICENSE`. Rule text and diagrams carry their own terms,
+recorded per asset — see `PROVENANCE.md` once data lands.