colregs 0.1.0 → 0.2.0

package/docs/adr/0005-rule-categories-and-the-situation-record.md

@@ -0,0 +1,323 @@
+# ADR 0005 — Rule categories, the situation record, and the Rule 2 region
+
+Date: 2026-09-04
+Status: accepted, **all of it in pencil**
+
+Everything this ADR records is `✎` **pencil** under
+[`docs/conventions.md`](../conventions.md): any session may change any of it
+for a better idea, logging the change and what would settle the item. That is
+the decision — proceed on this shape — not a claim that the shape is right.
+The house default for an ADR is ink; this one inverts it deliberately and
+says so once here rather than marking every paragraph.
+
+## Context
+
+Part C (lights and shapes) was modelled first because it is the easy half:
+one vessel's facts in, a set of lights out. `REQ-PART-4` then declared Part B
+— the steering and sailing rules — out of scope and possibly permanent:
+"they govern conduct between two vessels, not the appearance of one, and the
+fact record is single-vessel by construction."
+
+The second clause is the real one, and it is a statement about the *input*,
+not about whether Part B can be modelled. Proposal
+`2026-09-04-rule-categories-v4.md` in `colregs-engine`
+(`docs/proposals/`) works out what input Part B actually needs, and what
+happens to the rest of the model once the answer is "a pair of vessels, with
+kinematics". It went through seven outside reviews across four drafts (three
+Claude subagents, codex, Gemini 3.1 Pro); the reviews are in that repo. Mark
+approved it on 2026-09-04 with everything in pencil, API breaks allowed
+while the package is 0.x.
+
+This ADR records that approval and amends `REQ-PART-4`. It does not
+re-argue the proposal; the proposal is the reasoning, this is the decision.
+
+## Decision
+
+### 1. Every rule paragraph carries exactly one category
+
+Nine values, a closed set:
+
+| category | reads | produces | who evaluates it |
+|---|---|---|---|
+| `definition` | — | vocabulary | n/a |
+| `standard` | — | technical values (ranges, heights) | n/a |
+| `scope` | visibility, in-sight, jurisdiction | which sections apply | engine |
+| `display` | one vessel's facts | signals + modality | engine |
+| `classification` | relative geometry, history | encounter type, risk of collision | engine |
+| `precedence` | two vessels' facts + encounter type | give-way / stand-on / shall-not-impede / none | engine |
+| `conduct` | encounter + role + phase + kinematics + observations | obligated or prohibited action | monitored over a trace, not evaluated at a point |
+| `care` | anything | residual responsibility | represented, never independently evaluated |
+| `meta` | the region state (§4 below) | banner + advisories | computed by a solver, reviewed by humans |
+
+The unit is the **paragraph**, as everywhere else in this package
+(ADR 0001). `care` is Rule 2(a) alone; `meta` is Rule 2(b) alone. Part D
+(Rules 32–37) has no category yet and stays blocked on `REQ-PART-3`'s ADR.
+
+One category per paragraph holds because dual roles are *relations*, not
+second categories: 13(a) is `classification`, and its effect on Rule 18 is
+`rel:overrides` from 13 to 18. The proposal's first-cut membership table is
+pencil paragraph by paragraph; the nine names are pencil as a set.
+
+`display` is the default, so every entry in `data/applicability.json` today
+is already correctly categorised without being touched.
+
+### 2. Part B reads a situation; the fact record does not change
+
+The per-vessel fact record — `data/facts.json`, the three axes, the
+scalars — is unchanged, and nothing in this ADR renames or repoints an
+identifier in it (`REQ-MODEL-10`).
+
+A **situation record** wraps it: two fact records, a kinematic state per
+vessel, relative geometry, and history. **Kinematic state is a new fact
+class** — position, heading, speed, rate of turn, and a dynamics class
+(tanker, ferry, yacht, …) — not an extension of the existing one. A
+consumer that only shows lights never constructs a situation and never
+reads a kinematic fact.
+
+The fixture format cannot carry a situation, so a fixture-schema step
+precedes any two-subject data. Existing fixtures are untouched and stay
+valid.
+
+### 3. `care` and `meta` are not entries
+
+Rules 2(a) and 2(b) do not produce lights, and evaluating them is precisely
+what this package must not do. They go in a **sibling registry beside
+`known_omissions`** in `data/applicability.json` — recorded, addressable,
+citable, and deliberately not evaluable. A registry entry is the machine-
+visible statement "this paragraph exists, this package represents it, and
+nothing here computes it".
+
+### 4. Two new modalities, and a sixth relation
+
+`shall-not` and `shall-not-impede` join `shall`, `may`,
+`shall-if-practicable`, `conditional` and `exempt`. Both are needed by
+Part B and neither is expressible as a negated `shall`: `shall-not-impede`
+is a distinct duty in the rules' own vocabulary (18(d), 8(f)), and 8(f)(iii)
+restores full Section II duties once risk of collision exists.
+
+`rel:overrides` joins the five relations of `REQ-MODEL-7` as a sixth. It is
+the superiority relation — "this paragraph's requirement prevails over
+that one's" — carrying Rule 18's "except where Rules 9, 10 and 13 otherwise
+require". It is checkable: a solver looks for cycles, and for two `shall`
+norms in conflict with no override between them.
+
+### 5. The status alphabet, and the R0/R1/R2 ontology as the research goal
+
+The engine's output carries one of four statuses, fixed as a closed
+alphabet: `not-flagged`, `model-rule-conflict`, `no-robust-policy-in-model`,
+`inconclusive-in-model`. Each says what the *model* knows and nothing about
+what the law concludes; `not-flagged` means "not flagged by this model",
+never "the rules suffice".
+
+The alphabet is the surface of an ontology this project states as its
+**research goal**, not as an implemented feature. With `Safe(s, σown,
+σother)` meaning no invariant violation within a horizon *T*, and *A* a
+declared set of admissible other-vessel strategies:
+
+| region | definition |
+|---|---|
+| **R0** rules-suffice | ∃ compliant σown ∀ σother ∈ A: Safe |
+| **R1** departure-required-in-model | ¬R0 ∧ ∃ σown ∀ σother ∈ A: Safe |
+| **R2** unwinnable-in-model | ¬∃ σown ∀ σother ∈ A: Safe |
+
+R1 is a model finding bearing on Rule 2(b), not a legal classification.
+Rule 2 is not evaluated at runtime as a predicate; it names a *region* of
+situation space that a game solver computes offline, and Rule 2 is
+deliberately absent from the compliance predicate or the definition is
+circular.
+
+None of this lands in `colregs`. The solver, the region grid and the output
+envelope live in `colregs-engine`; what this package owes them is the
+category field, the registry, the modalities and `rel:overrides`. The
+ontology is recorded here so the data decisions above have a stated purpose
+and so a later reader can see what they were shaped for.
+
+### 6. `REQ-PART-4` is superseded, not deleted
+
+`REQ-PART-4` said Part B is out of v1 scope and may never be modelled. The
+scope half stands: Part B is out of v1, Part C for `intl` completes first
+(`REQ-PART-1`), and nothing in this ADR ships data. The "may never" half
+does not: the obstacle it named — a single-vessel fact record — is
+addressed by the situation record without changing that record. The
+requirement is struck through in place and replaced by `REQ-CAT-1..5`, per
+the ID-stability rule in the requirements preamble. No requirement ID is
+reused.
+
+## Pencil changed since
+
+Logged here rather than left to a commit message, as `docs/conventions.md`
+requires of a pencil change.
+
+- **2026-09-04, PR #24 — 13(a) is `precedence`, not `classification`.** §1
+  above gives 13(a) to `classification` and says its effect on Rule 18 is a
+  relation. The relation part held: entry `13a` carries `rel:overrides`
+  against every Rule 18 entry. The category did not. 13(a) is the one
+  paragraph of Rule 13 that assigns a role — the overtaking vessel keeps out
+  of the way — and a `classification` entry produces an encounter type, with
+  nowhere to put a role. 13(b) is the classification: it is the sector test
+  that sets the `hist:was_overtaking` latch, and it is not yet written.
+  Tracked as `Q-37`; it does not disturb the one-category-per-paragraph rule,
+  which is what §1 was really defending.
+- **2026-09-04, PR #24 — a fifth fact class, `env`, `pair`-only.** §2 names
+  four classes. Rules 9 and 10 are scoped to *places*, and a narrow channel is
+  neither a vessel's fact nor the pair's geometry. `pair:env:narrow_channel`
+  and `pair:env:traffic_lane` are the addition; `fixtures/situation-fixtures.json`
+  had already recorded the gap before the class existed.
+- **2026-09-04, PR #24 — `effect` is the fourth new field.** §4 widens
+  `modality` and adds `rel:overrides`; it does not say what a norm that
+  produces no lights produces instead. `effect` is that, written up in
+  `docs/identifiers.md` §"Effects" and required by `REQ-CAT-8`.
+
+- **2026-09-04, PR #25 — the predicate language grows `not` and `any_of`.**
+  `Q-33`. ADR 0005 says nothing about the predicate language because it did not
+  expect to need to; the first two-subject data found that a conjunction of
+  equalities cannot say "any vessel other than …" (18(d)(i)) or "under 20 m or
+  a sailing vessel" (9(b), 10(j)). Both constructs live in `satisfies` and one
+  shared walker, so both evaluators get them. The absent-fact rule is extended
+  rather than excepted: `not` over an absent fact is unsatisfied, so a
+  predicate never fires on silence. `9b-small`/`9b-sail` and
+  `10j-small`/`10j-sail` collapse to `9b` and `10j`; the four suffixed ids are
+  retired and recorded in `retired_entry_ids`, and never reused
+  (`REQ-MODEL-10`). Nothing has shipped a Part B entry, so retirement is free
+  once and will not be again.
+- **2026-09-04, PR #25 — a fact may be derived.** `Q-32`. §2 says the
+  per-vessel fact record does not change, and it does not: `fact:rule18_class`
+  is a new key in a new `derived` section, computed by this package from the
+  record rather than supplied with it, with a decode table as its definition in
+  the style `signalk_navigation_state` already set. It is the answer to the
+  largest strain the first two-subject data found — that `fact:activity` is a
+  display axis and Rule 18's rank is not the same thing — and it is what lets a
+  `precedence` entry stop enumerating activity values it must be edited to keep
+  correct. One new boolean, `fact:tow_restricts_deviation` (27(c)), because the
+  rank genuinely needs a fact the record did not carry.
+
+- **2026-09-04, PR #26 — a `classification` effect has two shapes, and Rule 12
+  is not one of them.** §1 gives `classification` two outputs at once —
+  "encounter type, risk of collision" — and §4 says nothing about what a
+  classification entry produces. It produces an `effect` with exactly one key:
+  `{"encounter": "head-on"|"crossing"|"overtaking"|"none"}` for Rules 13, 14 and
+  15, or `{"risk_of_collision": true}` for 7(d)(i). Two shapes rather than one
+  merged shape, because a merged one would have made every encounter entry state
+  a risk it does not decide. There is no `false`: 7(a) deems risk to exist in
+  any doubt, so an entry may add a ground for risk and nothing here may deny
+  one. Written up in `docs/identifiers.md` §"Effects" and required by
+  `REQ-CAT-8`.
+  **Rule 12 departs from §1's table** the way 13(a) did in PR #24 and for the
+  same reason: 12(a) assigns a role, and a classification effect has nowhere to
+  put one. `12a1`–`12a3` are `precedence`; 12(b) is a `definition` and is the
+  cite on the new `kin:wind_side` fact rather than an entry. `Q-40`.
+- **2026-09-04, PR #26 — the partition is a property of the data, not of the
+  engine.** The proposal's verification column gives `classification` an "Alloy
+  partition". The data-level half of it is asserted here: 13(b)'s sector is one
+  constraint object, Rule 15's crossing is `not` over that same object, and Rule
+  14's cone is negated the same way inside an `any_of`, so no crossing sector is
+  enumerated and the three encounter types cannot overlap or leave a gap unless
+  someone edits one of two constraints without the other. The suite sweeps both
+  subjects' bearings in half-degree steps over all 518 400 points. Recorded as
+  `REQ-CAT-9`, which also requires that a threshold the Rules do not state be
+  declared once in `data/facts.json` under `situation.constants` and read from
+  there — `appreciable_bearing_change_deg_min` (pencil, 1.0 °/min) and
+  `head_on_half_angle_deg` (pencil, 11.25° — one point of the compass, the same
+  angular vocabulary 13(b)'s two points come from) are the two that were
+  invented; the two `overtaking_sector_*_deg` are ink, because 13(b) states
+  them.
+- **2026-09-04, PR #26 — the `ram` refinement was a special case and is now a
+  property of the value.** Not a design decision so much as a defect PR #25
+  recorded and this one repaid: `activity:ram_underwater` matched a predicate
+  written for `activity:ram` under scalar equality and, silently, not under list
+  membership. The `fact:rule18_class` decode carried an `any_of` written to work
+  around it. The refinement now expands the value once, so equality, membership
+  and each `any_of` disjunct read it alike, `not` still negates the refined
+  reading, and the decode row is a bare list again.
+
+Sixteen things the model could not express are recorded as `Q-31`–`Q-48` in
+`docs/requirements.md` §11 rather than bent into the data. The largest is
+`Q-32`: `fact:activity` is a display axis, and a vessel's rank under Rule 18
+is not the same thing as the lights she shows.
+- **2026-09-05, PR #35 — Rules 13 and 18 override Rule 12.** §4's sixth
+  relation was written down for Rules 9, 10 and 13 over Rule 18, and for 18(f)
+  within it. Rule 18's chapeau excepts only those three, so where Rule 18 and
+  Rule 12 are both in force — two sailing vessels, one of them fishing or not
+  under command — Rule 18 governs: `18b1`–`18b3` and `18c1`–`18c2` carry
+  `rel:overrides` against `12a1`–`12a3`, and `13a` does too. The Rule 12
+  entries now read 3(c) rather than the Rule 18 rank, which is what made the
+  relation necessary. `Q-40`.
+- **2026-09-05, PR #36 — the head-on classification cites 14(b).** §1 gives
+  each paragraph one category. 14(a) is `conduct` — it prescribes the
+  alteration to starboard — and 14(b) is the deeming test, which is what a
+  `classification` entry evaluates, as 13(b) is for overtaking. Entry `14a` is
+  retired and `14b` cites the paragraph it reads. `Q-45`.
+- **2026-09-05, PR #46 — Rule 18 overrides Rule 15, and Rule 15 reads 3(b).**
+  The other half of the same question. `15a-give-way` kept the four Rule 18
+  ranks — NUC, RAM, fishing and WIG — out of Rule 15 by negating them on both
+  subjects in its own predicate. That is the sixth relation written as a gate:
+  it produced the right roles wherever Rule 18 spoke, and the wrong ones where
+  Rule 18 is silent, because two vessels engaged in fishing under power, or a
+  NUC and a RAM under power, took no helm role from any entry at all. The gate
+  is gone; `18a1`–`18a3`, `18c1`–`18c2` and `18f1` carry `rel:overrides`
+  against `15a-give-way`. Where Rule 18 does not order the pair, Rule 15 now
+  does — including onto a vessel that may be unable to discharge the duty,
+  which is §5's Rule 2 region and is recorded rather than gated. `13a` needs no
+  override here: `15a-give-way` excludes every overtaking by the `hist`
+  latch and by 13(b)'s sector, and a test pins that so the absence stays a
+  reason rather than an oversight. `Q-40`.
+
+  The line this draws, since it is the second time the question has come up:
+  a condition on whether a paragraph *applies at all* belongs in the
+  predicate, and a condition on which of two applicable paragraphs *wins*
+  belongs in a relation. Rule 15 does apply to a fishing vessel under power;
+  what Rule 18 does is displace the role it assigns. Writing that as a gate
+  did not merely put the reason somewhere a test could not read it — it lost
+  the cases where the displacing paragraph is silent.
+
+## What is unchanged
+
+Stated plainly, because the value of the design above is mostly in what it
+does not disturb:
+
+- **The light rules.** Every entry in `data/applicability.json`, every
+  light, every relation, every predicate: unchanged.
+- **Every fixture.** `fixtures/applicability-fixtures.json` is untouched;
+  the cross-implementation contract (`REQ-VERIFY-1`) still holds exactly.
+- **Every test.** `npm test` passes on this PR with no data change at all.
+- **The fact record.** Kinematics are a new class beside it, not a change
+  to it.
+- **Identifiers.** Nothing renamed, nothing repointed (`REQ-MODEL-10`).
+
+This PR is documentation only. The data changes it authorises land later,
+additively, in the sequence the proposal sets out.
+
+## v0.x compatibility
+
+Concretely, for this package: `category` and `subjects` have defaults
+(`display`, `1`), so adding them is additive and no existing entry needs
+editing. The two new modality values and `rel:overrides` widen closed
+vocabularies, which is additive for a consumer that reads them and a
+breaking change only for one that exhaustively switches on the old set.
+
+Beyond that, while the package is `0.x`: **an API break is allowed if the
+design is wrong.** Field names, the situation record's shape, the registry's
+file and schema, and the fixture schema for situations are all pencil, and
+correcting one of them is worth a version bump rather than a compatibility
+shim. `REQ-PKG-4`'s major-version rule and `REQ-MODEL-10`'s immutability
+both continue to apply on their own terms — additive is still additive, and
+no identifier is ever repointed — but nothing here is a stability promise to
+consumers, and the README should not read as one until 1.0.
+
+## Consequences
+
+- `docs/requirements.md` gains `REQ-CAT-1..5` (§4.1) and `REQ-PART-4` is
+  struck through citing this ADR.
+- Eighteen pencilled items from the proposal are recorded as open questions
+  `Q-13`–`Q-30`, each with what settles it. Most are `colregs-engine`'s to
+  settle; they are listed here because this ADR is what makes them live.
+- `docs/conventions.md` is copied into this repo so the ink/pencil marker
+  read above is resolvable from inside it, and `CLAUDE.md` points at it.
+- No gate opens or closes. The category field, the registry and
+  `rel:overrides` are additive; none of them declines a design that gets
+  more expensive to adopt later, which is what `REQ-GATE-1` records.
+  `Q-10`'s `rel:conditional_includes` question gains a sixth verb to weigh
+  against, and is still decided in the second-jurisdiction bundle.
+- The proposal's step 1 is this ADR. Steps 2–4 (rule text for Rules 1–19,
+  the `care`/`meta` registry with the kinematic fact class, the engine
+  output envelope) can run in parallel once this lands.

