colregs 0.2.2 → 0.2.4

package/data/rules.json

@@ -904,28 +904,41 @@
    "rule": "21",
    "rule_title": "Definitions",
    "jurisdiction": "intl",
-   "text": "\"Masthead light\" means a white light placed over the fore and aft centerline of the vessel showing an unbroken light over an arc of the horizon of 225 degrees and so fixed as to show the light from right ahead to 22.5 degrees abaft the beam on either side of the vessel."
+   "text": "\"Masthead light\" means a white light placed over the fore and aft centerline of the vessel showing an unbroken light over an arc of the horizon of 225 degrees and so fixed as to show the light from right ahead to 22.5 degrees abaft the beam on either side of the vessel.",
+   "images": [
+    "mastheadarc.gif"
+   ]
   },
   "21(b)": {
    "path": "21(b)",
    "rule": "21",
    "rule_title": "Definitions",
    "jurisdiction": "intl",
-   "text": "\"Sidelights\" means a green light on the starboard side and a red light on the port side each showing an unbroken light over an arc of the horizon of 112.5 degrees and so fixed as to show the light from right ahead to 22.5 degrees abaft the beam on its respective side. In a vessel of less than 20 meters in length the sidelights may be combined in one lantern carried on the fore and aft centerline of the vessel."
+   "text": "\"Sidelights\" means a green light on the starboard side and a red light on the port side each showing an unbroken light over an arc of the horizon of 112.5 degrees and so fixed as to show the light from right ahead to 22.5 degrees abaft the beam on its respective side. In a vessel of less than 20 meters in length the sidelights may be combined in one lantern carried on the fore and aft centerline of the vessel.",
+   "images": [
+    "portarc.gif",
+    "stbdarc.gif"
+   ]
   },
   "21(c)": {
    "path": "21(c)",
    "rule": "21",
    "rule_title": "Definitions",
    "jurisdiction": "intl",
-   "text": "\"Sternlight\" means a white light placed as nearly as practicable at the stern showing an unbroken light over an arc of the horizon of 135 degrees and so fixed as to show the light 67.5 degrees from right aft on each side of the vessel."
+   "text": "\"Sternlight\" means a white light placed as nearly as practicable at the stern showing an unbroken light over an arc of the horizon of 135 degrees and so fixed as to show the light 67.5 degrees from right aft on each side of the vessel.",
+   "images": [
+    "sternarc.gif"
+   ]
   },
   "21(d)": {
    "path": "21(d)",
    "rule": "21",
    "rule_title": "Definitions",
    "jurisdiction": "intl",
-   "text": "\"Towing light\" means a yellow light having the same characteristics as the \"sternlight\" defined in Rule 21(c)."
+   "text": "\"Towing light\" means a yellow light having the same characteristics as the \"sternlight\" defined in Rule 21(c).",
+   "images": [
+    "towingarc.gif"
+   ]
   },
   "21(e)": {
    "path": "21(e)",
@@ -1003,6 +1016,7 @@
    "jurisdiction": "intl",
    "text": "a second masthead light abaft of and higher than the forward one; except that a vessel of less than 50 meters in length shall not be obliged to exhibit such a light but may do so;",
    "images": [
+    "NRHB_23_a.png",
     "NRHB_23_aii.png"
    ]
   },
@@ -1103,7 +1117,10 @@
    "rule": "24",
    "rule_title": "Towing and Pushing",
    "jurisdiction": "intl",
