colregs 0.2.4 → 0.3.1

package/schema/rule2-departure-finding.schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mark-brannan/colregs/schema/rule2-departure-finding.schema.json",
+  "title": "Rule2DepartureFinding",
+  "description": "The result of evaluateRule2Departure: what a named grid found for a situation, with the rule-derived obligations unchanged beside it and the model that made the claim (ADR 0012 §4, ADR 0014). Advisories are ranked best margin first and are empty under no-robust-policy-in-model. Structure only.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "status",
+    "rules",
+    "advisories",
+    "model"
+  ],
+  "properties": {
+    "status": {
+      "$ref": "rule2-departure-model.schema.json#/$defs/status"
+    },
+    "rules": {
+      "$ref": "encounter-evaluation.schema.json"
+    },
+    "advisories": {
+      "type": "array",
+      "items": {
+        "$ref": "rule2-departure-model.schema.json#/$defs/advisory"
+      }
+    },
+    "model": {
+      "$comment": "`version` names the grid, `colregs_version` the release it was solved against; a mismatch with rules.colregs.version is reported, not refused. `assumptions_violated` is display text, never matched on.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "version",
+        "colregs_version",
+        "parameters",
+        "assumptions_violated"
+      ],
+      "properties": {
+        "version": {
+          "type": "string",
+          "minLength": 1
+        },
+        "colregs_version": {
+          "type": "string",
+          "minLength": 1
+        },
+        "parameters": {
+          "type": "object",
+          "allOf": [
+            {
+              "$ref": "rule2-departure-model.schema.json#/$defs/solverParameters"
+            }
+          ],
+          "required": [
+            "dynamics",
+            "horizon_s",
+            "cadence_s",
+            "separation_m",
+            "information",
+            "adversary"
+          ],
+          "unevaluatedProperties": false
+        },
+        "assumptions_violated": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/schema/rule2-departure-model.schema.json

@@ -0,0 +1,159 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mark-brannan/colregs/schema/rule2-departure-model.schema.json",
+  "title": "Rule2DepartureModel",
+  "description": "One solved region grid, named immutably by `version`, the positional second input of evaluateRule2Departure (ADR 0012 §4, ADR 0014). Only `version`, `colregs_version`, the solver parameters and the `regions` encoding are API; any other field is the artefact's own, so additional properties are allowed. Structure only.",
+  "type": "object",
+  "required": [
+    "version",
+    "colregs_version",
+    "dynamics",
+    "horizon_s",
+    "cadence_s",
+    "separation_m",
+    "information",
+    "adversary"
+  ],
+  "allOf": [
+    {
+      "$ref": "#/$defs/solverParameters"
+    }
+  ],
+  "properties": {
+    "version": {
+      "type": "string",
+      "minLength": 1
+    },
+    "colregs_version": {
+      "type": "string",
+      "minLength": 1
+    },
+    "regions": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/region"
+      }
+    }
+  },
+  "$defs": {
+    "solverParameters": {
+      "$comment": "The axes the Rule 2 sensitivity matrix varies (colregs Q-17 to Q-22); the field set is a claim about what that matrix is.",
+      "type": "object",
+      "properties": {
+        "dynamics": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "horizon_s": {
+          "type": "number"
+        },
+        "cadence_s": {
+          "type": "number"
+        },
+        "separation_m": {
+          "type": "number"
+        },
+        "information": {
+          "type": "string",
+          "enum": [
+            "full",
+            "partial"
+          ]
+        },
+        "adversary": {
+          "type": "string",
+          "enum": [
+            "compliant",
+            "physics"
+          ]
+        }
+      }
+    },
+    "status": {
+      "$comment": "The status alphabet is colregs' (ADR 0005 §5), not an engine's to rename: not-flagged, model-rule-conflict and no-robust-policy-in-model name R0, R1 and R2; inconclusive-in-model names none.",
+      "type": "string",
+      "enum": [
+        "not-flagged",
+        "model-rule-conflict",
+        "no-robust-policy-in-model",
+        "inconclusive-in-model"
+      ]
+    },
+    "advisory": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "action",
+        "margin_m",
+        "breaches",
+        "envelope"
+      ],
+      "properties": {
+        "action": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "alter_deg": {
+              "type": "number"
+            },
+            "sog_kn": {
+              "type": "number"
+            }
+          }
+        },
+        "margin_m": {
+          "type": "number"
+        },
+        "breaches": {
+          "type": "array",
+          "items": {
+            "$ref": "evaluation.schema.json#/$defs/paragraphCite"
+          }
+        },
+        "envelope": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "holds_until_s"
+          ],
+          "properties": {
+            "holds_until_s": {
+              "type": "number"
+            }
+          }
+        }
+      }
+    },
+    "region": {
+      "$comment": "Regions of situation space as predicates over the flat `<subject>:<class>:<key>` namespace, first match wins, no match is inconclusive-in-model.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "when",
+        "status"
+      ],
+      "properties": {
+        "when": {
+          "$ref": "applicability.schema.json#/$defs/situationWhen"
+        },
+        "status": {
+          "$ref": "#/$defs/status"
+        },
+        "advisories": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/advisory"
+          }
+        },
+        "assumptions_violated": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/schema/rules.schema.json

