colregs 0.2.0 → 0.2.2

package/docs/requirements.md

@@ -76,7 +76,9 @@ Neither consumer lives in this repo.
   (Rule 28 "[Reserved]") means silence-means-inherit would apply
   international law where the national body deliberately has none, so no
   non-`intl` jurisdiction lands before an explicit suppression mechanism
-  exists.
+  exists. A delta that only *adds* entries is exempt: it suppresses nothing,
+  so the Q-11 hazard cannot arise from it (ADR 0008, `30a-buoy`/`30b-buoy`).
+  A delta that suppresses or replaces an `intl` entry still waits.
 - **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,
@@ -93,7 +95,10 @@ 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.
+  part or jurisdiction is added, except a purely additive jurisdiction delta
+  recorded in an ADR — one that adds entries and edits or suppresses none
+  (ADR 0008). Such a delta is not a claim to model that jurisdiction, and
+  REQ-SCOPE-6's coverage statement MUST say what it does and does not cover.
 - **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
@@ -133,8 +138,11 @@ Four layers, each independently addressable.
     `activity:pilot` / `activity:diving`
   - `fact:position` ∈ `position:underway` / `position:anchored` /
     `position:aground` / `position:moored`
-  plus `fact:making_way` as a boolean refining `fact:position=position:underway`,
-  and numeric and boolean facts (`fact:length_m`, `fact:tow_length_m`,
+  plus `fact:making_way` as a boolean refining `fact:position=position:underway`
+  and `fact:on_mooring_buoy` as a boolean refining
+  `fact:position=position:moored` — made fast to a buoy, not to the shore;
+  the Convention prescribes lights for neither, and only a jurisdiction that
+  deems her at anchor reads it (ADR 0008) — and numeric and boolean facts (`fact:length_m`, `fact:tow_length_m`,
   `fact:max_speed_kn`, `fact:composite_unit`, and the education-only facts).
   Fact keys, and the values of the enumerated facts, carry a type prefix;
   `docs/identifiers.md` states the scheme and why citation-derived
@@ -151,7 +159,10 @@ Four layers, each independently addressable.
 - **REQ-MODEL-7** — Five relations MUST be supported:
   - `rel:includes` — import another entry's **lights only**, never its predicate;
   - `rel:in_lieu_of` — legal alternatives for the same fact record;
-  - `rel:excludes` — mutual exclusion, including across rules;
+  - `rel:excludes` — mutual exclusion, including across rules; symmetric
+    (A excludes B implies B excludes A), and no participating entry MAY be
+    forceful (`shall`/`shall-if-practicable`) — a directed "this one
+    prevails" is `rel:overrides` (ADR 0007), not `rel:excludes`;
   - `rel:exempts` — one entry lifting another's obligation;
   - `rel:conditional_includes` — import or alternatives, gated on a predicate.
   The five are not interchangeable; README.md holds the working semantics.
@@ -364,7 +375,52 @@ towards, not because the shape is settled.
   whose threshold does not match the declared constant. `✎` pencil, with the
   rest of §4.1.
 
----
+### 4.2 Part B invariants
+
+`docs/part-b-invariants.md` states what COLREGS requires of a *trace* of
+situations, where an entry says which norms one state selects; it is a separate
+document because its propositions are about COLREGS, not requirements on this
+package, and would be misread under a `REQ-` id and an RFC 2119 MUST. Everything
+here is **pencil** (`docs/conventions.md`) with §4.1.
+
+- **REQ-INV-1** — Part B's steering and sailing rules MUST be recorded as prose
+  invariants in `docs/part-b-invariants.md`, each with a stable identifier,
+  each citing the paragraph path it comes from, and each precise enough that a
+  formalisation can be written from it without returning to the rule text.
+- **REQ-INV-2** — An invariant identifier MUST be `INV-` followed by the
+  entry-id derivation of its paragraph path (`docs/identifiers.md`, "Entry
+  ids"), with a descriptive hyphenated suffix where one paragraph yields more
+  than one invariant. A suffix MUST name what distinguishes the invariant, and
+  MUST NOT be an ordinal. Identifiers MUST be stable and MUST NOT be reused; a
+  withdrawn invariant is struck through and kept, as a requirement is. Once a
+  formal specification cites an invariant identifier, its **Invariant.**
+  statement MUST NOT change in place; a changed statement is a new identifier
+  and the old one is struck through and kept.
+- **REQ-INV-3** — Every paragraph path in `data/rules.json` within the range
+  the document covers MUST appear exactly once in its coverage table, mapped
+  either to an invariant identifier or to an explicit exclusion with a reason.
+  CI MUST fail on a paragraph in range that appears in neither, on one that
+  appears twice, and on an invariant whose citation does not resolve in
+  `data/rules.json`. Enforced by `test/data.test.mjs`.
+- **REQ-INV-4** — An invariant that is temporal MUST state what state must be
+  remembered and over what window. "Temporal" means it relates two or more
+  states of a trace; a property of a single state MUST say so.
+- **REQ-INV-5** — Where the rule text admits two readings, the document MUST
+  record both and MUST NOT choose. The choice is an open question in §11 and is
+  the maintainer's; a session MAY argue for a reading, and MUST NOT resolve one
+  by writing only its preferred half down. A proposition that is neither the
+  rule text, arithmetic over the rule text, nor a decision recorded as such
+  MUST NOT appear as an invariant.
+- **REQ-INV-6** — An invariant that covers its paragraph while leaving a term
+  the Rules do not define MUST name that term in the document's list of
+  undetermined terms, so that "covered" is never read as "checkable". A numeric
+  stand-in for such a term MUST be a declared constant under
+  `situation.constants` (`REQ-CAT-9`), never a literal inside an invariant.
+- **REQ-INV-7** — An invariant's **Invariant.** paragraph MUST be at most 120
+  words. This is a readability bound on the normative statement itself, not a
+  document-length budget (`docs/budgets.json` governs those); it keeps a single
+  invariant from growing into a paragraph a formalisation can't be checked
+  against sentence-by-sentence. Enforced by `test/data.test.mjs`.
 
 ## 5. Languages and localization
 
@@ -1318,3 +1374,76 @@ written up in `docs/identifiers.md` §"Effects"; what it could not is here.
   is closed — the definition a consumer would need is now in the data — and
   the relative quantities as derived facts stays open in the block's
   `settled_by`.
+
+- **Q-49** — **Must `13d`'s effect cross the Section II/III boundary for Rule 19(d)(i) to be expressible?**
+  - *broad* — drop `13d`'s `pair:geo:in_sight` gate so `encounter: overtaking` is visible in Section III; breaks the scope invariant.
+  - *narrow* — `13d` stays gated; a 19(d)(i) entry reads `own:hist:was_overtaking`/`other:hist:was_overtaking` directly, as `14b` and `15a-crossing` already do.
+  - Default: narrow (nothing changes).
+  - Recommendation: narrow — the test named below shows the fact resolves out of sight
+    (`Q-49: hist:was_overtaking resolves out of sight; 13d does not fire`, `test/data.test.mjs`).
+
+### From the Part B invariants (P4.1)
+
+Eight places where the rule text admits two readings, recorded here under
+`REQ-INV-5`. Each is the maintainer's, and each names the data's default so
+nothing is blocked while open.
+
+- **Q-50** — **Does risk of collision gate Rules 13 and 18?** 14(a) and 15(a)
+  say "so as to involve risk of collision"; Rule 13 and Rule 18 do not.
+  *Wide:* they attach whenever in sight and the geometry holds — Rule 11 is the
+  only gate Section II states — so a vessel overtaking a mile clear abeam is
+  give-way and Rule 16 binds her. *Narrow:* Section II's duties attach only with
+  risk of collision; 14 and 15 are emphasis. Default **wide**: `13a`, `13b-*`,
+  `13d` and every Rule 18 entry read `in_sight` only. No recommendation.
+- **Q-51** — **What arms 13(d)'s latch?** *A:* 13(b)'s deeming, at the first
+  state the geometry holds. *B:* 13(a)'s duty actually attaching. They differ
+  where the geometry holds but a condition on 13(a) does not — `Q-50`'s
+  surface. Default **A**: `hist:was_overtaking` is "was, at some earlier point
+  in this encounter, an overtaking vessel" and `13b-overtaking` is geometry.
+  No recommendation; downstream of `Q-50`.
+- **Q-52** — **What does 13(d)'s latch forbid?** *Narrow:* reclassification to
+  *crossing* only, as the paragraph says, leaving head-on to Rule 14 on the
+  geometry of the moment. *Broad:* the encounter stays an overtaking and no
+  other Section II classification attaches. Both preserve the duty; they differ
+  on encounter type, which Rule 17's phases and 14(a) hang off. Default
+  **broad**: `13d` yields `encounter: overtaking` from history alone, `14b` and
+  `15a-crossing` gate on `was_overtaking: false`. No recommendation.
+- **Q-53** — **Does 17(a)(ii) suspend 17(a)(i)'s duty, or add an exception?**
+  *Suspension:* "may, however" lifts the duty once non-compliance is apparent;
+  a monitor then flags nothing. *Exception:* the duty stands and a departure is
+  lawful only as action to avoid collision by her manoeuvre alone; a monitor
+  flags any other alteration. No default (Rule 17 has no entry). Recommend
+  **exception**: 17(a)(ii) describes an action, not a proviso, and leaves a
+  monitor something to check — a drafting argument, not a source.
+- **Q-54** — **Are Rule 17's phases monotone?** *Latching:* one three-valued
+  monotone latch per stand-on vessel per encounter; late compliance does not
+  take the permission away. *Re-evaluating:* each phase is a predicate on the
+  current state and the vessel may fall back — and must she then hold her *new*
+  course and speed? TLC distinguishes them on a four-state trace, so settle
+  before P4.2. No default. Recommend **latching**: one late alteration does not
+  restore reliance — an argument from purpose, not a source.
+- **Q-55** — **What does a visibility transition do to Section II state?**
+  Rule 11 and 19(a) switch on the current state; no paragraph says what
+  becomes of a 13(d) latch or a Rule 17 phase. *Persisting:* they belong to the
+  encounter and survive the fog. *Resetting:* Section II starts afresh on the
+  geometry when sight is regained — the reclassification 13(d) forbids, via
+  visibility. No default (nothing is temporal). Recommend **persisting**, which
+  `INV-13d`'s "same encounter" is written for; likeliest surprising TLC trace.
+- **Q-56** — **The third visibility state: a hole, or closed by the model?**
+  Not in sight *and* not in or near restricted visibility (clear weather, beyond
+  visual range, radar contact) is outside Rule 11 and 19(a): Section I only.
+  *Hole:* represent it; a fact for "in or near restricted visibility" is owed.
+  *Closed:* treat not-in-sight as Section III. Default **closed**: `19a` drops
+  the second conjunct, recorded as a `gap`. Recommend **hole**: the default is
+  safe for a switching consumer and unsafe for a traceability claim.
+- **Q-57** — **The baseline for "keep her course and speed"?** 17(a)(i) fixes
+  no instant. *Attachment:* course and speed when the role attached; any later
+  change is a departure — checkable, occasionally absurd. *Steady state:* the
+  vessel's settled condition, so a turn in progress may complete — seamanlike,
+  and needs a definition of "settled" the Rules lack. No default. Recommend
+  **attachment**, with the departure tolerance an explicit monitor parameter.
+
+Two decisions taken in pencil, reversible in one edit: the invariants live in
+their own document under `REQ-INV-1`–`REQ-INV-7` (§4.2 says why), and the id
+scheme is `REQ-INV-2`'s — cheap to change until P4.2 cites an id from a TLA+
+module, expensive after.

package/fixtures/applicability-fixtures.json

@@ -190,6 +190,47 @@
     "30d-anchor"
    ]
   },
