colregs 0.3.1 → 0.3.3

package/docs/adr/0018-jurisdiction-delta-is-a-merge-patch.md

@@ -0,0 +1,102 @@
+# ADR 0018 — A jurisdiction delta is an RFC 7396 merge patch, and a tombstone is its `null`
+
+Date: 2026-09-16
+Status: proposed — merging this PR is the ruling; a revert undoes it
+
+## Context
+
+REQ-SCOPE-3 says a jurisdiction is a delta over `intl`: entries it does not
+mention are inherited. Q-11 found that unsafe as stated. 33 CFR 83 leaves
+Rule 28 "[Reserved]" and has no counterpart to 23(d)(ii), so a `us/inland`
+delta that was merely silent there would inherit `rule:28` and assert an
+international obligation the Inland Rules deliberately do not carry. Both
+absences are verified against the primary source (Cornell LII's copy of
+33 CFR 83: "§ 83.28 [Reserved] (Rule 28)"; 83.23(d) is a single paragraph
+with no subparagraphs). Q-11 asked for tombstones — "this entry deliberately
+does not exist here", distinguishable from "not yet transcribed" — and held
+every non-`intl` jurisdiction until the mechanism existed. Issue #45 asked,
+separately, which standard encoding the delta should follow.
+
+Both questions have been waiting on a second jurisdiction to force them.
+Issue #137 records that nothing was proposing one. `us/inland` already exists
+with two add-only entries under ADR 0008's carve-out, and the two absences
+above are the counterexample that carve-out was left open for: a delta that
+must suppress, not only add.
+
+## Decision
+
+1. **The delta semantics are RFC 7396, JSON Merge Patch.** A jurisdiction's
+   delta over `intl` is, in meaning, a merge-patch document keyed by entry
+   id: present keys are that jurisdiction's own entries, `null` keys are its
+   tombstones, and every key the patch does not mention is inherited. Any
+   conformant merge-patch implementation applied to the `intl` entries by
+   id reproduces the jurisdiction's resolved rule set. RFC 6902 is not
+   adopted: an operation script with JSON Pointer paths would duplicate the
+   id addressing `docs/identifiers.md` already provides.
+
+2. **Storage stays columnar; the patch is derived.** Entries keep their
+   `jurisdiction` field in the one `entries[]` table, as ADR 0008 laid them
+   down. Tombstones are a second top-level table, `suppressions[]`, one
+   record per (jurisdiction, entry): `jurisdiction`, `suppresses` (the
+   `intl` entry id), `cite` (the paragraph that has no counterpart) and
+   `why` (one sentence and the source). `test/data.test.mjs` builds the
+   merge patch from those two tables, applies it with a literal RFC 7396
+   implementation, and asserts the result equals the evaluator's
+   jurisdiction filter. That test is the statement that storage and
+   semantics agree; if they ever diverge, the test names which.
+
+3. **Replace is suppress plus add.** A jurisdiction that reads a paragraph
+   differently tombstones the `intl` entry and adds its own, under its own
+   id (ADR 0015 — the ids are distinct because the norms are). There is no
+   third operation and no in-place edit of an `intl` entry: REQ-SCOPE-4
+   holds.
+
+4. **The array caveat is accepted and irrelevant here.** Merge Patch
+   replaces an array wholesale. The patch is keyed at entry granularity, so
+   the only arrays it ever touches are inside a whole entry being added, and
+   an entry is small. A jurisdiction never patches one element of an
+   inherited entry's `lights`; it replaces the entry (point 3).
+
+5. **Only an inherited entry can be tombstoned.** A tombstone naming a
+   jurisdiction's own entry, or another jurisdiction's, is rejected by test:
+   the first is a deletion, the second was never in force.
+
+6. **A tombstone is verified the way an entry is.** Each needs one fixture
+   under its jurisdiction whose facts match the suppressed entry's predicate
+   and whose expectation omits it, and one `intl` fixture showing the entry
+   in force at the base (REQ-VERIFY-3, both sides).
+
+7. **Two tombstones land with this ADR**, both verified: `us/inland`
+   suppresses `rule:28` (Rule 28 "[Reserved]") and `rule:23d_ii` (no
+   counterpart to the under-7 m, 7 kn exception). They are enough to
+   exercise inherit and delete; no verified replace case exists in Part C
+   yet, so that branch of point 3 is stated, schema-ready and unexercised.
+
+## Consequences
+
+- **Q-11 is answered and its hold is lifted.** REQ-SCOPE-3's "no non-`intl`
+  jurisdiction lands before an explicit suppression mechanism exists" is
+  discharged by this mechanism; a jurisdiction lands with its tombstones or
+  it does not land. ADR 0008's add-only carve-out survives as the trivial
+  case: a delta with no tombstones is a merge patch with no `null`s.
+- **Issue #45 is closed by this ADR.** README names the RFC beside the
+  jurisdiction paragraph so a consumer knows which library semantics
+  reproduce the inheritance.
+- **A suppressed entry can leave a record out of vocabulary.** Under
+  `us/inland` a record carrying `activity:cbd` now selects nothing:
+  `rule:28` is gone and the Rule 23(a) entries it imported read
+  `activity:none`. That is the honest answer — "constrained by her draft" is
+  not an Inland status — and the package does not pick a reading. It is
+  recorded in `known_omissions` and pinned by a fixture. Whether the fact
+  vocabulary should carry per-jurisdiction membership so a consumer's
+  decode can be checked is a new question, not decided here.
+- **`rule:23d_i` cites a path Inland does not spell.** 33 CFR 83.23(d) has
+  no `(i)`; the content sits at bare `83.23(d)`. The entry is inherited
+  correctly — the norm is the same — and the citation-spelling question is
+  GATE-1's, untouched here.
+- **GATE-1, Q-10 and Q-8 are not taken.** Q-11 named a "second-jurisdiction
+  bundle"; this ADR takes only the item that gated data. The others stay
+  open on their own triggers.
+- **Cost to reverse.** Delete `suppressions[]` from data, schema and the
+  three tests; the two fixtures fail and are deleted with them. No consumer
+  reads the table yet. Pre-1.0, a revert.