@@ -2,53 +2,15 @@
   "$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": "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.",
+  "description": "The language-neutral skeleton: paragraph paths, rule numbers, jurisdictions and figures. No text -- the words live in data/text/ corpora (schema/corpus.schema.json); the edition each jurisdiction consolidates is declared in data/editions.json. Structure only -- see docs/adr/0006-json-schema-and-identifier-diff.md, docs/adr/0003-language-as-a-dimension.md and docs/adr/0013-corpus-files-with-editions.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"]
-      }
-    }
+  "required": [
+    "paragraphs"
   ],
   "properties": {
-    "source": { "type": "string", "minLength": 1 },
-    "source_url": { "type": "string", "minLength": 1 },
-    "retrieved": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" },
-    "note": { "type": "string" },
-    "gaps": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "additionalProperties": false,
-        "required": ["path", "reason"],
-        "properties": {
-          "path": { "type": "string", "minLength": 1 },
-          "reason": { "type": "string", "minLength": 1 }
-        }
-      }
+    "note": {
+      "type": "string"
     },
     "paragraphs": {
       "type": "object",
@@ -57,62 +19,30 @@
         "^[0-9]+(\\([a-z]\\))?(\\([ivx]+\\))?$": {
           "type": "object",
           "additionalProperties": false,
-          "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"]
-              }
-            }
+          "required": [
+            "path",
+            "rule",
+            "jurisdiction"
           ],
           "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
+            "path": {
+              "type": "string",
+              "pattern": "^[0-9]+(\\([a-z]\\))?(\\([ivx]+\\))?$"
             },
-            "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.",
+            "rule": {
               "type": "string",
-              "pattern": "^[a-z0-9-]+:[A-Za-z0-9+/=]+$"
+              "pattern": "^[0-9]+$"
             },
-            "mirrors": {
-              "$comment": "Paragraph path in intl this provision restates; display labelled as the international equivalent, never as this jurisdiction's text.",
+            "jurisdiction": {
               "type": "string",
-              "pattern": "^[0-9]+(\\([a-z]\\))?(\\([ivx]+\\))?$"
+              "pattern": "^[a-z]+(/[a-z]+)*$"
             },
             "images": {
               "type": "array",
-              "items": { "type": "string", "minLength": 1 },
+              "items": {
+                "type": "string",
+                "minLength": 1
+              },
               "minItems": 1
             }
           }

package/schema/situation-fixtures.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/mark-brannan/colregs/schema/situation-fixtures.schema.json",
   "title": "fixtures/situation-fixtures.json",
