colregs 0.3.0 → 0.3.2

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) | ✎ | 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/0014-engine-interface-owned-by-colregs.md

@@ -0,0 +1,103 @@
+# ADR 0014 — The engine interface is colregs' to own: an operations manifest and result schemas
+
+Date: 2026-09-16
+Status: proposed. Solace ordered options 2 and 3 built on 2026-09-16; the
+register marks what settles each row.
+
+## Context
+
+ADR 0011 and ADR 0012 fix the engine's verbs and result envelopes, in prose
+and TypeScript blocks, in this repository. The only machine-readable copy
+lives in colregs-engine's `src/types.ts`, so the interface is de facto
+colregs-owned and de jure the engine's: a second engine, in any language,
+would transcribe the ADRs by hand and drift the way the engine's own
+generator was written to stop.
+
+colregs already owns *shapes* in production: the engine compiles every
+`schema/*.schema.json` into generated types and derives `FactRecord` and
+`Situation` from `data/facts.json`. What it does not own is the *operations*
+— which verb reads which input and answers which envelope — and the fixture
+files bind to verbs only by convention.
+
+Ten routes were surveyed on 2026-09-16 for making the interface a colregs
+artefact, the Java sense of interface against implementation:
+
+| # | route | what it gives, what it costs |
+|---|---|---|
+| 1 | result schemas only, verbs stay prose | shapes checkable, operations still hand-read |
+| 2 | **operations manifest**: verb → inputs → result → companion, in JSON | language-neutral; any engine derives its own binding |
+| 3 | **fixtures bound to verbs** in the manifest | the conformance replay becomes the behavioural contract |
+| 4 | hand-written `.d.ts` in colregs | TypeScript-only; the transcription the engine's generator exists to avoid |
+| 5 | `x-operation` keywords inside the existing schemas | option 2 spread over eleven files |
+| 6 | OpenAPI / AsyncAPI | a projection generable *from* 2, not a source |
+| 7 | Protobuf / Smithy | model operations natively; a toolchain a data-only package does not have |
+| 8 | TypeSpec | one source projecting JSON Schema and OpenAPI; same toolchain cost |
+| 9 | a separate `colregs-api` package | a third release train for two files |
+| 10 | status quo | the drift above |
+
+## Decision
+
+1. **`data/operations.json` is the interface.** One operation per verb ADR
+   0011 and ADR 0012 name, each with positional `inputs` (name and schema),
+   an `output` schema, the entry-id `companion` verb where one exists, and
+   the `fixtures` that exercise it. `schema/operations.schema.json` checks
+   its shape; `test/data.test.mjs` checks that every reference resolves.
+2. **Result envelopes are schemas under `schema/`:** `display-evaluation`,
+   `encounter-evaluation`, `conduct-evaluation`, `rule2-departure-finding`,
+   transcribed from the engine's `src/types.ts` at colregs-engine 0.1.5.
+   JSON-Schema-expressible only: `Record<EntryId, Modality>` becomes
+   `patternProperties`, the `EntryId` and `ParagraphCite` aliases become
+   `$defs`, the two deprecated camelCase aliases are marked `deprecated` and
+   optional. From here the schema is the normative statement of each
+   envelope; the TypeScript blocks in ADR 0011 §4 and ADR 0012 §2–4 are
+   illustrations of record, and an envelope changes here first, the engine
+   second.
+3. **Inputs get schemas too:** `fact-record`, `situation`, `trace`,
+   `rule2-departure-model`. The two fixture schemas `$ref` the first two
+   for a case's `facts` and `situation` instead of carrying a copy; a fixture
+   case is the verb's input, and the tests validate every bound case against
+   it.
+4. **Schema files compose by `$ref`,** relative to their `$id`
+   (`applicability.schema.json#/$defs/ruleId`). ADR 0006's "no cross-file
+   references" is about data references — cite to `rules.json` — which stay in
+   the tests; a `$ref` between two schema files is one shape reused, not a
+   data reference. The suite registers every schema by `$id` before compiling.
+   What every envelope shares — the `colregs` stamp, `provenance`, the
+   `ruleId` and `paragraphCite` vocabularies — is `schema/evaluation.schema.json`,
+   `$defs` only, so moving one later is never a two-repository change.
+5. **A fixture file is bound to a verb** by `fixtures[].file` and
+   `case_inputs`, one case key per positional input, with the answer under
+   `expect`: the companion's entry ids unless the binding names another
+   schema. A case's `status` and `jurisdiction` are the fixture file's own.
+   Every file under `fixtures/` must be bound; `evaluateConduct` and
+   `evaluateRule2Departure` bind nothing yet, and say so with an empty list.
+6. **Not in the manifest:** trailing options a binding accepts (`opts.data`),
+   which verbs are built, and what a verb throws. Build status is ADR 0011's
+   and ADR 0012's tables; errors are the binding's.
+
+## Consequences
+
+- Ten new files under `schema/`. The engine's `generate-schema-types.ts`
+  throws on any schema its `ROOT_NAMES` does not list, so the next colregs
+  bump fails its build until colregs-engine#86 lands: emit
+  `interface ColregsEngine` from `operations.json`, `satisfies ColregsEngine`
+  at the engine's root, settle the `fact-record.ts` / `situation.ts`
+  collision with the types it derives from `facts.json` today, and validate
+  real output against these schemas for every fixture case.
+- A YAML rendering of the manifest is lossless; XML is a generated view (JSON
+  Schema to XSD). Authoring the interface in TypeScript first is the one route
+  that forecloses both.
+- The 2026-09-16 hand-off named the finding's schema `rule2-departure`; it
+  lands as `rule2-departure-finding` beside `rule2-departure-model`, since
+  the verb has two shapes to name.
+
+## Register
+
+| item | level | what would settle it |
+|---|---|---|
+| Options 2 and 3, not 1 or 4–10 | ✎ | this ADR accepted |
+| Manifest shape: positional `inputs`, `output`, `companion`, `fixtures[].case_inputs` and `expect` | ✎ | the engine generator consuming it; the first conduct or Rule 2 fixture |
+| Envelope schemas transcribed from `types.ts`, envelope changes land here first | ✎ | the first envelope change after the follow-up |
+| Cross-file `$ref` between schema files | ✎ | a consumer whose validator cannot register a schema set |
+| Deprecated aliases optional in the schema, required in the engine | ✎ | the engine dropping them |
+| `opts` and thrown errors stay out of the manifest | ✎ | a second binding needing either |

