DRAFT: T041, U-0: opendox.health_contract, the finding vocabulary, and the first copy of the finding shape (plan 038)

src/opendox/contracts/__init__.py

@@ -4,19 +4,27 @@
 batch G amends on R1Q11 (a) and R1Q12 (a) (`openxFactory#656` comment
 `5850003126`): *"openDox's validator validates its spec leg's FOUR kinds ...
 The code leg carries digest-checked copies of the four, which a test holds to
-the spec-leg commit the openDox root pins."* 7.1 also settles how the four
+the spec-leg commit the openDox root pins."* 7.1 also settles how the copies
 reach an install. They ship as PACKAGE DATA, *"so `pip install openDox-code`
 puts them on disk beside the validator and the assembly root remains their
 source of truth for editing"*. So a code-leg checkout with no assembly root
 around it still has them, and so does an install. `opendox.validator` reads
-them from here, and so do its doxBench validators
+the validator's copies from here, and so do its doxBench validators
 (`opendox.validator.doxbench_validators`, the default T085 registers).
 
+T005's batch Q adds to batch G's text on R2Q22 (a) (`6003486656`) and N-15
+(`6013547504`): openDox-spec's three health schemas travel as the four do,
+and the finding's neutral shape is *"a copy the engine reads and NOT a
+validator kind"*, because a finding's `kind` is its family and no `kind`
+constant can name the schema. Plan 038's T041 carries that copy here, at the
+spec-leg commit T060 pinned (`dox-v1.2`), and `opendox.health_contract`
+mirrors it. T047 and T054 add the two file kinds after it.
+
 WHAT IS HERE.
 
-* `schemas/`: the four copies. Each one is byte for byte the spec leg's file
-  of the same name, `contracts/schemas/<id>.schema.yaml` in
-  opensoft/openDox-spec.
+* `schemas/`: the copies, the validator's four and the finding shape. Each one
+  is byte for byte the spec leg's file of the same name,
+  `contracts/schemas/<id>.schema.yaml` in opensoft/openDox-spec.
 * `copies.yaml`: the record. It names the spec-leg commit the copies were taken
   at, and each copy's id, spec-leg path and sha256.
 
@@ -29,7 +37,7 @@
 recomputed digest can never equal an empty recorded one, so an empty digest is
 drift, and a file that merely exists proves nothing.
 
-CONSUMED, NOT OWNED. openDox-spec owns these four schemas. The code leg
+CONSUMED, NOT OWNED. openDox-spec owns these schemas. The code leg
 releases none of them, and a copy is changed in the spec leg and then copied
 here again, never edited here. The copies, the record, and the `commit` it
 names move together, in one commit.
@@ -78,11 +86,13 @@
 SCHEMA_DIR = "schemas"
 
 #: THE INPUT SET, as a record must hold it: openDox's own spec leg's four
-#: schemas (7.1, as T007's batch G amends it). A record that names any other
+#: validated schemas (7.1, as T007's batch G amends it), and the finding's
+#: neutral shape, which the health engine reads and no validator kind names
+#: (batch Q's addendum; N-15; plan 038 T041). A record that names any other
 #: copy, or leaves one of these out, is refused, like a record naming another
 #: leg. So no edit to the record lets a copy of `gate-intent` or of the
 #: possibles register (7.1b) be served, even with its file beside the others.
