colregs 0.2.2 → 0.2.4

package/docs/adr/0012-trace-and-rule2-departure-api.md

@@ -0,0 +1,203 @@
+# ADR 0012 — The trace and Rule 2 departure verbs: kinematic and temporal evaluation
+
+Date: 2026-09-07
+Origin: colregs-engine, where it was ADR 0002 until 2026-09-09. The
+decision is about colregs-engine's public API; "this package" below is
+colregs-engine. ADRs for the whole family live here (AGENTS.md).
+Status: draft, full stop. It names the verbs and frames their inputs and
+results so the programme has a target to build toward; it does not build
+them, and it expects to be broken while the package is 0.x.
+
+## Context
+
+ADR 0011 fixed two verbs, one per input, and put kinematic and temporal
+evaluation out of *that* shape: a different input and a different tool. It did
+not say what the verbs would be, which reads as "never" — the wrong lesson,
+since the formal-methods programme (colregs-engine#1, phases 3–5) exists to do
+this evaluation and colregs' ADR 0005 has fixed most of the input.
+
+What the data settles today:
+
+- The **situation record** carries `kin:`, `geo:` and `hist:` per subject,
+  every threshold a paragraph reads declared once under `situation.constants`.
+- `conduct` is "monitored over a trace, not evaluated at a point";
+  `kin:rot_deg_min` and `hist:latched_at_s` are read by no point predicate.
+- Rule 2 is a region of situation space a game solver finds, with a closed
+  status alphabet and a fixed output list (ADR 0005 §5, proposal v4 §4).
+  R0/R1/R2 are research-ontology labels — colregs' vocabulary, not this API.
+
+Not settled: the dynamics model (Q-18), the game's parameters (Q-19, Q-20),
+offline or runtime (Q-22), the conduct effect shape, a trace fixture schema.
+
+## Decision
+
+### 1. Four inputs, four verbs
+
+| input | verb | result | status |
+|---|---|---|---|
+| `FactRecord` — one vessel | `evaluateDisplay` | `DisplayEvaluation` | built |
+| `Situation` — two vessels, one instant | `evaluateEncounter` | `EncounterEvaluation` | target |
+| `Trace` — the situation over time | `evaluateConduct` | `ConductEvaluation` | named here |
+| `Situation` under a `Rule2DepartureModel` | `evaluateRule2Departure` | `Rule2DepartureFinding` | named here |
+
+The two new verbs live **in this package**, superseding ADR 0011's pencilled
+"separate package": a function of a trace and a lookup in a precomputed grid are
+both pure and total, under the same validator, `opts.data` and `colregs.version`
+provenance. What is *not* pure — the solver, the model checker — stays in
+`research/`.
+
+### 2. `Trace` — the input `conduct` reads
+
+```ts
+interface TraceSample { t_s: number; situation: Situation; }
+/** Non-empty, strictly increasing `t_s`, the same two vessels throughout. */
+interface Trace { samples: TraceSample[]; }
+```
+
+`Trace` is runtime-verification vocabulary — the object an STL monitor reads, a
+checker's counterexample — not the Rules'. `t_s` is seconds on the caller's
+clock; the engine reads differences only. A trace is a window, not a session:
+the caller (searoom, the simulator, a fixture) decides how much history to hand
+over, and the result says what window it saw. An object, so a field can be added
+without breaking a caller. The validator that rejects an unknown fact key
+rejects what it can see — an empty trace, non-increasing `t_s`, `other` in some
+samples and not others. It cannot see identity (a `Situation` names no vessel):
+the pair staying the same is the caller's, like the latch; purity is over
+well-formed input.
+
+`hist:was_overtaking` is a snapshot fact the caller supplies and clears, not
+history the engine derives: set when 13(b)'s sector held at an earlier sample,
+because "finally past and clear" is a judgement colregs declines to threshold
+(Q-47). A windowed trace cannot see a latch set before it; time is the caller's.
+
+### 3. `ConductEvaluation` — verdicts over the window
+
+```ts
+interface ConductEvaluation {
+  colregs: { version: string; source: 'resolved' | 'caller' };
+  window: { from_s: number; to_s: number; samples: number };
+  applied: EntryId[];
+  verdicts: ConductVerdict[];
+  phases: ConductPhaseChange[];
+}
+interface ConductVerdict {
+  id: EntryId; subject: 'own' | '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; }
+```
+
+- One **verdict** per applied conduct entry per subject it attached to; an
+  entry that never attached is absent, as it is from `applied`.
+  `kept`/`breached` are decided; `pending` means the window ended before the
+  duty could be judged (17(a)(ii)'s "as soon as it becomes apparent" hasn't
+  run out). `attached_at_s` is when the entry attached the role judged;
+  `decided_at_s` when a breach began or a duty was met. `robustness`, like
+  `Trace`, is runtime-verification vocabulary: the STL margin the monitor
+  computes, value and unit, so a near miss and a wide pass do not look alike.
+- A **phase** is the Rule 13(d)/17 protocol state: the latch, the stand-on
+  vessel passing from 17(a)(i) to 17(a)(ii) to 17(b). `phase` is a
+  `ParagraphCite`, never an `EntryId` — ADR 0011 §4's aliases, used throughout
+  here, and several phases have no entry — naming the state machine
+  programme phase 4's TLA+ or UPPAAL model checks; the monitor refines it.
+- `applied` and the companion `appliedConductEntries(trace)` keep the fixture
+  contract; per-sample encounter evaluations are not returned — call `evaluateEncounter`.
+
+Vague quantities a conduct paragraph reads — "readily apparent" (8(b)), "ample
+time" (16), "as soon as it becomes apparent" (17(a)(ii)) — are declared once in
+colregs' `situation.constants`, as `appreciable_bearing_change_deg_min` is in
+`facts.json` at 0.2.0. A number a paragraph reads belongs in colregs; one only
+the solver reads, inside the grid.
+
+### 4. `Rule2DepartureModel` and `Rule2DepartureFinding` — the Rule 2 departure finding
+
+```ts
+interface SolverParameters {
+  dynamics: string[]; horizon_s: number; cadence_s: number; separation_m: number;
+  information: 'full' | 'partial'; adversary: 'compliant' | 'physics';
+}
+interface Rule2DepartureModel extends SolverParameters {
+  version: string; colregs_version: string;
+}
+interface Rule2DepartureFinding {
+  status: 'not-flagged' | 'model-rule-conflict'
+        | 'no-robust-policy-in-model' | 'inconclusive-in-model';
+  rules: EncounterEvaluation; advisories: Rule2DepartureAdvisory[];
+  model: { version: string; colregs_version: string; parameters: SolverParameters;
+           assumptions_violated: string[] };
+}
+interface Rule2DepartureAdvisory {
+  action: { alter_deg?: number; sog_kn?: number }; margin_m: number;
+  breaches: ParagraphCite[]; envelope: { holds_until_s: number };
+}
+```
+
+The model is required and positional, not an `opts` field: `opts.data` defaults
+to the colregs release this package resolves and a grid has no default. Any
+field beyond `version`, `colregs_version` and the parameters is the artefact's
+own, not API. `SolverParameters` are the axes the sensitivity matrix will vary
+(Q-17 to Q-22): the field set is a claim about what that matrix is. `version`
+names one grid, immutably; `colregs_version` the release it was solved against,
+carried beside `rules.colregs.version` (a mismatch is reported, not refused);
+the finding echoes the parameters, so a consumer can say under which ones it
+holds. `action` and `envelope` take the shapes the worked scenarios used.
+Otherwise the shape follows proposal v4 §4. `not-flagged`, `model-rule-conflict`
+and `no-robust-policy-in-model` name R0, R1 and R2, `inconclusive-in-model`
+none, so a `region` field could only repeat the status or invent one. The
+rule-derived obligations sit in `rules` unchanged, so the reader sees what the
+Rules said; R1's advisories are ranked best margin first, each with the
+paragraphs it breaks; R2's list is empty; `assumptions_violated` is display
+text, never matched on. `not-flagged` means not flagged by this model, never
+"the rules suffice". `breaches` carries `ParagraphCite`s (`17(c)`), as
+`phase` does, never entry ids: a `breaches` entry against a shall-if-practicable
+paragraph is the model's verdict and not the Rules' — the compliance predicate's
+rule for those, and for 17(a)(ii)'s `may`, is open and carded.
+
+The guard rail is narrower than "no danger input": the grid asserts departures,
+and a caller who swaps it changes every finding. What the signature buys is that
+no *situation* input names a departure — correcting facts moves the outputs;
+asserting danger is not an input — and that `model.version` rides on every
+finding, so a claim is attributable to a named grid, never to the Rules.
+Disclaimers live in the README and licence, not here.
+
+### 5. How each layer is checked
+
+| layer | verb | what discharges it |
+|---|---|---|
+| point | `evaluateDisplay`, `evaluateEncounter` | exhaustive enumeration; Z3; Alloy for the sectors |
+| trace | `evaluateConduct` | STL monitors *are* the verdict function; TLA+/UPPAAL for the 13(d)/17 phase machine |
+| Rule 2 departure | `evaluateRule2Departure` | the game solver, offline; the artefact checked in, its parameters on the model |
+
+The tools do not move into `src/`. What moves is their *output*: a counterexample
+trace becomes a fixture; a certified grid, a `Rule2DepartureModel`.
+
+## Consequences
+
+- README's roadmap paragraph names all four verbs and their status; ADR 0011
+  §5's `conduct` and Rule 2 bullets and its register row point here.
+- Order of work, each step shipping something a consumer can call:
+  1. colregs: a trace fixture schema and the first `conduct` entries (16,
+     17, 8(b)) with an effect shape, as `situation-fixtures.json` did.
+  2. `Trace`, `appliedConductEntries` against those fixtures — phase 3
+     starts here.
+  3. `evaluateConduct` with verdicts and phases; the constants above.
+  4. `evaluateRule2Departure` once a grid exists. Until then the name is
+     reserved and nothing exported: a stub answering `inconclusive-in-model`
+     is a stub wearing a status.
+
+## Register
+
+| item | level | what would settle it |
+|---|---|---|
+| Two more verbs, one per input, in this package | ✎ | Mark's confirmation; supersedes ADR 0011's "separate package" row |
+| `Trace` an object over `TraceSample[]`, `t_s` on the caller's clock, pair identity the caller's | ✎ | the first trace fixture |
+| `hist:was_overtaking` a caller-supplied snapshot fact, never engine-derived | ✎ | Q-47; the first conduct monitor |
+| `ConductVerdict` alphabet `kept`/`breached`/`pending`; absent is absent | ✎ | the first STL monitor being written |
+| Field names snake_case with unit suffixes; `EntryId`/`ParagraphCite` per ADR 0011 §4 | ✎ | that ADR's row; the compiler enforces neither |
+| `ConductPhaseChange.phase` values are paragraph cites, not entry ids | ✎ | the programme phase-4 TLA+ or UPPAAL model |
+| Vague-quantity constants live in colregs; `SolverParameters` on the model and echoed on the finding, `colregs_version` naming the release solved against; nothing else on the model is API | ✎ | the first constant a conduct entry reads; Q-19's sensitivity matrix |
+| `Rule2DepartureFinding` field set — `rules`, `Rule2DepartureAdvisory[]`, no banner cite (it is a function of `status`); the status alphabet is colregs' (ADR 0005 §5), not this package's to rename | ✎ | proposal v4 §4's sensitivity matrix; Q-19, Q-20 |
+| No *situation* input names a departure; the grid does, and is named in every finding | ✎ | — |
+| Nothing exported until a fixture backs it; exports then carry TSDoc's `@beta` release tag | ✎ | — |

package/docs/budgets.json

@@ -1,14 +1,19 @@
 {
   "$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,
-    "AGENTS.md": 120,
+    "README.md": 200,
+    "AGENTS.md": 122,
     "CLAUDE.md": 10,
     "docs/requirements.md": 1500,
     "docs/identifiers.md": 450,
     "docs/part-b-invariants.md": 950,
     "docs/adr/0007-rule26-overrides-and-aground.md": 90,
     "docs/adr/0008-mooring-buoy-modifier.md": 90,
+    "docs/adr/0009-data-version-stamp.md": 90,
+    "docs/adr/0010-text-withheld-jurisdictions.md": 125,
+    "docs/adr/0011-api-shape.md": 173,
+    "docs/adr/0012-trace-and-rule2-departure-api.md": 203,
+    "docs/verification/2026-09-09-text-slug-straw-man.md": 270,
     "required": true,
     "pending": []
   },

package/docs/requirements.md

@@ -76,7 +76,9 @@ Neither consumer lives in this repo.
   (Rule 28 "[Reserved]") means silence-means-inherit would apply
   international law where the national body deliberately has none, so no
   non-`intl` jurisdiction lands before an explicit suppression mechanism
-  exists. A delta that only *adds* entries is exempt: it suppresses nothing,
+  exists. That bar is about suppression, not licensing: it is independent of
+  REQ-PROV-2 and ADR 0010, and it binds whether a jurisdiction's text ships or
+  is withheld. A delta that only *adds* entries is exempt: it suppresses nothing,
   so the Q-11 hazard cannot arise from it (ADR 0008, `30a-buoy`/`30b-buoy`).
   A delta that suppresses or replaces an `intl` entry still waits.
 - **REQ-SCOPE-4** — Adding a jurisdiction MUST be additive. It MUST NOT require
@@ -123,7 +125,12 @@ Four layers, each independently addressable.
 
 - **REQ-MODEL-1** — **Rule text**, verbatim, keyed by paragraph path. Text MUST
   NOT be paraphrased, summarised or reflowed. Where a jurisdiction's text
-  differs, both MUST be stored, keyed by jurisdiction.
+  differs, both MUST be stored, keyed by jurisdiction — unless the paragraph is
+  `text_status: withheld` (ADR 0010), which stores no rule text. What a
+  withheld paragraph carries instead — citation alone, a digest, a
+  deterministic non-prose reduction, or the `intl` equivalent — is pencil in
+  ADR 0010, deliberately unsettled. This requirement bars paraphrasing text
+  the package *ships*; it does not by itself decide the withheld case.
 - **REQ-MODEL-2** — **Light definitions** (Rule 21) MUST carry colour, arc of
   visibility in degrees, and range by length band (Rule 22). Jurisdictions MAY
   add definitions (e.g. the US special flashing light, Inland 21(g)).
@@ -509,9 +516,10 @@ See ADR 0003.
 
 - **REQ-PROV-1** — Every text and image asset MUST record its source, the date
   retrieved, and its licence or public-domain basis.
-- **REQ-PROV-2** — A jurisdiction MUST NOT be added until its reproduction terms
-  have been checked against the primary source and recorded. Recalled or assumed
-  terms are not sufficient.
+- **REQ-PROV-2** — A jurisdiction's *rule text* MUST NOT be published until its
+  reproduction terms have been checked against the primary source and recorded.
+  Recalled or assumed terms are not sufficient. This does not bar *modelling* a
+  jurisdiction: its structure may ship with the text withheld — ADR 0010.
 - **REQ-PROV-3** — Where a licence requires attribution (e.g. OGL, CC BY), the
   attribution text MUST ship in the package, not only in the repo.
 - **REQ-PROV-4** — Code licence and data licence MUST be stated separately. The
@@ -792,6 +800,9 @@ Tracked here until resolved; each becomes an ADR.
   unece.org was unreachable from the checking host, and the UN's default
   terms (personal, non-commercial use only) block it until written
   permission or a national transposition is chosen instead.
+  **Ruled 2026-09-09 (ADR 0010):** this blocks CEVNI's *text*, not CEVNI.
+  A jurisdiction may be modelled in full with its text withheld, so no
+  session should treat `eu/cevni` as unimplementable.
 - **Q-4** — Two upstream SignalK spec asks are outstanding and independent of
   this package: a making-way indicator, and `design.maxSpeed`.
 - **Q-5** — REQ-VERIFY-5 asks for boundary fixtures on every numeric gate.
@@ -918,7 +929,9 @@ Tracked here until resolved; each becomes an ADR.
   "this path/entry deliberately does not exist here", distinguishable from
   "not yet transcribed". Decide the mechanism in the second-jurisdiction
   bundle (GATE-1 re-take, GATE-2, Q-10); until then no non-`intl`
-  jurisdiction lands.
+  jurisdiction lands. This is the live blocker on CEVNI, and it is *not* the
+  licence one: ADR 0010 removed the licence block by permitting structure with
+  the text withheld, and left this one standing.
   Also from the same verification pass, tracked on the global board rather
   than here: four transcription defects in `data/rules.json` itself
   (`21(a)`, `21(b)`, `23(b)`, `29(b)`) — a data fix, not a design
@@ -1328,6 +1341,16 @@ written up in `docs/identifiers.md` §"Effects"; what it could not is here.
   be a number invented rather than declared. Settled by whatever settles the
   `conduct` monitors, which are the things that watch a duty end rather than
   begin.
+
+  **Ruled 2026-09-08:** while one vessel holds the latch, 13(a)'s sector
+  test is suppressed on the other, newly-gaining vessel — once overtaking,
+  always overtaking, per 13(d)'s own text, so a geometry test that would
+  newly name a second give-way vessel must not fire while the first still
+  holds the role by history alone. `13a`'s sector branch now also reads
+  `other:hist:was_overtaking: false`; the closing fixture in
+  `fixtures/situation-fixtures.json` is the case this closes — a vessel
+  drops back onto the latch-holder's own stern, and only the latch-holder
+  gives way.
 - **Q-48** — **Nothing checks that a situation is geometrically possible.**
   `own:geo:rel_bearing_deg`, `other:geo:rel_bearing_deg`, the two
   `kin:heading_deg` and the two `kin:sog_kn` are six facts related by two
@@ -1447,3 +1470,10 @@ Two decisions taken in pencil, reversible in one edit: the invariants live in
 their own document under `REQ-INV-1`–`REQ-INV-7` (§4.2 says why), and the id
 scheme is `REQ-INV-2`'s — cheap to change until P4.2 cites an id from a TLA+
 module, expensive after.
+
+A third, ruled rather than pencil: **`docs/part-b-invariants.md` stays
+hand-written Markdown; no derived JSON registry.** Ruled 2026-09-08. Revisit
+only if P4.2's TLA+ needs to cite `INV-` ids mechanically — the id scheme
+just above is already the cheap-to-change half of that trigger, so the
+revisit costs one file's worth of tooling, not a re-derivation of the ids
+themselves.

package/docs/verification/2026-09-09-text-slug-straw-man.md

@@ -0,0 +1,264 @@
+# The `text_slug` straw man, built on `intl` Rules 1-19
+
+ADR 0010 leaves in pencil what a withheld paragraph carries in place of its
+text, and names a slug as a straw man to be built and judged rather than
+argued about. This is the build and the judgement. The research issue is
+colregs#83; nothing here decides the pencil item.
+
+Everything below is reproducible from `scripts/text-slug.mjs` over
+`data/rules.json` at this commit. Nothing was written into `data/`.
+
+## What the pipeline does
+
+Deterministic, no model in the loop, no dependencies:
+
+1. **Citations first.** `Rule 13`, `Rules 4-19`, `Rule 34(c)(i)` become
+   `rule-13`, `rules-4-19`, `rule-34ci`. A citation is a fact about which
+   provision is invoked, not expression, and it is the most navigable term a
+   slug can carry.
+2. **Terms of art as one term.** A fixed table of multi-word terms collapses
+   each to a hyphenated token: `traffic-separation-scheme`, `not-under-command`,
+   `restricted-ability-maneuver`, `keep-out-of-way`, `risk-of-collision`,
+   `in-sight`, `narrow-channel`. The target form is the applicability
+   vocabulary's wherever one exists.
+3. **Stop words out.** Function words, modals and the words that are in nearly
+   every paragraph and say nothing about which one this is: `vessel`, `rule`,
+   `shall`, `circumstances`, `practicable`.
+4. **Lemmatise.** Plurals by rule; every `-ed` and `-ing` form by a table,
+   because a suffix rule cannot tell `speed` from `stopped` without a lexicon.
+   Gerunds that name an activity in `facts.json` keep the gerund (`fishing`,
+   `towing`), so the slug's form is the vocabulary's form.
+5. **Sorted set.** No order, no syntax, no counts.
+
+Numbers keep their unit (`20-meter`, `22-5-degree`).
+
+## Shape of the output
+
+| measure | Rules 1-19 |
+|---|---|
+| paragraphs | 122 |
+| terms per slug, min / median / max | 0 / 6 / 34 |
+| empty slugs | 1: `6(a)`, whose text is "By all vessels:" |
+| identical slugs | 3 groups, all in Rule 18: `18(a)(i)=18(b)(i)=18(c)(i)`, `18(a)(ii)=18(b)(ii)=18(c)(ii)`, `18(a)(iii)=18(b)(iii)` |
+| near-duplicates, Jaccard ≥ 0.6 | 1 pair: `13(c)` and `14(c)`, the two "if in doubt, assume" paragraphs |
+
+The identical slugs are identical source text: "a vessel not under command"
+under three different chapeaux. No slug can separate them, and neither can
+the text; the path does. That is the ceiling on question 1 for this corpus.
+
+## Question 1: can a reader navigate to the paragraph from the slug alone?
+
+Method: the 122 slugs, shuffled by a fixed hash of the path and stripped of
+their paths (`--blind`), were given to two readers with no access to the
+repository or any other file, asked to name the paragraph for each line with
+a confidence from 1 to 3. The readers were two language models chosen as
+proxies for a strong and a weak human reader of the Rules: one that knows
+COLREGS closely (Claude Opus) and one that knows it loosely (Claude Haiku).
+Scored against the key.
+
+| reader | exact paragraph | correct rule | wrong while "sure" |
+|---|---|---|---|
+| strong | 115 / 122 | 122 / 122 | 1 |
+| weak | 30 / 122 | 79 / 122 | 38 |
+
+The strong reader's seven misses: six are inside the three identical-slug
+groups above, where the answer is one of the group and the slug cannot say
+which; the seventh is `15` for `15(a)`, a citation-form slip on a rule with
+one paragraph. Every miss that the slug could in principle have prevented,
+it prevented.
+
+The weak reader reached the right rule in two cases out of three and the
+right paragraph in one out of four, and was confidently wrong 38 times. The
+misses are almost all off-by-one within a rule (`8(b)` read as `8(a)`) or a
+Rule 18 sub-item read as its Rule 3 definition, which is to say the reader
+did not know the paragraph numbering, and the slug does not teach it.
+
+Reading: **the slug is an index, not a substitute.** A reader who knows the
+Rules lands on the paragraph from the slug alone, at the ceiling the corpus
+allows. A reader who does not know the Rules lands on the rule, mostly, and
+on the paragraph rarely. For the case ADR 0010 is for, that ordering
+matters: a CEVNI reader will usually be the second kind, the source is not
+English, and the terms would be translations, so the strong-reader number is
+an upper bound and the weak-reader number is the honest expectation.
+
+## Question 2: do the terms overlap the applicability vocabulary?
+
+Method: every fact key and enumerated value that `data/applicability.json`
+predicates and `data/facts.json` axes use, 67 terms, mapped to slug space by
+a table that is mostly the four abbreviations (`nuc`, `ram`, `cbd`, `wig`)
+and the underscores.
+
+- **59 of 67 terms appear in some slug of Rules 1-19.** The eight that do not
+  are terms from outside the range or not terms at all: `activity:diving`,
+  `activity:pushing`, `activity:none`, `position:moored`, `propulsion:oars`,
+  `fact:composite_unit`, `fact:on_mooring_buoy`, `wind_side:unknown`. Within
+  the range the overlap is complete.
+- **Per entry, the cited paragraph's slug carries the term the entry turns
+  on.** All 31 entries citing a paragraph in Rules 1-19 were checked
+  (`--stats`). `13a` reads `hist:was_overtaking`; `13(a)`'s slug carries
+  `overtake`. `9b` reads `length_m`, `propulsion:sail` and
+  `confined_to_channel`; `9(b)`'s slug carries `20-meter`, `sailing-vessel`,
+  `narrow-channel`, `navigate`. `18d1` reads three Rule 18 classes;
+  `18(d)(i)`'s slug carries all three. What the slug does not carry are the
+  gates an entry inherits from a chapeau or a scope rule rather than from
+  its own paragraph: `pair:geo:in_sight` (Rule 11), `position:underway`
+  (`18(a)`'s chapeau), and the derived `fact:rule18_class` key. Those are in
+  the chapeau's slug, which is where the text puts them.
+
+Reading: **the overlap is real and it runs the useful way.** The
+applicability vocabulary was written from these paragraphs, so the slug of a
+paragraph recovers the terms its entries gate on. A term-set built for a
+withheld jurisdiction the same way would give a consumer a vocabulary-level
+hook into each paragraph without a word of it.
+
+## What this does and does not settle
+
+Settled by the build: the pipeline is deterministic, cheap, and produces a
+navigable index for a reader who already knows the Rules, at the corpus's
+own ceiling. The terms line up with the vocabulary.
+
+Not settled, and not this document's to settle:
+
+- Whether a slug ships for CEVNI at all, alone or beside `text_digest` and
+  `mirrors`. The weak-reader result says a slug does not replace the words
+  for the reader most likely to need them; `mirrors` does, for the majority
+  of CEVNI, and the slug's value is in the remainder.
+- Where the derivative-work line falls. Out of scope on colregs#82; redaction
+  ships whatever the answer.
+- The pipeline's tables are hand-built for this corpus. A CEVNI run needs a
+  translation step to English counterparts before the same tables apply,
+  and a lexicon for forms the tables do not know. That is engineering, not
+  a design question.
+
+What would move the pencil item: a decision on the first bullet, taken with
+the `mirrors` coverage of CEVNI in hand, since that number is what says how
+much of CEVNI the slug would be the only thing standing in for.
+
+## The slugs
+
+`node scripts/text-slug.mjs`, Rules 1-19, at this commit:
+
+```
+4           apply, rules-4-10, visibility
+5           appraisal, available, hearing, look-out, maintain, risk-of-collision, sight, situation
+6           action, avoid, collision, determine, distance, effective, factor, proceed, safe-speed, stop
+11          apply, in-sight, rules-11-18
+16          action, direct, early, keep-clear, keep-out-of-way, substantial
+18          except, rule-10, rule-13, rule-9
+1(a)        apply, connect, high-seas, navigable, seagoing, water
+1(b)        authority, conform, connect, harbor, high-seas, inland, interfere, lake, navigable, operation, river, roadstead, seagoing, waterway
+1(c)        additional, authorize, convoy, elsewhere, engaged-in-fishing, fishing, fleet, government, interfere, light, mistake, operation, proceed, shape, ship, signal, state, station, war, whistle
+1(d)        adopt, organization, traffic-separation-scheme
+1(e)        appliance, arc, characteristic, comply, concern, construction, determine, disposition, government, light, number, position, range, shape, sound-signaling, visibility
+2(a)        comply, consequence, crew, exonerate, master, neglect, owner, practice, precaution, seaman
+2(b)        avoid, collision, comply, construe, danger, departure, immediate, limitation, navigation
+3(a)        craft, non-displacement, seaplane, transportation, water, watercraft, wig-craft
+3(b)        machinery, power-driven, propel
+3(c)        fit, machinery, propel, sail, sailing-vessel
+3(d)        apparatus, engaged-in-fishing, fishing, line, maneuver, net, restrict, trawl, trolling
+3(e)        aircraft, design, maneuver, seaplane, water
+3(f)        exceptional, keep-out-of-way, maneuver, not-under-command, unable
+3(g)        ability, aircraft, cable, cargo, clear, course, deviate, dredging, engage, keep-out-of-way, launch, lay, limit, mark, mine, navigational, operation, person, pick-up, pipeline, recover, replenish, restrict, restricted-ability-maneuver, service, submarine, surveying, tow, towing, transfer, unable, underwater, underway, work
+3(h)        available, constrained-by-draft, course, depth, draft, navigable, power-driven, restricted-ability-maneuver, water, width
+3(i)        aground, anchor, fast, shore, underway
+3(j)        breadth, length, overall
+3(k)        in-sight, observe
+3(l)        fall, fog, mist, rainstorm, restrict, restricted-visibility, sandstorm, snow, visibility
+3(m)        action, close, craft, fly, mode, multimodal, operational, proximity, surface, surface-effect, utilize, wig, wing-in-ground
+6(a)        
+6(a)(i)     state, visibility
+6(a)(ii)    concentration, density, fishing, traffic
+6(a)(iii)   ability, distance, maneuver, stop, turn
+6(a)(iv)    back, background, light, night, scatter, shore
+6(a)(v)     current, hazard, navigational, proximity, sea, state, wind
+6(a)(vi)    available, depth, draft, water
+6(b)        operational, radar
+6(b)(i)     characteristic, efficiency, equipment, limitation, radar
+6(b)(ii)    constraint, impose, radar, range, scale
+6(b)(iii)   detect, effect, interference, radar, sea, source, state, weather
+6(b)(iv)    adequate, detect, float, ice, object, radar, range, small
+6(b)(v)     detect, location, movement, number, radar
+6(b)(vi)    assess, determine, object, radar, range, vicinity, visibility
+7(a)        available, determine, doubt, risk, risk-of-collision
+7(b)        detect, early, equipment, equivalent, fit, long-range, object, observe, operational, plot, radar, risk-of-collision, scan, systematic, warning
+7(c)        assume, information, radar, scanty
+7(d)        consideration, determine, risk-of-collision
+7(d)(i)     approach, change, compass-bearing, risk
+7(d)(ii)    appreciable, approach, bearing, change, close, large, range, risk, tow
+8(a)        action, avoid, collision, observe, positive, rules-4-19, seamanship
+8(b)        alter, avoid, collision, course, large, observe, radar, small, speed, succession
+8(c)        action, alone, alter, avoid, close-quarters, course, effective, room, sea, substantial
+8(d)        action, avoid, check, clear, collision, distance, effective, pass, past, safe
+8(e)        assess, avoid, collision, propulsion, reverse, situation, slacken, speed, stop, way
+8(f)(i)     action, early, impede, passage, room, safe, sea
+8(f)(ii)    action, approach, impede, obligation, passage, relieve, risk-of-collision, rules-4-19, safe
+8(f)(iii)   approach, comply, impede, oblige, passage, risk-of-collision, rules-4-19, two
+9(a)        channel, course, fairway, keep, lie, limit, narrow-channel, near, outer, proceed, safe, side, starboard
+9(b)        20-meter, fairway, impede, length, narrow-channel, navigate, passage, sailing-vessel
+9(c)        engaged-in-fishing, fairway, impede, narrow-channel, navigate, passage
+9(d)        channel, cross, doubt, fairway, impede, intention, narrow-channel, navigate, passage, prescribe, rule-34d, signal
+9(e)(i)     action, agreement, doubt, fairway, indicate, intend, intention, narrow-channel, overtake, pass, prescribe, rule-34ci, rule-34cii, rule-34d, safe, signal, sound, step
+9(e)(ii)    obligation, overtake, relieve, rule-13
+9(f)        alertness, area, bend, caution, fairway, intervene, narrow-channel, navigate, near, obscure, obstruction, prescribe, rule-34e, signal, sound
+9(g)        anchor, avoid, narrow-channel
+10(a)       adopt, apply, obligation, organization, relieve, traffic-separation-scheme
+10(b)       traffic-separation-scheme
+10(b)(i)    direction, flow, lane, proceed, traffic, traffic-lane
+10(b)(ii)   keep-clear, separation-line, separation-zone, traffic
+10(b)(iii)  angle, direction, flow, join, lane, leave, side, small, termination, traffic, traffic-lane
+10(c)       angle, avoid, cross, direction, flow, heading, oblige, right, traffic, traffic-lane
+10(d)(i)    20-meter, adjacent, engaged-in-fishing, inshore-traffic-zone, length, sailing-vessel, traffic-lane, traffic-separation-scheme
+10(d)(ii)   avoid, danger, immediate, inshore-traffic-zone, installation, offshore, pilot, port, route, rule-10di, situate, station, structure
+10(e)       cross, enter, except, join, lane, leave, separation-line, separation-zone
+10(e)(i)    avoid, danger, emergency, immediate
+10(e)(ii)   engage, fishing, separation-zone
+10(f)       area, caution, navigate, near, termination, traffic-separation-scheme
+10(g)       anchor, area, avoid, near, termination, traffic-separation-scheme
+10(h)       avoid, margin, traffic-separation-scheme, wide
+10(i)       engaged-in-fishing, impede, passage, traffic-lane
+10(j)       20-meter, impede, length, passage, power-driven, safe, sailing-vessel, traffic-lane
+10(k)       carry, comply, engage, exempt, maintenance, navigation, operation, restricted-ability-maneuver, safety, traffic-separation-scheme
+10(l)       cable, carry, comply, engage, exempt, lay, operation, pick-up, restricted-ability-maneuver, service, submarine, traffic-separation-scheme
+12(a)       approach, keep-out-of-way, risk-of-collision, sailing-vessel, two
+12(a)(i)    keep-out-of-way, port, side, wind
+12(a)(ii)   keep-out-of-way, leeward, side, wind, windward
+12(a)(iii)  certainty, determine, keep-out-of-way, port, see, side, starboard, wind, windward
+12(b)       carry, fore-and-aft, mainsail, opposite, sail, side, square-rigged, windward
+13(a)       contain, keep-out-of-way, overtake, rules-4-18
+13(b)       22-5-degree, abaft, beam, come, direction, night, overtake, position, see, sidelight, sternlight
+13(c)       act, assume, doubt, overtake
+13(d)       alter, bearing, clear, cross, duty, keep, overtake, past, relieve, subsequent, two
+14(a)       alter, course, meet, pass, port, power-driven, reciprocal, risk-of-collision, side, starboard, two
+14(b)       ahead, aspect, correspond, day, line, masthead-light, night, observe, see, sidelight, situation
+14(c)       act, assume, doubt, situation
+15(a)       ahead, avoid, cross, keep-out-of-way, power-driven, risk-of-collision, side, starboard, two
+17(a)(i)    course, keep, keep-out-of-way, speed, two
+17(a)(ii)   action, alone, avoid, collision, comply, keep-out-of-way, maneuver
+17(b)       action, aid, alone, avoid, close, collision, course, give-way, keep, speed
+17(c)       action, alter, avoid, collision, course, cross, port, power-driven, rule-17aii, side, situation
+17(d)       give-way, keep-out-of-way, obligation, relieve
+18(a)       keep-out-of-way, power-driven, underway
+18(a)(i)    not-under-command
+18(a)(ii)   restricted-ability-maneuver
+18(a)(iii)  engaged-in-fishing
+18(a)(iv)   sailing-vessel
+18(b)       keep-out-of-way, sailing-vessel, underway
+18(b)(i)    not-under-command
+18(b)(ii)   restricted-ability-maneuver
+18(b)(iii)  engaged-in-fishing
+18(c)       engaged-in-fishing, keep-out-of-way, underway
+18(c)(i)    not-under-command
+18(c)(ii)   restricted-ability-maneuver
+18(d)(i)    avoid, constrained-by-draft, exhibit, impede, not-under-command, passage, restricted-ability-maneuver, rule-28, safe, signal
+18(d)(ii)   caution, constrained-by-draft, navigate
+18(e)       avoid, comply, impede, keep-clear, navigation, risk-of-collision, rules-4-19, seaplane, water
+18(f)(i)    avoid, flight, impede, keep-clear, land, navigation, near, surface, wig-craft
+18(f)(ii)   comply, operate, power-driven, rules-4-19, surface, water, wig-craft
+19(a)       apply, area, in-sight, navigate, near, restricted-visibility
+19(b)       adapt, engine, immediate, maneuver, power-driven, proceed, ready, restricted-visibility, safe-speed
+19(c)       comply, restricted-visibility, rules-4-10
+19(d)       action, alone, alter, avoid, close-quarters, course, detect, determine, develop, radar, risk-of-collision
+19(d)(i)    alter, beam, course, forward, overtake, port
+19(d)(ii)   abaft, abeam, alter, beam, course
+19(e)       avoid, beam, caution, close-quarters, collision, course, danger, determine, except, extreme, fog-signal, forward, hear, keep, minimum, navigate, reduce, risk-of-collision, speed, way
+```

package/fixtures/applicability-fixtures.json

@@ -362,6 +362,23 @@
     "24a-rest"
    ]
   },