-   "text": "a towing light in a vertical line above the sternlight; and"
+   "text": "a towing light in a vertical line above the sternlight; and",
+   "images": [
+    "towingarc.gif"
+   ]
   },
   "24(a)(v)": {
    "path": "24(a)(v)",
@@ -1428,7 +1445,8 @@
    "jurisdiction": "intl",
    "text": "A vessel engaged in dredging or underwater operations, when restricted in her ability to maneuver, shall exhibit the lights and shapes prescribed in Rules 27(b)(i), (ii) and (iii) and shall in addition when an obstruction exists, exhibit:",
    "images": [
-    "NRHB_27_d.png"
+    "NRHB_27_d.png",
+    "NRHB_27_diii.png"
    ]
   },
   "27(d)(i)": {
@@ -1438,7 +1456,8 @@
    "jurisdiction": "intl",
    "text": "two all-round red lights or two balls in a vertical line to indicate the side on which the obstruction exists;",
    "images": [
-    "NRHB_27_d.png"
+    "NRHB_27_d.png",
+    "NRHB_27_diii.png"
    ]
   },
   "27(d)(ii)": {
@@ -1448,7 +1467,8 @@
    "jurisdiction": "intl",
    "text": "two all-round green lights or two diamonds in a vertical line to indicate the side on which another vessel may pass; and",
    "images": [
-    "NRHB_27_d.png"
+    "NRHB_27_d.png",
+    "NRHB_27_diii.png"
    ]
   },
   "27(d)(iii)": {
@@ -1456,10 +1476,7 @@
    "rule": "27",
    "rule_title": "Vessels Not Under Command or Restricted in Their Ability to Maneuver",
    "jurisdiction": "intl",
-   "text": "when at anchor, the lights or shapes prescribed in this paragraph instead of the lights or shapes prescribed in Rule 30.",
-   "images": [
-    "NRHB_27_diii.png"
-   ]
+   "text": "when at anchor, the lights or shapes prescribed in this paragraph instead of the lights or shapes prescribed in Rule 30."
   },
   "27(e)": {
    "path": "27(e)",
@@ -1473,10 +1490,7 @@
    "rule": "27",
    "rule_title": "Vessels Not Under Command or Restricted in Their Ability to Maneuver",
    "jurisdiction": "intl",
-   "text": "Three all-round lights in a vertical line where they can best be seen. The highest and lowest of these lights shall be red and the middle light shall be white;",
-   "images": [
-    "NRHB_27_ei.png"
-   ]
+   "text": "Three all-round lights in a vertical line where they can best be seen. The highest and lowest of these lights shall be red and the middle light shall be white;"
   },
   "27(e)(ii)": {
    "path": "27(e)(ii)",
@@ -1485,6 +1499,7 @@
    "jurisdiction": "intl",
    "text": "a rigid replica of the International Code flag \"A\" not less than 1 meter in height. Measures shall be taken to ensure its all-round visibility.",
    "images": [
+    "NRHB_27_ei.png",
     "NRHB_27_eii.png"
    ]
   },
@@ -1573,7 +1588,7 @@
    "jurisdiction": "intl",
    "text": "A vessel at anchor shall exhibit where it can best be seen: (i) in the fore part, an all-round white light or one ball; (ii) at or near the stern and at a lower level than the light prescribed in Rule 30(a)(i), an all-round white light.",
    "images": [
-    "NRHB_30_a.png"
+    "NRHB_30_d.png"
    ]
   },
   "30(b)": {
@@ -1581,14 +1596,20 @@
    "rule": "30",
    "rule_title": "Anchored Vessels and Vessels Aground",
    "jurisdiction": "intl",
-   "text": "A vessel of less than 50 meters in length may exhibit an all-round white light where it can best be seen instead of the lights prescribed in Rule 30(a)."
+   "text": "A vessel of less than 50 meters in length may exhibit an all-round white light where it can best be seen instead of the lights prescribed in Rule 30(a).",
+   "images": [
+    "NRHB_30_a.png"
+   ]
   },
   "30(c)": {
    "path": "30(c)",
    "rule": "30",
    "rule_title": "Anchored Vessels and Vessels Aground",
    "jurisdiction": "intl",
-   "text": "A vessel at anchor may, and a vessel of 100 meters and more in length shall, also use the available working or equivalent lights to illuminate her decks."
+   "text": "A vessel at anchor may, and a vessel of 100 meters and more in length shall, also use the available working or equivalent lights to illuminate her decks.",
+   "images": [
+    "NRHB_30_d.png"
+   ]
   },
   "30(d)": {
    "path": "30(d)",
@@ -1597,7 +1618,6 @@
    "jurisdiction": "intl",
    "text": "A vessel aground shall exhibit the lights prescribed in Rule 30(a) or (b) and in addition, if practicable, where they can best be seen: (i) two all-round red lights in a vertical line; (ii) three balls in a vertical line.",
    "images": [
-    "NRHB_30_d.png",
     "NRHB_30_dii.png"
    ]
   },

