colregs 0.2.4 → 0.3.1

package/package.json

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

@@ -8,14 +8,7 @@
   "additionalProperties": false,
   "required": ["jurisdiction", "cases"],
   "$defs": {
-    "factValue": {
-      "oneOf": [
-        { "type": "string", "pattern": "^[a-z][a-z0-9_]*:[a-z0-9_]+$" },
-        { "type": "number" },
-        { "type": "boolean" }
-      ]
-    },
-    "entryId": { "type": "string", "pattern": "^[0-9]+[a-z0-9]*(-[a-z0-9]+)?$" }
+    "ruleId": { "$ref": "applicability.schema.json#/$defs/ruleId" }
   },
   "properties": {
     "note": { "type": "string" },
@@ -31,16 +24,14 @@
           "name": { "type": "string", "minLength": 1 },
           "jurisdiction": { "type": "string", "pattern": "^[a-z]+(/[a-z]+)*$" },
           "facts": {
+            "$comment": "A FactRecord (schema/fact-record.schema.json, ADR 0014); a case asserts at least one fact.",
             "type": "object",
             "minProperties": 1,
-            "additionalProperties": false,
-            "patternProperties": {
-              "^fact:[a-z0-9_]+$": { "$ref": "#/$defs/factValue" }
-            }
+            "$ref": "fact-record.schema.json"
           },
           "expect": {
             "type": "array",
-            "items": { "$ref": "#/$defs/entryId" }
+            "items": { "$ref": "#/$defs/ruleId" }
           }
         }
       }

package/schema/applicability.schema.json

@@ -7,7 +7,21 @@
   "additionalProperties": false,
   "required": ["entries"],
   "$defs": {
-    "entryId": { "type": "string", "pattern": "^[0-9]+[a-z0-9]*(-[a-z0-9]+)*$" },
+    "ruleCategory": {
+      "type": "string",
+      "enum": [
+        "definition",
+        "standard",
+        "scope",
+        "display",
+        "classification",
+        "precedence",
+        "conduct",
+        "care",
+        "meta"
+      ]
+    },
+    "ruleId": { "type": "string", "pattern": "^rule:[0-9]+[a-z]?(_[ivx]+)*(:[a-z][a-z0-9_]*)?$" },
     "modality": {
       "type": "string",
       "enum": ["shall", "may", "shall-if-practicable", "conditional", "exempt", "shall-not", "shall-not-impede"]
@@ -174,20 +188,20 @@
         "one_of": {
           "type": "array",
           "minItems": 2,
-          "items": { "$ref": "#/$defs/entryId" }
+          "items": { "$ref": "#/$defs/ruleId" }
         },
         "rel:includes": {
           "type": "array",
           "minItems": 1,
-          "items": { "$ref": "#/$defs/entryId" }
+          "items": { "$ref": "#/$defs/ruleId" }
         },
         "cite": { "type": "string", "minLength": 1 }
       }
     },
-    "entryIdList": {
+    "ruleIdList": {
       "type": "array",
       "minItems": 1,
-      "items": { "$ref": "#/$defs/entryId" }
+      "items": { "$ref": "#/$defs/ruleId" }
     }
   },
   "properties": {
@@ -312,7 +326,7 @@
         "additionalProperties": false,
         "required": ["id", "jurisdiction", "cite", "category", "note"],
         "properties": {
-          "id": { "$ref": "#/$defs/entryId" },
+          "id": { "$ref": "#/$defs/ruleId" },
           "jurisdiction": { "type": "string", "pattern": "^[a-z]+(/[a-z]+)*$" },
           "cite": { "type": "string", "minLength": 1 },
           "category": { "type": "string", "enum": ["care", "meta"] },
@@ -320,19 +334,6 @@
         }
       }
     },
