colregs 0.3.0 → 0.3.2

package/docs/identifiers.md

@@ -17,10 +17,23 @@ citation: `27(a)(i)` is what a mariner, a lawyer and a court all write, and
 what a consumer stores when it records why a light was shown. Prefixing it
 would put a package-local token in front of a reference that belongs to the
 Convention rather than to this repository, and would make a stored citation
-unreadable outside the tool that stored it. Entry ids are derived from
-paragraph paths (below) and inherit the same transparency for the same
-reason. Paragraph-keying is argued in ADR 0001 and required by
-REQ-MODEL-4; nothing here reopens either.
+unreadable outside the tool that stored it. Rule ids sit beside this class
+rather than in it: `rule:13b` is *shaped* like the cite it was minted from,
+but it is a name in a namespace and a consumer reads the paragraph out of
+`cite`, never out of the id (ADR 0015).
+Paragraph-keying is argued in ADR 0001 and required by REQ-MODEL-4; nothing
+here reopens either.
+
+**Jurisdiction values sit beside paragraph paths in this class, and for the
+same reason.** `intl` and `us/inland` are not names this package coined:
+jurisdiction is a coordinate with REQ-SCOPE-2's own `<body>/<waters>`
+grammar, its left segment borrowed from ISO 3166, the whole value doubling
+as a corpus key and a `data/text/` filesystem path — its sibling axis,
+`language`, is a bare BCP 47 tag for the same reason. A jurisdiction value
+is immutable under REQ-MODEL-10 like any identifier here — renaming
+`us/inland` would break every stored provenance and corpus path — it just
+carries no prefix, because the grammar that owns it already keeps it stable
+and collision-free (ADR 0017).
 
 **Vocabulary identifiers carry a type prefix.** These names are this
 package's own — nothing in COLREGS calls anything `masthead` or `nuc`. They
@@ -29,16 +42,25 @@ collided in it: `towing` was simultaneously a light id (Rule 21(d)) and an
 `activity` value (Rule 24(a)), so a consumer holding the string `towing`
 could not say what it was a name *for* without knowing which field it came
 out of. The prefix makes the namespace part of the identifier, which
-resolves that collision by construction rather than by convention.
+resolves that collision by construction rather than by convention. The same
+shape recurs inside the closed vocabularies themselves: `shall-not-impede`
+names both a modality and a role, and `none` names both a role and an
+encounter — resolved the identical way, `modality:shall-not-impede` and
+`role:shall-not-impede` being two names rather than one (ADR 0017).
 
 ## The scheme
 
 | form | class | examples |
 |---|---|---|
+| `rule:<paragraph-slug>` | applicability entries (`data/applicability.json`) | `rule:30a`, `rule:24a_i:exceeds_200m`, `rule:15a:keep_out_of_the_way` |
 | `light:<id>` | light definitions (`data/lights.json`) | `light:masthead`, `light:sidelight_starboard`, `light:all_round` |
 | `fact:<key>` | fact keys — the input vocabulary (`data/facts.json`) | `fact:activity`, `fact:length_m`, `fact:making_way`, `fact:on_mooring_buoy` |
 | `<fact>:<value>` | values of an enumerated fact | `activity:nuc`, `position:anchored`, `propulsion:sail`, `obstruction_side:port` |
 | `rel:<name>` | the five relation verbs (`data/applicability.json`) | `rel:includes`, `rel:in_lieu_of`, `rel:exempts` |
+| `modality:<value>` | modality values (`data/applicability.json` `modalities`) | `modality:shall`, `modality:may` |
+| `role:<value>` | effect role values (`data/applicability.json` `effects.roles`) | `role:give-way`, `role:none` |
+| `encounter:<value>` | effect encounter values (`data/applicability.json` `effects.encounters`) | `encounter:head-on`, `encounter:none` |
+| `category:<value>` | entry category values (`data/applicability.json` `categories`) | `category:precedence`, `category:display` |
 
 The prefix names the namespace the identifier lives in. For a fact *value*
 that namespace is the fact itself, written bare: `activity:nuc`, not
@@ -69,9 +91,9 @@ for a better idea, logging the change. What would settle it: the first
 two-subject entry — Rule 18 — actually being written against it. This
 section answers `Q-28`.
 
