colregs 0.3.1 → 0.3.3

package/data/facts.json

@@ -459,7 +459,7 @@
   ]
  },
  "situation": {
-  "note": "The input a two-subject rule reads (ADR 0005, REQ-CAT-4). A situation wraps two per-vessel fact records without changing either: `own.fact` and `other.fact` are exactly the record above, key for key. Beside them sit three new fact classes -- kinematic state (`kin:`), relative geometry (`geo:`) and history (`hist:`) -- which no `display` entry reads, so a consumer that only shows lights never constructs a situation and never supplies one of these.",
+  "note": "The input a two-subject rule reads (ADR 0005, REQ-CAT-4). A situation wraps two per-vessel fact records without changing either: `self.fact` and `other.fact` are exactly the record above, key for key. Beside them sit three new fact classes -- kinematic state (`kin:`), relative geometry (`geo:`) and history (`hist:`) -- which no `display` entry reads, so a consumer showing only lights never builds a situation or supplies one of these.",
   "status": "pencil",
   "adr": "0005",
   "requirements": [
@@ -471,19 +471,19 @@
    "form": "<subject>:<class>:<key>",
    "doc": "docs/identifiers.md, section 'Two subjects'",
    "subjects": {
-    "own": "the vessel the rule addresses -- the subject of every one-subject entry in applicability.json today",
-    "other": "the vessel own is in an encounter with",
+    "self": "the vessel the rule addresses -- the subject of every one-subject entry in applicability.json today",
+    "other": "the vessel self is in an encounter with",
     "pair": "the encounter itself. Only facts that are symmetric between the two vessels live here."
    },
    "classes": {
-    "fact": "the per-vessel fact record above, unchanged and unprefixed inside the record. `own` and `other` only.",
-    "kin": "kinematic state: where a vessel is, where it is pointing, how fast it is going and turning, and what it handles like. `own` and `other` only.",
-    "geo": "relative geometry. Under `own`/`other` it is directional, measured in that subject's own frame; under `pair` it is symmetric between them.",
-    "hist": "what has already been true of this encounter and latches. `own` and `other` only; directional.",
+    "fact": "the per-vessel fact record above, unchanged and unprefixed inside the record. `self` and `other` only.",
+    "kin": "kinematic state: where a vessel is, where it is pointing, how fast it is going and turning, and what it handles like. `self` and `other` only.",
+    "geo": "relative geometry. Under `self`/`other` it is directional, measured in that subject's own frame; under `pair` it is symmetric between them.",
+    "hist": "what has already been true of this encounter and persists. `self` and `other` only; directional.",
     "env": "environmental scope: a property of the water the encounter is in, not of either vessel. `pair` only -- a narrow channel is not one vessel's channel. Added by the Rule 18 PR, which is the first data to need it; fixtures/situation-fixtures.json flagged the gap before the class existed."
    },
-   "bare_key": "A key with no subject segment means `own:`. Every predicate in data/applicability.json today is therefore already a valid situation predicate, unedited, and every fixture in fixtures/applicability-fixtures.json is already a valid one-subject situation (REQ-CAT-4).",
-   "directional_note": "Swapping `own` and `other` reverses the encounter, which is what a `precedence` rule needs. It also earns the directional geometry class its keep: `own:geo:rel_bearing_deg` is the bearing of the other vessel off own's bow, and `other:geo:rel_bearing_deg` is the same fact from the other side -- which is aspect. Aspect is not a separate fact; it is the other subject's relative bearing."
+   "bare_key": "A key with no subject segment means `self:`. Every predicate in data/applicability.json today is therefore already a valid situation predicate, unedited, and every fixture in fixtures/applicability-fixtures.json is already a valid one-subject situation (REQ-CAT-4).",
+   "directional_note": "Swapping `self` and `other` reverses the encounter, which is what a `precedence` rule needs. It also earns the directional geometry class its keep: `self:geo:rel_bearing_deg` is the bearing of the other vessel off self's bow, and `other:geo:rel_bearing_deg` is the same fact from the other side -- which is aspect. Aspect is not a separate fact; it is the other subject's relative bearing."
   },
   "kinematics": {
    "note": "A new fact class, not an extension of the fact record (ADR 0005 sec. 2). Absolute quantities, in the world frame, one set per vessel. `kin:dynamics` is the one exception left uncited -- it is not a COLREGS concept and no paragraph will ever justify it.",
@@ -536,7 +536,7 @@
     ],
     "cite": null,
     "cite_pending": null,
-    "note": "What the vessel handles like -- the manoeuvring envelope a solver bounds own's actions by. Not a COLREGS concept and deliberately not derivable from the three axes: two power-driven vessels underway have identical facts and unrelated turning circles. The value list is a first cut and is Q-18; `dynamics:unknown` is the honest default and must stay in the set.",
+    "note": "What the vessel handles like -- the manoeuvring envelope a solver bounds self's actions by. Not a COLREGS concept and deliberately not derivable from the three axes: two power-driven vessels underway have identical facts and unrelated turning circles. The value list is a first cut and is Q-18; `dynamics:unknown` is the honest default and must stay in the set.",
     "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 rule:13b and rule:15a:crossing both 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 (self) heading. Under `self` 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) -- self 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
     },