package/docs/adr/0006-json-schema-and-identifier-diff.md

@@ -0,0 +1,95 @@
+# ADR 0006 — JSON Schema for structural validation, identifier diff for version discipline
+
+Date: 2026-09-04
+Status: accepted
+
+## Context
+
+`test/data.test.mjs` is the entire verification surface. It enforces
+referential integrity exhaustively — every cite resolves to `rules.json`,
+every light id to `lights.json`, every fact key to `facts.json`, every
+cross-reference to an entry — and it runs the fixture replay and drift
+test (REQ-VERIFY-1/2). What it does not check is *shape*: a misspelled
+key (`modaltiy`), a `count` given as a string, an unexpected top-level
+field, or a malformed `{gte, lt}` predicate all pass silently until some
+consumer trips on them.
+
+The package exists to be consumed without a JavaScript runtime
+(REQ-PKG-2). A consumer in Python or Rust cannot run the Node suite. It
+has no machine-readable statement of what a well-formed entry looks like;
+today that lives in prose in README.md and in the tests.
+
+A third question was raised at the same time: whether semantic versioning
+could be derived from a schema, so that a breaking change is detected
+mechanically rather than by the committer choosing a conventional-commit
+prefix.
+
+Alternatives considered and declined:
+
+- **CUE, TypeSpec, JSON-LD/SHACL.** Each can express more than JSON Schema
+  (CUE in particular can state cross-file constraints). None has a
+  validator a consumer of this package already runs, and each adds a
+  toolchain to a repo whose contract is "plain JSON, nothing else". The
+  extra expressiveness would only re-encode checks the test suite already
+  performs.
+- **Schema-derived semver** (`json-schema-diff` or equivalent in CI).
+  REQ-PKG-4 defines a breaking change as removal of an entry id, a fact
+  vocabulary value, or a change in relation semantics. All three are data
+  changes that leave the schema untouched. A schema diff would therefore
+  miss nearly every real break and flag only the rare structural one.
+- **Generating enums from data into the schema at test time.** Keeps the
+  schema "complete" but makes it a build product rather than a document,
+  and duplicates checks the suite already does. Declined; the schema
+  stays static and hand-written.
+
+## Decision
+
+**Ship hand-written JSON Schema 2020-12**, one schema per data file plus
+one for `fixtures/applicability-fixtures.json`, under `schema/`, listed in
+`package.json` `files` so consumers get it with the data.
+
+The schema covers **structure only**: required keys, types,
+`additionalProperties: false` at every object level, the id patterns from
+`docs/identifiers.md`, the closed enums for `modality` and the five
+relation verbs, the shape of predicate operators (`gte`/`gt`/`lte`/`lt`,
+list membership, equality), and the shape of a light reference
+(`light`/`position`/`count`).
+
+The schema does **not** attempt cross-file references. Cite-to-rule,
+light-to-definition, fact-to-vocabulary and entry-to-entry resolution
+stay in `test/data.test.mjs`. JSON Schema has no cross-document
+reference mechanism; a partial imitation would be a second, weaker copy
+of checks that already exist.
+
+**Validate in the suite with Ajv as a devDependency.** REQ-PKG-1 (zero
+runtime dependencies) governs what ships, not what tests. The published
+package stays dependency-free.
+
+**Version discipline comes from an identifier diff, not the schema.** A
+test extracts every published identifier — entry ids, fact axis values,
+light ids, relation verbs — from the last release tag (or the published
+npm tarball) and compares them with HEAD. Any removal not accompanied by
+a deprecation marker fails the build. This mechanises REQ-MODEL-10 and
+the "removal is major" clause of REQ-PKG-4. release-please still owns
+the version number; the test only refuses to let a silent removal reach
+it.
+
+## Consequences
+
+- A new file under `data/` needs a schema before it can merge, and the
+  schema needs a test that loads it. Schema and data change together.
+- `additionalProperties: false` means an experimental key in an entry
+  fails the build until the schema admits it. That is intended: the
+  schema is the record of what the shape is, and a key nobody wrote down
+  is a key nobody will maintain.
+- Consumers in other languages can validate a vendored copy of the data
+  against `schema/` with any 2020-12 validator. The schema is now part of
+  the public contract and is subject to REQ-PKG-4: removing a property or
+  narrowing a type is a major version.
+- The identifier-diff test needs the previous release available at test
+  time. In CI that is a `git fetch --tags`; locally it is whatever tag is
+  present. A missing baseline must fail loudly, not skip.
+- If a future jurisdiction or Part D landing needs a constraint that
+  spans files — "every `us/inland` entry overrides an `intl` id that
+  exists" — it goes in the test suite, not the schema. This ADR is the
+  answer to the next "should we use CUE" question.

