@tiphys/kernel 0.0.0 → 0.2.0

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"
+        }
+      }
+    }
+  }
+}

package/schemas/gate-registry.schema.json

@@ -0,0 +1,260 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tiphys.dev/schemas/gate-registry.schema.json",
+  "title": "Tiphys canonical gate registry",
+  "$comment": "R-094: the canonical list of gates per assurance mode, intended as the single source consumed by CI and by the role briefs. As delivered by M3-P2 the BRIEFS half is real (CLAUDE.md's gate section is rendered from the registry) and the CI half is not (CI invokes the runner with --manifest gates.manifest.json); gate-registry.yaml's own header states the divergence and test/gate-registry.test.ts asserts it in both directions. Kernel plan M3, M3-P2 step 2. A SUPERSET of the M2-P1 gate manifest (src/gates/schemas/gate-manifest.schema.json): every field that schema defines is defined here with the same meaning, and this document adds four, `modes` (made live from the field M2 reserved), `events`, `verified-by` and `probe`, plus the top-level `preflight` list. SC-011 is carried over unchanged: a gate whose precondition is unmet reports not-applicable and NEVER green.",
+  "description": "One registry per repository. Which gates exist, how each is invoked, which assurance modes select it, which CI events evaluate it, whether a script or a clean-room checklist probe verifies it, and which commands can destroy work.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["kind", "version", "preflight", "gates", "destructiveCommands"],
+  "properties": {
+    "kind": {
+      "description": "The artifact type, so `tiphys validate --type auto` resolves this document without being told. Every M3-P1 artifact type carries one and this mirrors them.",
+      "type": "string",
+      "const": "gate-registry"
+    },
+    "note": {
+      "description": "Free prose for the registry's own readers.",
+      "type": "string"
+    },
+    "version": {
+      "$comment": "A closed set rather than a minimum, because the authoring vocabulary of schemas/README.md has no `minimum` keyword and a bare `type: integer` would admit 0 and negatives.",
+      "type": "integer",
+      "enum": [1]
+    },
+    "preflight": {
+      "$comment": "R-094. The ordered local commands every change must pass before any registry gate means anything. They live IN the registry rather than beside it because CLAUDE.md's gate section is rendered from this document IN FULL (M3-P2 criterion 6, scripts/render-agent-rules-gates.mjs), and a step left outside the registry would be exactly the hand-maintained gate list criterion 6 forbids.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/preflightStep"
+      }
+    },
+    "gates": {
+      "description": "Append-only registry keyed by id. No minItems, matching the M2 manifest: a registry with zero gates must reach the runner and be reported as no applicable gate, not rejected at load.",
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/gate"
+      }
+    },
+    "destructiveCommands": {
+      "description": "CLI commands and module paths whose operations can destroy work. Carried over from the M2 manifest unchanged; M2-P2 rule (e) DERIVES a witness class from it rather than trusting an implementer's declaration.",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "$defs": {
+    "commandArray": {
+      "description": "argv array. The runner appends --result and --evidence, plus one flag per declared parameter. Defined once in $defs because strict mode requires every `required` name to be declared in `properties` at the SAME level, so the conditional rules below must restate it and a second copy of the constraint would be a second thing to keep in sync.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string"
+      }
+    },
+    "probeId": {
+      "description": "The checklist probe id M3-P7 must supply. Required exactly when verified-by is clean-room-checklist.",
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]*$"
+    },
+    "preflightStep": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["command", "note"],
+      "properties": {
+        "command": {
+          "description": "argv array, run in the repository root.",
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string"
+          }
+        },
+        "note": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "gate": {
+      "$comment": "THREE conditional rules, chained through $ref rather than stacked in one object, because JSON Schema allows one `if`/`then` pair per schema object and `allOf` is outside the authoring vocabulary of schemas/README.md. Each link adds exactly one rule and each rule has its own acceptance criterion. This link: M3-P2 criterion 4. A gate declared `conditional` is one that MAY report not-applicable, and SC-011 says not-applicable ASSERTS an evaluated, unmet precondition; a conditional gate with no precondition can therefore report not-applicable with nothing evaluated, which is the vacuous pass this registry exists to make impossible. `deploy` and `migrations` are the two conditional entries this rule binds.",
+      "$ref": "#/$defs/gateProbeRule",
+      "if": {
+        "type": "object",
+        "required": ["applicability"],
+        "properties": {
+          "applicability": {
+            "const": "conditional"
+          }
+        }
+      },
+      "then": {
+        "type": "object",
+        "required": ["precondition"],
+        "properties": {
+          "precondition": {
+            "$ref": "#/$defs/precondition"
+          }
+        }
+      }
+    },
+    "gateProbeRule": {
+      "$comment": "M3-P2 criterion 2. A clean-room-checklist entry with no probe names no question, so nothing can ever verify it and the entry is a gate id with nothing behind it. D-11 settles that R-043 and R-044 are verified this way.",
+      "$ref": "#/$defs/gateCommandRule",
+      "if": {
+        "type": "object",
+        "required": ["verified-by"],
+        "properties": {
+          "verified-by": {
+            "const": "clean-room-checklist"
+          }
+        }
+      },
+      "then": {
+        "type": "object",
+        "required": ["probe"],
+        "properties": {
+          "probe": {
+            "$ref": "#/$defs/probeId"
+          }
+        }
+      }
+    },
+    "gateCommandRule": {
+      "$comment": "A `script` gate is verified by running a process, so it must say which one. A `clean-room-checklist` gate has no process and carries no command, which is why `command` is not in the base required list.",
+      "$ref": "#/$defs/gateShape",
+      "if": {
+        "type": "object",
+        "required": ["verified-by"],
+        "properties": {
+          "verified-by": {
+            "const": "script"
+          }
+        }
+      },
+      "then": {
+        "type": "object",
+        "required": ["command"],
+        "properties": {
+          "command": {
+            "$ref": "#/$defs/commandArray"
+          }
+        }
+      }
+    },
+    "gateShape": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "unitLabel", "applicability", "verified-by", "modes", "events"],
+      "properties": {
+        "$comment": {
+          "description": "Clause ids this entry discharges, per schemas/README.md.",
+          "type": "string"
+        },
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9-]*$"
+        },
+        "command": {
+          "$ref": "#/$defs/commandArray"
+        },
+        "unitLabel": {
+          "type": "string",
+          "minLength": 1
+        },
+        "applicability": {
+          "description": "required: an unmet precondition fails the run. conditional: an unmet precondition does not.",
+          "type": "string",
+          "enum": ["required", "conditional"]
+        },
+        "verified-by": {
+          "$comment": "D-11. R-043 and R-044 are not reliably computable from a diff, so their gate is a clean-room checklist probe rather than a script, and the registry SAYS which of the two a reader is looking at instead of leaving it to be inferred from whether a command happens to be present.",
+          "type": "string",
+          "enum": ["script", "clean-room-checklist"]
+        },
+        "probe": {
+          "$ref": "#/$defs/probeId"
+        },
+        "modes": {
+          "$comment": "The field the M2 manifest schema RESERVED (src/gates/schemas/gate-manifest.schema.json line 70, validated if present and ignored by the M2 runner), made LIVE here. Blueprint section 5: the canonical list of gates PER ASSURANCE MODE. The item enum is the three mode ids M3-P3 defines.",
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "enum": ["full", "direct-pr", "local-only"]
+          }
+        },
+        "events": {
+          "$comment": "T-009, D-M3-34. A gate result is evidence only for the configuration that produced it, and this repository's workflow runs DIFFERENT bundles on `pull_request` and on `push` to `main`. An entry that does not say which events evaluate it carries a claim nobody can check. For every entry PROMOTED from gates.manifest.json the value is derived from the two bundle definitions in scripts/m2-exit-test.sh and never assigned by judgment; for an entry that is not in that manifest it is derived from whatever mechanism does evaluate it, which for agent-rules-drift is a workflow step carrying no `if:`. Both derivations are asserted in test/gate-registry.test.ts.",
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "enum": ["pull_request", "push"]
+          }
+        },
+        "parameters": {
+          "description": "Run parameters this gate's command REQUIRES. Declared rather than inferred. An absent declared parameter makes the gate error, never not-applicable (M2-C-3).",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["base", "head", "phase"]
+          }
+        },
+        "precondition": {
+          "$ref": "#/$defs/precondition"
+        }
+      }
+    },
+    "precondition": {
+      "$comment": "SC-011, carried over from the M2-P1 manifest schema UNCHANGED, field for field. A gate whose precondition is unmet reports not-applicable and never green; not-applicable ASSERTS that a precondition was evaluated and found unmet.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "kind"],
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "kind": {
+          "description": "The closed set. Kind-specific required fields are checked by src/gates/manifest.ts, which emits the same INVALID <pointer> <message> diagnostics.",
+          "type": "string",
+          "enum": [
+            "file-exists",
+            "file-absent",
+            "branch-matches",
+            "diff-touches",
+            "command-exit-zero"
+          ]
+        },
+        "path": {
+          "description": "file-exists and file-absent.",
+          "type": "string"
+        },
+        "pattern": {
+          "description": "branch-matches. A JavaScript regular expression source that is ANCHORED: it is compiled as ^(?:<pattern>)$ and must match the WHOLE branch name. The token {phase} is replaced by the --phase value, REGEX-ESCAPED.",
+          "type": "string"
+        },
+        "paths": {
+          "description": "diff-touches. Path prefixes; the precondition is met when the diff changes a path under any of them.",
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string"
+          }
+        },
+        "command": {
+          "description": "command-exit-zero. argv array, run in the runner's working directory.",
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/mechanism-index.schema.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tiphys.dev/schemas/mechanism-index.schema.json",
+  "title": "Tiphys mechanism index",
+  "$comment": "Kernel plan M3, M3-P6 criterion 8 and D-M3-23. T-005's structural consequence: a rule M1-P3 paid for in a multi-hour investigation did not reach M1-P5, which reimplemented the same claim-file mechanism silently and produced the most severe defect found in M1. The implementer there had read the plan, the agent-rules file, the constraint list, the environment warnings and three work histories, and NONE of them carried the rule, because a rule about a MECHANISM has no home in a document organised by phase. This document is that home. THE SCHEMA SHIPS HERE AND THE GENERATOR SHIPS AT M3-P8, which is the only forward reference in M3-P6 and is why D-M3-23 exists: M3-P8 EDITS this document to add `machine-readable-form` and does not create it. WHAT THIS SCHEMA CANNOT DO. It cannot tell a rule from a platitude: `rule` is a string, and whether its text is something an implementer can obey or a sentiment they can agree with is judgment. It cannot check that `evidence[]` resolves; entries are prose citations of artifacts that may live in delivery/, which the kernel does not ship, so resolution is not computable from an installed package. And it cannot tell whether the index is COMPLETE, which is the property M3-P6's registered superset test and M3-P8 criterion 4c cover from the two ends.",
+  "description": "One document per project. Every mechanism this project has already learned something about, the rule that learning established, the sibling implementations that share the mechanism, and the artifacts that paid for it. Read the row before you use the mechanism.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["kind", "version", "mechanisms"],
+  "properties": {
+    "kind": {
+      "type": "string",
+      "const": "mechanism-index"
+    },
+    "version": {
+      "$comment": "Document format version, not a project version. A closed set rather than a minimum, for the reason schemas/gate-registry.schema.json:21 already records: the authoring vocabulary has no `minimum` keyword, so a bare `type: integer` would admit 0 and negatives.",
+      "type": "integer",
+      "enum": [1]
+    },
+    "supersedes": {
+      "$comment": "The interim artifact this index replaces, by path, when there is one. Carried so a reader of the index can find what it was converted FROM, and so M3-P8's generated projection can be checked against the same source rather than against a memory of it. Optional: a project with no interim file omits it.",
+      "type": "string",
+      "minLength": 1,
+      "pattern": "\\S"
+    },
+    "mechanisms": {
+      "$comment": "minItems 1, because an index with no mechanisms is a file that satisfies every lookup obligation by having nothing to look up. That is the third row of M3-P6's own hazard table ('the index it names is the stub nobody replaced'), and the schema closes the degenerate end of it; the other end is the registered superset test, which no schema can express.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["key", "name", "rule", "evidence"],
+        "properties": {
+          "key": {
+            "$comment": "The stable id, and the thing a citation elsewhere names. DERIVED FROM `name` rather than invented: lowercase, every run of characters outside [a-z0-9] replaced by a single hyphen, leading and trailing hyphens removed. M3-P6's registered test applies that derivation to `name` and compares, so a key that drifts from its name is red rather than merely odd. Ids are never renumbered and a retired key is never reused, which is the rule CLAUDE.md's identifier-schemes section states for every scheme in this project.",
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+          },
+          "name": {
+            "$comment": "The mechanism in the words a reader would search for. For a row converted from an interim index, this is the interim table's own first column VERBATIM, which is what makes the conversion checkable against the file it came from instead of against a paraphrase of it.",
+            "type": "string",
+            "minLength": 1,
+            "pattern": "\\S"
+          },
+          "rule": {
+            "$comment": "What this project learned, stated as something to DO or NOT DO. Not a description of the mechanism: an implementer who reads this row and changes nothing has read a description, and the row has failed.",
+            "type": "string",
+            "minLength": 1,
+            "pattern": "\\S"
+          },
+          "siblings": {
+            "$comment": "The other implementations that share this mechanism, by path. The `mechanism-sibling` clause in roles/implementer.md is the instruction that keeps this list current: a phase establishing a rule about a mechanism records it here AND names the siblings, because the recorded cost of not doing so is one silent reimplementation two phases later. Optional, and an EMPTY list is meaningful: it says the mechanism has exactly one implementation today.",
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "pattern": "\\S"
+            }
+          },
+          "machine-readable-form": {
+            "$comment": "ADDED BY M3-P8 (D-M3-23's forward reference, step 2). Where the SAME rule exists as data: a path plus the key inside it. The `destructive-git-operation` row is the worked example and the reason the field exists: its prose rule and the `destructiveCommands` list in `gates.manifest.json` are two views of one thing (M2 plan section 2 item 10), and a citation is what stops them drifting apart silently. PROJECTED, NEVER AUTHORED HERE: this document is generated from the tuition feed's `mechanisms[]` by `tiphys tuition index`, so the field is written in the entry that established the rule. The derived check mechanism-rule-evidence-resolves resolves both halves against the real document, so a key M2 renames reddens rather than rotting. Optional: most rules exist only as prose, which is a fact about the rule and not a defect.",
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["path", "key"],
+            "properties": {
+              "path": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "\\S"
+              },
+              "key": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "\\S"
+              }
+            }
+          },
+          "evidence": {
+            "$comment": "What paid for the rule: a defect, a fix round, an investigation, a review finding, a tuition entry. minItems 1 is the load-bearing constraint of this whole document. The interim index states it in prose ('a rule with no citation is not a rule'), and prose is what this project has recorded three times as not surviving; here it is a validation failure.",
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "pattern": "\\S"
+            }
+          }
+        }
+      }
+    }
+  }
+}