package/data/version.json

@@ -0,0 +1,3 @@
+{
+  "version": "0.2.4"
+}

package/docs/adr/0001-name-and-jurisdiction-model.md

@@ -1,7 +1,8 @@
 # ADR 0001 — Package name, and jurisdiction as a dimension
 
 Date: 2026-08-29
-Status: accepted; amended 2026-09-05 (licence terms verified, see Amendments)
+Status: accepted; amended 2026-09-05 and 2026-09-09 (licence terms verified,
+see Amendments). CEVNI's text stays blocked; ADR 0010 unblocks modelling it.
 
 ## Context
 
@@ -94,7 +95,7 @@ what it implies for which instrument supplies the Rules *text*.
 | Jurisdiction | Instrument (text source) | Delta | Licence, verified | Attribution to ship (REQ-PROV-3) |
 |---|---|---|---|---|
 | `us/inland` | 33 CFR 83, eCFR | large | 17 U.S.C. §105, public domain | none; credit USCG by custom |
-| `eu/cevni` | CEVNI Rev.6 (UNECE) | largest | **unverified** — unece.org unreachable from the checking host; the UN default terms are personal, non-commercial only. Blocked until written permission is obtained or a national transposition is chosen instead | — |
+| `eu/cevni` | CEVNI Rev.6 (UNECE) | largest | **unverified** — unece.org unreachable from the checking host; the UN default terms are personal, non-commercial only. Text blocked until written permission or a national transposition; structure may be modelled now with the text withheld — ADR 0010 | — |
 | `ca/inland` | Collision Regulations, C.R.C. c.1416, Schedule 1 | moderate | Reproduction of Federal Law Order SI/97-5 | none; accuracy diligence required, and must not be represented as an official version |
 | `de/binnen` | SeeSchStrO (delta) + KVR, Anlage to SeeStrOV (text) | large | §5(1) UrhG, no copyright | none |
 | `uk` | SI 1996/75 (delta) + MSN 1781 (text) | near-zero | OGL v3.0, Crown copyright | "Contains public sector information licensed under the Open Government Licence v3.0." |
