colregs 0.2.4 → 0.3.0

package/PROVENANCE.md

@@ -3,7 +3,7 @@
 Everything in this package is transcribed or copied from US Government
 publications. Nothing here is authoritative: consult the published rules.
 
-## Rule text — `data/rules.json`
+## Rule text — `data/text/intl/2016/en-US.uscg.json`
 
 - **Source:** USCG Navigation Center, *Navigation Rules, International —
   Inland* (amalgamated), <https://www.navcen.uscg.gov/navigation-rules-amalgamated>
@@ -16,8 +16,8 @@ publications. Nothing here is authoritative: consult the published rules.
 - **Rights:** a work of the US Government, not subject to copyright in the
   United States (17 U.S.C. 105).
 - **Known hole:** Rule 24(g)(i) is absent from the source page. Rather than
-  reconstruct it from memory, `rules.json` records it under `gaps` and the
-  paragraph is omitted. 24(g) covers inconspicuous, partly submerged tows and
+  reconstruct it from memory, the corpus records it under `gaps` and carries
+  no text for it; the skeleton still has the path. 24(g) covers inconspicuous, partly submerged tows and
   is outside the applicability table in this release.
 - **Withheld text is not a gap.** A `gaps` entry is a paragraph we could not
   obtain. A paragraph with `text_status: withheld` is one we hold but may not

package/README.md

@@ -26,7 +26,10 @@ See a [live demo](https://mark-brannan.github.io/searoom/) of searoom and the co
 > by the published rules.
 
 ```text
-data/rules.json          rule text, keyed by paragraph path and jurisdiction
+data/rules.json          the skeleton: paragraph paths, rule numbers, jurisdictions -- no text
+data/editions.json       which edition of which instrument each jurisdiction is on
+data/text/               rule text, one corpus per edition x language x source
+data/corpora.json        index of those corpora and how much each covers
 data/lights.json         the six Rule 21 lights: colour, arc, Rule 22 range
 data/facts.json          the fact record, and how to decode SignalK navigation.state
 data/applicability.json  predicate -> lights, each entry also carrying modality, citation, jurisdiction
@@ -59,7 +62,10 @@ mooring buoy, lives only under `us/inland`
 ## The layers
 
 **Rule text.** Verbatim, keyed by *paragraph path*, like `27(a)(i)`, because
-the paragraph is the unit you actually cite. Where a licence bars republishing
+the paragraph is the unit you actually cite. The paths live in a
+language-neutral skeleton; the words live in corpora, one per edition,
+language and source, each with its own provenance and legal tier. A mixed
+rendering across corpora is never a single authoritative edition. Where a licence bars republishing
 a jurisdiction's words, the paragraph is still modelled and its text withheld
 rather than paraphrased — evaluation never reads the text.
 
@@ -89,8 +95,9 @@ identifier is immutable once published; retirements go through
 
 Requirements-first: sessions work against the numbered requirements in
 [`docs/requirements.md`](docs/requirements.md) and decisions live in
-[`docs/adr/`](docs/adr/) rather than being argued again. Four ideas carry
-most of it.
+[`docs/adr/`](docs/adr/) rather than being argued again; the amendment and
+national-adoption history is in [`docs/timeline.md`](docs/timeline.md). Four
+ideas carry most of it.
 
 **The paragraph is the unit.** Rule text, citations and composition all key
 on the paragraph path. Citation unit and composition unit turn out to be the

package/data/corpora.json

@@ -0,0 +1,41 @@
+{
+ "note": "Index of the text corpora under data/text/, one entry per file; test/data.test.mjs regenerates it from the files and fails on drift -- REQ-LANG-5.",
+ "corpora": {
+  "intl@2016.en-US.uscg": {
+   "file": "text/intl/2016/en-US.uscg.json",
+   "edition": "intl@2016",
+   "edition_status": "verified",
+   "language": "en-US",
+   "source_id": "uscg",
+   "tier": "national",
+   "paragraphs": 212
+  },
+  "intl@2016.fi.finlex": {
+   "file": "text/intl/2016/fi.finlex.json",
+   "edition": "intl@2016",
+   "edition_status": "claimed",
+   "language": "fi",
+   "source_id": "finlex",
+   "tier": "national",
+   "paragraphs": 0
+  },
+  "intl@2016.es.boe": {
+   "file": "text/intl/2016/es.boe.json",
+   "edition": "intl@2016",
+   "edition_status": "claimed",
+   "language": "es",
+   "source_id": "boe",
+   "tier": "national",
+   "paragraphs": 0
+  },
+  "us/inland@2014.en-US.ecfr": {
+   "file": "text/us/inland/2014/en-US.ecfr.json",
+   "edition": "us/inland@2014",
+   "edition_status": "claimed",
+   "language": "en-US",
+   "source_id": "ecfr",
+   "tier": "national",
+   "paragraphs": 0
+  }
+ }
+}

package/data/editions.json

@@ -0,0 +1,27 @@
+{
+ "note": "Registry of instruments and their editions, per jurisdiction. A corpus names the edition its text reflects; the skeleton names the one it consolidates -- REQ-LANG-10, ADR 0013.",
+ "jurisdictions": {
+  "intl": {
+   "instrument": "Convention on the International Regulations for Preventing Collisions at Sea, 1972 (COLREG)",
+   "skeleton": "intl@2016",
+   "editions": {
+    "intl@2016": {
+     "amended_through": "A.1085(28)",
+     "in_force": "2016-01-01",
+     "note": "2013 amendment (Part F) verified on imo.org; the resolution number and date are recalled, not yet verified against the resolution text -- REQ-LANG-10."
+    }
+   }
+  },
+  "us/inland": {
+   "instrument": "33 CFR Part 83, Inland Navigation Rules",
+   "skeleton": null,
+   "editions": {
+    "us/inland@2014": {
+     "amended_through": "79 FR 37898 (2014 final rule)",
+     "in_force": "2014-08-01",
+     "note": "Recalled, not verified; a stub edition so the second jurisdiction has one to name -- REQ-LANG-10."
+    }
+   }
+  }
+ }
+}