-    "retired_entry_ids": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["ids"],
-      "properties": {
-        "note": { "type": "string" },
-        "ids": {
-          "type": "object",
-          "propertyNames": { "$ref": "#/$defs/entryId" },
-          "additionalProperties": { "type": "string", "minLength": 1 }
-        }
-      }
-    },
     "entries": {
       "type": "array",
       "minItems": 1,
@@ -341,12 +342,11 @@
         "additionalProperties": false,
         "required": ["id", "jurisdiction", "cite", "when", "modality"],
         "properties": {
-          "id": { "$ref": "#/$defs/entryId" },
+          "id": { "$ref": "#/$defs/ruleId" },
           "jurisdiction": { "type": "string", "pattern": "^[a-z]+(/[a-z]+)*$" },
           "cite": { "type": "string", "minLength": 1 },
           "category": {
-            "type": "string",
-            "enum": ["definition", "standard", "scope", "display", "classification", "precedence", "conduct", "care", "meta"]
+            "$ref": "#/$defs/ruleCategory"
           },
           "subjects": { "type": "integer", "const": 2 },
           "when": { "$ref": "#/$defs/situationWhen" },
@@ -366,16 +366,16 @@
           "note": { "type": "string" },
           "gap": { "type": "string", "minLength": 1 },
           "no_gate_note": { "type": "string", "minLength": 1 },
-          "rel:includes": { "$ref": "#/$defs/entryIdList" },
+          "rel:includes": { "$ref": "#/$defs/ruleIdList" },
           "rel:conditional_includes": {
             "type": "array",
             "minItems": 1,
             "items": { "$ref": "#/$defs/conditionalInclude" }
           },
-          "rel:in_lieu_of": { "$ref": "#/$defs/entryIdList" },
-          "rel:excludes": { "$ref": "#/$defs/entryIdList" },
-          "rel:exempts": { "$ref": "#/$defs/entryIdList" },
-          "rel:overrides": { "$ref": "#/$defs/entryIdList" }
+          "rel:in_lieu_of": { "$ref": "#/$defs/ruleIdList" },
+          "rel:excludes": { "$ref": "#/$defs/ruleIdList" },
+          "rel:exempts": { "$ref": "#/$defs/ruleIdList" },
+          "rel:overrides": { "$ref": "#/$defs/ruleIdList" }
         },
         "allOf": [
           {

package/schema/conduct-evaluation.schema.json

@@ -0,0 +1,135 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mark-brannan/colregs/schema/conduct-evaluation.schema.json",
+  "title": "ConductEvaluation",
+  "description": "The result of evaluateConduct: one verdict per applied conduct entry per subject over the window the caller handed over, and the Rule 13(d)/17 phase changes seen (ADR 0012 §3, ADR 0014). Structure only.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "colregs",
+    "window",
+    "applied",
+    "verdicts",
+    "phases"
+  ],
+  "properties": {
+    "colregs": {
+      "$ref": "evaluation.schema.json#/$defs/colregs"
+    },
+    "window": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "from_s",
+        "to_s",
+        "samples"
+      ],
+      "properties": {
+        "from_s": {
+          "type": "number"
+        },
+        "to_s": {
+          "type": "number"
+        },
+        "samples": {
+          "type": "integer",
+          "minimum": 1
+        }
+      }
+    },
+    "applied": {
+      "$ref": "evaluation.schema.json#/$defs/ruleIds"
+    },
+    "verdicts": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/verdict"
+      }
+    },
+    "phases": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/phaseChange"
+      }
+    }
+  },
+  "$defs": {
+    "subject": {
+      "type": "string",
+      "enum": [
+        "own",
+        "other"
+      ]
+    },
+    "verdict": {
+      "$comment": "`pending`: the window ended before the duty could be judged. An entry that never attached is absent, not pending.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "subject",
+        "verdict"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "evaluation.schema.json#/$defs/ruleId"
+        },
+        "subject": {
+          "$ref": "#/$defs/subject"
+        },
+        "verdict": {
+          "type": "string",
+          "enum": [
+            "kept",
+            "breached",
+            "pending"
+          ]
+        },
+        "attached_at_s": {
+          "type": "number"
+        },
+        "decided_at_s": {
+          "type": "number"
+        },
+        "robustness": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "value",
+            "unit"
+          ],
+          "properties": {
+            "value": {
+              "type": "number"
+            },
+            "unit": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        }
+      }
+    },
+    "phaseChange": {
+      "$comment": "`phase` is a paragraph cite, never an entry id: several phases have no entry.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "subject",
+        "phase",
+        "at_s"
+      ],
+      "properties": {
+        "subject": {
+          "$ref": "#/$defs/subject"
+        },
+        "phase": {
+          "$ref": "evaluation.schema.json#/$defs/paragraphCite"
+        },
+        "at_s": {
+          "type": "number"
+        }
+      }
+    }
+  }
+}