package/docs/adr/0019-relation-reach-and-import-reads.md

@@ -0,0 +1,106 @@
+# ADR 0019 — What a relation reaches, and what an import reads
+
+Date: 2026-09-16
+Status: proposed — merging this PR is the ruling; a revert undoes it
+
+## Context
+
+REQ-MODEL-7 and the README define the six relation verbs by meaning and
+leave composition to the consumer (REQ-CONS-3). colregs-engine#33 checked
+the seven composition decisions its evaluator makes where the data is
+silent. ADR 0007 settled the largest, direction: a directed "this one
+prevails" is `rel:overrides`, and `rel:excludes` is pick-one between
+alternatives. Three readings of the verbs remain stated only in
+colregs-engine's `docs/engine-notes.md` (items 2, 3 and 5) and pinned only
+by its tests: how far a relation reaches, what a `one_of` yields, and which
+part of a referenced entry's predicate an import consults. Each is a
+reading of the Rules, and the package that carries the Rules should say it.
+
+## Decision
+
+1. **Displacing relations reach entries in force; composing relations
+   reach what is exhibited.** An entry is *in force* when its own predicate
+   holds. `rel:overrides` and `rel:exempts` act on entries in force and on
+   nothing else: an import is not in force, it is a light set its carrier
+   exhibits, and the carrier is what a displacing relation must name.
+   `rel:in_lieu_of`, `rel:excludes`, `rel:includes` and
+   `rel:conditional_includes` act on what one display may contain, imports
+   included, and remove nothing from the set of entries in force. Direction
+   is carried by the verb, never by modality: an override fires from a
+   forceful entry (ADR 0007), an exemption from a `modality:exempt` one,
+   and `rel:excludes` fires from nowhere — it is symmetric and already
+   barred to forceful entries by CI (`test/data.test.mjs`, "rel:excludes is
+   reciprocated"). A consumer that infers a veto from an excluder's modality
+   is reading a relation the data does not carry.
+
+2. **A `one_of` yields exactly one option per display, or none when the
+   carrier is `modality:may`.** Under a `may` carrier the chosen option is
+   exhibited in lieu of the carrier's own lights, and the none choice
+   exhibits them (25(d)(ii): the sailing lights, or failing them the torch).
+   An option already in force by its own predicate discharges the set: the
+   carrier imports nothing, and the option composes as the entry it is. A
+   vessel restricted in her ability to manoeuvre at anchor shows 30(a) or
+   30(b) because 30(a) and 30(b) apply to her, not because 27(b)(iv)
+   redirects her to them. Every choice is returned (REQ-MODEL-8).
+
+3. **An import reads the referenced entry's lights, their modality, and
+   its scalar gates — never its axes.** An import is a `rel:includes`, the
+   `rel:includes` of a `rel:conditional_includes` branch, or a `one_of`
+   option. `facts.json`'s `axes` and `modifiers` are the field: a key
+   declared there is the vessel's situation, and the carrier's redirect has
+   already placed her in it — 30(d) sends a vessel aground to "the lights
+   prescribed in paragraph (a) or (b)", and that she is not at anchor is the
+   premise of the redirect, not a gate on it. A key not declared there is a
+   fact the redirect does not alter, and the referenced entry's condition
+   on it binds: 30(b)'s "less than 50 metres" binds a vessel aground as it
+   binds one at anchor, and 25(b)'s "less than 20 metres" binds a vessel
+   under oars. Modality is the referenced entry's, resolved against the
+   vessel (Rule 28's three reds are `may`; the Rule 23 lights it imports
+   stay `shall`). A gate the carrier needs that the source does not carry is
+   written on the carrier's branch `when`, as 27(f) and 29(a) do; nothing
+   is inferred from a source's axes in either direction. REQ-MODEL-7's
+   "lights only, never its predicate" is amended to say this.
+
+4. **Two entries in force whose `rel:in_lieu_of` targets intersect are
+   alternatives to each other** and never share a display. This is an
+   invariant of the verb, not a declared pair list. The two pairs the data
+   can hold in force together read that way in the text: 23(d)(ii)'s
+   display is 23(d)(i)'s with the sidelights made practicable-only, and
+   25(d)(i)'s torch is what a vessel shows *if she does not* exhibit (a) or
+   (b). The Rule 24 entries that share targets — 24(a)(i) below and above
+   200 m, and 24(c) — are disjoint on their own predicates and never meet.
+   A future pair that lawfully combines is the evidence to reopen this
+   point; until one exists, the target sets are the declaration.
+
+Three shapes were considered and not adopted. Restating each option's
+scalar gate on the carrier's branch (30(d) split at 50 m) keeps "lights
+only" literal at the cost of transcribing 30(b)'s condition into 27(b)(iv),
+27(f), 29(a) and 30(d), and 25(b)'s into 25(d)(ii), plus a CI check to
+police the copies; the text redirects, it does not restate, and REQ-MODEL-5
+puts a gate where its fact lives. Declaring the point-4 pairs as a relation
+duplicates what the target sets say. A per-verb "reaches imports" flag
+would be set the same way on every entry, and a field nothing varies is
+decoration.
+
+## Consequences
+
+- **No data changes.** The README relation table, REQ-MODEL-7 and the
+  `relations` notes in `data/applicability.json` say the four points in
+  this PR. `docs/identifiers.md` and the schema are untouched.
+- **colregs-engine implements this in one issue, three deletions.** Its
+  modality-inferred exclusion path goes: `rel:excludes` is a co-occurrence
+  check on a display and nothing more. Its `includeApplies` goes: it
+  consulted one axis by name on `rel:includes` imports, the inverse of
+  point 3, and no import in the data reaches it on a coherent record —
+  every carrier either shares the source's position gate (23(b), 23(c),
+  25(c), 28), gates its branch on it (24, 27(f), 29(a)), or reads
+  `fact:making_way`, which refines `position:underway` (26(b)(iii),
+  26(c)(iii), 27(a)(iii), 27(b)(iii)). The availability test it already
+  applies to `one_of` options becomes the one rule for every import. Its
+  `docs/engine-notes.md` items 2–5 become pointers here. colregs-engine#33
+  items 1, 6 and 7 stay the engine's: presentation and output shape.
+- **A `one_of` option's scalar gate is a normative read of the source
+  entry.** Editing 30(b)'s length gate changes what a vessel aground may
+  show. That is the intended coupling: one paragraph, one gate.
+- **Cost to reverse.** Delete this file and restore two sentences; the
+  engine's deleted paths come back by revert. Pre-1.0, a revert.

