colregs 0.1.1 → 0.2.2

package/data/facts.json

@@ -1,74 +1,80 @@
 {
  "note": "The fact record a consumer evaluates applicability predicates against. Three orthogonal axes plus scalars; there is no separate COLREGS vessel-class field, because under COLREGS what a vessel is follows from what it is doing.",
  "axes": {
-  "propulsion": {
+  "fact:propulsion": {
    "values": [
-    "power",
-    "sail",
-    "oars"
+    "propulsion:power",
+    "propulsion:sail",
+    "propulsion:oars"
    ],
    "cites": {
-    "power": "3(b)",
-    "sail": "3(c)",
-    "oars": "25(d)(ii)"
+    "propulsion:power": "3(b)",
+    "propulsion:sail": "3(c)",
+    "propulsion:oars": "25(d)(ii)"
    },
    "note": "A vessel under sail with propelling machinery in use is 'power' (Rule 3(c)); the 25(e) day shape is the only trace motorsailing leaves at night."
   },
-  "activity": {
+  "fact:activity": {
    "values": [
-    "none",
-    "fishing",
-    "trawling",
-    "towing",
-    "pushing",
-    "being_towed",
-    "nuc",
-    "ram",
-    "ram_underwater",
-    "cbd",
-    "mine",
-    "pilot",
-    "diving"
+    "activity:none",
+    "activity:fishing",
+    "activity:trawling",
+    "activity:towing",
+    "activity:pushing",
+    "activity:being_towed",
+    "activity:nuc",
+    "activity:ram",
+    "activity:ram_underwater",
+    "activity:cbd",
+    "activity:mine",
+    "activity:pilot",
+    "activity:diving"
    ],
    "cites": {
-    "fishing": "3(d)",
-    "trawling": "26(b)",
-    "nuc": "3(f)",
-    "ram": "3(g)",
-    "ram_underwater": "27(d)",
-    "cbd": "3(h)",
-    "mine": "27(f)",
-    "pilot": "29(a)",
-    "diving": "27(e)",
-    "towing": "24(a)",
-    "pushing": "24(b)",
-    "being_towed": "24(e)"
+    "activity:fishing": "3(d)",
+    "activity:trawling": "26(b)",
+    "activity:nuc": "3(f)",
+    "activity:ram": "3(g)",
+    "activity:ram_underwater": "27(d)",
+    "activity:cbd": "3(h)",
+    "activity:mine": "27(f)",
+    "activity:pilot": "29(a)",
+    "activity:diving": "27(e)",
+    "activity:towing": "24(a)",
+    "activity:pushing": "24(b)",
+    "activity:being_towed": "24(e)"
    },
    "note": "'ram_underwater' is a vessel restricted in her ability to maneuver that is dredging or engaged in underwater operations (27(d)); it is a refinement of 'ram', not a peer of it, and predicates written for 'ram' also read it."
   },
-  "position": {
+  "fact:position": {
    "values": [
-    "underway",
-    "anchored",
-    "aground",
-    "moored"
+    "position:underway",
+    "position:anchored",
+    "position:aground",
+    "position:moored"
    ],
    "cites": {
-    "underway": "3(i)"
+    "position:underway": "3(i)"
    },
    "note": "Rule 3(i): underway means not at anchor, not made fast to the shore, not aground."
   }
  },
  "modifiers": {
-  "making_way": {
+  "fact:making_way": {
    "type": "boolean",
-   "refines": "position=underway",
+   "refines": "fact:position=position:underway",
    "note": "Undefined in the Rules; it means moving through the water. Underway but not making way is free drifting. Only the 26/27-family predicates read it (26(b)(iii), 26(c)(iii), 27(a)(iii), 27(b)(iii)); Rules 23 and 25 gate on 'underway' alone, so a power-driven vessel drifting in neutral still shows full running lights.",
    "actuable": true
+  },
+  "fact:on_mooring_buoy": {
+   "type": "boolean",
+   "refines": "fact:position=position:moored",
+   "note": "Made fast to a mooring buoy rather than to the shore. Rule 3(i) makes both 'moored', and the Convention prescribes no lights for either. Only a jurisdiction that deems a buoy-moored vessel to be at anchor reads it -- US Inland, 33 CFR 90.5 -- so under intl it selects nothing.",
+   "actuable": true
   }
  },
  "numerics": {
-  "length_m": {
+  "fact:length_m": {
    "type": "number",
    "unit": "m",
    "cite": "3(j)",
@@ -76,7 +82,7 @@
    "actuable": true,
    "signalk": "design.length.value.overall"
   },
-  "tow_length_m": {
+  "fact:tow_length_m": {
    "type": "number",
    "unit": "m",
    "cite": "24(a)(i)",
@@ -84,7 +90,7 @@
    "actuable": true,
    "signalk": null
   },
-  "max_speed_kn": {
+  "fact:max_speed_kn": {
    "type": "number",
    "unit": "kn",
    "cite": "23(d)(ii)",
@@ -92,14 +98,14 @@
    "actuable": true,
    "signalk": null
   },
-  "gear_extent_m": {
+  "fact:gear_extent_m": {
    "type": "number",
    "unit": "m",
    "cite": "26(c)(ii)",
    "actuable": false,
    "signalk": null
   },
-  "beam_m": {
+  "fact:beam_m": {
    "type": "number",
    "unit": "m",
    "cite": "24(g)",
@@ -108,61 +114,197 @@
   }
  },
  "booleans": {
-  "composite_unit": {
+  "fact:composite_unit": {
    "cite": "24(b)",
    "actuable": false
   },
-  "non_displacement": {
+  "fact:non_displacement": {
    "cite": "23(b)",
    "actuable": false,
    "note": "Air-cushion vessel operating in non-displacement mode."
   },
-  "wig": {
+  "fact:wig": {
    "cite": "23(c)",
    "actuable": false,
    "note": "The vessel is a wing-in-ground craft. Doesn't by itself mean 23(c) applies -- see wig_near_surface."
   },
-  "wig_near_surface": {
+  "fact:wig_near_surface": {
    "cite": "23(c)",
    "actuable": false,
    "note": "Taking off, landing, or in flight near the surface. 23(c) is scoped to this phase, not to being a WIG craft generally."
   },
-  "near_channel": {
+  "fact:near_channel": {
    "cite": "30(e)",
    "actuable": false,
    "note": "At anchor in or near a narrow channel, fairway, or where other vessels normally navigate."
   },
-  "inconspicuous_partly_submerged_tow": {
+  "fact:inconspicuous_partly_submerged_tow": {
    "cite": "24(g)",
    "actuable": false
   },
-  "towed_alongside": {
+  "fact:towed_alongside": {
    "cite": "24(c)",
    "actuable": false
   },
-  "obstruction_exists": {
+  "fact:obstruction_exists": {
    "cite": "27(d)",
    "actuable": false
+  },
+  "fact:tow_restricts_deviation": {
+   "cite": "27(c)",
+   "actuable": false,
+   "note": "The towing operation severely restricts the towing vessel and her tow in their ability to deviate from their course. Rule 27(c) makes such a pair restricted in her ability to manoeuvre; `activity:towing` alone does not, because most tows are not. Read only by the fact:rule18_class decode table, which is where Q-32's missing 27(c) case lives."
+  },
+  "fact:confined_to_channel": {
+   "cite": "9(b)",
+   "actuable": false,
+   "note": "A vessel which can safely navigate only within the narrow channel or fairway -- 9(b)'s and 9(d)'s protected vessel, read of whichever vessel it is asked of rather than assumed from `pair:env:narrow_channel`. Closes Q-34's 9(b)/9(d) half: a consumer sets this from the vessel's draft and the channel, the same judgement `pair:env:narrow_channel` already asks of a chart or an ENC."
+  },
+  "fact:following_traffic_lane": {
+   "cite": "10(i)",
+   "actuable": false,
+   "note": "Following a traffic lane of a scheme adopted by the Organization -- 10(i)'s and 10(j)'s protected vessel, read of whichever vessel it is asked of rather than assumed from `pair:env:traffic_lane`. Closes Q-34's 10(i)/10(j) half."
   }
  },
  "enums": {
-  "obstruction_side": {
+  "fact:obstruction_side": {
    "values": [
-    "port",
-    "starboard"
+    "obstruction_side:port",
+    "obstruction_side:starboard"
    ],
    "cite": "27(d)(i)",
    "actuable": false
   }
  },
+ "derived": {
+  "note": "Facts this package computes from the fact record rather than asking a consumer for. A derived fact carries `derived: true` and a decode table that *is* its definition, in the same style as `signalk_navigation_state` below: an ordered list of {when, value} rows read top to bottom, first match wins, and no row a match means the fact is absent. `when` is the ordinary predicate language of README.md 'Predicate semantics', so the decode is checkable by the same evaluator the entries use rather than by a second one. A consumer never supplies a derived fact and is never asked to; an evaluator computes it before matching.",
+  "fact:rule18_class": {
+   "type": "enum",
+   "derived": true,
+   "cite": "18",
+   "values": [
+    "rule18_class:nuc",
+    "rule18_class:ram",
+    "rule18_class:fishing",
+    "rule18_class:wig",
+    "rule18_class:cbd",
+    "rule18_class:sail",
+    "rule18_class:power"
+   ],
+   "cites": {
+    "rule18_class:nuc": "3(f)",
+    "rule18_class:ram": "3(g)",
+    "rule18_class:fishing": "3(d)",
+    "rule18_class:wig": "3(m)",
+    "rule18_class:cbd": "3(h)",
+    "rule18_class:sail": "3(c)",
+    "rule18_class:power": "3(b)"
+   },
+   "actuable": false,
+   "signalk": null,
+   "note": "A vessel's rank under Rule 18, which is not the same thing as the lights she shows. `fact:activity` is a *display* axis -- it answers what a vessel exhibits -- and Rule 18 ranks vessels by the Rule 3 terms of art instead, which cut across it: mine clearance (27(f)) and diving (27(e)) are restricted in their ability to manoeuvre by 3(g), trawling is fishing by 3(d), and a towing operation is RAM by 27(c) only when it severely restricts the pair. Before this fact each precedence entry re-listed those correspondences by hand and had to be edited every time the activity axis gained a value, with no test behind the omission. This is Q-32's answer: the rank is a derived fact, decoded once here, and a precedence entry reads the rank. `fact:activity` is unchanged and no entry that reads it was touched.",
+   "decode": [
+    {
+     "when": {
+      "fact:activity": "activity:nuc"
+     },
+     "value": "rule18_class:nuc",
+     "cite": "3(f)"
+    },
+    {
+     "when": {
+      "fact:activity": [
+       "activity:ram",
+       "activity:mine",
+       "activity:diving"
+      ]
+     },
+     "value": "rule18_class:ram",
+     "cite": "3(g)",
+     "note": "A bare list, which it could not be until the refinement bug was fixed: the ram -> ram_underwater refinement used to fire on a scalar constraint only, so a list would have silently missed `activity:ram_underwater` and `any_of` was written here to route each disjunct through the scalar path. The refinement is now a property of the fact's value and applies to equality, list membership and `any_of` alike, so the list says what it means. Mine clearance and diving are here because 3(g) enumerates them as restricted in their ability to manoeuvre while 27(e)/(f) give them their own lights -- the exact display/rank divergence this fact exists for."
+    },
+    {
+     "when": {
+      "fact:activity": {
+       "any_of": [
+        "activity:towing",
+        "activity:being_towed"
+       ]
+      },
+      "fact:tow_restricts_deviation": true
+     },
+     "value": "rule18_class:ram",
+     "cite": "27(c)",
+     "note": "The case Q-32 recorded as uncaught. 3(g)(vi) names \"the towing vessel and her tow\" together, so both sides of a severely-restricted tow rank as RAM here -- each from her own fact record, since a consumer supplies `fact:tow_restricts_deviation` per vessel and this decode never looks at the other subject. `any_of` for the same reason as the row above: a bare list would still work today, but a scalar disjunct keeps this open to a future refinement the way 3(g)'s row is. A tow that does not severely restrict the pair falls through to her propulsion, which is right: most tows are ordinary power-driven vessels under Rule 18."
+    },
+    {
+     "when": {
+      "fact:activity": [
+       "activity:fishing",
+       "activity:trawling"
+      ]
+     },
+     "value": "rule18_class:fishing",
+     "cite": "3(d)",
+     "note": "Ranked by activity and not by propulsion: 18(c) does not distinguish, so a fishing vessel under sail is fishing here and not sail."
+    },
+    {
+     "when": {
+      "fact:wig": true,
+      "fact:wig_near_surface": true
+     },
+     "value": "rule18_class:wig",
+     "cite": "3(m)",
+     "note": "18(f)(i) is scoped to the phase, not to being a WIG craft. A WIG on the water surface falls through to `rule18_class:power`, which is 18(f)(ii) -- recorded in known_omissions as a decode-table statement rather than a precedence norm, and this is that table."
+    },
+    {
+     "when": {
+      "fact:activity": "activity:cbd"
+     },
+     "value": "rule18_class:cbd",
+     "cite": "3(h)",
+     "note": "3(h) makes a vessel constrained by her draught a power-driven vessel, so `rule18_class:cbd` is a refinement of `rule18_class:power` and not a peer of it. Rule 18 does not rank her above anyone: 18(d) protects her, and 18(a) still obliges her, which is why the 18(a) entries gate on `fact:propulsion` rather than on this class."
+    },
+    {
+     "when": {
+      "fact:propulsion": "propulsion:sail"
+     },
+     "value": "rule18_class:sail",
+     "cite": "3(c)"
+    },
+    {
+     "when": {
+      "fact:propulsion": "propulsion:power"
+     },
+     "value": "rule18_class:power",
+     "cite": "3(b)"
+    }
+   ],
+   "undecodable": [
+    {
+     "case": "fact:propulsion = propulsion:oars, with no ranking activity",
+     "why": "Rule 3 has no term for a vessel under oars and Rule 18 does not rank her. 25(d)(ii) lets her show a sailing vessel's lights, which is a permission about lights and not a statement about rank, so decoding her to `rule18_class:sail` would put a display fact back into the rank this fact exists to separate from display. She decodes to nothing, and a predicate reading the class never matches her -- conservative, and visible here rather than silent."
+    },
+    {
+     "case": "a seaplane (3(e))",
+     "why": "The eighth term Rule 18 distinguishes, and the one value this fact does not carry: 18(e) needs a fact for being a seaplane and none exists, which known_omissions already records. A value with no row and no fact behind it would be a promise the data cannot keep, so it is absent rather than unreachable."
+    },
+    {
+     "case": "a fact record with no fact:propulsion",
+     "why": "Absent is absent. No row matches, the derived fact is absent, and every constraint over it is unsatisfied -- including a negated one."
+    }
+   ]
+  }
+ },
  "actuable_subset": {
-  "note": "What a switching consumer needs and can get: the three axes (decodable from navigation.state), making_way, and length_m. Everything else is education-side.",
+  "note": "What a switching consumer needs: the three axes (decodable from navigation.state), making_way, on_mooring_buoy, and length_m. Decodability is not the test -- making_way and on_mooring_buoy change which lights must burn and the helm knows both, so a consumer must ask. Everything else is education-side.",
   "fields": [
-   "propulsion",
-   "activity",
-   "position",
-   "making_way",
-   "length_m"
+   "fact:propulsion",
+   "fact:activity",
+   "fact:position",
+   "fact:making_way",
+   "fact:on_mooring_buoy",
+   "fact:length_m"
   ]
  },
  "signalk_navigation_state": {
@@ -170,108 +312,108 @@
   "verified": "2026-08-29",
   "decode": {
    "not under command": {
-    "activity": "nuc",
-    "position": "underway"
+    "fact:activity": "activity:nuc",
+    "fact:position": "position:underway"
    },
    "anchored": {
-    "activity": "none",
-    "position": "anchored"
+    "fact:activity": "activity:none",
+    "fact:position": "position:anchored"
    },
    "moored": {
-    "activity": "none",
-    "position": "moored"
+    "fact:activity": "activity:none",
+    "fact:position": "position:moored"
    },
    "sailing": {
-    "propulsion": "sail",
-    "activity": "none",
-    "position": "underway"
+    "fact:propulsion": "propulsion:sail",
+    "fact:activity": "activity:none",
+    "fact:position": "position:underway"
    },
    "motoring": {
-    "propulsion": "power",
-    "activity": "none",
-    "position": "underway"
+    "fact:propulsion": "propulsion:power",
+    "fact:activity": "activity:none",
+    "fact:position": "position:underway"
    },
    "towing < 200m": {
-    "propulsion": "power",
-    "activity": "towing",
-    "position": "underway",
-    "tow_length_m": {
+    "fact:propulsion": "propulsion:power",
+    "fact:activity": "activity:towing",
+    "fact:position": "position:underway",
+    "fact:tow_length_m": {
      "lte": 200
     }
    },
    "towing > 200m": {
-    "propulsion": "power",
-    "activity": "towing",
-    "position": "underway",
-    "tow_length_m": {
+    "fact:propulsion": "propulsion:power",
+    "fact:activity": "activity:towing",
+    "fact:position": "position:underway",
+    "fact:tow_length_m": {
      "gt": 200
     }
    },
    "pushing": {
-    "propulsion": "power",
-    "activity": "pushing",
-    "position": "underway"
+    "fact:propulsion": "propulsion:power",
+    "fact:activity": "activity:pushing",
+    "fact:position": "position:underway"
    },
    "fishing": {
-    "activity": "fishing",
-    "position": "underway"
+    "fact:activity": "activity:fishing",
+    "fact:position": "position:underway"
    },
    "fishing-hampered": {
-    "activity": "fishing",
-    "position": "underway",
+    "fact:activity": "activity:fishing",
+    "fact:position": "position:underway",
     "annex_ii_signal": "purse_seine_hampered"
    },
    "trawling": {
-    "activity": "trawling",
-    "position": "underway"
+    "fact:activity": "activity:trawling",
+    "fact:position": "position:underway"
    },
    "trawling-shooting": {
-    "activity": "trawling",
-    "position": "underway",
+    "fact:activity": "activity:trawling",
+    "fact:position": "position:underway",
     "annex_ii_signal": "shooting"
    },
    "trawling-hauling": {
-    "activity": "trawling",
-    "position": "underway",
+    "fact:activity": "activity:trawling",
+    "fact:position": "position:underway",
     "annex_ii_signal": "hauling"
    },
    "pilotage": {
-    "activity": "pilot"
+    "fact:activity": "activity:pilot"
    },
    "not-under-way": {},
    "aground": {
-    "activity": "none",
-    "position": "aground"
+    "fact:activity": "activity:none",
+    "fact:position": "position:aground"
    },
    "restricted manouverability": {
-    "activity": "ram"
+    "fact:activity": "activity:ram"
    },
    "restricted manouverability towing < 200m": {
-    "propulsion": "power",
-    "activity": "ram",
-    "also_activity": "towing",
-    "tow_length_m": {
+    "fact:propulsion": "propulsion:power",
+    "fact:activity": "activity:ram",
+    "also_activity": "activity:towing",
+    "fact:tow_length_m": {
      "lte": 200
     }
    },
    "restricted manouverability towing > 200m": {
-    "propulsion": "power",
-    "activity": "ram",
-    "also_activity": "towing",
-    "tow_length_m": {
+    "fact:propulsion": "propulsion:power",
+    "fact:activity": "activity:ram",
+    "also_activity": "activity:towing",
+    "fact:tow_length_m": {
      "gt": 200
     }
    },
    "restricted manouverability underwater operations": {
-    "activity": "ram_underwater"
+    "fact:activity": "activity:ram_underwater"
    },
    "constrained by draft": {
-    "propulsion": "power",
-    "activity": "cbd",
-    "position": "underway"
+    "fact:propulsion": "propulsion:power",
+    "fact:activity": "activity:cbd",
+    "fact:position": "position:underway"
    },
    "mine clearance": {
-    "activity": "mine"
+    "fact:activity": "activity:mine"
    }
   },
   "undecodable": [
@@ -284,6 +426,11 @@
    "not defined (example)"
   ],
   "lossy": [
+   {
+    "what": "made fast to a mooring buoy vs. made fast to the shore",
+    "why": "'moored' covers both and no SignalK path distinguishes them, so fact:on_mooring_buoy cannot be derived from navigation.state and must be asked of the consumer. Under us/inland it decides whether the 30(a)/(b) anchor lights are required.",
+    "cite": "3(i)"
+   },
    {
     "what": "fishing or trawling at anchor",
     "why": "Rule 26(a) applies 'whether underway or at anchor', but 'fishing' and 'anchored' are mutually exclusive values of one flat enum, so the pair cannot be stated.",
@@ -310,5 +457,301 @@
     "cite": "24(e), 27(e)"
    }
   ]
+ },
+ "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.",
+  "status": "pencil",
+  "adr": "0005",
+  "requirements": [
+   "REQ-CAT-4",
+   "REQ-CAT-6"
+  ],
+  "pencil": "Everything in this section is pencil (docs/conventions.md): ADR 0005 puts the whole shape there and v0.x allows the break. Settled by the first two-subject entry -- Rule 18 -- actually being written against it.",
+  "namespace": {
+   "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",
+    "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.",
+    "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."
+  },
+  "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.",
+   "kin:position": {
+    "type": "position",
+    "unit": "deg",
+    "cite": "7(b)",
+    "cite_pending": null,
+    "note": "WGS84 latitude/longitude as {\"latitude\": <deg>, \"longitude\": <deg>}. Range and bearing are derived from the pair of positions; a predicate never reads a position directly. Rule 7(b)'s \"radar plotting or equivalent systematic observation of detected objects\" is the tracking of positions this fact supplies.",
+    "actuable": true,
+    "signalk": "navigation.position.value"
+   },
+   "kin:heading_deg": {
+    "type": "number",
+    "unit": "deg",
+    "cite": "13(b)",
+    "cite_pending": null,
+    "note": "True heading, 0-360, clockwise from true north. Heading, not course over ground: Rule 13(b)'s overtaking sector and Rule 14's 'reciprocal or nearly reciprocal courses' are both about where the vessel is pointing. SignalK publishes radians.",
+    "actuable": true,
+    "signalk": "navigation.headingTrue.value"
+   },
+   "kin:sog_kn": {
+    "type": "number",
+    "unit": "kn",
+    "cite": "6",
+    "cite_pending": null,
+    "note": "Speed over ground. Cited to Rule 6 ('every vessel shall at all times proceed at a safe speed'), not the originally-pending 13(a): 13(a) only states the overtaking vessel's duty and never mentions speed, and 13(b)'s overtaking test turns on relative bearing alone ('more than 22.5 degrees abaft her beam'), not on a speed comparison. Rule 6 is the paragraph that actually reads speed.",
+    "actuable": true,
+    "signalk": "navigation.speedOverGround.value"
+   },
+   "kin:rot_deg_min": {
+    "type": "number",
+    "unit": "deg/min",
+    "cite": "8(b)",
+    "cite_pending": null,
+    "note": "Rate of turn, positive to starboard. Read by a `conduct` monitor rather than by a predicate at a point: Rule 8(b)'s 'readily apparent' alteration is a property of a trace.",
+    "actuable": true,
+    "signalk": "navigation.rateOfTurn.value"
+   },
+   "kin:dynamics": {
+    "type": "enum",
+    "values": [
+     "dynamics:tanker",
+     "dynamics:cargo",
+     "dynamics:ferry",
+     "dynamics:fishing",
+     "dynamics:yacht",
+     "dynamics:rib",
+     "dynamics:unknown"
+    ],
+    "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.",
+    "actuable": false,
+    "signalk": null
+   },
+   "kin:wind_side": {
+    "type": "enum",
+    "values": [
+     "wind_side:port",
+     "wind_side:starboard",
+     "wind_side:unknown"
+    ],
+    "cite": "12(b)",
+    "cite_pending": null,
+    "note": "Which side this vessel has the wind on, which 12(b) defines as the side opposite that on which the mainsail is carried, or for a square-rigged vessel the side opposite the largest fore-and-aft sail. `wind_side:unknown` is not a missing value: it is 12(a)(iii)'s case, a vessel with the wind on the port side who cannot determine with certainty which side the other has it on, and entry 12a3 reads it. An absent fact would be silence, and silence satisfies nothing. Declared in `kin` rather than in the fact record because a display consumer never supplies it and the fact record does not change for Part B (REQ-CAT-4) -- but it is a sailing state and not kinematics, which is recorded as strain in Q-44 rather than fixed by widening the class.",
+    "actuable": false,
+    "signalk": null
+   }
+  },
+  "geometry": {
+   "note": "Relative geometry. Directional facts are stated once per subject and mean 'measured from this subject'; symmetric facts are stated once, under `pair`. All of these are computable from the two kinematic states, and are declared as facts anyway because a consumer that has them from radar or ARPA should not be forced to round-trip through positions it does not trust.",
+   "directional": {
+    "geo:rel_bearing_deg": {
+     "type": "number",
+     "unit": "deg",
+     "cite": "13(b)",
+     "cite_pending": null,
+     "note": "Bearing of the *other* subject, 0-360 clockwise from this subject's own heading. Under `own` this is relative bearing; under `other` it is aspect. Rule 13(b)'s overtaking sector is `other:geo:rel_bearing_deg` in (112.5, 247.5) -- own is more than 22.5 degrees abaft the other vessel's beam. The two sector edges are declared once in `constants` below (`overtaking_sector_from_deg`, `overtaking_sector_to_deg`) and entries 13b-overtaking, 13b-overtaken and 15a-crossing all read them, so the sector and its complement cannot drift apart.",
+     "actuable": false,
+     "signalk": null
+    },
+    "geo:windward": {
+     "type": "boolean",
+     "cite": "12(a)(ii)",
+     "cite_pending": null,
+     "note": "This subject is to windward of the other. Directional and antisymmetric: where it is true for one subject it is false for the other. Computable from the wind direction and the two positions; declared as a fact for the same reason `geo:rel_bearing_deg` is, because a consumer who has it should not be made to round-trip through a wind vector this package does not carry.",
+     "actuable": false,
+     "signalk": null
+    }
+   },
+   "symmetric": {
+    "geo:range_m": {
+     "type": "number",
+     "unit": "m",
+     "cite": "7(a)",
+     "cite_pending": null,
+     "note": "Distance between the two vessels. Symmetric by construction. Rule 7(a)'s 'all available means... to determine if risk of collision exists' is the duty this and the other derived-geometry facts (`geo:cpa_m`, `geo:tcpa_s`) exist to serve.",
+     "actuable": false,
+     "signalk": null
+    },
+    "geo:bearing_change_deg_min": {
+     "type": "number",
+     "unit": "deg/min",
+     "cite": "7(d)(i)",
+     "cite_pending": null,
+     "note": "Rate of change of the compass bearing between the two vessels, signed. Rule 7(d)(i): a bearing that does not appreciably change means risk of collision exists. The Rules do not say what appreciably means; `constants.appreciable_bearing_change_deg_min` fixes it in pencil and entry 7d1 is the only reader.",
+     "actuable": false,
+     "signalk": null
+    },
+    "geo:cpa_m": {
+     "type": "number",
+     "unit": "m",
+     "cite": "7(a)",
+     "cite_pending": null,
+     "note": "Closest point of approach on present courses and speeds. Derived, and declared so a consumer with an ARPA solution can supply it directly. See `geo:range_m` for why Rule 7(a) is the cite.",
+     "actuable": false,
+     "signalk": null
+    },
+    "geo:tcpa_s": {
+     "type": "number",
+     "unit": "s",
+     "cite": "7(a)",
+     "cite_pending": null,
+     "note": "Time to closest point of approach on present courses and speeds. Negative once the CPA is past. See `geo:range_m` for why Rule 7(a) is the cite.",
+     "actuable": false,
+     "signalk": null
+    },
+    "geo:in_sight": {
+     "type": "boolean",
+     "cite": "3(k)",
+     "cite_pending": null,
+     "note": "Rule 3(k): vessels are deemed to be in sight of one another only when one can be observed visually from the other. Symmetric because the rule defines it that way, not because visibility is. This is the `scope` gate that selects Section II over Section III, and it is a fact of the pair, never of one vessel.",
+     "actuable": false,
+     "signalk": null
+    },
+    "geo:risk_of_collision": {
+     "type": "boolean",
+     "cite": "7(a)",
+     "cite_pending": null,
+     "note": "Risk of collision exists between the two vessels. Rule 7 is the whole apparatus for determining it and Rule 7(a) makes it a judgement on all available means, so this is supplied by the consumer rather than derived here from a bearing-change threshold this package declines to fix. Read by 8(f)(iii), and by every Section II conduct rule when those land.",
+     "actuable": false,
+     "signalk": null
+    }
+   },
+   "consistency": {
+    "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.",
+     "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."
+    },
+    "tolerances": {
+     "bearing_deg": 1.0,
+     "range_m": 15,
+     "range_fraction": 0.01,
+     "cpa_m": 10,
+     "cpa_fraction": 0.05,
+     "tcpa_s": 5,
+     "tcpa_fraction": 0.05,
+     "bearing_change_deg_min": 0.1
+    },
+    "tolerance_note": "A position stated to five decimal places is about a metre; to four, about ten. The absolute floors are for close ranges, where a fraction of the range is smaller than the position is stated to; the fractions are for long ranges, where the floor is tighter than a bearing rounded to a tenth of a degree. A stated quantity is compared to the computed one within the larger of the two.",
+    "settled_by": "Whether the relative quantities become derived facts computed from the two kinematic states -- in which case these equations become the decode and the check goes with them -- or stay supplied and checked, for the consumer with an ARPA solution and no positions it trusts. Q-48 names both; this block is the second, done."
+   }
+  },
+  "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.",
+   "hist:was_overtaking": {
+    "type": "boolean",
+    "cite": "13(d)",
+    "cite_pending": null,
+    "note": "This subject was, at some earlier point in this encounter, an overtaking vessel with respect to the other. Rule 13(d): any subsequent alteration of the bearing shall not make the overtaking vessel a crossing vessel, nor relieve her of the duty of keeping clear until finally past and clear. Without this fact the geometry alone reclassifies an overtaking as a crossing and hands the duty to the wrong vessel -- which is the exact error the paragraph exists to forbid.",
+    "actuable": false,
+    "signalk": null
+   },
+   "hist:latched_at_s": {
+    "type": "number",
+    "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.",
+    "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.",
+   "shape": {
+    "own": {
+     "fact": "<the fact record above>",
+     "kin": "<kinematics>",
+     "geo": "<directional geometry>",
+     "hist": "<history>"
+    },
+    "other": {
+     "fact": "<the fact record above>",
+     "kin": "<kinematics>",
+     "geo": "<directional geometry>",
+     "hist": "<history>"
+    },
+    "pair": {
+     "geo": "<symmetric geometry>",
+     "env": "<environment>"
+    }
+   }
+  },
+  "environment": {
+   "note": "Where the encounter is happening. `pair` only, and symmetric by construction: both vessels are in the same channel or the same scheme. Declared because Rules 9 and 10 are scoped to places, and a place is neither a vessel's fact nor the pair's geometry. These are booleans a consumer sets from a chart or an ENC; nothing here derives them from a position.",
+   "env:narrow_channel": {
+    "type": "boolean",
+    "cite": "9(a)",
+    "cite_pending": null,
+    "note": "The encounter is in or near a narrow channel or fairway. Does not say which vessel can safely navigate only within it -- that further fact is `fact:confined_to_channel`, read per vessel (Q-34).",
+    "actuable": false,
+    "signalk": null
+   },
+   "env:traffic_lane": {
+    "type": "boolean",
+    "cite": "10(a)",
+    "cite_pending": null,
+    "note": "The encounter is within a traffic separation scheme adopted by the Organization. Does not say which vessel is following a lane -- that further fact is `fact:following_traffic_lane`, read per vessel (Q-34).",
+    "actuable": false,
+    "signalk": null
+   }
+  },
+  "constants": {
+   "note": "Numeric constants a Part B predicate needs and the Rules do not always state. Each names the fact it thresholds, its status under docs/conventions.md, and -- where it is pencil -- what would settle it. They are declared here rather than written inline in an entry so that the number appears once and a test can assert every entry uses it; they are not identifiers (docs/identifiers.md, 'What is not an identifier'), they are values like a modality or a jurisdiction.",
+   "appreciable_bearing_change_deg_min": {
+    "value": 1.0,
+    "unit": "deg/min",
+    "fact": "pair:geo:bearing_change_deg_min",
+    "status": "pencil",
+    "cite": null,
+    "cite_pending": "7(d)(i)",
+    "note": "Rule 7(d)(i) deems risk of collision to exist if the compass bearing of an approaching vessel 'does not appreciably change', and nowhere says what appreciably means. Read as a magnitude: entry 7d1 gates on the open interval (-1.0, 1.0) so a bearing drawing out either way is treated alike, because the paragraph asks whether the bearing changes and not which way.",
+    "settled_by": "A source that fixes the figure -- Cockcroft & Lameijer, or an administration's guidance -- or a sensitivity sweep in colregs-engine showing which values change a region finding. Until then it is one session's number and any session may change it."
+   },
+   "head_on_half_angle_deg": {
+    "value": 11.25,
+    "unit": "deg",
+    "fact": "own:geo:rel_bearing_deg and other:geo:rel_bearing_deg",
+    "status": "pencil",
+    "cite": null,
+    "cite_pending": "14(b)",
+    "note": "Half the head-on cone: 14(a)'s 'reciprocal or nearly reciprocal courses' and 14(b)'s 'ahead or nearly ahead'. 11.25 degrees is one point of the compass, which is the angular unit the Rules themselves use -- 13(b)'s 22.5 degrees is two points -- so the sub-unit is drawn from the same vocabulary rather than invented. Both vessels must be inside it: 14(b) is a statement about aspect as well as bearing.",
+    "settled_by": "The same sweep as above. The usual published figures are 5 or 6 degrees, so this constant is deliberately the wider of the candidates: 14(c) says a vessel in doubt shall assume a head-on situation exists, and a wider cone is the reading that errs the way the paragraph errs."
+   },
+   "overtaking_sector_from_deg": {
+    "value": 112.5,
+    "unit": "deg",
+    "fact": "geo:rel_bearing_deg",
+    "status": "ink",
+    "cite": "13(b)",
+    "cite_pending": null,
+    "note": "22.5 degrees abaft the beam, stated in 13(b) itself, and the forward edge of the sternlight arc of Rule 21(c). Ink because the number is in the rule text, not because anyone is confident about it."
+   },
+   "overtaking_sector_to_deg": {
+    "value": 247.5,
+    "unit": "deg",
+    "fact": "geo:rel_bearing_deg",
+    "status": "ink",
+    "cite": "13(b)",
+    "cite_pending": null,
+    "note": "The mirror of the above: 360 - 112.5. The sector is open at both ends -- 13(b) says 'more than 22.5 degrees abaft her beam', so a vessel exactly on the edge is not overtaking."
+   }
+  }
  }
 }