package/docs/adr/0015-rule-ids-are-paragraph-keys.md

@@ -0,0 +1,191 @@
+# ADR 0015 — Rule ids are paragraph keys in the `rule:` namespace
+
+Date: 2026-09-16
+Status: accepted — Solace's ruling, 2026-09-16
+
+## Context
+
+Issue #121 asked what an applicability entry should be called, and ruling C
+was read as *names, not citations*. The first draft of this ADR wrote that
+reading out: every id became a coined name in an `entry:` namespace —
+`entry:anchored`, `entry:towing_mastheads_long_tow`, `entry:being_overtaken`.
+It never landed and never shipped. Solace superseded that reading on
+2026-09-16 and this file is the replacement.
+
+What the rename was buying was insulation: `cite` is a data field, revised
+whenever the package reads the Rules better, and `14a` had already become
+`14b` when the reading of *which paragraph deems a head-on* moved. An
+identifier containing a data field gets renamed every time the field is.
+
+What it cost is the vocabulary. An entry is a norm out of the Convention,
+and the people who read these ids — and the consumers that store them
+alongside a `cite` anyway — already have a name for every norm in the
+package: the Rule. `rule:13b` is *Rule 13(b)* in the mariner's mouth. A
+coined name is a second vocabulary beside that one, invented here,
+unguessable from the Rules, and needing a lookup in this file to be read
+back as the paragraph it came from. The insulation is worth one rename in
+a pre-1.0 package; the second vocabulary is permanent. Ruled by Solace,
+2026-09-16.
+
+## Decision
+
+1. **The namespace noun is `rule:`.** It replaces `entry:` everywhere. The
+   overload with the Convention's Rules is the point, not an accident to
+   be designed around.
+2. **An id is `rule:<paragraph-slug>`.** The slug is the cite with its
+   punctuation dropped: rule number, paragraph letter attached, each roman
+   subparagraph joined by `_`. `27(a)(i)` → `27a_i`; `13(b)` → `13b`;
+   `11` → `11`; `23(a)(iii)-(iv)` → `23a_iii_iv`.
+3. **A bare id is the paragraph's principal norm.** Where the text yields
+   a further norm from the same paragraph, it takes a third segment after
+   a colon, named in the text's own words: `rule:24a_i` is 24(a)(i)'s two
+   masthead lights and `rule:24a_i:exceeds_200m` its three, the threshold
+   being the Convention's own, which is when a number may appear in a name.
+4. **Where one sentence fuses a deeming test and a duty, both norms are
+   named.** 15(a) gives `rule:15a:crossing` — the classification, effect
+   `encounter: crossing` — and `rule:15a:keep_out_of_the_way` — the
+   precedence, own give-way. `avoid_crossing_ahead` is reserved for 15(a)'s
+   second duty when the `conduct` shape exists; it is not in use.
+5. **A Convention subparagraph keeps its own cite.** 30(d)'s chapeau is
+   `rule:30d`, citing `30(d)`, importing the 30(a)/(b) anchor lights,
+   modality `shall`; the two all-round red lights are `rule:30d_i`, citing
+   `30(d)(i)`, modality `shall-if-practicable` because the paragraph says
+   "if practicable". `30(d)(i)` joins `rules.json` as a skeleton path with
+   this change. `rule:30d_ii` is reserved for the three balls, and lands
+   when day shapes do.
+6. **A jurisdiction override is named by its difference**, and jurisdiction
+   stays a field: `rule:30a:mooring_buoy` and `rule:30b:mooring_buoy`, both
+   `us/inland`. The name says what 33 CFR 90.5 adds, not who adds it.
+7. **13(b) is one symmetric entry.** The two entries that preceded it were
+   identical but for which subject's `geo:rel_bearing_deg` fell in
+   (112.5, 247.5), and both produced `encounter: overtaking`. `rule:13b`
+   reads the same sector object on either subject under `any_of` — the
+   pattern 13(d) already used over `hist:was_overtaking` — because the
+   encounter type belongs to the pair. One paragraph, one norm, one id.
+8. **Every other entry with a unique cite takes the bare slug of it.**
+9. **`represented_paragraphs` ids take the prefix too** — `2a` becomes
+   `rule:2a` — and keep their own list. They no longer need a schema
+   definition of their own: the id pattern is the same one.
+10. **The schema pattern is**
+    `^rule:[0-9]+[a-z]?(_[ivx]+)*(:[a-z][a-z0-9_]*)?$`.
+    **An id is opaque to a consumer.** It looks like a citation and is not
+    one: a consumer that wants the paragraph reads `cite`, and never splits
+    the id to find it. The resemblance is for the human reading a trace;
+    the `cite` field is the machine-readable link to the Convention, and it
+    is the field that moves when the package's reading of a paragraph moves.
+11. **The identifier-diff mechanism is removed, not left dormant.**
+    `retired_entry_ids`, `data/deprecated-identifiers.json`, its schema, the
+    dormant diff test and the retired-id half of the REQ-MODEL-10 collision
+    test all go. Nothing pre-1.0 is immutable, so there was nothing for the
+    registry to hold and no diff for the test to run; a mechanism that
+    cannot fire is a mechanism nobody maintains. It returns, if at all, with
+    the 1.0.0 tag that REQ-MODEL-10's baseline names. Ruled by Solace,
+    2026-09-16.
+
+## The names
+
+`was` is the `entry:` name from the superseded draft of this ADR, which
+shipped in no release. The citation-derived ids that preceded *it* —
+`24a-m2`, `23a1`, `30d-red` — were never names either and are not carried
+forward.
+
+| was | is | cite |
+|---|---|---|
+| `entry:power_forward_masthead` | `rule:23a_i` | 23(a)(i) |
+| `entry:power_second_masthead` | `rule:23a_ii` | 23(a)(ii) |
+| `entry:power_sidelights_sternlight` | `rule:23a_iii_iv` | 23(a)(iii)-(iv) |
+| `entry:air_cushion_non_displacement` | `rule:23b` | 23(b) |
+| `entry:wig_near_surface` | `rule:23c` | 23(c) |
+| `entry:power_under_12m` | `rule:23d_i` | 23(d)(i) |
+| `entry:power_under_7m_slow` | `rule:23d_ii` | 23(d)(ii) |
+| `entry:towing_mastheads` | `rule:24a_i` | 24(a)(i) |
+| `entry:towing_mastheads_long_tow` | `rule:24a_i:exceeds_200m` | 24(a)(i) |
+| `entry:towing_light` | `rule:24a_ii_iv` | 24(a)(ii)-(iv) |
+| `entry:pushing_composite_unit` | `rule:24b` | 24(b) |
+| `entry:pushing_ahead_or_alongside` | `rule:24c` | 24(c) |
+| `entry:being_towed` | `rule:24e` | 24(e) |
+| `entry:sail_sidelights_sternlight` | `rule:25a` | 25(a) |
+| `entry:sail_combined_lantern` | `rule:25b` | 25(b) |
+| `entry:sail_red_over_green` | `rule:25c` | 25(c) |
+| `entry:sail_under_7m` | `rule:25d_i` | 25(d)(i) |
+| `entry:under_oars` | `rule:25d_ii` | 25(d)(ii) |
+| `entry:trawling_green_over_white` | `rule:26b_i` | 26(b)(i) |
+| `entry:trawling_masthead` | `rule:26b_ii` | 26(b)(ii) |
+| `entry:trawling_making_way` | `rule:26b_iii` | 26(b)(iii) |
+| `entry:fishing_red_over_white` | `rule:26c_i` | 26(c)(i) |
+| `entry:fishing_outlying_gear` | `rule:26c_ii` | 26(c)(ii) |
+| `entry:fishing_making_way` | `rule:26c_iii` | 26(c)(iii) |
+| `entry:nuc_red_over_red` | `rule:27a_i` | 27(a)(i) |
+| `entry:nuc_making_way` | `rule:27a_iii` | 27(a)(iii) |
+| `entry:ram_red_white_red` | `rule:27b_i` | 27(b)(i) |
+| `entry:ram_making_way` | `rule:27b_iii` | 27(b)(iii) |
+| `entry:ram_anchored` | `rule:27b_iv` | 27(b)(iv) |
+| `entry:ram_underwater_obstruction` | `rule:27d` | 27(d) |
+| `entry:diving` | `rule:27e_i` | 27(e)(i) |
+| `entry:mine_clearance` | `rule:27f` | 27(f) |
+| `entry:cbd` | `rule:28` | 28 |
+| `entry:pilot` | `rule:29a` | 29(a) |
+| `entry:anchored` | `rule:30a` | 30(a) |
+| `entry:anchored_under_50m` | `rule:30b` | 30(b) |
+| `entry:anchored_deck_lights` | `rule:30c` | 30(c) |
+| `entry:aground_anchor_lights` | `rule:30d` | 30(d) |
+| `entry:aground_red_over_red` | `rule:30d_i` | 30(d)(i) |
+| `entry:anchored_under_7m_not_near_channel` | `rule:30e` | 30(e) |
+| `entry:any_visibility` | `rule:4` | 4 |
+| `entry:in_sight` | `rule:11` | 11 |
+| `entry:restricted_visibility` | `rule:19a` | 19(a) |
+| `entry:power_gives_way_to_nuc` | `rule:18a_i` | 18(a)(i) |
+| `entry:power_gives_way_to_ram` | `rule:18a_ii` | 18(a)(ii) |
+| `entry:power_gives_way_to_fishing` | `rule:18a_iii` | 18(a)(iii) |
+| `entry:power_gives_way_to_sail` | `rule:18a_iv` | 18(a)(iv) |
+| `entry:sail_gives_way_to_nuc` | `rule:18b_i` | 18(b)(i) |
+| `entry:sail_gives_way_to_ram` | `rule:18b_ii` | 18(b)(ii) |
+| `entry:sail_gives_way_to_fishing` | `rule:18b_iii` | 18(b)(iii) |
+| `entry:fishing_gives_way_to_nuc` | `rule:18c_i` | 18(c)(i) |
+| `entry:fishing_gives_way_to_ram` | `rule:18c_ii` | 18(c)(ii) |
+| `entry:avoid_impeding_cbd` | `rule:18d_i` | 18(d)(i) |
+| `entry:wig_keeps_well_clear` | `rule:18f_i` | 18(f)(i) |
+| `entry:not_impeded_remains_obliged` | `rule:8f_iii` | 8(f)(iii) |
+| `entry:overtaking_gives_way` | `rule:13a` | 13(a) |
+| `entry:narrow_channel_small_or_sail` | `rule:9b` | 9(b) |
+| `entry:narrow_channel_fishing` | `rule:9c` | 9(c) |
+| `entry:traffic_lane_fishing` | `rule:10i` | 10(i) |
+| `entry:traffic_lane_small_or_sail` | `rule:10j` | 10(j) |
+| `entry:steady_bearing` | `rule:7d_i` | 7(d)(i) |
+| `entry:sail_port_tack_gives_way` | `rule:12a_i` | 12(a)(i) |
+| `entry:sail_windward_gives_way` | `rule:12a_ii` | 12(a)(ii) |
+| `entry:sail_port_tack_uncertain_gives_way` | `rule:12a_iii` | 12(a)(iii) |
+| `entry:overtaking` | `rule:13b` | 13(b) |
+| `entry:being_overtaken` | `rule:13b` | 13(b) |
+| `entry:overtaking_until_past_and_clear` | `rule:13d` | 13(d) |
+| `entry:head_on` | `rule:14b` | 14(b) |
+| `entry:crossing` | `rule:15a:crossing` | 15(a) |
+| `entry:crossing_gives_way` | `rule:15a:keep_out_of_the_way` | 15(a) |
+| `entry:mooring_buoy` | `rule:30a:mooring_buoy` | 30(a) |
+| `entry:mooring_buoy_under_50m` | `rule:30b:mooring_buoy` | 30(b) |
+
+## Consequences
+
+- One pass, one commit: `data/applicability.json`, both fixture files,
+  `data/geometry.json`, `data/images.json`, `data/facts.json`,
+  `data/rules.json`, the schemas, the suite and the living docs. The
+  schema `$defs` that named the type follow the noun: `entryId` is
+  `ruleId`, `entryIdList` is `ruleIdList`.
+- Two entries may still share a cite — `rule:24a_i` and
+  `rule:24a_i:exceeds_200m`, the two halves of 15(a), the two mooring-buoy
+  deltas. What they never share is an id, and the third segment says which
+  norm out of the paragraph the entry carries.
+- Earlier ADRs and closed questions cite entries by the superseded names;
+  the table above is the map and stays in this file permanently. ADR 0006
+  carries a dated note that its identifier-diff half is gone.
+- `represented_paragraphs` is now a second list of records that look like
+  entries, differing only in carrying no `when`. Folding it into `entries`
+  with a `care`/`meta` category is the obvious follow-up and is not done
+  here.
+- Open, and not ruled: whether `fact:rule18_class` should be renamed. It
+  carries a rule number inside a fact name, which is the shape this ADR
+  moved *entry* ids towards and says nothing about for facts. Left visibly
+  open.
+- An encounter with more than two vessels is issue #135; nothing in this
+  scheme is aimed at it, and a third subject would need a segment none of
+  these ids have.

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.