package/schema/corpora.schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mark-brannan/colregs/schema/corpora.schema.json",
+  "title": "data/corpora.json",
+  "description": "Index of the text corpora under data/text/: which exist, where each lives, and how many paragraphs it covers. Derived from the corpus files and checked against them by test/data.test.mjs; a consumer that cannot list a directory reads this instead. See docs/adr/0013-corpus-files-with-editions.md.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "corpora"
+  ],
+  "properties": {
+    "note": {
+      "type": "string"
+    },
+    "corpora": {
+      "type": "object",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^[a-z]+(/[a-z]+)*@[a-z0-9-]+\\.[A-Za-z0-9-]+\\.[a-z0-9]+$": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "file",
+            "edition",
+            "edition_status",
+            "language",
+            "source_id",
+            "tier",
+            "paragraphs"
+          ],
+          "properties": {
+            "file": {
+              "type": "string",
+              "pattern": "^text/.+\\.json$"
+            },
+            "edition": {
+              "type": "string",
+              "pattern": "^[a-z]+(/[a-z]+)*@[a-z0-9-]+$"
+            },
+            "edition_status": {
+              "enum": ["verified", "claimed", "unknown"]
+            },
+            "language": {
+              "type": "string",
+              "minLength": 2
+            },
+            "source_id": {
+              "type": "string",
+              "pattern": "^[a-z0-9]+$"
+            },
+            "tier": {
+              "enum": [
+                "authentic",
+                "official",
+                "national",
+                "community"
+              ]
+            },
+            "paragraphs": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schema/corpus.schema.json

@@ -0,0 +1,329 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mark-brannan/colregs/schema/corpus.schema.json",
+  "title": "data/text/<jurisdiction>/<edition>/<language>.<source_id>.json",
+  "description": "One rule-text corpus: the words of one edition of one jurisdiction's rules, in one language, from one source, keyed by paragraph path into data/rules.json. Verbatim unless withheld under a licence bar. See docs/adr/0003-language-as-a-dimension.md, docs/adr/0010-text-withheld-jurisdictions.md and docs/adr/0013-corpus-files-with-editions.md.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "edition",
+    "edition_status",
+    "language",
+    "source_id",
+    "tier",
+    "normalization",
+    "source",
+    "rights",
+    "paragraphs"
+  ],
+  "allOf": [
+    {
+      "$comment": "colregs#85 / ADR 0010: a withheld paragraph is a citation, not a reproduction -- 'retrieved' is when that citation was last checked against the primary source.",
+      "if": {
+        "properties": {
+          "paragraphs": {
+            "not": {
+              "type": "object",
+              "patternProperties": {
+                "^.*$": {
+                  "not": {
+                    "type": "object",
+                    "properties": {
+                      "text_status": {
+                        "const": "withheld"
+                      }
+                    },
+                    "required": [
+                      "text_status"
+                    ]
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "source": {
+            "type": "object",
+            "properties": {
+              "retrieved": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "retrieved"
+            ]
+          }
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "path": {
+      "type": "string",
+      "pattern": "^[0-9]+(\\([a-z]\\))?(\\([ivx]+\\))?$"
+    },
+    "date": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+    }
+  },
+  "properties": {
+    "id": {
+      "$comment": "<edition>.<language>.<source_id>; CI checks it agrees with the file's path, with data/corpora.json, and that the edition is registered in data/editions.json.",
+      "type": "string",
+      "pattern": "^[a-z]+(/[a-z]+)*@[a-z0-9-]+\\.[A-Za-z0-9-]+\\.[a-z0-9]+$"
+    },
+    "edition": {
+      "$comment": "Edition id from data/editions.json (<jurisdiction>@<tag>): the consolidated state this text reflects -- REQ-LANG-10. The jurisdiction is the edition's, never restated here.",
+      "type": "string",
+      "pattern": "^[a-z]+(/[a-z]+)*@[a-z0-9-]+$"
+    },
+    "edition_status": {
+      "$comment": "Confidence in the `edition` claim above, not in the text itself: 'verified' means this corpus's edition was checked against the primary source; 'claimed' means asserted but not yet checked (every stub starts here); 'unknown' means even the claim is inherited/guessed. See ADR 0013.",
+      "enum": ["verified", "claimed", "unknown"]
+    },
+    "language": {
+      "$comment": "BCP 47. Carries the language of the text and nothing else -- REQ-LANG-1.",
+      "type": "string",
+      "pattern": "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-[A-Z]{2}|-[0-9]{3})?$"
+    },
+    "source_id": {
+      "$comment": "Short handle for the publishing route (uscg, finlex, boe, ecfr); the identity of the source is the structured `source` object.",
+      "type": "string",
+      "pattern": "^[a-z0-9]+$"
+    },
+    "tier": {
+      "$comment": "Legal authority of the source, never of the language -- REQ-LANG-3.",
+      "enum": [
+        "authentic",
+        "official",
+        "national",
+        "community"
+      ]
+    },
+    "normalization": {
+      "$comment": "Unicode normalization form the text is stored in -- REQ-LANG-9.",
+      "enum": [
+        "NFC",
+        "NFD",
+        "NFKC",
+        "NFKD"
+      ]
+    },
+    "translation_of": {
+      "$comment": "Corpus id this text is a translation of, where it is one and that is known. Absent for independently promulgated national texts.",
+      "type": "string"
+    },
+    "source": {
+      "$comment": "REQ-PROV-6: structured source identity, not a prose string.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "publisher",
+        "title",
+        "url",
+        "retrieved"
+      ],
+      "properties": {
+        "publisher": {
+          "type": "string",
+          "minLength": 1
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1
+        },
+        "edition": {
+          "type": "string",
+          "minLength": 1
+        },
+        "published": {
+          "$ref": "#/$defs/date"
+        },
+        "effective": {
+          "$ref": "#/$defs/date"
+        },
+        "url": {
+          "type": "string",
+          "minLength": 1
+        },
+        "retrieved": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "$ref": "#/$defs/date"
+            }
+          ]
+        }
+      }
+    },
+    "rights": {
+      "$comment": "REQ-PROV-6: three separate statements, never one flat licence field.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "source_text",
+        "redistribution_basis",
+        "package_licence"
+      ],
+      "properties": {
+        "source_text": {
+          "type": "string",
+          "minLength": 1
+        },
+        "redistribution_basis": {
+          "type": "string",
+          "minLength": 1
+        },
+        "attribution": {
+          "type": "string",
+          "minLength": 1
+        },
+        "package_licence": {
+          "type": "string",
+          "minLength": 1
+        },
+        "contributors": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "minItems": 1
+        },
+        "reviewers": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "minItems": 1
+        }
+      }
+    },
+    "note": {
+      "type": "string"
+    },
+    "gaps": {
+      "$comment": "Skeleton paths this source could not supply. Distinct from withheld: a gap is text we could not obtain, withheld is text we may not publish.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "path",
+          "reason"
+        ],
+        "properties": {
+          "path": {
+            "$ref": "#/$defs/path"
+          },
+          "reason": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "paragraphs": {
+      "type": "object",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^[0-9]+(\\([a-z]\\))?(\\([ivx]+\\))?$": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "rule_title"
+          ],
+          "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": {
+            "rule_title": {
+              "$comment": "Verbatim source material like `text`; on a withheld paragraph, a neutral label written for this package -- ADR 0010.",
+              "type": "string",
+              "minLength": 1
+            },
+            "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.",
+              "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>'.",
+              "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.",
+              "$ref": "#/$defs/path"
+            }
+          }
+        }
+      }
+    }
+  }
+}