colregs 0.2.2 → 0.2.3

package/README.md

@@ -347,7 +347,7 @@ came out right.
 From 0.2.0 on, every identifier in the package is immutable once published
 (REQ-MODEL-10). [`data/deprecated-identifiers.json`](data/deprecated-identifiers.json)
 is the REQ-MODEL-11 registry a retired identifier goes into, and `npm test`
-refuses a removal that is not recorded there.
+refuses a removal that is not recorded there. [`data/version.json`](data/version.json) mirrors `package.json`; release-please keeps it in sync (see [ADR 0009](docs/adr/0009-data-version-stamp.md)).
 
 ## Provenance and licence
 

package/data/applicability.json

@@ -410,8 +410,15 @@
      "count": 1
     }
    ],
-   "rel:includes": [
-    "23a34"
+   "rel:conditional_includes": [
+    {
+     "when": {
+      "fact:position": "position:underway"
+     },
+     "rel:includes": [
+      "23a34"
+     ]
+    }
    ],
    "modality": "shall",
    "images": [
@@ -427,10 +434,17 @@
     "fact:composite_unit": true
    },
    "lights": [],
-   "rel:includes": [
-    "23a1",
-    "23a2",
-    "23a34"
+   "rel:conditional_includes": [
+    {
+     "when": {
+      "fact:position": "position:underway"
+     },
+     "rel:includes": [
+      "23a1",
+      "23a2",
+      "23a34"
+     ]
+    }
    ],
    "modality": "shall",
    "images": [
@@ -453,8 +467,15 @@
      "arrangement": "vertical"
     }
    ],
-   "rel:includes": [
-    "23a34"
+   "rel:conditional_includes": [
+    {
+     "when": {
+      "fact:position": "position:underway"
+     },
+     "rel:includes": [
+      "23a34"
+     ]
+    }
    ],
    "rel:in_lieu_of": [
     "23a1",

package/data/version.json

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

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/budgets.json

@@ -9,6 +9,7 @@
     "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,
     "required": true,
     "pending": []
   },

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": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "colregs",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "COLREGS 72 and its national amalgamations as language-neutral JSON — rule text, light definitions, and applicability predicates — with cross-implementation fixtures",
   "license": "Apache-2.0",
   "repository": {

package/schema/version.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mark-brannan/colregs/schema/version.schema.json",
+  "title": "data/version.json",
+  "description": "The single version stamp for all of data/ and fixtures/, mirroring package.json's version at release time. One source of truth -- see docs/adr/0009-data-version-stamp.md (release-please's extra-files generic JSON updater keeps this in sync; never hand-edit). Structure only -- see docs/adr/0006-json-schema-and-identifier-diff.md.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version"],
+  "properties": {
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Matches package.json's version at release time (REQ-VERIFY; docs/adr/0009-data-version-stamp.md). Not hand-edited -- release-please's extra-files JSON updater stamps it on every release."
+    }
+  }
+}