package/docs/budgets.json

@@ -2,6 +2,7 @@
   "$comment": "Prose budgets enforced by prose-budget (the engine in dotfiles .local/bin), run locally by npm test and in CI by the shared workflow. Raising a number or adding an exception is a deliberate, reviewable diff.",
   "lines": {
     "README.md": 360,
+    "docs/normative-language.md": 130,
     "AGENTS.md": 200,
     "CLAUDE.md": 10,
     "docs/requirements.md": 1500,
@@ -18,7 +19,13 @@
     "required": true,
     "pending": [],
     "docs/adr/0013-corpus-files-with-editions.md": 95,
-    "docs/timeline.md": 130
+    "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/timeline.md": 130,
+    "docs/maritime-sources.md": 130,
+    "docs/decisions.md": 40
   },
   "json_prose": {
     "targets": [
@@ -55,14 +62,10 @@
       "data/applicability.json#/entries/62/note",
       "data/applicability.json#/entries/63/note",
       "data/applicability.json#/entries/64/note",
-      "data/applicability.json#/entries/64/gap",
       "data/applicability.json#/entries/65/note",
-      "data/applicability.json#/entries/65/gap",
       "data/applicability.json#/entries/66/note",
       "data/applicability.json#/entries/67/note",
       "data/applicability.json#/entries/68/note",
-      "data/applicability.json#/entries/68/gap",
-      "data/applicability.json#/entries/69/note",
       "data/facts.json#/derived/note",
       "data/facts.json#/derived/fact:rule18_class/note",
       "data/facts.json#/derived/fact:rule18_class/decode/1/note",
@@ -134,16 +137,6 @@
       ]
     },
     "grandfathered": [
-      {
-        "file": "data/applicability.json",
-        "hash": "447b3984d57b",
-        "match": "PR #24"
-      },
-      {
-        "file": "data/applicability.json",
-        "hash": "5ff9d39319b8",
-        "match": "PR #24"
-      },
       {
         "file": "docs/conventions.md",
         "hash": "d1f1ed997431",

package/docs/decisions.md

@@ -0,0 +1,6 @@
+# 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 — 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).