@@ -633,10 +633,10 @@
     "status": "pencil",
     "note": "The relative geometry is redundant with the kinematic state, and a record may state a set that no two vessels can occupy (Q-48). A situation is geometrically consistent when every quantity it states agrees with every other under the equations below; a quantity the record does not state constrains nothing, so a record with bearings and no headings is not inconsistent, only unchecked. The suite enforces this on every situation fixture and on every situation its sweeps construct (REQ-VERIFY-8). This block is the definition, so that an engine applying the same check before it classifies applies this one and not a private one.",
     "equations": {
-     "headings": "own:geo:rel_bearing_deg + own:kin:heading_deg + 180 == other:geo:rel_bearing_deg + other:kin:heading_deg (mod 360). Both bearings are of the same line of sight, read from its two ends, so this needs no positions.",
+     "headings": "self:geo:rel_bearing_deg + self:kin:heading_deg + 180 == other:geo:rel_bearing_deg + other:kin:heading_deg (mod 360). Both bearings are of the same line of sight, read from its two ends, so this needs no positions.",
      "positions": "The great-circle range and the initial bearings between the two kin:position values reproduce pair:geo:range_m and, less each subject's heading, both geo:rel_bearing_deg.",
-     "motion": "With each vessel moving along her heading at her kin:sog_kn, the relative velocity in own's frame reproduces pair:geo:cpa_m, pair:geo:tcpa_s and pair:geo:bearing_change_deg_min, the last positive when the compass bearing of the other from own is increasing. The range and own's relative bearing the motion starts from are the stated pair:geo:range_m and own:geo:rel_bearing_deg, or, where the record leaves either out, the values the two kin:position fix. Course over ground is taken as heading: the record carries no set or drift.",
-     "steady_bearing": "A consequence of `motion` worth stating because Rule 15 rests on it: on a steady bearing with both vessels making way, own's speed times the sine of her relative bearing equals minus the other's speed times the sine of the aspect, so the two bearings lie on opposite sides. Two vessels each with the other on her starboard side are never on a collision course, which is why 15(a) never lays give-way on both -- and the suite asserts that over a sweep of steady-bearing geometries rather than over free bearings."
+     "motion": "With each vessel moving along her heading at her kin:sog_kn, the relative velocity in self's frame reproduces pair:geo:cpa_m, pair:geo:tcpa_s and pair:geo:bearing_change_deg_min, the last positive when the compass bearing of the other from self is increasing. The range and self's relative bearing the motion starts from are the stated pair:geo:range_m and self:geo:rel_bearing_deg, or, where the record leaves either out, the values the two kin:position fix. Course over ground is taken as heading: the record carries no set or drift.",
+     "steady_bearing": "A consequence of `motion` worth stating because Rule 15 rests on it: on a steady bearing with both vessels making way, self's speed times the sine of her relative bearing equals minus the other's speed times the sine of the aspect, so the two bearings lie on opposite sides. Two vessels each with the other on her starboard side are never on a collision course, which is why 15(a) never lays give-way on both -- and the suite asserts that over a sweep of steady-bearing geometries rather than over free bearings."
     },
     "tolerances": {
      "bearing_deg": 1.0,
@@ -653,7 +653,7 @@
    }
   },
   "history": {
-   "note": "The situation is not memoryless: Rule 13(d) latches a classification that the instantaneous geometry would later contradict. History is directional -- it is own that was or was not the overtaking vessel -- so it takes a subject segment like the fact record does.",
+   "note": "The situation is not memoryless: Rule 13(d) carries forward a classification that the instantaneous geometry would later contradict. History is directional -- it is self that was or was not the overtaking vessel -- so it takes a subject segment like the fact record does.",
    "hist:was_overtaking": {
     "type": "boolean",
     "cite": "13(d)",
@@ -667,15 +667,15 @@
     "unit": "s",
     "cite": "13(d)",
     "cite_pending": null,
-    "note": "Seconds since the latched classification first held, or null if nothing has latched. Carried so a `conduct` monitor can say when the duty attached; a predicate at a point does not read it.",
+    "note": "Seconds since the carried-forward classification first held, or null if none has held yet. Carried so a `conduct` monitor can say when the duty attached; a predicate at a point does not read it.",
     "actuable": false,
     "signalk": null
    }
   },
   "record": {
-   "note": "The shape, as an illustration rather than a schema. `own.fact` and `other.fact` hold the fact record defined above, verbatim. `own` and `other` carry directional geometry; `pair` carries only the symmetric geometry. Absent is absent: a missing key never satisfies a constraint, exactly as in the one-subject evaluator.",
+   "note": "The shape, as an illustration rather than a schema. `self.fact` and `other.fact` hold the fact record defined above, verbatim. `self` and `other` carry directional geometry; `pair` carries only the symmetric geometry. Absent is absent: a missing key never satisfies a constraint, exactly as in the one-subject evaluator.",
    "shape": {
-    "own": {
+    "self": {
      "fact": "<the fact record above>",
      "kin": "<kinematics>",
      "geo": "<directional geometry>",
@@ -727,7 +727,7 @@
    "head_on_half_angle_deg": {
     "value": 11.25,
     "unit": "deg",
-    "fact": "own:geo:rel_bearing_deg and other:geo:rel_bearing_deg",
+    "fact": "self:geo:rel_bearing_deg and other:geo:rel_bearing_deg",
     "status": "pencil",
     "cite": null,
     "cite_pending": "14(b)",

package/data/i18n/en.json

@@ -7,21 +7,87 @@
     "reviewed_by": [
       "mark-brannan"
     ],
-    "review_date": "2026-09-13"
+    "review_date": "2026-09-16"
   },
   "strings": {
-    "light": {
+    "lights": {
       "light:masthead": "Masthead light",
+      "light:sidelights": "Sidelights",
       "light:sidelight_starboard": "Starboard sidelight",
       "light:sidelight_port": "Port sidelight",
       "light:sternlight": "Sternlight",
       "light:towing": "Towing light",
-      "light:all_round": "All-round light"
+      "light:all_round": "All-round light",
+      "light:flashing": "Flashing light",
+      "light:torch": "Electric torch or lighted lantern",
+      "light:deck_lights": "Working or equivalent lights"
     },
-    "modality": {
-      "shall": "Required",
-      "may": "Permitted",
-      "shall-if-practicable": "Required if practicable"
+    "modalities": {
+      "modality:shall": "Required",
+      "modality:may": "Permitted",
+      "modality:shall-if-practicable": "Required if practicable",
+      "modality:conditional": "Conditional",
+      "modality:exempt": "Exempt",
+      "modality:shall-not": "Prohibited",
+      "modality:shall-not-impede": "Must not impede"
+    },
+    "roles": {
+      "role:give-way": "Give way",
+      "role:stand-on": "Stand on",
+      "role:shall-not-impede": "Must not impede",
+      "role:keep-clear": "Keep clear",
+      "role:none": "No role"
+    },
+    "encounters": {
+      "encounter:head-on": "Head-on",
+      "encounter:crossing": "Crossing",
+      "encounter:overtaking": "Overtaking",
+      "encounter:none": "No encounter"
+    },
+    "jurisdictions": {
+      "intl": "International",
+      "us/inland": "US Inland"
+    },
+    "facts": {
+      "propulsion:power": "Power-driven",
+      "propulsion:sail": "Sailing",
+      "propulsion:oars": "Oars",
+      "activity:none": "None",
+      "activity:fishing": "Fishing",
+      "activity:trawling": "Trawling",
+      "activity:towing": "Towing",
+      "activity:pushing": "Pushing",
+      "activity:being_towed": "Being towed",
+      "activity:nuc": "Not under command",
+      "activity:ram": "Restricted in her ability to manoeuvre",
+      "activity:ram_underwater": "Restricted in her ability to manoeuvre, engaged in underwater operations",
+      "activity:cbd": "Constrained by her draught",
+      "activity:mine": "Engaged in minesweeping",
+      "activity:pilot": "Engaged on pilotage duty",
+      "activity:diving": "Engaged in diving operations",
+      "position:underway": "Underway",
+      "position:anchored": "At anchor",
+      "position:aground": "Aground",
+      "position:moored": "Moored",
+      "rule18_class:nuc": "Not under command",
+      "rule18_class:ram": "Restricted in ability to manoeuvre",
+      "rule18_class:fishing": "Fishing",
+      "rule18_class:wig": "Wing-in-ground craft",
+      "rule18_class:cbd": "Constrained by draught",
+      "rule18_class:sail": "Sailing vessel",
+      "rule18_class:power": "Power-driven vessel",
+      "dynamics:tanker": "Tanker",
+      "dynamics:cargo": "Cargo ship",
+      "dynamics:ferry": "Ferry",
+      "dynamics:fishing": "Fishing vessel",
+      "dynamics:yacht": "Yacht",
+      "dynamics:rib": "RIB",
+      "dynamics:unknown": "Unknown",
+      "obstruction_side:port": "Port",
+      "obstruction_side:starboard": "Starboard",
+      "wind_side:port": "Port",
+      "wind_side:starboard": "Starboard",
+      "wind_side:unknown": "Unknown"
     }
   }
 }

package/data/i18n/fi.json

@@ -8,7 +8,7 @@
     "review_date": "2026-09-15"
   },
   "strings": {
-    "light": {
+    "lights": {
       "light:masthead": "Mastovalo",
       "light:sidelight_starboard": "Oikea sivuvalo",
       "light:sidelight_port": "Vasen sivuvalo",
@@ -16,10 +16,10 @@
       "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"
+    "modalities": {
+      "modality:shall": "Pakollinen",
+      "modality:may": "Sallittu",
+      "modality:shall-if-practicable": "Pakollinen, jos mahdollista"
     }
   }
 }

package/data/lights.json

@@ -8,8 +8,7 @@
  },
  "lights": {
   "light:masthead": {
-   "name": "masthead light",
-   "colregs_term": "masthead light",
+   "term": "masthead light",
    "cite": "21(a)",
    "color": "white",
    "character": "steady",
@@ -22,8 +21,7 @@
    "rule21": true
   },
   "light:sidelights": {
-   "name": "sidelights",
-   "colregs_term": "sidelights",
+   "term": "sidelights",
    "cite": "21(b)",
    "character": "steady",
    "composite": true,
@@ -36,8 +34,7 @@
    "rule21": true
   },
   "light:sidelight_starboard": {
-   "name": "starboard sidelight",
-   "colregs_term": "sidelight",
+   "term": "sidelight",
    "cite": "21(b)",
    "color": "green",
    "character": "steady",
@@ -50,8 +47,7 @@
    "rule21": true
   },
   "light:sidelight_port": {
-   "name": "port sidelight",
-   "colregs_term": "sidelight",
+   "term": "sidelight",
    "cite": "21(b)",
    "color": "red",
    "character": "steady",
@@ -64,8 +60,7 @@
    "rule21": true
   },
   "light:sternlight": {
-   "name": "sternlight",
-   "colregs_term": "sternlight",
+   "term": "sternlight",
    "cite": "21(c)",
    "color": "white",
    "character": "steady",
@@ -78,8 +73,7 @@
    "rule21": true
   },
   "light:towing": {
-   "name": "towing light",
-   "colregs_term": "towing light",
+   "term": "towing light",
    "cite": "21(d)",
    "color": "yellow",
    "character": "steady",
@@ -92,8 +86,7 @@
    "rule21": true
   },
   "light:all_round": {
-   "name": "all-round light",
-   "colregs_term": "all-round light",
+   "term": "all-round light",
    "cite": "21(e)",
    "color": null,
    "color_note": "colour is fixed by the citing paragraph, not by Rule 21",
@@ -106,8 +99,7 @@
    "rule21": true
   },
   "light:flashing": {
-   "name": "flashing light",
-   "colregs_term": "flashing light",
+   "term": "flashing light",
    "cite": "21(f)",
    "color": null,
    "color_note": "colour is fixed by the citing paragraph",
@@ -122,8 +114,7 @@
    "rule21": true
   },
   "light:torch": {
-   "name": "electric torch or lighted lantern",
-   "colregs_term": "electric torch or lighted lantern",
+   "term": "electric torch or lighted lantern",
    "cite": "25(d)(i)",
    "color": "white",
    "character": "shown in sufficient time to prevent collision",
@@ -133,8 +124,7 @@
    "note": "Not a fixed navigation light: it is held ready at hand and shown on approach. It has no prescribed arc, range or position."
   },
   "light:deck_lights": {
-   "name": "working or equivalent lights",
-   "colregs_term": "working or equivalent lights",
+   "term": "working or equivalent lights",
    "cite": "30(c)",
    "color": null,
    "character": "steady",

package/data/version.json

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

package/docs/adr/0010-text-withheld-jurisdictions.md

@@ -102,6 +102,8 @@ data one.
   international law where a national body deliberately has none. That is
   about deltas, not licences; it survives this ADR untouched and is the live
   blocker on CEVNI. Read the two together or the wrong one gets blamed.
+  *(ADR 0018 has since supplied that mechanism; the bar is now "land with
+  your tombstones", not "wait".)*
 - `schema/rules.schema.json` carries the conditional: `text` required unless
   `text_status` is `withheld`, in which case it is forbidden and
   `withheld_reason` is required. Only `withheld_reason` is refused on a

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

@@ -49,7 +49,7 @@ that is the fixture contract: both fixture files `expect` entry ids.
 
 ### 2. `FactRecord` keeps its name
 
-It is colregs' name for the per-vessel record (`own.fact` is "exactly the
+It is colregs' name for the per-vessel record (`self.fact` is "exactly the
 record above, key for key"). ADR 0005 §2 has the situation wrap two fact
 records; the fact record itself does not widen, and a display consumer never
 sees a situation. A name that hinted at two vessels would describe the wrapper,
@@ -59,13 +59,13 @@ not the thing.
 
 colregs states the situation twice: nested by subject and class in
 `facts.json` §`situation.record` and in every fixture case, and flat as
-`own:fact:activity` inside predicates. The engine's public type is the
+`self:fact:activity` inside predicates. The engine's public type is the
 **nested** form. The flat form is the predicate namespace and stays internal
 to the walker.
 
 ```ts
 interface Situation {
-  own: Subject;
+  self: Subject;
   other?: Subject;
   pair?: Pair;
 }
@@ -73,7 +73,7 @@ interface Subject { fact: FactRecord; kin?: Kinematics; geo?: DirectionalGeometr
 interface Pair    { geo?: PairGeometry; env?: Environment; }
 ```
 
-- `own` is required; `other`/`Subject.fact` follow colregs' own fixture schema
+- `self` is required; `other`/`Subject.fact` follow colregs' own fixture schema
   (`situation-fixtures.schema.json`, `0.2.0`) — `other` optional (Rule 19's
   single-vessel scope needs no synthesized one), `fact` required. Every other
   class, and every key inside a class, is optional — absent is absent.
@@ -98,7 +98,7 @@ interface EncounterEvaluation {
   scope: EntryId[];
   encounter?: 'head-on' | 'crossing' | 'overtaking' | 'none';
   risk_of_collision: { asserted: boolean; by: EntryId[] };
-  roles: { own: SubjectRole[]; other: SubjectRole[] };
+  roles: { self: SubjectRole[]; other: SubjectRole[] };
   overridden: { id: EntryId; by: EntryId }[];
   modalities: Record<EntryId, Modality>;
 }
@@ -164,10 +164,10 @@ resolution, and validation of the situation record.
 | `FactRecord` keeps its name | ink | — |
 | `Situation` nested by subject and class, generated from `facts.json` | ink | — |
 | Verb name `evaluateEncounter`; result name `EncounterEvaluation` | ✎ | colregs renaming the `pair` subject or the `encounter` effect |
-| `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 |
+| `self` 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); `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 |
+| `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; `roles` is the pooled two-frame read, ADR 0016 | ✎ | 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/0012-trace-and-rule2-departure-api.md

@@ -81,12 +81,12 @@ interface ConductEvaluation {
   phases: ConductPhaseChange[];
 }
 interface ConductVerdict {
-  id: EntryId; subject: 'own' | 'other';
+  id: EntryId; subject: 'self' | 'other';
   verdict: 'kept' | 'breached' | 'pending';
   attached_at_s?: number; decided_at_s?: number;
   robustness?: { value: number; unit: string };
 }
-interface ConductPhaseChange { subject: 'own' | 'other'; phase: ParagraphCite; at_s: number; }
+interface ConductPhaseChange { subject: 'self' | 'other'; phase: ParagraphCite; at_s: number; }
 ```
 
 - One **verdict** per applied conduct entry per subject it attached to; an

package/docs/adr/0016-encounter-roles-are-pooled-across-frames.md

@@ -0,0 +1,82 @@
+# ADR 0016 — An encounter's roles are read from both frames, pooled, then resolved
+
+Date: 2026-09-16
+Status: accepted — Solace's ruling on #141, 2026-09-16.
+
+## Context
+
+Every `precedence` entry in `data/applicability.json` is written from the
+duty-holder's seat: `effect.self` is one of `give-way`, `shall-not-impede`,
+`keep-clear`, `none`, and `effect.other` is `stand-on` or `none`. No entry
+names self stand-on. That is faithful to the text — a paragraph addresses the
+vessel it binds, and the other vessel's stand-on is Rule 17's inference —
+and it is why entry `rule:15a:keep_out_of_the_way` gates self's bearing on the
+starboard half only.
+
+ADR 0011 §4 defines `EncounterEvaluation.roles` as a role set for *both*
+subjects: what everyone is to do. Nothing between the two said how an engine
+gets from a one-seat table to a two-seat answer. colregs-engine read the
+situation once, from self's seat, and passed every fixture doing it, because
+`fixtures/situation-fixtures.json` expects one-seat entry ids.
+
+Measured on 2026-09-16 (#141), with colregs' own matcher, one-seat against
+pooled:
+
+| encounter | one seat tells self | pooled says self is |
+|---|---|---|
+| crossing, other on self's port bow | nothing | stand-on |
+| self not under command, ordinary power vessel to starboard | give-way (15(a)) | stand-on (18(a)(i)) |
+| self power-driven, a sailing vessel overtaking her | give-way (18(a)(iv)) | stand-on (13(a)) |
+
+The second and third are not gaps but wrong answers: both vessels give-way
+at once. The cause is that every `rel:overrides` edge of the Q-40 family —
+`rule:18a_i` → `rule:15a:keep_out_of_the_way`, `rule:13a` → `rule:18a_iv`,
+`rule:9c` → `rule:18a_iii` and the rest — has its source in one vessel's
+seat and its target in the other's. A one-seat reader never sees the source,
+so the target stands. The suite has pooled both seats since ADR 0005 §4
+(`pooledRoles` in `test/data.test.mjs`); with the swap removed it fails.
+
+Two repairs were on the table: reciprocal entries (self stand-on, other
+give-way, gates mirrored), or the pooled read stated as the contract.
+
+## Decision
+
+1. **`evaluateEncounter` reads two frames.** The situation as given, and its
+   swap (`self` and `other` exchanged, `pair` unchanged), are both matched
+   against every non-`display` entry. Derived facts are computed per frame.
+2. **Precedence entries are pooled, then resolved.** The precedence entries
+   that apply in either frame form one pool, keyed by which vessel each fired
+   for. `rel:overrides` is resolved over the pool, so an override may reach
+   an entry that fired in the other frame. Only then are roles read.
+3. **`roles.self` and `roles.other` come from the pool.** A vessel's roles are
+   every non-`none` role a surviving forceful entry lays on her, from
+   `effect.self` where she was the frame's self and from `effect.other` where
+   she was the frame's other; `by` names the entry either way.
+4. **`applied`, `scope`, `encounter`, `risk_of_collision`, `modalities` and
+   `categories` stay self-frame.** They answer the fixture's entry-id `expect`
+   as they do today, and a classification is the pair's already.
+5. **A situation fixture may state `roles`.** `roles: {self: [{role, by}],
+   other: [{role, by}]}` is the pooled, resolved answer for both subjects and
+   binds an engine to it; `expect` stays the self-frame entry ids.
+6. **No reciprocal entries.** They would double the table and every override
+   edge, make `effect.other` redundant, and still need the override to reach
+   across the pair.
+
+## Consequences
+
+- Four binding cases in `fixtures/situation-fixtures.json` carry `roles`:
+  the crossing as written and the three encounters in the table above.
+- `INV-PB-roles-exclusive` and `INV-PB-one-role-source` are stated over the
+  pooled read, as the suite already asserts them.
+- colregs-engine's `evaluateEncounter` changes to match; colregs-engine#85
+  (the 13(d) latch ordering) is independent of this.
+- 8(f)(iii)'s `none`/`none` and Q-35 are untouched: pooling adds no role,
+  it only lets every entry see the entries it was written to override.
+
+## Register
+
+| item | level | what would settle it |
+|---|---|---|
+| Two frames, pooled, resolved, then roles — not reciprocal entries | ink | Solace, 2026-09-16 |
+| Self-frame `applied`; pooled `roles` only | ✎ | a consumer needing the other frame's applied ids |
+| Fixture `roles` as `{role, by}` per subject | ✎ | the engine's conformance replay consuming it |

package/docs/adr/0017-closed-vocabularies-are-prefixed-identifiers.md

@@ -0,0 +1,105 @@
+# ADR 0017 — Closed vocabularies are prefixed identifiers
+
+Date: 2026-09-16
+Status: accepted — Solace's ruling, 2026-09-16
+
+## Context
+
+Issue #120 built a display catalog for the light, modality, role, encounter
+and jurisdiction vocabularies and, in doing so, named a fiction in
+`docs/identifiers.md`: "What is not an identifier" declared modality, role,
+jurisdiction and encounter values outside `REQ-MODEL-10`'s identifier space,
+on the theory that a closed vocabulary is a different kind of thing from a
+name. The carve-out never reduced what a rename costs. Every one of these
+values is emitted by the engine (`DisplayEvaluation.modality`,
+`EncounterEvaluation.roles[].role`, `.encounter`, `provenance.jurisdictions`,
+`evaluated_categories`) and compared by a consumer the same way an entry id
+or a fact value is — `if (role === 'give-way')` breaks on a rename exactly
+as `if (activity === 'nuc')` would. Declining to promise stability does not
+make the rename cheaper; it only leaves the promise unwritten.
+
+The collision that follows from treating them as a separate kind is not
+hypothetical. It has already happened, in the data on `main`:
+
+| string | is a … | and also a … |
+|---|---|---|
+| `shall-not-impede` | modality (`modalities`) | role (`effects.roles`) |
+| `none` | role (`effects.roles`) | encounter (`effects.encounters`) |
+
+This is the identical shape as `towing`, the collision ADR 0001's `light:`
+prefix and `activity:` axis already resolved: a consumer holding the bare
+string cannot say which field it came out of. The rule already on file —
+"the prefix makes the namespace part of the identifier, which resolves that
+collision by construction rather than by convention" — already applies here;
+it was only not applied.
+
+Issue #120's own draft, before this ruling, reached the opposite
+recommendation on its Q2: that prefixing sections into identifiers "later"
+costs the same as doing it now. That held only if the bare strings were not
+identifiers. They are — held and compared by consumers — so the option runs
+one way: pre-1.0, prefixing is a data-layer, one-PR change; post-1.0 it is
+an identifier-layer change REQ-MODEL-10 forbids outright, leaving only the
+two-names-forever shape `docs/identifiers.md` already rejected for
+`fact:own_activity`. Ruled by Solace, 2026-09-16.
+
+## Decision
+
+1. **Four closed vocabularies take a type prefix**, the same mechanism as
+   `light:`, `fact:`, `rel:`: `modality:` (`data/applicability.json`
+   `modalities`, every entry's `modality`, `modality_by` branches),
+   `role:` (`effects.roles`, `effect.own`/`effect.other`), `encounter:`
+   (`effects.encounters`, `effect.encounter`), and `category:` (`categories`,
+   every entry's and `represented_paragraphs` record's `category`) — new to
+   this list because it is the same class (package-coined, closed, emitted,
+   compared) and leaving it bare while prefixing the other three would
+   recreate the inconsistency this ADR closes.
+2. **Jurisdiction stays bare.** `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 (REQ-LANG-3) and a `data/text/`
+   filesystem path — its sibling axis, `language`, is a bare BCP 47 tag for
+   the same reason. `jurisdiction:us/inland` would put a colon namespace in
+   front of a slash path and claim the package minted `us`, which it did
+   not. Its stability is a property of the grammar (REQ-SCOPE-4 makes
+   adding a jurisdiction additive; no fact, light or role value can spell
+   `us/inland`), not of a prefix — the same reason a paragraph path carries
+   none. Jurisdiction moves from "What is not an identifier" to the bare
+   class beside paragraph paths in `docs/identifiers.md`: it *is* an
+   identifier, immutable under REQ-MODEL-10 exactly like `27(a)(i)`, and it
+   just carries no prefix.
+3. **The two live collisions are recorded, not just resolved.**
+   `modality:shall-not-impede` and `role:shall-not-impede` are two names;
+   `role:none` and `encounter:none` are two names. Each pair collided under
+   the old bare scheme and does not under this one.
+
+## Consequences
+
+- **One-pass rename, one commit.** `data/applicability.json`'s four
+  vocabulary maps and every entry field that names a value; both fixture
+  files (`applicability-fixtures.json` has no modality field to touch;
+  `situation-fixtures.json`'s `expect[].modality`); every schema enum/pattern
+  naming one of the four (`applicability.schema.json`,
+  `evaluation.schema.json`, `encounter-evaluation.schema.json`,
+  `i18n-catalog.schema.json`); the two i18n catalogs' `modality` section
+  keys; the test suite's literal comparisons; `docs/identifiers.md`,
+  `docs/requirements.md`, `README.md`. Jurisdiction values, patterns and
+  every corpus path are untouched.
+- **colregs-engine follow-up.** Its generated types (`DisplayEvaluation`,
+  `EncounterEvaluation`, and any hand-written literal comparing against a
+  modality, role, encounter or category string) regenerate from this
+  package's schemas and wait on a colregs release carrying this ADR. Until
+  that release, colregs-engine's own types name the pre-ADR bare values;
+  this is a breaking change for it in the ordinary pre-1.0 sense (no
+  deprecation window, no shim — `AGENTS.md` "Stage: pre-consumer"), tracked
+  as its own follow-up, not blocking this PR.
+- **The i18n catalog keys change shape**, not content: `modality:shall`
+  replaces `shall` as the key into `data/i18n/*.json`'s `modality` section;
+  the label strings themselves are untouched. A catalog section for role,
+  encounter or category is not added by this ADR — only the vocabulary
+  values those sections would key against.
+- Rule ids (`rule:15a:crossing`) and shape keys (`when`, `effect`, a
+  `category:scope` effect's `part`/`section`/`applies_rules`) are untouched: only
+  the four vocabularies' *values* take the prefix, never a key or an id
+  that happens to share a word with one.
+
+Ruled by Solace, 2026-09-16.