colregs 0.3.0 → 0.3.1

package/data/facts.json

@@ -549,7 +549,7 @@
     ],
     "cite": "12(b)",
     "cite_pending": null,
-    "note": "Which side this vessel has the wind on, which 12(b) defines as the side opposite that on which the mainsail is carried, or for a square-rigged vessel the side opposite the largest fore-and-aft sail. `wind_side:unknown` is not a missing value: it is 12(a)(iii)'s case, a vessel with the wind on the port side who cannot determine with certainty which side the other has it on, and entry 12a3 reads it. An absent fact would be silence, and silence satisfies nothing. Declared in `kin` rather than in the fact record because a display consumer never supplies it and the fact record does not change for Part B (REQ-CAT-4) -- but it is a sailing state and not kinematics, which is recorded as strain in Q-44 rather than fixed by widening the class.",
+    "note": "Which side this vessel has the wind on, which 12(b) defines as the side opposite that on which the mainsail is carried, or for a square-rigged vessel the side opposite the largest fore-and-aft sail. `wind_side:unknown` is not a missing value: it is 12(a)(iii)'s case, a vessel with the wind on the port side who cannot determine with certainty which side the other has it on, and entry rule:12a_iii reads it. An absent fact would be silence, and silence satisfies nothing. Declared in `kin` rather than in the fact record because a display consumer never supplies it and the fact record does not change for Part B (REQ-CAT-4) -- but it is a sailing state and not kinematics, which is recorded as strain in Q-44 rather than fixed by widening the class.",
     "actuable": false,
     "signalk": null
    }
@@ -562,7 +562,7 @@
      "unit": "deg",
      "cite": "13(b)",
      "cite_pending": null,
-     "note": "Bearing of the *other* subject, 0-360 clockwise from this subject's own heading. Under `own` this is relative bearing; under `other` it is aspect. Rule 13(b)'s overtaking sector is `other:geo:rel_bearing_deg` in (112.5, 247.5) -- own is more than 22.5 degrees abaft the other vessel's beam. The two sector edges are declared once in `constants` below (`overtaking_sector_from_deg`, `overtaking_sector_to_deg`) and entries 13b-overtaking, 13b-overtaken and 15a-crossing all read them, so the sector and its complement cannot drift apart.",
+     "note": "Bearing of the *other* subject, 0-360 clockwise from this subject's own heading. Under `own` this is relative bearing; under `other` it is aspect. Rule 13(b)'s overtaking sector is `other:geo:rel_bearing_deg` in (112.5, 247.5) -- own is more than 22.5 degrees abaft the other vessel's beam. The two sector edges are declared once in `constants` below (`overtaking_sector_from_deg`, `overtaking_sector_to_deg`) and entries rule:13b and rule:15a:crossing both read them, so the sector and its complement cannot drift apart.",
      "actuable": false,
      "signalk": null
     },
@@ -590,7 +590,7 @@
      "unit": "deg/min",
      "cite": "7(d)(i)",
      "cite_pending": null,
-     "note": "Rate of change of the compass bearing between the two vessels, signed. Rule 7(d)(i): a bearing that does not appreciably change means risk of collision exists. The Rules do not say what appreciably means; `constants.appreciable_bearing_change_deg_min` fixes it in pencil and entry 7d1 is the only reader.",
+     "note": "Rate of change of the compass bearing between the two vessels, signed. Rule 7(d)(i): a bearing that does not appreciably change means risk of collision exists. The Rules do not say what appreciably means; `constants.appreciable_bearing_change_deg_min` fixes it in pencil and entry rule:7d_i is the only reader.",
      "actuable": false,
      "signalk": null
     },
@@ -721,7 +721,7 @@
     "status": "pencil",
     "cite": null,
     "cite_pending": "7(d)(i)",
