@tiphys/kernel 0.0.0 → 0.1.0

package/schemas/checklist.schema.json

@@ -0,0 +1,114 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tiphys.dev/schemas/checklist.schema.json",
+  "title": "Tiphys review checklist",
+  "$comment": "R-026b, R-027, R-028a, R-050b, R-053, R-054, R-055, R-056a, R-057b, R-059, R-066, R-093. Kernel plan M3, M3-P7 steps 1 and 5. A CHECKLIST IS A PROBE LIST WITH DECLARED ENTRY POINTS. THE HAZARD THIS DOCUMENT EXISTS AGAINST is the phase's own: a checklist whose probes are present, unique, resolvable and USELESS. This schema reaches four of the seven ways that happens and reaches none of the other three, which is stated here rather than left for a reader to assume. WHAT IT REACHES: a probe with no question, no scope or no evidence policy (required plus minLength); an `applies-to` token that is prose rather than a scope a resolver can group by (pattern); a framing with no entry point or that orders nothing (required plus minItems); a `verifies-gate` that is blank. WHAT IT CANNOT REACH, each with the instrument that does. (1) Whether a probe's TEXT is specific enough to need opening a file: that is a property of prose, it is criterion 3b's registered tests for the five probe sets the plan names, and for the rest it is risk 2 and the suggested-tier note. (2) Whether two probes share an `id`: `uniqueItems` compares WHOLE array items, so two probes differing in any other field are already unique to it; that is the Kind B check `checklist-probe-ids-unique`. (2a) THE SAME THING ONE ARRAY ALONG, missed until fix round 2 because the keyword limitation was recorded for probes and not generalised: two FRAMINGS sharing an id, which is the check `checklist-framing-ids-unique`. (3) Whether a `verifies-gate` names a gate that exists, or whether a probe named by the registry carries the back-reference at all: both are cross-document and are the Kind B check `gate-probes-resolve`, running in both directions.",
+  "description": "A review checklist: a list of probes a reviewer answers, plus the framings that decide which probe they answer first.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["kind", "id", "applies-to", "probes"],
+  "properties": {
+    "kind": {
+      "$comment": "R-016's discriminator, so `tiphys validate --type auto` resolves this document without being told, and M3R-001's rule that a type is registered with the validator in the same step that ships its schema is satisfied in both halves. A per-phase extra probe file (R-054, `checklist resolve --extra`) is ALSO a checklist document and carries this same kind, which is what makes an extra probe set independently validatable instead of a fragment only one command can read.",
+      "type": "string",
+      "const": "checklist"
+    },
+    "id": {
+      "$comment": "The name `tiphys checklist resolve --checklist <id>` takes, and the basename of the shipped file. A TOKEN rather than free prose, because the resolver looks it up.",
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+    },
+    "applies-to": {
+      "$comment": "What kind of review this whole list is for, in one sentence. Prose, deliberately: this one is read by a human deciding which checklist to run and is never grouped on.",
+      "type": "string",
+      "minLength": 1,
+      "pattern": "\\S"
+    },
+    "probes": {
+      "$comment": "`uniqueItems` is here and it is NOT the id-uniqueness rule. It compares whole items, so it catches a probe pasted twice verbatim and nothing else. Two probes sharing an id and differing in their question are unique to this keyword and are exactly the dangerous instance, which is why criterion 1's rejection is the derived check and not this line.",
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "$ref": "#/$defs/probe"
+      }
+    },
+    "framings": {
+      "$comment": "T-001's second data point (M3R-004): the M1-P4 dual review found different defects because the two reviewers were given different STARTING QUESTIONS, and T-001's own words are that the checklists should vary the entry point rather than only the reviewer. A framing is therefore data in the artifact rather than a sentence in a dispatch prompt. Optional, because `checklists/flake-playbook.yaml` and `checklists/env-failure-diagnosis.yaml` are single-entry-point procedures and inventing framings for them would be ceremony. `uniqueItems` is here and, exactly as on `probes` above, it is NOT the id-uniqueness rule: it compares whole items, so two framings sharing an id and differing in their entry point are unique to it and are the dangerous instance, since `resolveChecklist` looks a framing up by id and first match wins. That is the derived check `checklist-framing-ids-unique`, added in fix round 2.",
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "$ref": "#/$defs/framing"
+      }
+    }
+  },
+  "$defs": {
+    "probe": {
+      "$comment": "One question, its scope, and whether an answer must cite something.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "probe", "applies-to", "evidence-required"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+        },
+        "probe": {
+          "$comment": "THE QUESTION. Prose, and the one field this schema can say least about: `minLength` stops it being empty and nothing here stops it being generic. That gap is the phase's whole hazard class and the instrument is criterion 3b.",
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        "applies-to": {
+          "$comment": "THE SCOPE TOKEN, and it is a token rather than prose because the resolver GROUPS ON IT. A framing's `orders-probes` names scopes, so this field is what makes `--framing` reorder the list rather than decorate it. A probe whose scope does not apply is still answerable ('not applicable, no destructive command in the diff'), so this is a grouping key and never a filter that silently drops a probe.",
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+        },
+        "evidence-required": {
+          "$comment": "R-054's second failure mode: an extra probe merged in without this field. A boolean rather than an optional flag, so a probe cannot be silently opinion-only. True means the answer must cite a path, a line, a captured command or an exit code.",
+          "type": "boolean"
+        },
+        "verifies-gate": {
+          "$comment": "NEW at revision 3, criterion 3c. The id of the `gate-registry.yaml` entry whose `verified-by: clean-room-checklist` names this probe. OPTIONAL because most probes verify no gate, and it is what makes the checklist-to-registry direction computable at all: without a back-reference there is nothing to resolve and an orphaned probe stays invisible by construction. That every registry-named probe MUST carry it is an `if`/`then` across two documents, which no keyword here reaches; it is enforced by `gate-probes-resolve`.",
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        }
+      }
+    },
+    "framing": {
+      "$comment": "One declared entry point into the same probe list.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "entry-point", "orders-probes"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+        },
+        "entry-point": {
+          "$comment": "The starting question this framing hands the reviewer, printed at the head of the resolved list. T-001's two real examples are walking the acceptance criteria as a contract, and starting from where this can destroy something or claim a guarantee it does not have.",
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        "orders-probes": {
+          "$comment": "The probe SCOPES, in the order this framing wants them, each naming an `applies-to` token. Probes in a named scope lead, scope by scope, and inside one scope the FILE ORDER decides; every probe in no named scope follows in file order. Ordering by scope rather than by probe id is what makes criterion 4d falsifiable: `CLAUDE.md` says the reviewer's FIRST check is item 3, and with a scope list the first resolved probe is the first `fix-round` probe IN THE FILE, so moving it later changes the answer. A framing that listed probe ids instead would pin the head no matter where the probe sat, which is the hazard class's 'ordering expressed as a comment rather than as position' wearing a schema's clothes.",
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/decision-record.schema.json

@@ -0,0 +1,88 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tiphys.dev/schemas/decision-record.schema.json",
+  "title": "Tiphys decision record",
+  "description": "Blueprint section 7's field list, plus the fields R-063 and R-090 need in order to be checkable rather than habitual. An OPEN QUESTION is a record with status open (D-7), so there is one register and never two.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "kind",
+    "id",
+    "project",
+    "task",
+    "question",
+    "options",
+    "reversibility",
+    "vetoable",
+    "revert-cost",
+    "status",
+    "decided",
+    "date"
+  ],
+  "properties": {
+    "kind": {
+      "type": "string",
+      "const": "decision-record"
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^DR-[0-9]{4}$"
+    },
+    "project": { "type": "string", "minLength": 1 },
+    "task": { "type": "string", "minLength": 1 },
+    "question": { "type": "string", "minLength": 1 },
+    "options": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["label", "consequence"],
+        "properties": {
+          "label": { "type": "string", "minLength": 1 },
+          "consequence": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "reversibility": {
+      "$comment": "R-063. Exactly three values, so the cost of being wrong is stated rather than implied.",
+      "type": "string",
+      "enum": ["reversible", "costly", "irreversible"]
+    },
+    "vetoable": {
+      "$comment": "R-090: a forced owner-adjacent call is decided, FLAGGED VETOABLE, and made trivially revertible. This field and revert-cost are what turn that sentence from a habit into a required field.",
+      "type": "boolean"
+    },
+    "revert-cost": {
+      "type": "string",
+      "minLength": 1
+    },
+    "status": {
+      "$comment": "D-7: an open question is a record with status open.",
+      "type": "string",
+      "enum": ["open", "deferred", "decided"]
+    },
+    "decided": {
+      "$comment": "The answer in the decider's own terms. Empty while the record is open or deferred; a record with status decided and an empty decided field is a record that claims an answer it does not carry, which is the Kind A pair the if/then below enforces.",
+      "type": "string"
+    },
+    "date": {
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
+    },
+    "evidence": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    }
+  },
+  "if": {
+    "type": "object",
+    "required": ["status"],
+    "properties": { "status": { "const": "decided" } }
+  },
+  "then": {
+    "type": "object",
+    "required": ["decided"],
+    "properties": { "decided": { "type": "string", "minLength": 1 } }
+  }
+}

package/schemas/final-report.schema.json

@@ -0,0 +1,90 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tiphys.dev/schemas/final-report.schema.json",
+  "title": "Tiphys final report",
+  "$comment": "R-089a. Kernel plan M3, M3-P4 step 2. THE FINAL REPORT IS A PROJECTION, NOT A SUMMARY, and that property is load-bearing beyond this phase. Every field here is DERIVED from records that already exist (findings, verdicts, decisions, work histories), which is the same relation M3-P8's mechanism index has to the tuition feed. That relation is what makes a dense read layer possible on top of a verbose archive: the projections are consumed at every dispatch and must stay dense, while the raw entries are read only in dispute. M3 BUILDS NO COMPACTOR AND THIS SCHEMA PROPOSES NONE; what it does is make the distinction structural, so a later compaction is a question about which layer a file is in rather than a judgement about which files look like filler. SILENCE AND EMPTINESS ARE DISTINGUISHABLE: each of the four enumerable sections is a two-branch oneOf, so `none: true` carries NO entries key at all and `none: false` carries at least one entry. That closes BOTH directions of the relation rather than one: an empty list without a marker is a rejection, and a `none: true` marker sitting on top of real entries is also a rejection. THE PARITY BETWEEN `inputs[]` AND `input-findings[]` IS NOT HERE: cross-array completeness is not a keyword property (M3R-002), so it is the derived check `final-report-finding-parity` in src/checks.ts, and it is checked a second time by the M2-P6 coverage checker's finding-to-outcome parity mode because the artifact should be self-checking AND the independent checker is the one the pipeline runs.",
+  "description": "One document per delivery. Every input finding mapped to an outcome, plus the decisions owed, the owner verifications outstanding, the infrastructure left behind, and anything done out of band.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "kind",
+    "subject",
+    "inputs",
+    "input-findings",
+    "decisions-owed",
+    "owner-verification",
+    "infrastructure-left",
+    "out-of-band"
+  ],
+  "properties": {
+    "kind": {
+      "description": "The artifact type, so `tiphys validate --type auto` resolves this document without being told.",
+      "type": "string",
+      "const": "final-report"
+    },
+    "subject": {
+      "description": "What this report is the final report OF.",
+      "type": "string",
+      "minLength": 1,
+      "pattern": "\\S"
+    },
+    "inputs": {
+      "$comment": "The finding ids this delivery took in. Kept SEPARATE from `input-findings[]` on purpose: a table that is its own inventory cannot be incomplete, which is the circularity scripts/check-clause-map.mjs's header names one level up. The derived check compares the two.",
+      "type": "array",
+      "items": { "type": "string", "minLength": 1, "pattern": "\\S" },
+      "uniqueItems": true
+    },
+    "input-findings": {
+      "$comment": "R-089a's table. Every id in `inputs[]` lands in exactly one row here with a non-empty outcome.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "outcome"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1, "pattern": "\\S" },
+          "outcome": { "type": "string", "minLength": 1, "pattern": "\\S" }
+        }
+      }
+    },
+    "decisions-owed": { "$ref": "#/$defs/enumerableSection" },
+    "owner-verification": { "$ref": "#/$defs/enumerableSection" },
+    "infrastructure-left": { "$ref": "#/$defs/enumerableSection" },
+    "out-of-band": { "$ref": "#/$defs/enumerableSection" }
+  },
+  "$defs": {
+    "enumerableSection": {
+      "$comment": "ALLOWED TO BE EMPTY ONLY WITH AN EXPLICIT MARKER, so silence and emptiness are distinguishable (plan step 2). The two branches are exclusive by construction: branch 1 permits `none: true` AND NOTHING ELSE, so a marker sitting on top of real entries is a rejection; branch 2 requires `none: false` with at least one entry, so an empty list hiding behind a false marker is a rejection too. Both directions, rather than the one the requirement's letter names. RESIDUE, ADDED IN M3-P4 FIX ROUND 2 BY THE CR-002 ENUMERATION: this is the same mechanism CR-002 named one document over. The branch is picked by A VALUE THE AUTHOR WRITES, and branch 1 owes NOTHING, so an author with three real decisions owed writes `none: true` and the schema is satisfied. What the two branches close is INTERNAL CONTRADICTION (a marker over entries, entries with no marker); what neither reaches is a marker over a truth outside the document. Nothing in this schema could reach it, because there is no second record here to compare against; the derived check `final-report-finding-parity` is what that comparison looks like where a second record exists, and `decisions-owed` has none.",
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["none"],
+          "properties": { "none": { "type": "boolean", "const": true } }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["none", "entries"],
+          "properties": {
+            "none": { "type": "boolean", "const": false },
+            "entries": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["statement"],
+                "properties": {
+                  "id": { "type": "string", "minLength": 1, "pattern": "\\S" },
+                  "statement": { "type": "string", "minLength": 1, "pattern": "\\S" },
+                  "owner": { "type": "string", "minLength": 1, "pattern": "\\S" }
+                }
+              }
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/schemas/finding.schema.json

@@ -0,0 +1,106 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tiphys.dev/schemas/finding.schema.json",
+  "title": "Tiphys finding set",
+  "$comment": "R-029. Kernel plan M3, M3-P5 step 5. THE OUTPUT OF A REVIEW: a verdict, the model family that produced it, and a severity-ranked list of findings each of which names the plan edit it demands. THE HAZARD THIS DOCUMENT EXISTS AGAINST is the one the phase's hazard-class table names: a schema that admits an EMPTY review as a thorough one. A review that found nothing and a review that looked at nothing produce the same JSON unless the empty case is made to say so, and `no-findings-statement` plus the `oneOf` below is what makes them different documents. WHAT THIS SCHEMA CANNOT DO. (1) It cannot tell a real `concrete-edit` from a restatement of the finding; that is M3-P7's probe territory, and what is bought here is that the field cannot be absent or blank. (2) It cannot tell a real `produced-by` from a guess; T-001's ask was that the family be RECORDED, and recorded is what `required` buys. (3) It cannot rank severities: `enum` is an unordered set and the rank is stated in this comment, low < medium < high < critical, the same four names schemas/plan.schema.json uses so the two documents do not carry two vocabularies. (4) It cannot see whether the same finding id appears twice; comparing array elements to each other is Kind B and this phase adds no Kind B row (criterion 5).",
+  "description": "A finding set: the artifact an adversarial plan review or a clean-room review outputs.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["kind", "verdict", "produced-by", "findings"],
+  "properties": {
+    "kind": {
+      "$comment": "R-016's discriminator, so `tiphys validate --type auto` resolves this document without being told, and M3R-001's rule that a type is registered with the validator in the same step that ships its schema is satisfied in both halves rather than one. A finding set is a YAML or JSON document, so unlike a role brief it CAN carry a kind.",
+      "type": "string",
+      "const": "finding"
+    },
+    "verdict": {
+      "$comment": "R-029's `verdict`, required. A NON-EMPTY STRING rather than an enum, deliberately: M3-P7 ships the verdict contract and its closed vocabulary, and inventing a second one here would be the two-vocabularies failure this file's kind field exists to avoid. `pattern: \\S` because `required` alone is satisfied by the empty string.",
+      "type": "string",
+      "minLength": 1,
+      "pattern": "\\S"
+    },
+    "produced-by": {
+      "$comment": "T-001's second ask, recorded in delivery/tuition/T-001-cross-model-review-catches.md: record in the review header which family produced it. DR-0012 condition 1 then makes the two clean-room reviews of one head differ in this field, and that comparison is between two DOCUMENTS and is therefore not reachable from inside either of them. What is reachable is that the field cannot be absent, which is what this is.",
+      "type": "string",
+      "minLength": 1,
+      "pattern": "\\S"
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/finding"
+      }
+    },
+    "no-findings-statement": {
+      "$comment": "The empty review's own sentence: what was looked at, and why nothing was found. Required exactly when `findings` is empty, by the `oneOf` below.",
+      "type": "string",
+      "minLength": 1,
+      "pattern": "\\S"
+    }
+  },
+  "oneOf": [
+    {
+      "$comment": "Branch A: the set carries at least one finding. `type: array` is RESTATED here and that is not redundancy: measured against ajv 8.20.0 under this validator's `strict: true`, a `minItems` inside a subschema whose type is declared only at the outer level is refused with `schema uses keyword minItems without declaring type array`.",
+      "properties": {
+        "findings": {
+          "type": "array",
+          "minItems": 1
+        }
+      }
+    },
+    {
+      "$comment": "Branch B: the set carries no finding and therefore must say what was looked at. `no-findings-statement` is RESTATED in a sibling `properties` here and that is not redundancy either: measured against the same engine, a `required` naming a property not declared in `properties` at the same level fails COMPILATION under strictRequired with `strict mode: required property \"no-findings-statement\" is not defined`. WHY `oneOf` AND NOT THE `if`/`then` THE PLAN'S PARENTHETICAL NAMES. The obligation is `findings` EMPTY implies a sibling required, so the `if` would have to match emptiness. The closed authoring vocabulary (schemas/README.md) has no `not` and no `maxItems`; `minItems: 1` and `contains` both match the NON-empty case, which is the wrong polarity, and `then` cannot remove an obligation. `oneOf` is in the vocabulary and does express it. The declared deviation and its captured probe output are in delivery/work-history/m3-p5.md. ONE CONSEQUENCE BEYOND WHAT CRITERION 5(b) ASKED FOR, recorded rather than discovered: a set carrying BOTH findings and a no-findings statement matches both branches and is therefore invalid too. That is the same both-directions property M3-P4's report contract reaches with a derived check.",
+      "required": ["no-findings-statement"],
+      "properties": {
+        "no-findings-statement": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "finding": {
+      "$comment": "R-029's severity-ranked findings with concrete plan edits.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "severity", "evidence", "concrete-edit"],
+      "properties": {
+        "id": {
+          "$comment": "The stable id the arbitration and the fix round cite. The identifier schemes are CLAUDE.md's; this schema does not pick one, because CR-nnn, PR-nnn and EXT-F-nn are all real and all cited.",
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        "severity": {
+          "$comment": "Ranked low < medium < high < critical. Same four names as schemas/plan.schema.json's phase severity.",
+          "type": "string",
+          "enum": ["low", "medium", "high", "critical"]
+        },
+        "evidence": {
+          "$comment": "Evidence beats assertion: exit codes, counts, file paths with line numbers, captured output, URLs. `minItems: 1` is the whole point, because a finding with no evidence is an opinion and this repository treats an agent's claim with no verifiable artifact behind it as unknown.",
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "\\S"
+          }
+        },
+        "concrete-edit": {
+          "$comment": "R-029's `concrete plan edits`. The edit the finding DEMANDS, not a description of the problem. Required on EVERY finding regardless of severity, which is strictly stronger than criterion 5(a)'s dangerous instance (a `severity: high` finding with no `concrete-edit`) and is stronger on purpose: a low finding with no proposed edit is a remark, and a review made of remarks is the empty review with extra steps.",
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        "analysis": {
+          "$comment": "Section 1.5's finding-set row: what is not enumerable is the ARGUMENT behind one finding, which is why it lives inside a field rather than becoming structure. Optional, and non-empty when present.",
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        }
+      }
+    }
+  }
+}