-A `display` entry reads one vessel. A `classification` or `precedence`
-entry reads two, and needs to say *whose* `fact:activity` it means. The form
-is three segments:
+A `category:display` entry reads one vessel. A `category:classification` or
+`category:precedence` entry reads two, and needs to say *whose*
+`fact:activity` it means. The form is three segments:
 
 ```
 <subject>:<class>:<key>
@@ -79,14 +101,14 @@ is three segments:
 
 | segment | values |
 |---|---|
-| subject | `own`, `other`, `pair` |
+| subject | `self`, `other`, `pair` |
 | class | `fact`, `kin`, `geo`, `hist` |
 | key | the identifier as it already exists, or a new one in a new class |
 
-`own:fact:activity`, `other:kin:heading_deg`, `pair:geo:in_sight`,
-`own:hist:was_overtaking`.
+`self:fact:activity`, `other:kin:heading_deg`, `pair:geo:in_sight`,
+`self:hist:was_overtaking`.
 
-**A key with no subject segment means `own:`.** This is the whole of the
+**A key with no subject segment means `self:`.** This is the whole of the
 backward-compatibility story and it is why the subject is a *prefix* rather
 than a change to the fact keys. `fact:activity` still spells `fact:activity`
 and still denotes what it always denoted, so every predicate in
@@ -94,14 +116,14 @@ and still denotes what it always denoted, so every predicate in
 `fixtures/applicability-fixtures.json` and every stored citation a consumer
 holds stays correct unedited — `REQ-MODEL-10` is satisfied by construction
 rather than by a migration. The alternative shapes were a suffix
-(`fact:activity:own`), which buries the thing you are scanning for at the
+(`fact:activity:self`), which buries the thing you are scanning for at the
 end of a variable-length name, and per-subject fact keys
 (`fact:own_activity`), which would double the fact vocabulary and repoint
 nothing but would leave two names for one concept forever. Prefixing is the
 only one of the three where the existing vocabulary is a strict subset of
 the new one.
 
-The cost, stated so nobody rediscovers it: `own`, `other` and `pair` are now
+The cost, stated so nobody rediscovers it: `self`, `other` and `pair` are now
 reserved at the head of the identifier space, and no fact, light or relation
 may ever be named one of them. That is the price of a subject segment that
 is not itself prefixed, and it is cheap — the three words are not candidate
@@ -109,9 +131,9 @@ names for anything this package models.
 
 ### The three subjects
 
-`own` is the vessel the rule addresses; `other` is the vessel it is in an
+`self` is the vessel the rule addresses; `other` is the vessel it is in an
 encounter with. **`pair` is the encounter itself**, and it exists because
-some facts belong to neither vessel: range is one number, not own's number
+some facts belong to neither vessel: range is one number, not self's number
 and the other's. Putting `geo:range_m` under both subjects would create two
 identifiers for one quantity and a class of bug — the two disagreeing —
 that has no meaning.
@@ -122,21 +144,21 @@ Geometry splits on whether the quantity is symmetric between the vessels:
 
 | fact | subject | |
 |---|---|---|
-| `geo:rel_bearing_deg` | `own` / `other` | bearing of the *other* subject, clockwise from this subject's heading |
+| `geo:rel_bearing_deg` | `self` / `other` | bearing of the *other* subject, clockwise from this subject's heading |
 | `geo:range_m` | `pair` | |
 | `geo:bearing_change_deg_min` | `pair` | Rule 7(d)(i)'s steady bearing |
 | `geo:cpa_m`, `geo:tcpa_s` | `pair` | |
 | `geo:in_sight` | `pair` | Rule 3(k), symmetric because the rule defines it that way |
 
 The directional row is where the namespace earns its keep.
-`own:geo:rel_bearing_deg` is relative bearing — where the other vessel is
-off own's bow. `other:geo:rel_bearing_deg` is the same fact read from the
+`self:geo:rel_bearing_deg` is relative bearing — where the other vessel is
+off self's bow. `other:geo:rel_bearing_deg` is the same fact read from the
 other side, which is **aspect**. So aspect gets no identifier of its own: it
 is a subject swap, not a second fact. Rule 13(b)'s overtaking sector is then
-`other:geo:rel_bearing_deg` in (112.5, 247.5) — own more than 22.5° abaft
+`other:geo:rel_bearing_deg` in (112.5, 247.5) — self more than 22.5° abaft
 the other vessel's beam — written once, in the units the rule itself uses.
-Swapping `own` and `other` throughout a predicate reverses the encounter,
-which is exactly the operation a `precedence` rule needs and the reason to
+Swapping `self` and `other` throughout a predicate reverses the encounter,
+which is exactly the operation a `category:precedence` rule needs and the reason to
 prefer a subject namespace over two parallel vocabularies.
 
 The directional and the pair geometry are redundant with `kin:` wherever both
@@ -150,7 +172,7 @@ and a record that omits the kinematics is unchecked rather than wrong.
 
 `kin:` is the kinematic class ADR 0005 introduces — `kin:position`,
 `kin:heading_deg`, `kin:sog_kn`, `kin:rot_deg_min`, `kin:dynamics`. It takes
-`own`/`other` only; there is no kinematic state of a pair. `kin:dynamics`
+`self`/`other` only; there is no kinematic state of a pair. `kin:dynamics`
 is an enumerated fact, so its values follow the bare-fact-name rule above:
 `dynamics:tanker`, not `kin:dynamics:tanker`.
 
@@ -161,12 +183,12 @@ overtaking, a subsequent alteration of the bearing does not make her a
 crossing vessel; the instantaneous geometry, read alone, says otherwise and
 hands the duty to the wrong vessel. So the latch is a fact:
 
-- `own:hist:was_overtaking` — this subject was, earlier in this encounter,
+- `self:hist:was_overtaking` — this subject was, earlier in this encounter,
   an overtaking vessel with respect to the other.
-- `own:hist:latched_at_s` — how long ago that attached, for a `conduct`
+- `self:hist:latched_at_s` — how long ago that attached, for a `category:conduct`
   monitor. A predicate at a point does not read it.
 
-History is directional — it is *own* that was overtaking — so it takes a
+History is directional — it is *self* that was overtaking — so it takes a
 subject segment like the fact record does, and never `pair`.
 
 ### What this does not do
@@ -180,41 +202,41 @@ keys would have broken.
 ## Effects `✎`
 
 **Pencil** (`docs/conventions.md`): ADR 0005 puts the whole two-subject shape
-there. What would settle it: a second family of `precedence` paragraphs —
+there. What would settle it: a second family of `category:precedence` paragraphs —
 Rules 12, 14 and 15 — written against it. **Written, and it held with one
-addition**: Rules 7(d) and 13–15 are the first `classification` entries, and a
+addition**: Rules 7(d) and 13–15 are the first `category:classification` entries, and a
 classification produces neither a role nor a section, so the table below grows
-a third row. Rule 12 turned out to be `precedence` and not `classification`
+a third row. Rule 12 turned out to be `category:precedence` and not `category:classification`
 (below). This section answers the data half of `Q-27` and is required by
 `REQ-CAT-8`.
 
-A `display` entry produces `lights`. A `scope` or `precedence` entry produces
+A `category:display` entry produces `lights`. A `category:scope` or `category:precedence` entry produces
 an **effect**, and the shape of the effect is fixed by the category:
 
 | category | effect |
 |---|---|
-| `scope` | `{"part", "section", "applies_rules"}` — which section of which Part governs, and the rules it contains |
-| `precedence` | `{"own": <role>, "other": <role>}` — one role per subject |
-| `classification` | `{"encounter": <encounter>}` **or** `{"risk_of_collision": true}` — exactly one key |
+| `category:scope` | `{"part", "section", "applies_rules"}` — which section of which Part governs, and the rules it contains |
+| `category:precedence` | `{"self": <role>, "other": <role>}` — one role per subject |
+| `category:classification` | `{"encounter": <encounter>}` **or** `{"risk_of_collision": true}` — exactly one key |
 
-Five roles, a closed set: `give-way`, `stand-on`, `shall-not-impede`,
-`keep-clear`, `none`. They are declared in `data/applicability.json` under
-`effects`, and they are **not identifiers** — like modality and jurisdiction
-values they are a closed vocabulary of their own, outside what `REQ-MODEL-10`
-binds.
+Five roles, a closed set: `role:give-way`, `role:stand-on`,
+`role:shall-not-impede`, `role:keep-clear`, `role:none`. They are declared
+in `data/applicability.json` under `effects`, and, like modality and
+category, they are identifiers: prefixed closed vocabularies `REQ-MODEL-10`
+binds (ADR 0017).
 
 ### Encounters, and why a classification effect has two shapes
 
-Four encounters, a closed set like the roles: `head-on` (Rule 14), `crossing`
-(Rule 15), `overtaking` (Rule 13) and `none`. They are declared in
-`data/applicability.json` under `effects.encounters` and, like the roles, they
-are not identifiers.
+Four encounters, a closed set like the roles: `encounter:head-on` (Rule 14),
+`encounter:crossing` (Rule 15), `encounter:overtaking` (Rule 13) and
+`encounter:none`. They are declared in `data/applicability.json` under
+`effects.encounters` and, like the roles, they are identifiers.
 
-A `classification` effect carries **exactly one key**, and which key it is
+A `category:classification` effect carries **exactly one key**, and which key it is
 depends on which question the paragraph answers. Rule 7(d)(i) answers *does
 risk of collision exist* and produces `{"risk_of_collision": true}`; Rules 13,
 14 and 15 answer *what kind of encounter is this* and produce an `encounter`.
-ADR 0005 gives both questions to `classification` — "relative geometry,
+ADR 0005 gives both questions to `category:classification` — "relative geometry,
 history → encounter type, risk of collision" — and the two do not merge. A
 single shape would have made every encounter entry state a risk it does not
 decide, and 15(a)'s crossing test reads `pair:geo:risk_of_collision` as an
@@ -223,7 +245,7 @@ input rather than producing it.
 There is no `{"risk_of_collision": false}` and there never will be. 7(a) makes
 risk a judgement on all available means and deems it to exist in any doubt, so
 an entry can add a ground for risk and nothing in this package can deny one.
-`none` is declared as an encounter for the completeness of the vocabulary and
+`encounter:none` is declared for the completeness of the vocabulary and
 no entry produces it: an encounter type is asserted by a paragraph, and the
 absence of one is the absence of an entry rather than an entry with a null
 value.
@@ -239,17 +261,17 @@ subjects' bearings in half-degree steps and asserts exactly one encounter at
 each of the 518 400 points; the Alloy version of the same property lives in
 `colregs-engine`.
 
-### Rule 12 is `precedence`, not `classification`
+### Rule 12 is `category:precedence`, not `category:classification`
 
 ADR 0005 §1 and the proposal's first-cut table file Rule 12 under
-`classification`. It is `precedence` here, for the reason `Q-37` gives for
+`category:classification`. It is `category:precedence` here, for the reason `Q-37` gives for
 13(a): **12(a) produces a role, and a classification effect has nowhere to put
 one.** "One of them shall keep out of the way of the other" is give-way and
 stand-on in the effect vocabulary that already exists, and it is not an
 encounter type — two sailing vessels meeting are still in a head-on, a
 crossing or an overtaking, and Rule 12 says which of them gives way rather
 than which kind of meeting it is. Rule 12 has no deeming paragraph at all:
-12(b) defines the windward side and is a `definition`, so it is the cite on the
+12(b) defines the windward side and is a `category:definition`, so it is the cite on the
 `kin:wind_side` fact rather than an entry.
 
 The category is `Q-14`'s to settle paragraph by paragraph and this is two more
@@ -257,88 +279,83 @@ of them; the departure from the table is recorded in ADR 0005's pencil log and
 in `Q-40`.
 
 **Who governs over Rule 12.** 12(a)'s subjects are "two sailing vessels",
-which is 3(c), so `12a1`–`12a3` gate on `fact:propulsion` and not on the Rule
+which is 3(c), so the three Rule 12 entries gate on `fact:propulsion` and not on the Rule
 18 rank — a fishing vessel under sail is a sailing vessel. Where Rule 18 also
-ranks the pair, its entry displaces Rule 12's: `18b1`–`18b3` and `18c1`–`18c2`
+ranks the pair, its entry displaces Rule 12's: the three 18(b) entries and the two 18(c) entries
 carry `rel:overrides` against all three, because Rule 18's opening words
-except Rules 9, 10 and 13 and nothing else. `13a` overrides them for the same
+except Rules 9, 10 and 13 and nothing else. `rule:13a` overrides them for the same
 reason it overrides Rule 18 — 13(a) is "notwithstanding" the rest of Sections
 I and II. The test that pins the relation asserts both reasons from
 `rules.json`, so the data cannot keep an override after losing the words.
 
 **And over Rule 15, the same way.** 15(a)'s subjects are "two power-driven
-vessels", which is 3(b), so `15a-give-way` gates on `fact:propulsion` and on
+vessels", which is 3(b), so `rule:15a:keep_out_of_the_way` gates on `fact:propulsion` and on
 no Rule 18 rank either — a vessel engaged in fishing, or not under command,
 whose machinery is in use is a power-driven vessel. It used to negate the four
 ranks in its own predicate, which said the same thing in the one place a test
-could not see the reason; `18a1`–`18a3`, `18c1`–`18c2` and `18f1` now carry
+could not see the reason; the 18(a)(i)–(iii) entries, the two 18(c) entries and `rule:18f_i` now carry
 `rel:overrides` against it instead. The derived half of the test is what makes
 that checkable: a Rule 18 entry meets Rule 15 when it assigns a helm role and
 neither subject is gated to a sailing vessel, and every such entry must carry
 the override, so a Rule 18 paragraph added later cannot join Rule 15 silently.
 
-**The effect names both subjects, and that is the point.** A `precedence`
-entry is evaluated from own's side, so 18(a)(i) says own gives way *and* the
-other vessel stands on. Writing only own's half would lose Rule 17, which
+**The effect names both subjects, and that is the point.** A `category:precedence`
+entry is evaluated from self's side, so 18(a)(i) says self gives way *and* the
+other vessel stands on. Writing only self's half would lose Rule 17, which
 attaches to the counterpart of a give-way duty and to nothing else. So
-`stand-on` appears only opposite `give-way`, and the counterpart of
-`shall-not-impede` is always `none` — that is 8(f)(iii) in the data: a vessel
-whose passage is not to be impeded acquires no privilege by it. `none` is
+`role:stand-on` appears only opposite `role:give-way`, and the counterpart of
+`role:shall-not-impede` is always `role:none` — that is 8(f)(iii) in the data: a vessel
+whose passage is not to be impeded acquires no privilege by it. `role:none` is
 written rather than omitted, because a norm that confers nothing on a subject
-is a finding and not an absence: NUC against RAM is `none` on both sides, and
+is a finding and not an absence: NUC against RAM is `role:none` on both sides, and
 that is Rule 18's partial order rather than a gap in the table.
 
-`keep-clear` is one role for the two duties 18(e) and 18(f)(i) impose together
+`role:keep-clear` is one role for the two duties 18(e) and 18(f)(i) impose together
 — keep well clear, and avoid impeding navigation. The vocabulary cannot
 separate them and does not pretend to.
 
-### Two-subject entry ids
+### Two-subject rule ids
 
-Entry ids stay citation-derived, exactly as below: `18a1` is 18(a)(i), `9c` is
-9(c), `8f3` is 8(f)(iii). Where a paragraph's subject is disjunctive — 9(b) is
-"a vessel of less than 20 metres in length **or** a sailing vessel", and a
-`when` is a conjunction — the paragraph takes two entries and the suffix names
-the half: `9b-small` and `9b-sail`, `10j-small` and `10j-sail`. That is the
-same rule the `-m2`/`-mw`/`-anc` suffixes below follow: name what
-distinguishes them, in terms a reader with the rule text in front of them can
-find.
+A two-subject entry is keyed on its paragraph like any other (below):
+`rule:18a_i` is 18(a)(i), `rule:9c` is 9(c), `rule:8f_iii` is 8(f)(iii). No
+subject segment appears in an id: every entry is evaluated from self's side,
+and where the paragraph classifies the pair rather than one vessel the entry
+reads both subjects inside one predicate — `rule:13b` is 13(b) whichever
+vessel is coming up. Where a paragraph's subject is disjunctive — 9(b) is
+"a vessel of less than 20 metres in length **or** a sailing vessel" —
+`any_of` carries the disjunction inside one entry, `rule:9b`.
 
-## Entry ids
+## Rule ids
 
-An entry id is derived from the paragraph path its entry cites, lowercased
-with the parentheses dropped and roman sub-paragraph numerals written as
-arabic digits:
+An entry id is a paragraph key in the `rule:` namespace: `rule:` plus the
+cite with its punctuation dropped. ADR 0015 (Solace, 2026-09-16) made the
+change and carries the table from the ids it replaced; the rule for minting
+a new one is here.
 
-| paragraph path | entry id |
-|---|---|
-| Rule 28 (one paragraph) | `28` |
-| `23(b)` | `23b` |
-| `25(d)(ii)` | `25d2` |
-| `23(a)(iii)`–`(iv)`, one entry | `23a34` |
-
-Where one paragraph produces more than one entry, a hyphenated suffix names
-what distinguishes them. The suffixes are **not** drawn from a single
-scheme, because the paragraphs they split do not divide on a single axis:
-
-| suffix | means | example |
+| paragraph | rule id | why that id |
 |---|---|---|
-| `-m2` / `-m3` | two or three masthead lights | `24a-m2`, `24a-m3` |
-| `-rest` | the remainder of the rule's requirements once the split ones are taken out | `24a-rest` |
-| `-id` | the identity lights: the all-round group that says *what the vessel is* | `26b-id`, `27a-id`, `27b-id` |
-| `-mast` | the masthead light the paragraph adds on top of the identity lights | `26b-mast` |
-| `-mw` | the making-way half of a rule that lights differently when moving through the water | `26b-mw`, `27a-mw`, `27b-mw` |
-| `-gear` | the light indicating the direction of outlying gear | `26c-gear` |
-| `-anc` | the at-anchor branch | `27b-anc` |
-| `-anchor` / `-red` | 30(d)'s two halves: the anchor lights it requires, and the two red all-round lights of a vessel aground | `30d-anchor`, `30d-red` |
-
-This was reviewed and kept as it stands. The alternative — a uniform
-ordinal suffix, `27a-1` / `27a-2` — would be self-consistent and completely
-opaque: it tells a reader with the rule text in front of them nothing, in
-exchange for no gain to a machine, which only ever compares entry ids for
-equality. `24a-m2` / `24a-m3` are worth calling out in particular, because
-the two-or-three masthead split is stated in 24(a)(i) itself — the
-cardinality is in the law, not a modelling convenience of this package, and
-the suffix names something the reader can go and find.
+| 30(a) | `rule:30a` | the bare slug of the cite: rule number, paragraph letter attached |
+| 27(a)(i) | `rule:27a_i` | each roman subparagraph joined with `_` |
+| 23(a)(iii)-(iv) | `rule:23a_iii_iv` | a span of subparagraphs, joined the same way |
+| 24(a)(i), tow over 200 m | `rule:24a_i:exceeds_200m` | a further norm out of the same paragraph, named in the text's own words |
+| 15(a), the duty | `rule:15a:keep_out_of_the_way` | which half of a fused deeming-and-duty sentence this entry carries |
+| 30(a), US inland | `rule:30a:mooring_buoy` | a jurisdiction delta named by its difference; the jurisdiction stays a field |
+
+A bare id is the paragraph's principal norm. A third segment is added only
+where the text yields a second norm from the same paragraph, and it is named
+in the words of the text, not in what the entry produces. A number may appear
+there only when the Convention states the threshold itself (`exceeds_200m` is
+24(a)(i)'s).
+
+**The id is opaque.** It looks like a citation and it is not one: a consumer
+that wants "Rule 24(a)(i)" reads `cite`, and never splits an id to find a
+paragraph. `cite` is the field that moves when the package reads the Rules
+better — `14a` became `14b` once already — and the id resembling it is a
+convenience for the human reading a trace, nothing the data promises. Two
+entries may share a cite; they never share an id.
+
+`represented_paragraphs` take the same prefix and the same shape
+(`rule:2a` for 2(a)). They are not entries and nothing references them.
 
 ## Derived facts
 
@@ -393,11 +410,6 @@ implemented in the reference evaluator and asserted by the fixtures.
 
 ## What is not an identifier
 
-- **Modality values** (`shall`, `may`, `shall-if-practicable`,
-  `conditional`, `exempt`) and **jurisdiction values** (`intl`,
-  `us/inland`) are their own closed vocabularies, defined in §2 of the
-  requirements and not part of the identifier space REQ-MODEL-10 binds. So are
-  the **role** and **encounter** values of an effect.
 - **Constants** — `situation.constants` in `data/facts.json`: the numbers a
   Part B predicate needs and the Rules do not always give
   (`appreciable_bearing_change_deg_min`, `head_on_half_angle_deg`, the two
@@ -412,7 +424,7 @@ implemented in the reference evaluator and asserted by the fixtures.
   data is addressed by. Only the values inside them can be identifiers, and
   where they are (`also_activity` holds an activity value) they are prefixed.
   `not` and `any_of` are the second pair of words reserved at the head of an
-  identifier space, after `own`/`other`/`pair`: they appear where a fact key
+  identifier space, after `self`/`other`/`pair`: they appear where a fact key
   appears, so no fact may ever be named either. The cost is the same and as
   cheap — every fact key carries a class prefix (`fact:`, `geo:`, `kin:`,
   `hist:`, `env:`) and neither word could be one.

package/docs/maritime-sources.md

@@ -0,0 +1,58 @@
+# Maritime sources — case law and incident analysis
+
+Decisions and commentary on how the Rules are conventionally read, and
+collision forensics showing how they fail in the water.
+
+A case is evidence that a reading is or is not conventional. It never becomes
+a proposition in `docs/part-b-invariants.md`, which holds no maritime doctrine
+by design. Consult these where a `Q-` in `docs/requirements.md` §11 turns on a
+question the rule text leaves open.
+
+## Case law
+
+- **Monford Management Ltd v Afina Navigation Ltd ("KIVELI" c/w "AFINA I") [2025] EWHC 1185 (Admlty)**. Bryan J, Admiralty Court; permission to appeal refused, [2025] EWHC 1210. When a Section II classification arms and how long it persists — `Q-51` and `Q-52`. Held: Rule 14 applies once risk of collision arises, not on geometry alone, and risk of collision was found on Rule 7(d)(i) steady bearing plus an unsafe CPA; once armed, the classification persists until the risk has passed, unaffected by later course changes. The court rejected the submission that a head-on at C-22 had become a crossing by C-6 as the bearing opened. Reaches Rule 13 by analogy only; silent on overtaking.
+  <https://caselaw.nationalarchives.gov.uk/ewhc/admlty/2025/1185> · case note by Nigel Cooper KC, counsel for AFINA I: <https://www.quadrantchambers.com/sites/default/files/2025-05/avoiding_a_head-on_collision_-_it_is_not_just_about_the_side_lights.pdf>
+- **Evergreen Marine (UK) Ltd v Nautical Challenge Ltd ("Ever Smart" / "Alexandra 1") [2021] UKSC 6**. Frames Section II as a scheme about steady-bearing *collision* situations, with Rule 13 inside that taxonomy ([56]–[57]); leans against treating an engaged rule as inapplicable ([68]); describes Rule 17's obligations as qualified stages, predicates on the current state, with keep-course-and-speed accommodating manoeuvres such as slowing to pick up a pilot ([61]–[62]). Not asked when Rule 13 arms, and did not decide it. Separately, at [60] and [66]–[67], settles `Q-23`'s asymmetry: Rule 2(a) is a standing responsibility clause that authorises nothing, while Rule 2(b) is a conjunctive test — special circumstance *and* immediate danger — and rejects Rule 2 as a gap-filler for the steering rules.
+  <https://caselaw.nationalarchives.gov.uk/uksc/2021/6>
+- **Crowley Marine Services Inc. v. Maritrans Inc., 447 F.3d 719 (9th Cir. 2006)**. `Q-23`: the burden of justifying a Rule 2(b) departure falls on the departing vessel, and the departure must respond to an immediate danger already created — a pre-emptive departure does not qualify (n.6).
+  <https://cdn.ca9.uscourts.gov/datastore/opinions/2006/05/08/0435724.pdf>
+
+## Commentary and guidance
+
+- **Kemp — *When Do Collision Regulations Begin to Apply?* (Journal of Navigation)**. A judicial split on the antecedent question: some decisions hold the steering and sailing rules begin at risk of collision, others that they apply just before it, risk of collision being the thing to be avoided.
+  <https://www.cambridge.org/core/journals/journal-of-navigation/article/abs/when-do-collision-regulations-begin-to-apply/E6DBCD8A6ABC43FA88B5E6CB3ABF807C>
+- **eCOLREGs — overtaking and crossing on the high seas**. States the broad reading of Rule 13(d) as conventional: an overtaking vessel "maintains overtaking status and cannot transition into a crossing or head-on situation until completely past and clear".
+  <https://advanced.ecolregs.com/index.php?option=com_k2&view=item&id=172>
+- **Nautical Institute — *Action by the Stand-On Vessel*** (Seaways case study). The stand-on vessel's stages as taught; does not reach whether they are reversible.
+  <https://www.nautinst.org/resources-page/200115-action-by-the-stand-on-vessel.html>
+- **USCG Navigation Rules (Amalgamated)**. <https://www.navcen.uscg.gov/navigation-rules-amalgamated>
+
+## Marine incident analysis
+
+Collision forensics. Radar misinterpretation, mismatched turn decisions and
+ambiguous give-way/stand-on roles are what the Rules are written against.
+
+- Garzke, Simpson — *The Loss of Andrea Doria: A Marine Forensic Analysis* (Marine Technology Society Journal 46(6), 2012). Reconstructs the 1956 Andrea Doria–Stockholm collision from radar, navigation and rules-of-the-road evidence.
+  <https://www.ingentaconnect.com/content/mts/mtsj/2012/00000046/00000006/art00008> · <https://onepetro.org/JSPD/article/26/02/98/172277/The-Loss-of-Andrea-Doria-A-Marine-Forensic>
+- British Wreck Commissioner (Lord Mersey) — *Report on the Loss of the Titanic* (1912). Excessive speed through a known ice field despite wireless ice warnings — a Rule 6 case, not give-way/stand-on.
+  <https://www.titanicinquiry.org/BOTInq/BOTReport/botRep01.php>
+- Halpern — *Strangers on the Horizon: Titanic and Californian – A Forensic Approach* (2019). Reconstruction of the Titanic–Californian near-encounter: lookout, distress-signal and stand-on/give-way failures. Book only.
+  <https://www.amazon.com/STRANGERS-HORIZON-Californian-Forensic-Approach/dp/1702121984>
+- MAIB (for the Isle of Man Ship Registry) — *Report on the investigation of
+  the collision between the bulk carrier Polesie and the general cargo ship
+  Verity* (Report No 5/2026, February 2026). German Bight TSS, 24 October
+  2023; *Verity* sank with five fatalities. Analysis covers Rules 5, 6, 7, 8,
+  15, 16 and 17(a)(ii)/(b) only — it does not reach Rule 2(b), correcting an
+  earlier claim that it paired 17(b) with 2(b) at closest quarters.
+  <https://www.bahamasmaritime.com/wp-content/uploads/2026/02/2026-5-Polesie-Verity-ReportAndAnnexes.pdf>
+- IMO GISIS Marine Casualties and Incidents module. Not a paper but a source class: the mandatory-reporting database of marine safety investigation reports. Ground truth for real COLREGS-relevant incidents.
+  <https://www.imo.org/en/OurWork/IIIS/Pages/Marine-Safety-Investigation-reports.aspx>
+
+## Known gaps
+
+- `Q-23`: *The Bywell Castle* and *Boy Andrew v St Rognvald* are unread, and no
+  case was found holding a Rule 2(b) departure justified on draught,
+  manoeuvrability, shoal water, a lee shore, set, visibility or sea state.
+- Two standard texts — Cockcroft & Lameijer, *A Guide to the Collision Avoidance Rules*, and Farwell's *Rules of the Nautical Road* — are not online. Either may settle how the stages of a close-quarters encounter are divided, and whether they are treated as irreversible.
+- Several of the questions in `docs/requirements.md` §11 appear unlitigated: overtaking geometry with no risk of collision, an overtaking situation becoming a head-on, resumption of course by a stand-on vessel that has acted, and the fate of accumulated Section II state across a visibility transition.
+- BAILII refuses automated access. Use the National Archives Find Case Law service: <https://caselaw.nationalarchives.gov.uk/>

package/docs/normative-language.md

@@ -0,0 +1,103 @@
+# Normative language — how "shall", "may" and friends are used here
+
+Status: **ink**, 2026-09-05. Reviewed and accepted by the maintainer; this is the
+standing decision until an ADR supersedes it.
+
+## The decision
+
+Two vocabularies, kept apart on purpose:
+
+1. **Our own requirements** (`docs/requirements.md` here, and any spec in
+   this repo or in colregs-engine) use **MUST / MUST NOT / SHOULD / SHOULD NOT / MAY** in capitals,
+   with the meaning given by [RFC 2119] as clarified by [RFC 8174]: only
+   the capitalised words carry that meaning. Lower-case "must" or "should" in our prose is
+   ordinary English.
+2. **The data follows the Convention.** The `modality` field in
+   `data/applicability.json` holds a lower-case token derived from the
+   Convention's own verb for that paragraph: `shall`, `may`, `shall-not`,
+   `shall-if-practicable`, `shall-not-impede`, `conditional`, `exempt`.
+   These are *not* RFC 2119 keywords. They are normalised from treaty text,
+   and the verbatim paragraph sits next to them in `data/rules.json` so a
+   reader can check the token against the words. Two tokens are not verbs:
+   `conditional` means the verb itself turns on a fact, and the entry's
+   `modality_by` table says which verb applies when (Rule 23(a)(ii) is
+   `shall` at 50 m and above, `may` below); `exempt` means the paragraph
+   lifts a duty another paragraph imposes, named by `rel:exempts` (Rule
+   30(e) for small vessels at anchor). Use `conditional` only when the
+   Convention states the threshold in the paragraph; use `exempt` only when
+   the paragraph's verb is "shall not be required" or equivalent.
+
+So a capitalised MUST is a claim about the package. A lower-case `shall` in
+the data is a claim about what COLREGS says. Nothing in the repo maps one
+onto the other.
+
+## Where COLREGS will surprise an RFC reader
+
+If you learned obligation words from RFCs, three things about the
+Convention are counterintuitive. The data model follows the Convention,
+not the RFC, on each.
+
+- **There is no SHOULD tier.** RFC 2119 gives you a recommended-but-waivable
+  level. COLREGS uses "should" once in the Rules (8(b); the Annexes are not checked) and
+  nowhere defines it as a weaker rank of duty. Instead the Convention
+  **softens a duty with a condition on it, not with a weaker verb**:
+  "so far as possible", "if the circumstances of the case admit", "if
+  practicable". The data carries that as `shall-if-practicable`, a
+  qualified obligation, rather than inventing a `should`. One token covers
+  several phrasings ("so far as possible", "if the circumstances of the
+  case admit"); whether the exact qualifier deserves its own field beside
+  `modality` is question Q-31, still open.
+- **`may` is a lawful alternative, not an optional extra.** In RFC 2119 a
+  MAY is something nobody may depend on. In COLREGS a `may` display is one
+  of several complete, lawful options, and the paragraph says how it
+  relates to the others. Rule 25(b) lets a small sailing vessel *combine*
+  the 25(a) lights into one masthead lantern, so it replaces 25(a) and the
+  data records that with `rel:in_lieu_of`. Rule 25(c) lets any sailing
+  vessel show red-over-green *in addition to* 25(a), so it is
+  `rel:includes`, and it may not be shown with the 25(b) lantern, so the
+  two `rel:excludes` each other. The data keeps every lawful option with
+  its own modality and never picks one.
+- **`shall not impede` is its own kind of duty.** It has no RFC analogue.
+  It is weaker than "shall keep out of the way", and Rule 8(f) says the
+  other vessel keeps all her own duties too. Where a paragraph's verb is
+  "shall not impede" (Rules 9(b), 9(c), 10(i), 10(j)) that is its
+  `modality`; the same duty is also recorded as an `effect` on the vessel,
+  so a paragraph with a different verb can still impose it (Rule 18(d)(i)).
+
+`shall not` (a prohibition) and `shall` (an obligation) mean what an RFC
+reader expects.
+
+## What we defer to, and for what
+
+| Question | Defer to |
+|---|---|
+| What MUST / SHOULD / MAY mean in our own specs | [RFC 2119], [RFC 8174]; the W3C's [RfcKeywords] page shows how other standards cite them |
+| What `shall` / `may` / `shall not` mean in the data | The paragraph text in `data/rules.json`; no external standard redefines it |
+| Which edition of COLREGS, and which amendments, the data encodes | `docs/adr/0001` and the provenance requirements (`REQ-PROV-*`); this note says nothing about editions |
+| How standards bodies read `shall`/`should`/`may`/`can` in their own documents | [ISO/IEC Directives, Part 2], Clause 7. Not adopted here; listed because marine-standards readers will assume it |
+
+The gap between ISO's `should` (a recommendation) and COLREGS's conditional
+`shall` is exactly the first surprise above. None of this is legal advice:
+the data records what the text says, not how a court would read it.
+
+## For reviewers
+
+A pull request that adds or changes an entry is held to this note. Check:
+
+- the `modality` token matches the paragraph's own verb, and a
+  practicability phrase ("so far as possible", "if the circumstances of the
+  case admit", "if practicable") becomes `shall-if-practicable`, never a
+  new `should`;
+- a `may` entry says how it relates to the displays it is an alternative
+  to: `rel:in_lieu_of` only where the paragraph replaces another display,
+  `rel:includes` where it adds to one, `rel:excludes` where the two may not
+  be shown together;
+- a "shall not impede" paragraph carries the `shall-not-impede` effect,
+  whatever its `modality`;
+- new prose in `requirements.md` capitalises the RFC keywords it means and
+  leaves ordinary "must" and "should" in lower case.
+
+[RFC 2119]: https://www.rfc-editor.org/rfc/rfc2119
+[RFC 8174]: https://www.rfc-editor.org/rfc/rfc8174
+[RfcKeywords]: https://www.w3.org/wiki/RfcKeywords
+[ISO/IEC Directives, Part 2]: https://www.iso.org/sites/directives/current/part2/index.xhtml