-    "note": "Rule 7(d)(i) deems risk of collision to exist if the compass bearing of an approaching vessel 'does not appreciably change', and nowhere says what appreciably means. Read as a magnitude: entry 7d1 gates on the open interval (-1.0, 1.0) so a bearing drawing out either way is treated alike, because the paragraph asks whether the bearing changes and not which way.",
+    "note": "Rule 7(d)(i) deems risk of collision to exist if the compass bearing of an approaching vessel 'does not appreciably change', and nowhere says what appreciably means. Read as a magnitude: entry rule:7d_i gates on the open interval (-1.0, 1.0) so a bearing drawing out either way is treated alike, because the paragraph asks whether the bearing changes and not which way.",
     "settled_by": "A source that fixes the figure -- Cockcroft & Lameijer, or an administration's guidance -- or a sensitivity sweep in colregs-engine showing which values change a region finding. Until then it is one session's number and any session may change it."
    },
    "head_on_half_angle_deg": {

package/data/geometry.json

@@ -92,8 +92,8 @@
    "cite": "AnxI.2(f)(ii)",
    "light": "light:all_round",
    "applies_to_entries": [
-    "27b-id",
-    "28"
+    "rule:27b_i",
+    "rule:28"
    ],
    "text": "When it is impracticable to carry the all-round lights prescribed by Rule 27(b)(i) or Rule 28 below the masthead lights, they may be carried above the after masthead light(s) or vertically in between the forward masthead light(s) and after masthead light(s), provided that in the latter case the requirement of paragraph 3(c) shall be complied with."
   },