package/docs/budgets.json

@@ -21,8 +21,13 @@
     "docs/adr/0013-corpus-files-with-editions.md": 95,
     "docs/adr/0014-engine-interface-owned-by-colregs.md": 110,
     "docs/adr/0015-rule-ids-are-paragraph-keys.md": 210,
+    "docs/adr/0016-encounter-roles-are-pooled-across-frames.md": 90,
+    "docs/adr/0017-closed-vocabularies-are-prefixed-identifiers.md": 120,
+    "docs/adr/0018-jurisdiction-delta-is-a-merge-patch.md": 120,
+    "docs/adr/0019-relation-reach-and-import-reads.md": 110,
     "docs/timeline.md": 130,
-    "docs/maritime-sources.md": 130
+    "docs/maritime-sources.md": 130,
+    "docs/decisions.md": 40
   },
   "json_prose": {
     "targets": [

package/docs/decisions.md

@@ -0,0 +1,8 @@
+# Decisions
+
+Rulings from `/sequence` sessions and other closed judgment calls. One line
+each: date, short name, the answer, a link to the argument.
+
+- 2026-09-16 — docs ownership: colregs-engine's docs are sited wrong; colregs owns docs going forward, no new doc lands in colregs-engine. `normative-language.md` was already migrated the same day (commit fe0f8c2, #125); migration of the remaining three (`formal-methods-glossary.md`, `formal-methods-reading-list.md`, `engine-notes.md`) is not yet scheduled. Argued on kanban; no public writeup to link.
+- 2026-09-16 — own vs self: rename the subject segment `own` to `self` across the situation record (fact keys, precedence effect keys, facts.json, fixtures, docs/identifiers.md). Work spawned as [colregs#138](https://github.com/mark-brannan/colregs/issues/138).
+- 2026-09-16 — Q-54, Rule 17's phases are monotone: once 17(a)(ii) permission or the 17(b) duty has arisen for the stand-on vessel, it does not fall back on belated give-way compliance. Argued in [colregs#72](https://github.com/mark-brannan/colregs/issues/72); recorded in `docs/requirements.md`.

package/docs/identifiers.md

@@ -24,6 +24,17 @@ but it is a name in a namespace and a consumer reads the paragraph out of
 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
 share one flat string space across five files, and before the prefix they
@@ -31,7 +42,11 @@ 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
 
@@ -42,6 +57,10 @@ resolves that collision by construction rather than by convention.
 | `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
@@ -72,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>
@@ -82,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
@@ -97,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
@@ -112,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.
@@ -125,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
@@ -153,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`.
 
@@ -162,14 +181,14 @@ is an enumerated fact, so its values follow the bare-fact-name rule above:
 Rule 13(d) is the reason history is a class and not a note. Once a vessel is
 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:
+hands the duty to the wrong vessel. So overtaking history 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
@@ -183,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
@@ -226,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.
@@ -242,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
@@ -280,18 +299,18 @@ 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.
 
@@ -299,7 +318,7 @@ separate them and does not pretend to.
 
 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 own's side,
+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
@@ -391,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
@@ -410,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.
@@ -419,6 +433,9 @@ implemented in the reference evaluator and asserted by the fixtures.
   words. It is deliberately not a light reference and does not resolve to
   one.
 
+Not being an identifier says nothing about whether a vocabulary gets a
+catalog label; see REQ-LANG-6.
+
 ## This does not reverse GATE-5
 
 GATE-5 declined a CI-enforced terminology glossary, permanently, for the