-COPY_IDS = frozenset({"ideation-workbench", "opendox-snapshot",
+COPY_IDS = frozenset({"ideation-workbench", "opendox-health-finding", "opendox-snapshot",
                       "xfactory-workbench-chat-turn", "xfactory-workbench-model-catalog"})
 
 _ID = re.compile(r"[a-z0-9]+(?:-[a-z0-9]+)*")
@@ -214,8 +224,9 @@ def record() -> Record:
         copies.append(PackagedCopy(copy_id, path, digest))
     recorded = {copy.id for copy in copies}
     if recorded != COPY_IDS:
-        raise _refuse(f"it records {sorted(recorded)}, not openDox's four, "
-                      f"{sorted(COPY_IDS)} (7.1; 7.1b keeps every other schema out)")
+        raise _refuse(f"it records {sorted(recorded)}, not the copies openDox carries, "
+                      f"{sorted(COPY_IDS)} (7.1, as batches G and Q amend it; 7.1b keeps "
+                      "every other schema out)")
     return Record(SPEC_LEG, commit, tuple(copies))
 
 

src/opendox/contracts/copies.yaml

@@ -11,29 +11,40 @@
 # WHERE THE VALUES CAME FROM, read with `git show <commit>:<path> | sha256sum`
 # in opensoft/openDox-spec.
 #
-# * `commit` is the spec-leg commit the openDox root pins: T053 as landed,
-#   openDox-spec#16's squash f7ee3c76, which the root's `contracts/spec-pin.yaml`
-#   and `spec` gitlink name since opensoft/openDox#14 (dox-v1.1). It is the one
-#   commit that carries all four files.
+# * `commit` is the spec-leg commit the openDox root pins: T040 as landed,
+#   openDox-spec#17's squash 7db9438b, which the root's `contracts/spec-pin.yaml`
+#   and `spec` gitlink name since opensoft/openDox#20 (plan 038 T060,
+#   dox-v1.2). It is the one commit that carries all five files.
 # * Each digest is the one the root's `contracts/manifest.yaml` records for that
-#   file at that commit. Three of the four files are unchanged from the root's
-#   previous spec pin, 8fe8c4c7. The fourth is T053's `opendox-snapshot`.
+#   file at that commit. Four of the five files are unchanged from the root's
+#   previous spec pin, f7ee3c76 (T053, dox-v1.1). The fifth is T040's
+#   `opendox-health-finding`, which plan 038's T041 copies here.
 #
-# `commit` moved here from #16's head, cd49eb25, in lockstep with the root's
-# spec pin. f7ee3c76 has cd49eb25's tree, so no digest moved. A digest moves
-# only when its file changes.
+# WHAT THE FIVE ARE (7.1, as T007's batch G amends it and T005's batch Q adds
+# to it; N-15). Four are the schemas of the validator's kinds. The fifth is
+# the finding's neutral shape: a copy the health engine reads, and no kind the
+# validator validates, because a finding's `kind` is its family and no `kind`
+# constant can name the schema. `opendox.health_contract` mirrors it.
+#
+# `commit` moved here from f7ee3c76 in lockstep with the root's spec pin (T041).
+# openDox-spec#17 only added files, so no digest of the four moved. Before
+# that, it moved from openDox-spec#16's head, cd49eb25, to its squash f7ee3c76,
+# which has cd49eb25's tree. A digest moves only when its file changes.
 #
 # NEVER EDIT A COPY OR A DIGEST IN PLACE. A copy changes in the spec leg. It
 # arrives here when the spec leg's file is copied at the pinned commit and its
 # digest recorded, in one commit.
 schema_version: 1
 kind: packaged-contract-copies
 spec_leg: opensoft/openDox-spec
-commit: "f7ee3c763b3af4581daf1cd54406e5111e9358e6"
+commit: "7db9438b4cc4446ab4e6ab5b552c220312deccc9"
 copies:
   - id: ideation-workbench
     path: contracts/schemas/ideation-workbench.schema.yaml
     sha256: "d30438491119c20928fbe4e85088fc33682829eeb6558d87dafce651000faafc"
+  - id: opendox-health-finding
+    path: contracts/schemas/opendox-health-finding.schema.yaml
+    sha256: "6fb9b29f23a4270fa0310624d9e59b5d82e9888a5168600671e90ed30f781016"
   - id: opendox-snapshot
     path: contracts/schemas/opendox-snapshot.schema.yaml
     sha256: "f9e3e111af1d4bd4c377c933027d81b582ae2b0a395b66f4e4621992454a584a"