@@ -162,8 +162,8 @@
   {
    "cite": "AnxI.2(j)",
    "applies_to_entries": [
-    "26b-id",
-    "26c-id"
+    "rule:26b_i",
+    "rule:26c_i"
    ],
    "datum": "sidelights",
    "min_multiple_of_pair_spacing": 2,
@@ -172,7 +172,7 @@
   {
    "cite": "AnxI.2(k)",
    "applies_to_entries": [
-    "30a"
+    "rule:30a"
    ],
    "datum": "after anchor light",
    "min_m": 4.5,
@@ -212,7 +212,7 @@
   {
    "cite": "AnxI.3(c)",
    "applies_to_entries": [
-    "27b-id"
+    "rule:27b_i"
    ],
    "min_offset_from_centerline_m": 2,
    "text": "When the lights prescribed in Rule 27(b)(i) are placed vertically between the forward masthead light(s) and the after masthead light(s), these all-round lights shall be placed at a horizontal distance of not less than 2 meters from the fore and aft centerline of the vessel in the athwartship direction."
@@ -227,7 +227,7 @@
   {
    "cite": "AnxI.4(a)",
    "applies_to_entries": [
-    "26c-gear"
+    "rule:26c_ii"
    ],
    "horizontal_from_identity_lights_m": {
     "min": 2,
@@ -239,7 +239,7 @@
   {
    "cite": "AnxI.4(b)",
    "applies_to_entries": [
-    "27d"
+    "rule:27d"
    ],
    "horizontal_from_ram_lights_m": {
     "min": 2

package/data/i18n/en.json

@@ -0,0 +1,27 @@
+{
+  "language": "en",
+  "provenance": {
+    "contributors": [
+      "mark-brannan"
+    ],
+    "reviewed_by": [
+      "mark-brannan"
+    ],
+    "review_date": "2026-09-13"
+  },
+  "strings": {
+    "light": {
+      "light:masthead": "Masthead light",
+      "light:sidelight_starboard": "Starboard sidelight",
+      "light:sidelight_port": "Port sidelight",
+      "light:sternlight": "Sternlight",
+      "light:towing": "Towing light",
+      "light:all_round": "All-round light"
+    },
+    "modality": {
+      "shall": "Required",
+      "may": "Permitted",
+      "shall-if-practicable": "Required if practicable"
+    }
+  }
+}

package/data/i18n/fi.json

@@ -0,0 +1,25 @@
+{
+  "language": "fi",
+  "provenance": {
+    "contributors": [
+      "claude-fable-5-1"
+    ],
+    "reviewed_by": [],
+    "review_date": "2026-09-15"
+  },
+  "strings": {
+    "light": {
+      "light:masthead": "Mastovalo",
+      "light:sidelight_starboard": "Oikea sivuvalo",
+      "light:sidelight_port": "Vasen sivuvalo",
+      "light:sternlight": "Perävalo",
+      "light:towing": "Hinausvalo",
+      "light:all_round": "Ympäri näköpiirin näkyvä valo"
+    },
+    "modality": {
+      "shall": "Pakollinen",
+      "may": "Sallittu",
+      "shall-if-practicable": "Pakollinen, jos mahdollista"
+    }
+  }
+}

package/data/images.json

@@ -21,7 +21,7 @@
     "23(d)(ii)"
    ],
    "entries": [
-    "23d2"
+    "rule:23d_ii"
    ],
    "depicts": "provision",
    "transcript": [
@@ -59,9 +59,9 @@
     "24(b)"
    ],
    "entries": [
-    "23a1",
-    "23a2",
-    "24b"
+    "rule:23a_i",
+    "rule:23a_ii",
+    "rule:24b"
    ],
    "depicts": "provision",
    "transcript": [
@@ -94,7 +94,7 @@
     "23(a)(ii)"
    ],
    "entries": [
-    "23a2"
+    "rule:23a_ii"
    ],
    "depicts": "exception",
    "transcript": [
@@ -127,7 +127,7 @@
     "23(b)"
    ],
    "entries": [
-    "23b"
+    "rule:23b"
    ],
    "depicts": "provision",
    "transcript": [
@@ -160,7 +160,7 @@
     "23(d)(i)"
    ],
    "entries": [
-    "23d1"
+    "rule:23d_i"
    ],
    "depicts": "provision",
    "transcript": [
@@ -215,8 +215,8 @@
     "24(a)(i)"
    ],
    "entries": [
-    "24a-m2",
-    "24a-rest"
+    "rule:24a_i",
+    "rule:24a_ii_iv"
    ],
    "depicts": "provision",
    "transcript": [
@@ -249,7 +249,7 @@
     "24(a)(v)"
    ],
    "entries": [
-    "24a-m3"
+    "rule:24a_i:exceeds_200m"
    ],
    "depicts": "provision",
    "transcript": [
@@ -314,7 +314,7 @@
     "24(e)"
    ],
    "entries": [
-    "24e"
+    "rule:24e"
    ],
    "depicts": "provision",
    "transcript": [
@@ -437,7 +437,7 @@
     "25(a)"
    ],
    "entries": [
-    "25a"
+    "rule:25a"
    ],
    "depicts": "provision",
    "transcript": [
@@ -466,7 +466,7 @@
     "25(b)"
    ],
    "entries": [
-    "25b"
+    "rule:25b"
    ],
    "depicts": "provision",
    "transcript": [
@@ -498,7 +498,7 @@
     "25(c)"
    ],
    "entries": [
-    "25c"
+    "rule:25c"
    ],
    "depicts": "provision",
    "transcript": [
@@ -531,7 +531,7 @@
     "25(d)(i)"
    ],
    "entries": [
-    "25d1"
+    "rule:25d_i"
    ],
    "depicts": "provision",
    "transcript": [
@@ -564,7 +564,7 @@
     "25(d)(ii)"
    ],
    "entries": [
-    "25d2"
+    "rule:25d_ii"
    ],
    "depicts": "provision",
    "transcript": [
@@ -629,7 +629,7 @@
     "26(b)(i)"
    ],
    "entries": [
-    "26b-id"
+    "rule:26b_i"
    ],
    "depicts": "provision",
    "transcript": [
@@ -665,7 +665,7 @@
     "26(b)(iii)"
    ],
    "entries": [
-    "26b-mw"
+    "rule:26b_iii"
    ],
    "depicts": "provision",
    "transcript": [
@@ -701,7 +701,7 @@
     "26(c)(iii)"
    ],
    "entries": [
-    "26c-mw"
+    "rule:26c_iii"
    ],
    "depicts": "provision",
    "transcript": [
@@ -740,7 +740,7 @@
     "27(a)(i)"
    ],
    "entries": [
-    "27a-id"
+    "rule:27a_i"
    ],
    "depicts": "provision",
    "transcript": [
@@ -776,7 +776,7 @@
     "27(a)(iii)"
    ],
    "entries": [
-    "27a-mw"
+    "rule:27a_iii"
    ],
    "depicts": "provision",
    "transcript": [
@@ -812,7 +812,7 @@
     "27(b)(iii)"
    ],
    "entries": [
-    "27b-mw"
+    "rule:27b_iii"
    ],
    "depicts": "provision",
    "transcript": [
@@ -849,7 +849,7 @@
     "27(b)(iv)"
    ],
    "entries": [
-    "27b-anc"
+    "rule:27b_iv"
    ],
    "depicts": "provision",
    "transcript": [
@@ -924,7 +924,7 @@
     "27(d)(ii)"
    ],
    "entries": [
-    "27d"
+    "rule:27d"
    ],
    "depicts": "provision",
    "transcript": [
@@ -967,7 +967,7 @@
     "27(d)(ii)"
    ],
    "entries": [
-    "27d"
+    "rule:27d"
    ],
    "depicts": "provision",
    "transcript": [
@@ -1069,7 +1069,7 @@
     "27(f)"
    ],
    "entries": [
-    "27f"
+    "rule:27f"
    ],
    "depicts": "provision",
    "transcript": [
@@ -1106,7 +1106,7 @@
     "28"
    ],
    "entries": [
-    "28"
+    "rule:28"
    ],
    "depicts": "provision",
    "transcript": [
@@ -1142,7 +1142,7 @@
     "29(a)(i)"
    ],
    "entries": [
-    "29a"
+    "rule:29a"
    ],
    "depicts": "provision",
    "transcript": [
@@ -1175,7 +1175,7 @@
     "29(a)(iii)"
    ],
    "entries": [
-    "29a"
+    "rule:29a"
    ],
    "depicts": "provision",
    "transcript": [
@@ -1210,7 +1210,7 @@
     "30(b)"
    ],
    "entries": [
-    "30b"
+    "rule:30b"
    ],
    "depicts": "provision",
    "transcript": [
@@ -1246,7 +1246,7 @@
     "30(c)"
    ],
    "entries": [
-    "30a"
+    "rule:30a"
    ],
    "depicts": "provision",
    "transcript": [
@@ -1281,7 +1281,7 @@
     "30(d)"
    ],
    "entries": [
-    "30d-red"
+    "rule:30d_i"
    ],
    "depicts": "provision",
    "transcript": [

package/data/operations.json

@@ -0,0 +1,79 @@
+{
+  "note": "The engine interface colregs owns: each verb ADR 0011 and ADR 0012 name, what it reads, what it answers, its entry-id companion and the fixture cases that bind it (ADR 0014).",
+  "operations": {
+    "evaluateDisplay": {
+      "adr": "0011",
+      "inputs": [
+        {
+          "name": "facts",
+          "schema": "schema/fact-record.schema.json"
+        }
+      ],
+      "output": "schema/display-evaluation.schema.json",
+      "companion": {
+        "verb": "appliedDisplayEntries",
+        "output": "schema/evaluation.schema.json#/$defs/ruleIds"
+      },
+      "fixtures": [
+        {
+          "file": "fixtures/applicability-fixtures.json",
+          "case_inputs": [
+            "facts"
+          ]
+        }
+      ]
+    },
+    "evaluateEncounter": {
+      "adr": "0011",
+      "inputs": [
+        {
+          "name": "situation",
+          "schema": "schema/situation.schema.json"
+        }
+      ],
+      "output": "schema/encounter-evaluation.schema.json",
+      "companion": {
+        "verb": "appliedEncounterEntries",
+        "output": "schema/evaluation.schema.json#/$defs/ruleIds"
+      },
+      "fixtures": [
+        {
+          "file": "fixtures/situation-fixtures.json",
+          "case_inputs": [
+            "situation"
+          ]
+        }
+      ]
+    },
+    "evaluateConduct": {
+      "adr": "0012",
+      "inputs": [
+        {
+          "name": "trace",
+          "schema": "schema/trace.schema.json"
+        }
+      ],
+      "output": "schema/conduct-evaluation.schema.json",
+      "companion": {
+        "verb": "appliedConductEntries",
+        "output": "schema/evaluation.schema.json#/$defs/ruleIds"
+      },
+      "fixtures": []
+    },
+    "evaluateRule2Departure": {
+      "adr": "0012",
+      "inputs": [
+        {
+          "name": "situation",
+          "schema": "schema/situation.schema.json"
+        },
+        {
+          "name": "model",
+          "schema": "schema/rule2-departure-model.schema.json"
+        }
+      ],
+      "output": "schema/rule2-departure-finding.schema.json",
+      "fixtures": []
+    }
+  }
+}

package/data/rules.json

@@ -1199,6 +1199,11 @@
     "NRHB_30_dii.png"
    ]
   },
+  "30(d)(i)": {
+   "path": "30(d)(i)",
+   "rule": "30",
+   "jurisdiction": "intl"
+  },
   "30(e)": {
    "path": "30(e)",
    "rule": "30",

package/data/version.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.3.0"
+  "version": "0.3.1"
 }

package/docs/adr/0006-json-schema-and-identifier-diff.md

@@ -1,5 +1,7 @@
 # ADR 0006 — JSON Schema for structural validation, identifier diff for version discipline
 
+The identifier-diff half is removed pre-1.0 by ADR 0015 (Solace, 2026-09-16); it returns, if at all, with the 1.0.0 tag.
+
 Date: 2026-09-04
 Status: accepted
 

package/docs/adr/0011-api-shape.md

@@ -167,7 +167,7 @@ resolution, and validation of the situation record.
 | `own` required, `other`/`Subject.fact` per colregs 0.2.0's fixture schema | ✎ | revised 2026-09-07 from "own/other both required"; Mark to confirm before ink |
 | `appliedEncounterEntries` as the fixture-replay companion | ✎ | the situation-fixture replay being written |
 | Field names snake_case with unit suffixes across both ADRs; `EntryId`/`ParagraphCite` alias `string` for ids and cites | ✎ | the rename's alias window closing; a consumer arguing the compiler should enforce the two apart |
-| `EncounterEvaluation` field set (§4) | ✎ | building it; Q-35, Q-36, Q-43 in colregs |
+| `EncounterEvaluation` field set (§4); `categories` and `provenance` added 2026-09-16 beyond the block above, as `DisplayEvaluation` carries them — colregs-engine 0.1.5 built them and ADR 0014's `encounter-evaluation.schema.json` is now the shape | ✎ | building it; Q-35, Q-36, Q-43 in colregs |
 | `encounter` absent vs the ADR 0005 §5 status alphabet | ✎ | Q-43 |
 | `conduct` is a separate package, not a third verb | ✎ | superseded by ADR 0012: a third and fourth verb, in this package |
 | Geometry-consistency validation (REQ-VERIFY-8) in the engine's validator | ? | deciding whether it is data-suite-only |

package/docs/adr/0014-engine-interface-owned-by-colregs.md

@@ -0,0 +1,103 @@
+# ADR 0014 — The engine interface is colregs' to own: an operations manifest and result schemas
+
+Date: 2026-09-16
+Status: proposed. Solace ordered options 2 and 3 built on 2026-09-16; the
+register marks what settles each row.
+
+## Context
+
+ADR 0011 and ADR 0012 fix the engine's verbs and result envelopes, in prose
+and TypeScript blocks, in this repository. The only machine-readable copy
+lives in colregs-engine's `src/types.ts`, so the interface is de facto
+colregs-owned and de jure the engine's: a second engine, in any language,
+would transcribe the ADRs by hand and drift the way the engine's own
+generator was written to stop.
+
+colregs already owns *shapes* in production: the engine compiles every
+`schema/*.schema.json` into generated types and derives `FactRecord` and
+`Situation` from `data/facts.json`. What it does not own is the *operations*
+— which verb reads which input and answers which envelope — and the fixture
+files bind to verbs only by convention.
+
+Ten routes were surveyed on 2026-09-16 for making the interface a colregs
+artefact, the Java sense of interface against implementation:
+
+| # | route | what it gives, what it costs |
+|---|---|---|
+| 1 | result schemas only, verbs stay prose | shapes checkable, operations still hand-read |
+| 2 | **operations manifest**: verb → inputs → result → companion, in JSON | language-neutral; any engine derives its own binding |
+| 3 | **fixtures bound to verbs** in the manifest | the conformance replay becomes the behavioural contract |
+| 4 | hand-written `.d.ts` in colregs | TypeScript-only; the transcription the engine's generator exists to avoid |
+| 5 | `x-operation` keywords inside the existing schemas | option 2 spread over eleven files |
+| 6 | OpenAPI / AsyncAPI | a projection generable *from* 2, not a source |
+| 7 | Protobuf / Smithy | model operations natively; a toolchain a data-only package does not have |
+| 8 | TypeSpec | one source projecting JSON Schema and OpenAPI; same toolchain cost |
+| 9 | a separate `colregs-api` package | a third release train for two files |
+| 10 | status quo | the drift above |
+
+## Decision
+
+1. **`data/operations.json` is the interface.** One operation per verb ADR
+   0011 and ADR 0012 name, each with positional `inputs` (name and schema),
+   an `output` schema, the entry-id `companion` verb where one exists, and
+   the `fixtures` that exercise it. `schema/operations.schema.json` checks
+   its shape; `test/data.test.mjs` checks that every reference resolves.
+2. **Result envelopes are schemas under `schema/`:** `display-evaluation`,
+   `encounter-evaluation`, `conduct-evaluation`, `rule2-departure-finding`,
+   transcribed from the engine's `src/types.ts` at colregs-engine 0.1.5.
+   JSON-Schema-expressible only: `Record<EntryId, Modality>` becomes
+   `patternProperties`, the `EntryId` and `ParagraphCite` aliases become
+   `$defs`, the two deprecated camelCase aliases are marked `deprecated` and
+   optional. From here the schema is the normative statement of each
+   envelope; the TypeScript blocks in ADR 0011 §4 and ADR 0012 §2–4 are
+   illustrations of record, and an envelope changes here first, the engine
+   second.
+3. **Inputs get schemas too:** `fact-record`, `situation`, `trace`,
+   `rule2-departure-model`. The two fixture schemas `$ref` the first two
+   for a case's `facts` and `situation` instead of carrying a copy; a fixture
+   case is the verb's input, and the tests validate every bound case against
+   it.
+4. **Schema files compose by `$ref`,** relative to their `$id`
+   (`applicability.schema.json#/$defs/ruleId`). ADR 0006's "no cross-file
+   references" is about data references — cite to `rules.json` — which stay in
+   the tests; a `$ref` between two schema files is one shape reused, not a
+   data reference. The suite registers every schema by `$id` before compiling.
+   What every envelope shares — the `colregs` stamp, `provenance`, the
+   `ruleId` and `paragraphCite` vocabularies — is `schema/evaluation.schema.json`,
+   `$defs` only, so moving one later is never a two-repository change.
+5. **A fixture file is bound to a verb** by `fixtures[].file` and
+   `case_inputs`, one case key per positional input, with the answer under
+   `expect`: the companion's entry ids unless the binding names another
+   schema. A case's `status` and `jurisdiction` are the fixture file's own.
+   Every file under `fixtures/` must be bound; `evaluateConduct` and
+   `evaluateRule2Departure` bind nothing yet, and say so with an empty list.
+6. **Not in the manifest:** trailing options a binding accepts (`opts.data`),
+   which verbs are built, and what a verb throws. Build status is ADR 0011's
+   and ADR 0012's tables; errors are the binding's.
+
+## Consequences
+
+- Ten new files under `schema/`. The engine's `generate-schema-types.ts`
+  throws on any schema its `ROOT_NAMES` does not list, so the next colregs
+  bump fails its build until colregs-engine#86 lands: emit
+  `interface ColregsEngine` from `operations.json`, `satisfies ColregsEngine`
+  at the engine's root, settle the `fact-record.ts` / `situation.ts`
+  collision with the types it derives from `facts.json` today, and validate
+  real output against these schemas for every fixture case.
+- A YAML rendering of the manifest is lossless; XML is a generated view (JSON
+  Schema to XSD). Authoring the interface in TypeScript first is the one route
+  that forecloses both.
+- The 2026-09-16 hand-off named the finding's schema `rule2-departure`; it
+  lands as `rule2-departure-finding` beside `rule2-departure-model`, since
+  the verb has two shapes to name.
+
+## Register
+
+| item | level | what would settle it |
+|---|---|---|
+| Options 2 and 3, not 1 or 4–10 | ✎ | this ADR accepted |
+| Manifest shape: positional `inputs`, `output`, `companion`, `fixtures[].case_inputs` and `expect` | ✎ | the engine generator consuming it; the first conduct or Rule 2 fixture |
+| Envelope schemas transcribed from `types.ts`, envelope changes land here first | ✎ | the first envelope change after the follow-up |
+| Cross-file `$ref` between schema files | ✎ | a consumer whose validator cannot register a schema set |
+| Deprecated aliases optional in the schema, required in the engine | ✎ | the engine dropping them |
+| `opts` and thrown errors stay out of the manifest | ✎ | a second binding needing either |