+  {
+   "name": "towing astern, at anchor (issue #44: Rule 23 running lights not imported)",
+   "facts": {
+    "fact:propulsion": "propulsion:power",
+    "fact:activity": "activity:towing",
+    "fact:position": "position:anchored",
+    "fact:length_m": 40,
+    "fact:tow_length_m": 150
+   },
+   "expect": [
+    "24a-m2",
+    "24a-rest",
+    "30a",
+    "30b",
+    "30c"
+   ]
+  },
   {
    "name": "pushing ahead, composite unit",
    "facts": {
@@ -375,6 +392,22 @@
     "24b"
    ]
   },
+  {
+   "name": "pushing ahead, composite unit, at anchor (issue #44: Rule 23 running lights not imported)",
+   "facts": {
+    "fact:propulsion": "propulsion:power",
+    "fact:activity": "activity:pushing",
+    "fact:position": "position:anchored",
+    "fact:length_m": 30,
+    "fact:composite_unit": true
+   },
+   "expect": [
+    "24b",
+    "30a",
+    "30b",
+    "30c"
+   ]
+  },
   {
    "name": "pushing ahead, not a composite unit",
    "facts": {
@@ -388,6 +421,22 @@
     "24c"
    ]
   },
+  {
+   "name": "pushing ahead, not a composite unit, at anchor (issue #44: Rule 23 running lights not imported)",
+   "facts": {
+    "fact:propulsion": "propulsion:power",
+    "fact:activity": "activity:pushing",
+    "fact:position": "position:anchored",
+    "fact:length_m": 30,
+    "fact:composite_unit": false
+   },
+   "expect": [
+    "24c",
+    "30a",
+    "30b",
+    "30c"
+   ]
+  },
   {
    "name": "constrained by draft",
    "facts": {