+  {
+   "name": "fishing, aground, 30 m",
+   "facts": {
+    "fact:propulsion": "propulsion:power",
+    "fact:activity": "activity:fishing",
+    "fact:position": "position:aground",
+    "fact:length_m": 30
+   },
+   "expect": [
+    "30d-anchor",
+    "30d-red"
+   ]
+  },
+  {
+   "name": "trawler, aground, 30 m",
+   "facts": {
+    "fact:propulsion": "propulsion:power",
+    "fact:activity": "activity:trawling",
+    "fact:position": "position:aground",
+    "fact:length_m": 30
+   },
+   "expect": [
+    "30d-anchor",
+    "30d-red"
+   ]
+  },
+  {
+   "name": "fishing at anchor, 30 m",
+   "facts": {
+    "fact:propulsion": "propulsion:power",
+    "fact:activity": "activity:fishing",
+    "fact:position": "position:anchored",
+    "fact:length_m": 30
+   },
+   "expect": [
+    "26c-id",
+    "30a",
+    "30b",
+    "30c"
+   ]
+  },
   {
    "name": "trawler 30 m making way",
    "facts": {
@@ -767,6 +808,72 @@
     "26c-id",
     "26c-mw"
    ]
+  },
+  {
+   "name": "yacht 11.6 m moored alongside a quay",
+   "facts": {
+    "fact:propulsion": "propulsion:power",
+    "fact:activity": "activity:none",
+    "fact:position": "position:moored",
+    "fact:on_mooring_buoy": false,
+    "fact:length_m": 11.6
+   },
+   "expect": []
+  },
+  {
+   "name": "same yacht made fast to a mooring buoy, US Inland",
+   "jurisdiction": "us/inland",
+   "facts": {
+    "fact:propulsion": "propulsion:power",
+    "fact:activity": "activity:none",
+    "fact:position": "position:moored",
+    "fact:on_mooring_buoy": true,
+    "fact:length_m": 11.6
+   },
+   "expect": [
+    "30a-buoy",
+    "30b-buoy"
+   ]
+  },
+  {
+   "name": "30b-buoy length boundary: on a mooring buoy at 49.9 m, US Inland",
+   "jurisdiction": "us/inland",
+   "facts": {
+    "fact:propulsion": "propulsion:power",
+    "fact:activity": "activity:none",
+    "fact:position": "position:moored",
+    "fact:on_mooring_buoy": true,
+    "fact:length_m": 49.9
+   },
+   "expect": [
+    "30a-buoy",
+    "30b-buoy"
+   ]
+  },
+  {
+   "name": "30b-buoy length boundary: on a mooring buoy at 50.0 m, US Inland",
+   "jurisdiction": "us/inland",
+   "facts": {
+    "fact:propulsion": "propulsion:power",
+    "fact:activity": "activity:none",
+    "fact:position": "position:moored",
+    "fact:on_mooring_buoy": true,
+    "fact:length_m": 50.0
+   },
+   "expect": [
+    "30a-buoy"
+   ]
+  },
+  {
+   "name": "same yacht made fast to a mooring buoy, International",
+   "facts": {
+    "fact:propulsion": "propulsion:power",
+    "fact:activity": "activity:none",
+    "fact:position": "position:moored",
+    "fact:on_mooring_buoy": true,
+    "fact:length_m": 11.6
+   },
+   "expect": []
   }
  ]
 }