-  "description": "Two-subject situation fixtures (ADR 0005, REQ-CAT-5). Structure only -- see docs/adr/0006-json-schema-and-identifier-diff.md. Namespace resolution (every kin:/geo:/hist: key declared in facts.json) stays in the tests.",
+  "description": "Two-subject situation fixtures (ADR 0005, REQ-CAT-5). Structure only -- see docs/adr/0006-json-schema-and-identifier-diff.md. A case's situation is schema/situation.schema.json; namespace resolution (every kin:/geo:/hist: key declared in facts.json) stays in the tests.",
   "type": "object",
   "additionalProperties": false,
   "required": [
@@ -12,26 +12,16 @@
     "cases"
   ],
   "$defs": {
-    "entryId": {
-      "type": "string",
-      "pattern": "^[0-9]+[a-z0-9]*(-[a-z0-9]+)*$"
+    "ruleId": {
+      "$ref": "applicability.schema.json#/$defs/ruleId"
     },
     "modality": {
-      "type": "string",
-      "enum": [
-        "shall",
-        "may",
-        "shall-if-practicable",
-        "conditional",
-        "exempt",
-        "shall-not",
-        "shall-not-impede"
-      ]
+      "$ref": "applicability.schema.json#/$defs/modality"
     },
     "expectItem": {
       "oneOf": [
         {
-          "$ref": "#/$defs/entryId"
+          "$ref": "#/$defs/ruleId"
         },
         {
           "type": "object",
@@ -42,7 +32,7 @@
           ],
           "properties": {
             "entry": {
-              "$ref": "#/$defs/entryId"
+              "$ref": "#/$defs/ruleId"
             },
             "modality": {
               "$ref": "#/$defs/modality"
@@ -50,109 +40,6 @@
           }
         }
       ]
-    },
-    "scalar": {
-      "oneOf": [
-        {
-          "type": "string",
-          "pattern": "^[a-z][a-z0-9_]*:[a-z0-9_]+$"
-        },
-        {
-          "type": "number"
-        },
-        {
-          "type": "boolean"
-        },
-        {
-          "type": "null"
-        },
-        {
-          "type": "object",
-          "additionalProperties": false,
-          "required": [
-            "latitude",
-            "longitude"
-          ],
-          "properties": {
-            "latitude": {
-              "type": "number",
-              "minimum": -90,
-              "maximum": 90
-            },
-            "longitude": {
-              "type": "number",
-              "minimum": -180,
-              "maximum": 180
-            }
-          }
-        }
-      ]
-    },
-    "factRecord": {
-      "type": "object",
-      "additionalProperties": false,
-      "patternProperties": {
-        "^fact:[a-z0-9_]+$": {
-          "$ref": "#/$defs/scalar"
-        }
-      }
-    },
-    "kinRecord": {
-      "type": "object",
-      "additionalProperties": false,
-      "patternProperties": {
-        "^kin:[a-z0-9_]+$": {
-          "$ref": "#/$defs/scalar"
-        }
-      }
-    },
-    "geoRecord": {
-      "type": "object",
-      "additionalProperties": false,
-      "patternProperties": {
-        "^geo:[a-z0-9_]+$": {
-          "$ref": "#/$defs/scalar"
-        }
-      }
-    },
-    "histRecord": {
-      "type": "object",
-      "additionalProperties": false,
-      "patternProperties": {
-        "^hist:[a-z0-9_]+$": {
-          "$ref": "#/$defs/scalar"
-        }
-      }
-    },
-    "envRecord": {
-      "type": "object",
-      "additionalProperties": false,
-      "patternProperties": {
-        "^env:[a-z0-9_]+$": {
-          "$ref": "#/$defs/scalar"
-        }
-      }
-    },
-    "vessel": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "fact"
-      ],
-      "properties": {
-        "fact": {
-          "$ref": "#/$defs/factRecord"
-        },
-        "kin": {
-          "$ref": "#/$defs/kinRecord"
-        },
-        "geo": {
-          "$ref": "#/$defs/geoRecord"
-        },
-        "hist": {
-          "$ref": "#/$defs/histRecord"
-        }
-      }
     }
   },
   "properties": {
@@ -200,7 +87,7 @@
           "type": "string"
         },
         "bare": {
-          "$ref": "#/$defs/entryId"
+          "$ref": "#/$defs/ruleId"
         },
         "with_modality": {
           "type": "object",
@@ -211,7 +98,7 @@
           ],
           "properties": {
             "entry": {
-              "$ref": "#/$defs/entryId"
+              "$ref": "#/$defs/ruleId"
             },
             "modality": {
               "$ref": "#/$defs/modality"
@@ -286,31 +173,8 @@
             }
           },
           "situation": {
-            "type": "object",
-            "additionalProperties": false,
-            "required": [
-              "own"
-            ],
-            "properties": {
-              "own": {
-                "$ref": "#/$defs/vessel"
-              },
-              "other": {
-                "$ref": "#/$defs/vessel"
-              },
-              "pair": {
-                "type": "object",
-                "additionalProperties": false,
-                "properties": {
-                  "geo": {
-                    "$ref": "#/$defs/geoRecord"
-                  },
-                  "env": {
-                    "$ref": "#/$defs/envRecord"
-                  }
-                }
-              }
-            }
+            "$comment": "A Situation (schema/situation.schema.json, ADR 0014).",
+            "$ref": "situation.schema.json"
           }
         }
       }

