colregs 0.3.0 → 0.3.2

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/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"
@@ -51,106 +41,19 @@
         }
       ]
     },
-    "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": {
+    "subjectRole": {
       "type": "object",
       "additionalProperties": false,
       "required": [
-        "fact"
+        "role",
+        "by"
       ],
       "properties": {
-        "fact": {
-          "$ref": "#/$defs/factRecord"
-        },
-        "kin": {
-          "$ref": "#/$defs/kinRecord"
-        },
-        "geo": {
-          "$ref": "#/$defs/geoRecord"
+        "role": {
+          "$ref": "applicability.schema.json#/$defs/effectRole"
         },
-        "hist": {
-          "$ref": "#/$defs/histRecord"
+        "by": {
+          "$ref": "#/$defs/ruleId"
         }
       }
     }
@@ -200,7 +103,7 @@
           "type": "string"
         },
         "bare": {
-          "$ref": "#/$defs/entryId"
+          "$ref": "#/$defs/ruleId"
         },
         "with_modality": {
           "type": "object",
@@ -211,7 +114,7 @@
           ],
           "properties": {
             "entry": {
-              "$ref": "#/$defs/entryId"
+              "$ref": "#/$defs/ruleId"
             },
             "modality": {
               "$ref": "#/$defs/modality"
@@ -286,28 +189,28 @@
             }
           },
           "situation": {
+            "$comment": "A Situation (schema/situation.schema.json, ADR 0014).",
+            "$ref": "situation.schema.json"
+          },
+          "roles": {
+            "$comment": "The pooled, resolved roles of both subjects (ADR 0016). `expect` stays the self-frame entry ids.",
             "type": "object",
             "additionalProperties": false,
             "required": [
-              "own"
+              "self",
+              "other"
             ],
             "properties": {
-              "own": {
-                "$ref": "#/$defs/vessel"
+              "self": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/$defs/subjectRole"
+                }
               },
               "other": {
-                "$ref": "#/$defs/vessel"
-              },
-              "pair": {
-                "type": "object",
-                "additionalProperties": false,
-                "properties": {
-                  "geo": {
-                    "$ref": "#/$defs/geoRecord"
-                  },
-                  "env": {
-                    "$ref": "#/$defs/envRecord"
-                  }
+                "type": "array",
+                "items": {
+                  "$ref": "#/$defs/subjectRole"
                 }
               }
             }

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; `self` required, `other` optional (Rule 19's single-vessel scope), every class and key optional -- absent is absent.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["self"],
+  "properties": {
+    "self": { "$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"
+          }
+        }
+      }
+    }
+  }
+}

package/data/deprecated-identifiers.json

@@ -1,7 +0,0 @@
-{
- "entry:14a": {
-  "denoted": "The head-on classification: encounter head-on when each vessel has the other ahead or nearly ahead, cited to 14(a). Renamed when the cite moved to 14(b), the deeming paragraph the entry actually reads (Q-45); the predicate and effect are unchanged.",
-  "deprecated_in": "0.2.0",
-  "replacement": "entry:14b"
- }
-}

package/schema/deprecated-identifiers.schema.json

@@ -1,29 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/mark-brannan/colregs/schema/deprecated-identifiers.schema.json",
-  "title": "data/deprecated-identifiers.json",
-  "description": "REQ-MODEL-11's deprecation registry: every retired identifier, what it denoted, the version that deprecated it, and its replacement where one exists. Keys are the same prefixed forms the identifier diff compares (test/data.test.mjs's extractIdentifiers) -- e.g. 'entry:25d2', 'paragraph:27(a)(i)', 'light:masthead', 'fact-key:activity', 'fact-value:activity:nuc', 'rel:includes'. Structure only -- see docs/adr/0006-json-schema-and-identifier-diff.md.",
-  "type": "object",
-  "additionalProperties": {
-    "type": "object",
-    "additionalProperties": false,
-    "required": ["denoted", "deprecated_in"],
-    "properties": {
-      "denoted": {
-        "type": "string",
-        "minLength": 1,
-        "description": "What the identifier meant, so a consumer pinned to an old version can resolve a stale reference without the identifier itself."
-      },
-      "deprecated_in": {
-        "type": "string",
-        "pattern": "^\\d+\\.\\d+\\.\\d+$",
-        "description": "The released version that deprecated this identifier (REQ-MODEL-10)."
-      },
-      "replacement": {
-        "type": ["string", "null"],
-        "minLength": 1,
-        "description": "The identifier that replaces this one, in the same prefixed form, or null where nothing replaces it."
-      }
-    }
-  }
-}