@@ -141,6 +142,9 @@ what it implies for which instrument supplies the Rules *text*.
    or a national transposition under an open licence (Germany's BinSchStrO
    under §5(1) UrhG, or the Netherlands' BPR) — the same corpus by a lawful
    route, at the cost of being a national delta rather than "CEVNI".
+   A third way opened later: ADR 0010 permits modelling CEVNI now, text
+   withheld. These two remedies restore the text; they no longer gate the
+   work.
 8. **IMO's own text is closed to this package.** The IMO website terms
    permit copying and adaptation "for the User's personal, non-commercial
    purposes" and state that "Reuse of the Materials for commercial purposes
@@ -192,3 +196,32 @@ is not made here.
   <https://www.un.org/en/about-us/terms-of-use>.
 - IMO: <https://www.imo.org/en/About/Conventions/Pages/COLREG.aspx>;
   <https://www.imo.org/en/About/Pages/IMO-Website-Terms-and-conditions-of-use.aspx>.
+
+### 2026-09-09 — Independent re-check (issue #75), plus per-language corpus sources (Q-7)
+
+Re-fetched issue #75's primary sources; checked Q-7's three per-language
+corpus candidates, previously unchecked. Q-6 (authenticity) verified
+2026-08-30.
+
+#### Six jurisdictions — confirms 2026-09-05 verbatim, nothing changed
+
+| Jurisdiction | Re-checked against | Result |
+|---|---|---|
+| `us` | [17 U.S.C. §105](https://uscode.house.gov/view.xhtml?req=granuleid:USC-prelim-title17-section105&num=0&edition=prelim) | Confirmed: "Copyright protection under this title is not available for any work of the United States Government." Public domain, as recorded. |
+| `uk` | [OGL v3.0](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/) | Confirmed: copy/adapt/exploit commercially permitted; required attribution string matches; excludes third-party rights. As recorded. |
+| `au` | [legislation.gov.au terms-of-use](https://www.legislation.gov.au/terms-of-use) | Confirmed CC BY 4.0; both attribution strings (unchanged/adapted) match verbatim. As recorded. |
+| `de` | [§5 UrhG](https://www.gesetze-im-internet.de/urhg/__5.html) | Confirmed: §5(1) excludes Gesetze, Verordnungen, amtliche Erlasse und Bekanntmachungen from copyright outright; §5(2)'s conditions apply only to the other class of official works. As recorded. |
+| `ca` | [Reproduction of Federal Law Order, SI/97-5](https://laws-lois.justice.gc.ca/eng/regulations/SI-97-5/page-1.html) | Confirmed: reproduction permitted "provided due diligence is exercised... and the reproduction is not represented as an official version." As recorded. |
+| `eu/cevni` | [unece.org/copyright](https://unece.org/copyright) (403), [unece.org/general/copyright-notice](https://unece.org/general/copyright-notice) (403); [un.org copyright](https://www.un.org/en/about-us/copyright), [un.org terms-of-use](https://www.un.org/en/about-us/terms-of-use) | Both unece.org paths 403 again — independently reproduces "unreachable" rather than assuming it. UN default terms confirmed restrictive: "personal, non-commercial use... no right to resell, redistribute... or create derivative works." Still blocked, not merely unclear — no change. |
+
+#### Per-language corpus sources (Q-7) — new ground, mixed result
+
+| Source | Checked against | Verdict |
+|---|---|---|
+| BOE (`es`) | [boe.es/informacion/aviso_legal](https://www.boe.es/informacion/aviso_legal/index.php) (the path Q-7 guessed, `boe.es/aviso_legal/`, 404s) | Clean — permits the reuse REQ-PROV-2 needs. Commercial + non-commercial reuse; required attribution ("Fuente de los datos: Agencia Estatal Boletín Oficial del Estado", or "Basado en datos de..." for derivatives); consolidated texts must not be represented as official. Matches Q-7's guess; cheapest language to unblock. |
+| UNTS (`en`/`fr`) | [un.org terms-of-use](https://www.un.org/en/about-us/terms-of-use), [un.org copyright](https://www.un.org/en/about-us/copyright), [treaties.un.org FAQ](https://treaties.un.org/pages/Overview.aspx?path=overview%2Ffaq%2Fpage1_en.xml) (no copyright content) | Ambiguous, new concern — no UNTS-specific rights page found; the only primary terms reachable were the UN's general "personal, non-commercial... no derivative works" terms, the same ones blocking CEVNI. Weakens rather than confirms Q-7's "UNTS deposit is likely lawful" assumption. Resolves via a UNTS-specific rights statement, written UN permission, or a national republication (the `de`/`uk`/`ca`/`us` pattern already used for `intl`). |
+| Finlex (`fi`) | [finlex.fi](https://www.finlex.fi/en/), [finlex.fi/en/legislation](https://www.finlex.fi/en/legislation/), [Tekijänoikeuslaki 404/1961](https://www.finlex.fi/fi/laki/ajantasa/1961/19610404) | Inconclusive — no terms/copyright text was present in the fetched HTML (JS-rendered shells); §9's carve-out for *säädökset* could not be confirmed from primary text. A secondary source (Electronic Frontier Finland) reports a live, contested Finlex copyright claim over compiled statute text. Resolves via a JS-capable fetch of §9 and Finlex's actual ToS page. |
+
+`es` clears REQ-PROV-2; `fi` and `en`/`fr` via UNTS stay open. Updating
+`docs/requirements.md` Q-7 for this is left as a follow-up (concurrent
+edits to that file are in flight elsewhere).

package/docs/adr/0003-language-as-a-dimension.md

@@ -124,7 +124,7 @@ consumer's call (the spirit of REQ-CONS-3).
 ### Sketch (illustrative, not binding on filenames)
 
 ```text
-data/rules.json                     # skeleton: paths, rule numbers, gaps
+data/rules.json                     # skeleton: paths, numbers, gaps, text_status
 data/text/intl.en-US.uscg.json      # today's text, relabeled for what it is
 data/text/intl.fr.unts.json         # authentic French, when licensed+landed
 data/text/intl.fi.finlex.json       # Finnish national text, contributable

package/docs/adr/0009-data-version-stamp.md

@@ -0,0 +1,47 @@
+# ADR 0009 — `data/version.json` is the single version stamp for `data/`
+
+Date: 2026-09-08
+Status: accepted
+
+## Context
+
+Nothing in this package's schema or data files carries a version anywhere a
+consumer can check it against. colregs-engine's `Evaluation.colregs.version`
+names the engine's own resolved npm dependency, not the `data` object it was
+actually handed — so a caller evaluating against a stale cached fixture, a
+monorepo with mismatched `colregs` versions, or applicability data
+reconstructed by hand from an old export gets a result silently attributed
+to whatever release happens to be resolved locally: not a crash, not a
+warning, just a wrong-but-plausible `Evaluation`.
+
+Two alternatives were considered and rejected:
+
+- **A `version`/`dataVersion` field on each of the seven `data/*.json`
+  files.** The files already release as one unit — one npm version, one
+  `package.json` — so seven independent copies can only drift, never add
+  information.
+- **Leaning on the npm package version alone (status quo).** That is
+  exactly what colregs-engine already does, and exactly what it cannot
+  verify against, because the installed package version and the data
+  actually passed into `evaluate()` are two different things once the data
+  crosses a process/cache/file boundary.
+
+## Decision
+
+A single manifest, `data/version.json`, is the one source of truth:
+
+- `{"version": "<semver>"}`, matching `package.json` at release time.
+- `schema/version.schema.json` validates it, same pattern as every other
+  `data/*.json` file.
+- `release-please-config.json`'s `extra-files` generic JSON updater keeps
+  it in sync on every release, the same way `.release-please-manifest.json`
+  already is — the version cannot go stale without the release itself
+  failing.
+
+## Consequences
+
+- colregs-engine (or any consumer) can compare its resolved package version
+  against `data/version.json` at the point `evaluate()` receives `data`,
+  and throw or warn on a mismatch instead of silently reporting the wrong
+  version. That comparison is a colregs-engine change, tracked separately.
+- `data/version.json` is never hand-edited; release-please owns it.

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

@@ -0,0 +1,123 @@
+# ADR 0010 — A jurisdiction may ship without its rule text
+
+Date: 2026-09-09
+Status: accepted
+
+## Context
+
+REQ-PROV-2 blocks a jurisdiction until its reproduction terms are checked
+against the primary source. Three passes have now checked CEVNI's and come
+back the same way: unece.org is unreachable from the checking hosts (403,
+reproduced independently), and the UN's default terms grant personal,
+non-commercial use with "no right to resell, redistribute, or create
+derivative works" — see ADR 0001's 2026-09-05 and 2026-09-09 amendments. The
+remedies named there — written permission from UN Publications, or a national
+transposition such as Germany's BinSchStrO — are both slow, and one of them
+is somebody else's decision.
+
+Meanwhile `eu/cevni` has sat in the jurisdiction vocabulary
+(requirements.md §2) as a value nothing may populate, and every session that
+has looked at it has read "licence blocked" as "jurisdiction blocked" and
+stopped.
+
+That reading is wrong, and it is the cost here. What this package is for is
+**evaluating rules correctly**: which entries apply, what modality they
+carry, which gates they turn on. None of that needs a word of the rule text.
+A licence forbidding reproduction of an expression does not forbid modelling
+what the expression provides, any more than a copyright in a timetable
+forbids knowing when the train leaves.
+
+## Decision
+
+**A jurisdiction whose reproduction terms fail or cannot be verified MAY be
+implemented as structure, with its text withheld.** REQ-PROV-2 continues to
+govern *reproducing text*; it does not govern *modelling rules*. Structure
+here means everything except the words: paragraph paths, rule numbers,
+applicability entries, facts, gates, geometry, modality, and the relations
+between a jurisdiction's paragraphs and the international ones.
+
+Referencing a rule by number is not reproduction: a citation is a fact about
+which provision is invoked, not its protected expression, and the package
+needs nothing more than that to be correct.
+
+**Mechanism.** `data/rules.json` gains a per-paragraph `text_status`:
+
+| `text_status` | `text` | meaning |
+|---|---|---|
+| `verbatim` (default when absent) | required | today's state: the source's own words |
+| `withheld` | MUST be absent | the paragraph is modelled; its text is not ours to ship |
+
+A `withheld` paragraph carries a `withheld_reason` naming the licence
+barrier, and its `rule_title` MUST be a neutral label written for this
+package — "Overtaking", "Sound signals in reduced visibility" — never a
+heading copied from the source. Where a withheld paragraph is substantively
+the same provision as an international one, it carries `mirrors`, a path
+into the `intl` ruleset; a consumer may then display the international text
+**labelled as the international equivalent**, never as that jurisdiction's
+text. CEVNI is largely a restatement of the Rules for inland waters, so
+`mirrors` should cover most of it, leaving the genuine CEVNI-only provisions
+as the short list that shows a placeholder.
+
+### ✎ What a withheld paragraph carries in place of text — pencil
+
+**Ink is only that the text is withheld and the structure ships.** What
+stands in for the text is deliberately *not* settled here, and this ADR does
+not license a later session to settle it by inference. Any of the following
+may be adopted, dropped or combined before a general release without another
+ADR, and more than one may ship at once — they occupy different keys:
+
+| option | key | note |
+|---|---|---|
+| **Redaction** — the citation alone | — | the floor; ships today, needs no decision |
+| **Digest** — a hash of the normalised text, algorithm-qualified | `text_digest` | lets a holder of a lawful copy bind it to our structure, and catches a silent upstream amendment |
+| **Slug** — key nouns and verbs lifted from the paragraph, lemmatised, English counterparts where the source is another language | `text_slug` | the straw man below |
+| **`mirrors`** — the `intl` equivalent | `mirrors` | real, lawful text for the majority of CEVNI; silent exactly where CEVNI differs |
+
+**Straw man for the slug**, so the option is designed against something
+rather than argued about in the abstract: take the paragraph, keep the key
+nouns and verbs, drop everything else, lemmatise, emit a sorted set —
+`blue-board`, `overtake`, `sound-signal`. Deterministic, reproducible from
+the same input, no word order, no syntax, no prose. Where the source is not
+English, the terms map to their English counterparts, which is the same
+vocabulary the applicability entries already use. Build it and judge it; it
+may be replaced or dropped. See the research issue.
+
+Nothing here turns on where the line between indexing and a derivative work
+falls. That question is not this ADR's to answer and does not gate the work:
+redaction ships today whatever the answer, and the slug is a straw man to be
+built, investigated or thrown away later.
+
+How a withheld paragraph reads on screen is likewise a display choice, not a
+data one.
+
+## Consequences
+
+- **No future session may record CEVNI as blocked.** It is unblocked for
+  structure as of this ADR, blocked for text until ADR 0001's licence
+  question is answered. The same route is open to any jurisdiction that
+  fails REQ-PROV-2 later; nothing here is CEVNI-specific.
+- **A different bar still stands, and it is not this one.** REQ-SCOPE-3 and
+  Q-11 hold that no non-`intl` jurisdiction lands until an explicit
+  suppression mechanism exists, because silence-means-inherit would apply
+  international law where a national body deliberately has none. That is
+  about deltas, not licences; it survives this ADR untouched and is the live
+  blocker on CEVNI. Read the two together or the wrong one gets blamed.
+- `schema/rules.schema.json` carries the conditional: `text` required unless
+  `text_status` is `withheld`, in which case it is forbidden and
+  `withheld_reason` is required. Only `withheld_reason` is refused on a
+  verbatim paragraph; `mirrors`, `text_digest` and `text_slug` are open to
+  any paragraph, defined but unwritten, so the pencil options above cannot be
+  foreclosed by `additionalProperties: false`. Additive under ADR 0006. Since
+  `data/rules.json` is entirely verbatim `intl`, nothing in the data
+  exercises that branch — the cases are asserted in `test/data.test.mjs`.
+- **Nothing in evaluation may read `text`.** That is the invariant this
+  decision rests on, so it wants a test rather than a promise: fixtures and
+  the evaluator output envelope must stay green over a ruleset with every
+  `text` stripped.
+- REQ-PROV-1 still binds: a withheld paragraph records its source, its
+  retrieval date and why the text is absent. Withholding is a provenance
+  record, not a gap in one — and not a `gaps` entry either, which keeps its
+  meaning of a paragraph we could not obtain at all.
+- The licence question stays open where it already is. If permission or a
+  national transposition arrives, `withheld` paragraphs gain their text and
+  drop the key; no modelling is redone.

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

@@ -0,0 +1,173 @@
+# ADR 0011 — The public API: one verb per input
+
+Date: 2026-09-07
+Origin: colregs-engine, where it was ADR 0001 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: accepted. Ink and pencil are marked per item in the register at the
+end, under colregs' `docs/conventions.md`.
+
+## Context
+
+The engine shipped one entry point, `evaluateDisplay`, and its README promised
+that colregs' `classification` and `precedence` categories would "get their own
+entry points" — a promise made in passing while renaming, with no target to
+build to. Meanwhile colregs' ADR 0005 (pencil, all of it) fixed the *input*
+those categories read: a situation record in `data/facts.json` §`situation`,
+exercised by `fixtures/situation-fixtures.json`, with some twenty two-subject
+entries written against it. The data side exists; the engine side has no shape.
+
+This ADR fixes the shape. It does not build it.
+
+## Decision
+
+### 1. Two inputs, two verbs
+
+| input | verb | result | status |
+|---|---|---|---|
+| `FactRecord` — one vessel | `evaluateDisplay` | `DisplayEvaluation` | built |
+| `Situation` — two vessels and the encounter | `evaluateEncounter` | `EncounterEvaluation` | target |
+
+A verb is named for the thing it evaluates, in colregs' own vocabulary: a
+*display* is what one vessel shows, an *encounter* is what colregs calls the
+`pair` subject. The proposed pair `classifyEncounter` / `resolvePrecedence`
+is **not** built, for three reasons that are about the data, not taste:
+
+- **One predicate pass.** Every `scope`, `classification` and `precedence`
+  entry matches the same situation by the same walker, as colregs' reference
+  evaluator does; two verbs run it twice or make the caller carry the type on.
+- **Relations cross categories.** Rule 18's precedence entries override Rule
+  15's; entry `13a` overrides every Rule 18 entry. `rel:overrides` can only be
+  resolved with both sides applied in the same result.
+- **Q-35 is open.** Whether a norm may read another norm's *effect* (8(f)(iii)
+  reads "a vessel whose passage is not to be impeded") is unsettled in colregs.
+  An API seam here would settle it by accident, in the wrong repository.
+
+Each verb has a companion that returns only the matched entry ids —
+`appliedDisplayEntries` today, `appliedEncounterEntries` to come — because
+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
+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,
+not the thing.
+
+### 3. The `Situation` type mirrors the fixture, not the predicate
+
+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
+**nested** form. The flat form is the predicate namespace and stays internal
+to the walker.
+
+```ts
+interface Situation {
+  own: Subject;
+  other?: Subject;
+  pair?: Pair;
+}
+interface Subject { fact: FactRecord; kin?: Kinematics; geo?: DirectionalGeometry; hist?: History; }
+interface Pair    { geo?: PairGeometry; env?: Environment; }
+```
+
+- `own` 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.
+- Keys keep their full colregs identifier (`'kin:heading_deg'`, not
+  `heading_deg`), as `FactRecord` keeps `'fact:length_m'`. A fixture's
+  `situation` object is then assignable to `Situation` unedited.
+- `Kinematics`, `History`, the two geometries and `Environment` are
+  **generated** from `facts.json` §`situation` by the generator that produces
+  `FactRecord`, and checked by the same validator: a situation arriving as
+  JSON is rejected on the same terms as a fact record.
+- `FactRecord` is reused, not copied, as `Subject.fact`.
+
+### 4. `EncounterEvaluation`, the target result
+
+```ts
+type EntryId = string;       // a colregs entry id: '13a', '18b'
+type ParagraphCite = string; // a Rules paragraph cite: '17(c)'
+
+interface EncounterEvaluation {
+  colregs: { version: string; source: 'resolved' | 'caller' };
+  applied: EntryId[];
+  scope: EntryId[];
+  encounter?: 'head-on' | 'crossing' | 'overtaking' | 'none';
+  risk_of_collision: { asserted: boolean; by: EntryId[] };
+  roles: { own: SubjectRole[]; other: SubjectRole[] };
+  overridden: { id: EntryId; by: EntryId }[];
+  modalities: Record<EntryId, Modality>;
+}
+interface SubjectRole { role: Role; by: EntryId; }
+```
+
+`EntryId` and `ParagraphCite` are both `string`, marking which vocabulary a
+field holds: `applied` and `overridden` cite entries, ADR 0012's `phase` and
+`breaches` cite paragraphs. Field names are snake_case with unit suffixes
+throughout, as colregs' own keys are (`kin:heading_deg`).
+
+`colregs` and `applied` mean what they mean on `DisplayEvaluation`. Roles are
+a *set* per subject, each citing the entry that assigned it: colregs' own
+suite pins a sailing vessel meeting a CBD vessel as holding `stand-on` and
+`shall-not-impede` at once (Q-36), and a result type that could hold one role
+would have to lie. `risk_of_collision` carries its grounds because 7(a) lets an
+entry add a ground and never deny one. `encounter` is absent when no
+classification entry fired, conflating "no encounter" with "cannot say" (Q-43);
+ADR 0005 §5's status alphabet is the fix, and is not part of this shape yet.
+
+### 5. What this shape does not evaluate
+
+Scoped to `evaluateDisplay`/`evaluateEncounter` as defined here, not a ceiling
+on the package; kinematic and temporal evaluation gets two verbs in ADR 0012.
+
+- **`conduct`.** Rules 8, 13(a)'s action, 14(a), 16, 17: what a vessel shall
+  *do*. Their predicates read a trace — 8(b)'s "readily apparent" alteration,
+  17(a)(ii)'s "as soon as it becomes apparent" — and colregs declares
+  `kin:rot_deg_min` read "by a conduct monitor, not by a predicate at a point".
+  A different input (a trace: a sequence of situations) and a different tool
+  (STL/TLA+): `evaluateConduct`, ADR 0012.
+- **`care` and `meta`.** Rules 2(a) and 2(b) are in colregs'
+  `represented_paragraphs` registry precisely so nothing computes them.
+- **The Rule 2 region solver** (R0/R1/R2, research-ontology labels, not API).
+  Research under `research/`; its runtime face is `evaluateRule2Departure`,
+  ADR 0012.
+- **Time.** Freshness, hysteresis and the 13(d) latch's clock are the caller's;
+  the engine receives `hist:*` as facts and does not maintain them.
+- **Choosing.** No verb picks a display or a role; every lawful answer is
+  returned (REQ-MODEL-8).
+
+In scope and expected of `evaluateEncounter`: derived facts (`fact:rule18_class`
+is computed before matching, as colregs specifies), `rel:overrides`
+resolution, and validation of the situation record.
+
+## Consequences
+
+- The README paragraph promising separate classification and precedence
+  entry points is replaced by a pointer here.
+- The next PR builds `Situation` generation and validation; the one after
+  `appliedEncounterEntries` against `situation-fixtures.json`; only then
+  `evaluateEncounter`. Composition decisions the data leaves open go in
+  `docs/engine-notes.md`, as the display ones did.
+- `colregs-engine/schema` stays the home of mirrored colregs shapes; `Situation`
+  and `EncounterEvaluation` are engine vocabulary, exported from the root.
+
+## Register
+
+| item | level | what would settle it |
+|---|---|---|
+| Two verbs, one per input; no `classifyEncounter` / `resolvePrecedence` | ink | — |
+| `evaluateDisplay`, `appliedDisplayEntries`, `DisplayEvaluation`, `opts.data`, `colregs.source` | ink | — |
+| `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 |
+| `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 |
+| `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 |