package/docs/conventions.md

@@ -0,0 +1,27 @@
+# Conventions
+
+## Ink, pencil, open
+
+Design documents in this project mark each decision with a confidence
+level. The level is not a comment on the author's certainty; it is the
+**rule for who may change it and on what grounds.** A session reads the
+level before it reads the content, and behaves accordingly.
+
+| level | marker | who changes it | on what grounds |
+|---|---|---|---|
+| **Ink** | none (default in ADRs) | Mark | significant evidence: a counterexample, a verification result, a primary source. A session may argue, citing the evidence. It never edits ink itself. |
+| **Pencil** | `✎` | any session | a better idea. Log the change and why. Each pencilled item names what would settle it. |
+| **Open** | `?` | anyone proposes | a proposal moves it to pencil |
+
+How to ask a session about them:
+
+- "What's in pencil?" — list them, with what would settle each.
+- "Should we change this pencil item?" — give an opinion and change it if
+  Mark agrees, or on your own if the doc says the session may.
+- "Should we change this ink item?" — answer only with evidence. If there is
+  none, say "no evidence to reopen it" and stop.
+
+Ink and pencil are per item, not per document. A document is mostly ink
+with pencilled items, or mostly pencil with a few ink anchors; both are
+normal. Moving an item from pencil to ink is a decision Mark makes, and it
+gets a one-line log entry saying what settled it.

