colregs 0.2.2 → 0.2.4

package/fixtures/situation-fixtures.json

@@ -3664,6 +3664,84 @@
      }
     }
    }
+  },
+  {
+   "name": "13(d) latch: 13(a)'s sector test suppressed on the newly-gaining vessel",
+   "status": "binding",
+   "narrative": "Own already holds 13(d)'s latch from an earlier overtaking. Since then the pair has closed again from the other direction: the other now sits dead astern of own, gaining at three knots -- 13(a)'s sector test, read on her geometry alone, would newly name her give-way too. The latch forbids it: only own, the latch-holder, gives way (Q-47).",
+   "expect": [
+    "4",
+    "11",
+    "7d1",
+    "8f3",
+    "13a",
+    "13b-overtaken",
+    "13d"
+   ],
+   "situation": {
+    "own": {
+     "fact": {
+      "fact:propulsion": "propulsion:power",
+      "fact:activity": "activity:none",
+      "fact:position": "position:underway",
+      "fact:making_way": true,
+      "fact:length_m": 28
+     },
+     "kin": {
+      "kin:position": {
+       "latitude": 50.0,
+       "longitude": -1.4
+      },
+      "kin:heading_deg": 0,
+      "kin:sog_kn": 10,
+      "kin:rot_deg_min": 0,
+      "kin:dynamics": "dynamics:cargo"
+     },
+     "geo": {
+      "geo:rel_bearing_deg": 180
+     },
+     "hist": {
+      "hist:was_overtaking": true,
+      "hist:latched_at_s": 900
+     }
+    },
+    "other": {
+     "fact": {
+      "fact:propulsion": "propulsion:power",
+      "fact:activity": "activity:none",
+      "fact:position": "position:underway",
+      "fact:making_way": true,
+      "fact:length_m": 16
+     },
+     "kin": {
+      "kin:position": {
+       "latitude": 49.995503,
+       "longitude": -1.4
+      },
+      "kin:heading_deg": 0,
+      "kin:sog_kn": 13,
+      "kin:rot_deg_min": 0,
+      "kin:dynamics": "dynamics:ferry"
+     },
+     "geo": {
+      "geo:rel_bearing_deg": 0
+     },
+     "hist": {
+      "hist:was_overtaking": false,
+      "hist:latched_at_s": null
+     }
+    },
+    "pair": {
+     "geo": {
+      "geo:range_m": 500,
+      "geo:bearing_change_deg_min": 0.0,
+      "geo:cpa_m": 0,
+      "geo:tcpa_s": 324.0,
+      "geo:in_sight": true,
+      "geo:risk_of_collision": true
+     }
+    }
+   }
   }
  ],
  "override_note": "`expect` names every entry whose predicate the situation satisfies, including entries that a rel:overrides then displaces. Applicability and resolution are two steps: 18(a)(iv) really does apply to a WIG craft near the surface -- she is a power-driven vessel underway -- and 18(f)(i) overriding it is what the engine does next. A fixture that hid the overridden entry would make the override unobservable and the relation untestable.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "colregs",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "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/images.schema.json

@@ -14,7 +14,7 @@
       "additionalProperties": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["file", "bytes", "sha256", "pixels", "source_url", "source", "retrieved", "rights"],
+        "required": ["file", "bytes", "sha256", "pixels", "source_url", "source", "retrieved", "rights", "transcript", "subjects", "description", "shapes"],
         "properties": {
           "file": { "type": "string", "minLength": 1 },
           "bytes": { "type": "integer", "minimum": 0 },
@@ -44,6 +44,31 @@
             "minItems": 1,
             "items": { "type": "string", "minLength": 1 }
           },
+          "depicts": {
+            "description": "Whether the figure shows the provision of the clauses it is mapped to, the exception they carve out, or both.",
+            "enum": ["provision", "exception", "mixed"]
+          },
+          "transcript": {
+            "description": "Every printed text block in the image, verbatim, in reading order. Empty when the image carries no text.",
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 }
+          },
+          "subjects": {
+            "description": "What is drawn, one noun phrase per vessel or object, in plain maritime vocabulary, not the Convention's classes.",
+            "type": "array",
+            "minItems": 1,
+            "items": { "type": "string", "minLength": 1 }
+          },
+          "description": {
+            "description": "One paragraph of what the drawing contains: vessel type and its evidence, viewpoint, then the lights and shapes as drawn. No rule citations.",
+            "type": "string",
+            "minLength": 40
+          },
+          "shapes": {
+            "description": "The day shapes the figure draws, top to bottom, from the closed vocabulary. Empty when it draws none.",
+            "type": "array",
+            "items": { "enum": ["ball", "diamond", "cone-up", "cone-down", "cylinder", "basket", "flag-a"] }
+          },
           "provenance_status": { "type": "string" },
           "unmapped_reason": { "type": "string", "minLength": 1 }
         }