package/fixtures/situation-fixtures.json

@@ -259,6 +259,76 @@
     }
    }
   },
+  {
+   "name": "19(d)(i) fact reachability: an overtaking latch, out of sight",
+   "status": "illustrative",
+   "narrative": "The `13(d)` latch case above with `pair:geo:in_sight` flipped to `false` and own's latch already set. No Rule 19 entry exists yet to read it, so `expect` is empty; the Q-49 test reads the fact directly.",
+   "expect": [],
+   "situation": {
+    "own": {
+     "fact": {
+      "fact:propulsion": "propulsion:power",
+      "fact:activity": "activity:none",
+      "fact:position": "position:underway",
+      "fact:making_way": true,
+      "fact:length_m": 30
+     },
+     "kin": {
+      "kin:position": {
+       "latitude": 50.0,
+       "longitude": -1.4
+      },
+      "kin:heading_deg": 20,
+      "kin:sog_kn": 14,
+      "kin:rot_deg_min": 0,
+      "kin:dynamics": "dynamics:cargo"
+     },
+     "geo": {
+      "geo:rel_bearing_deg": 90
+     },
+     "hist": {
+      "hist:was_overtaking": true,
+      "hist:latched_at_s": 420
+     }
+    },
+    "other": {
+     "fact": {
+      "fact:propulsion": "propulsion:power",
+      "fact:activity": "activity:none",
+      "fact:position": "position:underway",
+      "fact:making_way": true,
+      "fact:length_m": 22
+     },
+     "kin": {
+      "kin:position": {
+       "latitude": 49.99877,
+       "longitude": -1.39475
+      },
+      "kin:heading_deg": 40,
+      "kin:sog_kn": 9,
+      "kin:rot_deg_min": 0,
+      "kin:dynamics": "dynamics:fishing"
+     },
+     "geo": {
+      "geo:rel_bearing_deg": 250
+     },
+     "hist": {
+      "hist:was_overtaking": false,
+      "hist:latched_at_s": null
+     }
+    },
+    "pair": {
+     "geo": {
+      "geo:range_m": 400,
+      "geo:bearing_change_deg_min": 24.51,
+      "geo:cpa_m": 350,
+      "geo:tcpa_s": -60,
+      "geo:in_sight": false,
+      "geo:risk_of_collision": true
+     }
+    }
+   }
+  },
   {
    "name": "18 matrix: own power-driven, other power-driven, in sight",
    "status": "binding",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "colregs",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "COLREGS 72 and its national amalgamations as language-neutral JSON — rule text, light definitions, and applicability predicates — with cross-implementation fixtures",
   "license": "Apache-2.0",
   "repository": {

package/schema/applicability-fixtures.schema.json

@@ -3,6 +3,7 @@
   "$id": "https://github.com/mark-brannan/colregs/schema/applicability-fixtures.schema.json",
   "title": "fixtures/applicability-fixtures.json",
   "description": "The cross-implementation contract: fact record -> expected entry ids. Structure only -- see docs/adr/0006-json-schema-and-identifier-diff.md.",
+  "$comment": "The top-level `jurisdiction` is the corpus default; a case may name its own, and is then evaluated against `intl` plus that jurisdiction's deltas (REQ-SCOPE-3).",
   "type": "object",
   "additionalProperties": false,
   "required": ["jurisdiction", "cases"],
@@ -28,6 +29,7 @@
         "required": ["name", "facts", "expect"],
         "properties": {
           "name": { "type": "string", "minLength": 1 },
+          "jurisdiction": { "type": "string", "pattern": "^[a-z]+(/[a-z]+)*$" },
           "facts": {
             "type": "object",
             "minProperties": 1,