colregs 0.2.4 → 0.3.1

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,13 +26,15 @@ 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
 data/geometry.json       Annex I: heights, spacings, colour, intensity
 data/images.json         every image, its source, and what it illustrates
-data/deprecated-identifiers.json  retired identifiers: what they denoted, when, and their replacement
 images/                  38 USCG diagrams + 5 arc GIFs
 fixtures/                fact records and the entries that apply to them
 ```
@@ -59,7 +61,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.
 
@@ -76,21 +81,22 @@ loses.
 
 **Applicability entries.** Each is a predicate over facts, a set of lights or
 references to other entries, a modality, a citation, and a jurisdiction. Every
-entry has an id (`25b`, `27a-mw`) a consumer can point at.
+entry has an id (`rule:25b`, `rule:27a_iii`) a consumer can point at.
 
-**Identifiers.** Citation-derived ids (paragraph paths, entry ids) carry no
-prefix, because the path *is* the citation. Vocabulary ids do:
+**Identifiers.** Paragraph paths carry no prefix, because the path *is* the
+citation. Every other id names its namespace: `rule:30a`,
 `light:masthead`, `fact:activity`, `activity:nuc`, `rel:in_lieu_of`. Every
-identifier is immutable once published; retirements go through
-[`data/deprecated-identifiers.json`](data/deprecated-identifiers.json). See
+identifier is immutable from 1.0.0; before then it may be renamed or
+discarded outright, and the deprecation registry is absent. See
 [`docs/identifiers.md`](docs/identifiers.md).
 
 ## Design
 
 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
@@ -171,6 +177,9 @@ both vessels give-way.
 `fixtures/applicability-fixtures.json` and `fixtures/situation-fixtures.json`
 are the cross-implementation contract: an implementation in any language
 should reproduce those exactly.
+[`data/operations.json`](data/operations.json) names the verbs an engine
+implements and binds each to its input schema, its result schema and the
+fixture file that exercises it ([ADR 0014](docs/adr/0014-engine-interface-owned-by-colregs.md)).
 
 ## Provenance and licence