package/schema/rules.schema.json

@@ -2,10 +2,37 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/mark-brannan/colregs/schema/rules.schema.json",
   "title": "data/rules.json",
-  "description": "Verbatim rule text keyed by paragraph path. Structure only -- see docs/adr/0006-json-schema-and-identifier-diff.md.",
+  "description": "Rule text keyed by paragraph path, verbatim unless withheld under a licence bar. Structure only -- see docs/adr/0006-json-schema-and-identifier-diff.md and docs/adr/0010-text-withheld-jurisdictions.md.",
   "type": "object",
   "additionalProperties": false,
   "required": ["source", "paragraphs"],
+  "allOf": [
+    {
+      "$comment": "colregs#85: a withheld paragraph is a citation, not a reproduction (ADR 0010) -- 'retrieved' is when that citation was last checked against the primary source, so it can't be blank on a document that withholds text.",
+      "if": {
+        "properties": {
+          "paragraphs": {
+            "not": {
+              "type": "object",
+              "patternProperties": {
+                "^.*$": {
+                  "not": {
+                    "type": "object",
+                    "properties": { "text_status": { "const": "withheld" } },
+                    "required": ["text_status"]
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "then": {
+        "properties": { "retrieved": { "type": "string" } },
+        "required": ["retrieved"]
+      }
+    }
+  ],
   "properties": {
     "source": { "type": "string", "minLength": 1 },
     "source_url": { "type": "string", "minLength": 1 },
@@ -30,13 +57,59 @@
         "^[0-9]+(\\([a-z]\\))?(\\([ivx]+\\))?$": {
           "type": "object",
           "additionalProperties": false,
-          "required": ["path", "rule", "rule_title", "jurisdiction", "text"],
+          "required": ["path", "rule", "rule_title", "jurisdiction"],
+          "allOf": [
+            {
+              "$comment": "ADR 0010: a withheld paragraph is modelled but ships no text.",
+              "if": {
+                "properties": { "text_status": { "const": "withheld" } },
+                "required": ["text_status"]
+              },
+              "then": {
+                "properties": {
+                  "text": false,
+                  "withheld_reason": { "type": "string", "minLength": 1 }
+                },
+                "required": ["withheld_reason"]
+              },
+              "else": {
+                "$comment": "mirrors, text_digest and text_slug are open to verbatim paragraphs too; only withheld_reason is incoherent without a bar.",
+                "properties": {
+                  "text": { "type": "string", "minLength": 1 },
+                  "withheld_reason": false
+                },
+                "required": ["text"]
+              }
+            }
+          ],
           "properties": {
             "path": { "type": "string", "pattern": "^[0-9]+(\\([a-z]\\))?(\\([ivx]+\\))?$" },
             "rule": { "type": "string", "pattern": "^[0-9]+$" },
             "rule_title": { "type": "string", "minLength": 1 },
             "jurisdiction": { "type": "string", "pattern": "^[a-z]+(/[a-z]+)*$" },
             "text": { "type": "string", "minLength": 1 },
+            "text_status": {
+              "$comment": "Absent means verbatim. 'withheld' means the text is not ours to publish -- ADR 0010.",
+              "enum": ["verbatim", "withheld"]
+            },
+            "withheld_reason": { "type": "string", "minLength": 1 },
+            "text_slug": {
+              "$comment": "Pencil, ADR 0010: sorted set of lemmatised key nouns and verbs, English counterparts where the source is not English. Defined so the option is not walled off; nothing writes it yet.",
+              "type": "array",
+              "items": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" },
+              "minItems": 1,
+              "uniqueItems": true
+            },
+            "text_digest": {
+              "$comment": "Pencil, ADR 0010: algorithm-qualified digest of the normalised text, e.g. 'sha256:<hex>'. Defined so the option is not walled off by additionalProperties; nothing writes it yet.",
+              "type": "string",
+              "pattern": "^[a-z0-9-]+:[A-Za-z0-9+/=]+$"
+            },
+            "mirrors": {
+              "$comment": "Paragraph path in intl this provision restates; display labelled as the international equivalent, never as this jurisdiction's text.",
+              "type": "string",
+              "pattern": "^[0-9]+(\\([a-z]\\))?(\\([ivx]+\\))?$"
+            },
             "images": {
               "type": "array",
               "items": { "type": "string", "minLength": 1 },

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."
+    }
+  }
+}