package/docs/gates.json

@@ -0,0 +1,84 @@
+{
+  "note": "Machine-readable mirror of the reversibility gates in docs/requirements.md \u00a710. Governance metadata about this repository, not COLREGS data \u2014 it deliberately lives in docs/ rather than data/, which is the consumer-facing model. REQ-GATE-3 is enforced against this file by test/data.test.mjs; the prose section is authoritative for the reasoning, this file is authoritative for status.",
+  "requirements": [
+    "REQ-GATE-1",
+    "REQ-GATE-2",
+    "REQ-GATE-3",
+    "REQ-GATE-4"
+  ],
+  "closing_events": {
+    "1.0-tag": "the 1.0 version tag \u2014 REQ-GATE-3 blocks it until every gate carrying this closing event has been re-taken",
+    "first-non-english-corpus": "the second corpus of any one jurisdiction, which in practice is the first non-English text",
+    "first-community-translation-of-national-corpus": "the first `community`-tier translation of a `national`-tier corpus",
+    "first-external-contribution": "the first merged contribution from someone other than the copyright holder",
+    "none": "the decline does not get cheaper or dearer with time; recorded so it is not re-read as merely deferred"
+  },
+  "statuses": {
+    "open": "declined for now, not re-taken; adoption still possible at the stated cost",
+    "re-taken": "reconsidered deliberately and confirmed as declined, in the cited ADR",
+    "adopted": "the declined design was subsequently adopted, in the cited ADR",
+    "declined-permanently": "declined on grounds that do not decay; no closing event exists"
+  },
+  "gates": [
+    {
+      "id": "GATE-1",
+      "title": "`paragraph_id` split from `citation_path`",
+      "declined_in": "docs/adr/0003-language-as-a-dimension.md",
+      "closing_event": "1.0-tag",
+      "trigger": "a paragraph path that keeps its spelling while changing what text it denotes, WITHIN ONE JURISDICTION ACROSS RELEASES. Two routes: an IMO amendment renumbering an `intl` path (verified real \u2014 A.910(22) displaced 23(c) to 23(d); A.464(XII) relettered 24(g) to 24(h)), or a national body renumbering its own amalgamation, so that e.g. `us/inland 24(c)` denotes different text in vN+1 than in vN. Cross-jurisdiction divergence at one point in time is NOT this trigger: the effective identifier is (jurisdiction, path), so the 15 same-path-different-text rows in the 33 CFR 83 diff are REQ-MODEL-1 working as designed.",
+      "status": "open",
+      "settled_by": null,
+      "note": "Open on timing, not outcome: if the trigger fires the split is forced and lands as a major version. Ruling 2026-08-30 (requirements.md \u00a710): does not flip on today's data \u2014 no published path has changed denotation \u2014 but leans adopt, decided in the second-jurisdiction bundle with GATE-2 and Q-10. That bundle is also where the re-check happens; it is justified by Q-11 and GATE-2, not by cross-jurisdiction divergence."
+    },
+    {
+      "id": "GATE-2",
+      "title": "instrument \u2192 edition \u2192 corpus as first-class layers",
+      "declined_in": "docs/adr/0003-language-as-a-dimension.md",
+      "closing_event": "first-non-english-corpus",
+      "trigger": "a jurisdiction publishing two editions in force concurrently",
+      "status": "open",
+      "settled_by": null,
+      "note": "Due at translation #1, not at 1.0."
+    },
+    {
+      "id": "GATE-3",
+      "title": "legal-status \u00d7 translation-status as two enums",
+      "declined_in": "docs/adr/0003-language-as-a-dimension.md",
+      "closing_event": "first-community-translation-of-national-corpus",
+      "trigger": "a real corpus whose legal tier and translation tier disagree in a way a consumer must filter on and cannot from the metadata as structured",
+      "status": "open",
+      "settled_by": null,
+      "note": "Half-adopted: one tier for legal authority (REQ-LANG-3), translation provenance as structured metadata (REQ-LANG-8, REQ-PROV-6)."
+    },
+    {
+      "id": "GATE-4",
+      "title": "a package-encoded language fallback chain",
+      "declined_in": "docs/adr/0003-language-as-a-dimension.md",
+      "closing_event": "none",
+      "trigger": null,
+      "status": "declined-permanently",
+      "settled_by": "docs/adr/0003-language-as-a-dimension.md",
+      "note": "The door opens outward: loosening REQ-LANG-7 later is additive, tightening it later would break consumers. Recorded so the asymmetry is not re-discovered as an argument for adopting early."
+    },
+    {
+      "id": "GATE-5",
+      "title": "a CI-enforced terminology glossary",
+      "declined_in": "docs/adr/0003-language-as-a-dimension.md",
+      "closing_event": "none",
+      "trigger": null,
+      "status": "declined-permanently",
+      "settled_by": "docs/adr/0003-language-as-a-dimension.md",
+      "note": "Declined for legal corpora \u2014 it follows from verbatimness (REQ-MODEL-1) and does not decay. For display catalogs it is contributor guidance, gated on contribution docs existing at all."
+    },
+    {
+      "id": "GATE-6",
+      "title": "the compilation's outbound licence",
+      "declined_in": "docs/adr/0004-licence-layering.md",
+      "closing_event": "first-external-contribution",
+      "trigger": "deciding the data side wants CC0 or CC BY 4.0 separately from the code (REQ-PROV-4, Q-9)",
+      "status": "open",
+      "settled_by": null,
+      "note": "ADR 0004 settles the code licence (MIT \u2192 Apache-2.0) and leaves the data licence open. Already-published npm versions stay under the licence they shipped with; the gate governs future releases only, and is held open deliberately by REQ-PROV-7's CONTRIBUTING.md terms (DCO-style certification plus a relicensing grant); a CLA-assistant bot is the upgrade path if contributors arrive."
+    }
+  ]
+}