package/schema/situation.schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mark-brannan/colregs/schema/situation.schema.json",
+  "title": "Situation",
+  "description": "Two vessels and the encounter at one instant: the input evaluateEncounter reads, nested by subject and class (ADR 0005 §2, ADR 0011 §3, ADR 0014). Structure only -- every kin:/geo:/hist:/env: key must be declared in data/facts.json §situation, checked in the tests.",
+  "$comment": "The same shape as a case's `situation` in schema/situation-fixtures.schema.json, stated once here so an operation can name it; `own` required, `other` optional (Rule 19's single-vessel scope), every class and key optional -- absent is absent.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["own"],
+  "properties": {
+    "own": { "$ref": "#/$defs/subject" },
+    "other": { "$ref": "#/$defs/subject" },
+    "pair": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "geo": { "$ref": "#/$defs/geoRecord" },
+        "env": { "$ref": "#/$defs/envRecord" }
+      }
+    }
+  },
+  "$defs": {
+    "scalar": {
+      "oneOf": [
+        { "type": "string", "pattern": "^[a-z][a-z0-9_]*:[a-z0-9_]+$" },
+        { "type": "number" },
+        { "type": "boolean" },
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["latitude", "longitude"],
+          "properties": {
+            "latitude": { "type": "number", "minimum": -90, "maximum": 90 },
+            "longitude": { "type": "number", "minimum": -180, "maximum": 180 }
+          }
+        }
+      ]
+    },
+    "kinRecord": {
+      "type": "object",
+      "additionalProperties": false,
+      "patternProperties": { "^kin:[a-z0-9_]+$": { "$ref": "#/$defs/scalar" } }
+    },
+    "geoRecord": {
+      "type": "object",
+      "additionalProperties": false,
+      "patternProperties": { "^geo:[a-z0-9_]+$": { "$ref": "#/$defs/scalar" } }
+    },
+    "histRecord": {
+      "type": "object",
+      "additionalProperties": false,
+      "patternProperties": { "^hist:[a-z0-9_]+$": { "$ref": "#/$defs/scalar" } }
+    },
+    "envRecord": {
+      "type": "object",
+      "additionalProperties": false,
+      "patternProperties": { "^env:[a-z0-9_]+$": { "$ref": "#/$defs/scalar" } }
+    },
+    "subject": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["fact"],
+      "properties": {
+        "fact": { "$ref": "fact-record.schema.json" },
+        "kin": { "$ref": "#/$defs/kinRecord" },
+        "geo": { "$ref": "#/$defs/geoRecord" },
+        "hist": { "$ref": "#/$defs/histRecord" }
+      }
+    }
+  }
+}

package/schema/trace.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mark-brannan/colregs/schema/trace.schema.json",
+  "title": "Trace",
+  "description": "The situation over time: the window evaluateConduct reads (ADR 0012 §2, ADR 0014). A conforming implementation rejects an empty samples list, a `t_s` that does not strictly increase, and `other` present in some samples and absent in others; `t_s` is seconds on the caller's clock, read as differences only, and the pair's identity is the caller's, since a Situation names no vessel. Structure only.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "samples"
+  ],
+  "properties": {
+    "samples": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "t_s",
+          "situation"
+        ],
+        "properties": {
+          "t_s": {
+            "type": "number"
+          },
+          "situation": {
+            "$ref": "situation.schema.json"
+          }
+        }
+      }
+    }
+  }
+}