@tiphys/kernel 0.0.0 → 0.1.0

package/schemas/role-brief.schema.json

@@ -0,0 +1,105 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tiphys.dev/schemas/role-brief.schema.json",
+  "title": "Tiphys role-brief frontmatter",
+  "$comment": "Kernel plan M3, M3-P5 step 1. THIS DOCUMENT VALIDATES THE FRONTMATTER OF A ROLE BRIEF AND NOTHING ELSE. Section 1.5 of the plan grants role briefs the markdown-with-YAML-frontmatter exception on the ground that a brief's effect comes from argument, ordering and emphasis, which have no field decomposition that preserves them; the frontmatter carries everything that IS enumerable and this schema is what makes that half checkable. FOUR THINGS THIS SCHEMA CANNOT DO, stated here rather than left to be discovered. (1) IT CANNOT SEE THE BODY. `clauses[]` is a list of ids; whether each id has a heading with text under it, and whether that text says the opposite of the row it discharges, are not keyword properties. The first half is closed by the clause round trip in src/roles.ts, which `tiphys validate --type role-brief` runs after this schema passes; the second half is judgment and is M3-P7's `clause-text-matches-row` probe (the phase's own hazard-class table says so). (2) IT CANNOT SEE THE FILESYSTEM. Every entry of `mandated-reading[]` is a string here; whether the path exists, and whether it is a regular file rather than a named pipe, are resolved by `tiphys brief compose` (criteria 2 and 6c). (3) IT CANNOT TELL A COMPLETE MANDATED-READING LIST FROM AN INCOMPLETE ONE. Nothing can compute which document a role NEEDS, which the phase's hazard-class table records as unreachable by any criterion. (4) IT CARRIES NO `kind` FIELD AND THEREFORE NEVER RESOLVES UNDER `--type auto`. That is deliberate and it is not an oversight of M3R-001: `--type auto` reads `kind` from the DECODED instance, and decoding a role brief means knowing first that it is markdown with frontmatter rather than a YAML document, so the type must be named before the document can be decoded at all. The half of M3R-001 that matters, registering the type in `TYPE_TABLE` in the same step that ships the schema, is done in src/commands/validate.ts.",
+  "description": "The YAML frontmatter block of every roles/*.md file and of AGENTS.md. Role identity, lifetime, visibility, the reading it must do in order, the verifiers attached to it, what it may output, its default model tier, and the clause ids the clause map resolves against.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "role",
+    "lifetime",
+    "sees",
+    "never",
+    "mandated-reading",
+    "verifiers",
+    "outputs",
+    "model-tier",
+    "clauses"
+  ],
+  "properties": {
+    "role": {
+      "$comment": "R-004, R-005, R-006. The six roles of blueprint section 6 and of the process document's section 0 role table. A CLOSED enum, and closed on purpose: role-model-config.yaml binds a tier to each of these six names and a seventh role would silently have no tier. The vocabulary is identical to role-model-config.yaml's `role` values, which is the property test/roles.test.ts asserts rather than this comment.",
+      "type": "string",
+      "enum": [
+        "orchestrator",
+        "investigator",
+        "plan-writer",
+        "adversarial-plan-reviewer",
+        "implementer",
+        "clean-room-reviewer"
+      ]
+    },
+    "lifetime": {
+      "$comment": "The process document's role table, column 2. One mystery, one plan, one review, one phase, one pull request, or persistent across the whole run.",
+      "type": "string",
+      "minLength": 1,
+      "pattern": "\\S"
+    },
+    "sees": {
+      "$comment": "R-006 and SC-001. The process document's role table, column 3. An ARRAY rather than a sentence because the adversarial plan reviewer's visibility is the thing SC-001 found the two governing documents disagreeing about, and a list of three named inputs is comparable across documents where a sentence is not.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "pattern": "\\S"
+      }
+    },
+    "never": {
+      "$comment": "The process document's role table, column 4. The separation is the point: an investigator that fixes things and a reviewer that edits things are the two failures this column exists to prevent.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "pattern": "\\S"
+      }
+    },
+    "mandated-reading": {
+      "$comment": "R-033a's ordered-reading family. ORDER IS THE SEMANTIC: the first entry is read first. `minItems: 1` because a role with no mandated reading has declared that it needs no grounding, which no role in this process does. Resolution is done by `tiphys brief compose`, against the kernel root, through classifyEntry (D-M3-27), so a missing path and a named pipe are different reported failures rather than one hang.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "pattern": "\\S"
+      }
+    },
+    "verifiers": {
+      "$comment": "Blueprint section 6 attaches a verifier to a role. Values are gate ids from gate-registry.yaml or the name of an M2 component. NOT resolved against the registry here: that is a reference into another document and therefore Kind B, and this phase adds no entry to section 2.3's Kind B table (M3-P5 criterion 5). The residue is stated rather than hidden: a verifier naming a gate that does not exist passes this schema.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "pattern": "\\S"
+      }
+    },
+    "outputs": {
+      "$comment": "The artifact types the role may produce, named as `tiphys validate --type` names them. A PATTERN rather than an enum, and the reason is that an enum here would have to be edited by M3-P6, M3-P7 and M3-P8 as each ships a new type, which makes a shared file a serialisation point between phases the conflict pre-pass ruled concurrent. Residue, stated: an `outputs` entry naming a type no schema is registered for passes this schema.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "pattern": "^[a-z][a-z0-9-]*$"
+      }
+    },
+    "model-tier": {
+      "$comment": "R-075, resolved against role-model-config.yaml. The ENUM here is the Kind A half: the two tier names that file uses. The cross-document half, that this brief's tier equals the tier role-model-config.yaml binds to this role, is a reference into another document and is therefore Kind B; it is NOT built here, because a Kind B check registered for this type would need `--context` and criterion 1 requires `tiphys validate --type role-brief roles/<id>.md` to exit 0 with no context at all. test/roles.test.ts asserts the agreement instead, which is a registered test rather than a validator rule, and this comment says which of the two it is.",
+      "type": "string",
+      "enum": ["strongest", "cheaper"]
+    },
+    "clauses": {
+      "$comment": "The clause ids scripts/check-clause-map.mjs resolves against this artifact, plus the shared dispatch-contract clause ids. Every id here must occur EXACTLY ONCE as a body heading anchor of the form `## clause <id>` in the include-expanded body, and every anchor must occur here; that round trip is what stops a clause id being a label with nothing behind it, and it is enforced by src/roles.ts under `tiphys validate --type role-brief`. The pattern admits both requirement-row ids (R-004, R-010a) and named clauses (incremental-output).",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "pattern": "^[A-Za-z][A-Za-z0-9-]*$"
+      }
+    }
+  }
+}

package/schemas/role-model-config.schema.json

@@ -0,0 +1,90 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tiphys.dev/schemas/role-model-config.schema.json",
+  "title": "Tiphys role-to-model configuration",
+  "$comment": "R-075: model tier per risk, strongest for money-path and architecture phases, investigations and all reviews; cheaper for mechanical phases. Kernel plan M3, M3-P3 step 3. THIS IS CONFIGURATION AND NOTHING RESOLVES IT IN M3. Binding is done by the harness adapter (blueprint section 6), the charter override is L4 and lands at M4, and DR-0010's M3 half is still open with 'no action required before M4', so this document names no executor, no orchestration primitive and no model. It carries a TIER and a FAMILY POLICY per role and stops there.",
+  "description": "One document per repository. Which model tier each of blueprint section 6's roles defaults to, whether a charter may override it, and what constraint the role's model FAMILY is under.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["kind", "version", "roles"],
+  "properties": {
+    "kind": {
+      "description": "The artifact type, so `tiphys validate --type auto` resolves this document without being told.",
+      "type": "string",
+      "const": "role-model-config"
+    },
+    "note": {
+      "description": "Free prose for this document's own readers.",
+      "type": "string"
+    },
+    "version": {
+      "$comment": "A closed set rather than a minimum, for the same reason as the other M3 schemas: the authoring vocabulary has no `minimum` keyword.",
+      "type": "integer",
+      "enum": [1]
+    },
+    "roles": {
+      "description": "One entry per role. The six of blueprint section 6.",
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "$ref": "#/$defs/roleBinding"
+      }
+    }
+  },
+  "$defs": {
+    "roleBinding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["role", "tier", "charter-override", "rationale"],
+      "properties": {
+        "role": {
+          "$comment": "The six roles of blueprint section 6, in the process document's own role table. Closed, because M3-P5's role-brief schema resolves `model-tier` against this document and a role id that matches nothing here would resolve to nothing. CLOSED VOCABULARY AT v0.1.0 (DR-0020): these six are the tiphys kernel's OWN role ids. This enum rejects every other value, so a consuming project cannot bind a role of its own name at v0.1.0. Extension is an M4 question, deferred to a real pilot consumer for the same reversibility reason as the mode-id enum.",
+          "type": "string",
+          "enum": [
+            "orchestrator",
+            "investigator",
+            "plan-writer",
+            "adversarial-plan-reviewer",
+            "implementer",
+            "clean-room-reviewer"
+          ]
+        },
+        "tier": {
+          "$comment": "R-075's two tiers. NAMES A TIER, NEVER A MODEL: a model id here would go stale in weeks and would put a vendor's product name inside a versioned kernel artifact. The harness adapter maps tier to model at M4.",
+          "type": "string",
+          "enum": ["strongest", "cheaper"]
+        },
+        "strongest-for": {
+          "$comment": "R-075 is PHASE-CLASS SCOPED for one role and flat for the others: 'strongest model for money-path/architecture phases, investigations, and all reviews; cheaper tier for mechanical phases'. An implementer's tier therefore depends on the phase it is given, and a document carrying only a flat `tier` would silently drop half of R-075's rule. This field is that half, as DATA: the phase classes on which the role's tier is raised to `strongest`. Nothing in M3 classifies a phase, and no resolver reads this.",
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "enum": ["money-path", "architecture", "investigation", "review"]
+          }
+        },
+        "charter-override": {
+          "$comment": "Blueprint section 6 and R-075's migration-table note: the charter override is L4 and is resolved by the M4 harness adapter. The vocabulary is reserved here so the M4 adapter has a field to read rather than a convention to infer. Every role ships `allowed`, which is stated in delivery/work-history/m3-p3.md as a uniform value rather than presented as if it discriminated.",
+          "type": "string",
+          "enum": ["allowed", "forbidden"]
+        },
+        "review-model-family": {
+          "$comment": "T-001, and it is OPTIONAL because only review roles are under a family constraint. T-001 recorded a miss that survived three same-family review rounds and asked for 'at minimum, a charter-level option to route one review round of full-mode plans through a different family'. This is that option, expressed as a policy rather than as a family name, because naming a vendor's model family in a kernel artifact is the same staleness problem `tier` avoids.",
+          "type": "string",
+          "enum": [
+            "must-differ-from-sibling-review",
+            "must-differ-from-previous-round",
+            "unconstrained"
+          ]
+        },
+        "rationale": {
+          "description": "Why this role sits at this tier, referring to the rule it comes from. Required, so a tier cannot be lowered without someone writing down why.",
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    }
+  }
+}

package/schemas/status-line.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tiphys.dev/schemas/status-line.schema.json",
+  "title": "Tiphys status-line record",
+  "description": "R-084. The orchestrator narrates to the owner at MILESTONES ONLY. The sparseness is expressed structurally rather than as an instruction: there is no info state, no progress state and no heartbeat state, so routine noise is UNREPRESENTABLE. A vocabulary that cannot say 'still working' cannot be used to say it.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["kind", "at", "run", "project", "state", "detail", "refs"],
+  "properties": {
+    "kind": {
+      "type": "string",
+      "const": "status-line"
+    },
+    "at": {
+      "$comment": "RFC 3339 UTC, so two records from two machines sort.",
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]+)?Z$"
+    },
+    "run": {
+      "type": "string",
+      "minLength": 1
+    },
+    "project": {
+      "type": "string",
+      "minLength": 1
+    },
+    "state": {
+      "$comment": "Blueprint section 5, exactly five supervisor-actionable states. Every one of them is something the owner can DO something about; that is the membership rule, and it is why info, progress and heartbeat are absent rather than merely discouraged.",
+      "type": "string",
+      "enum": ["needs-decision", "blocked", "done", "failed", "phase-change"]
+    },
+    "detail": {
+      "type": "string"
+    },
+    "refs": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    }
+  }
+}

package/schemas/tuition.schema.json

@@ -0,0 +1,191 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tiphys.dev/schemas/tuition.schema.json",
+  "title": "Tiphys tuition entry",
+  "$comment": "Kernel plan M3, M3-P8 step 1 (R-091). ONE FAILURE MODE PER DOCUMENT, in the form a project that was not there can act on. THE LOAD-BEARING CONSTRAINT IS THE CONDITIONAL ONE: an entry with `kernel-relevant: true` must carry at least one `structural-consequence`, because an entry that claims kernel relevance and proposes no change to any kernel artifact is not tuition, it is an anecdote. The second is `mechanisms[].evidence`, minItems 1, which is T-005's checkability rule expressed as a validation failure rather than as advice: a rule with no citation to an investigation, review or tuition entry is not a rule. WHAT THIS SCHEMA CANNOT DO, stated so nobody reads a green as more than it is. It cannot tell a lesson from a platitude; every prose field is a non-empty string and whether its text changes what a reader does is judgment. It cannot tell whether a `structural-consequence` marked `applied` actually landed: the derived check `tuition-target-exists` resolves the target PATH against the tree, and whether that file contains the change claimed is a semantic relation no keyword and no check reaches (the plan's hazard table says so in the same words). And it cannot see an id collision with the delivery-side `T-nnn` space, which is `test/tuition.test.ts`'s registered duplicate-id scan.",
+  "description": "One failure mode this project paid for, with the mechanism it established and the change to a kernel artifact it forces. The tuition feed is the archive layer; tuition/mechanism-index.yaml is the dense READ layer projected out of the mechanisms[] field of every entry here.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "kind",
+    "version",
+    "id",
+    "project",
+    "date",
+    "stage",
+    "kernel-relevant",
+    "what-happened",
+    "lesson",
+    "evidence"
+  ],
+  "properties": {
+    "kind": {
+      "type": "string",
+      "const": "tuition"
+    },
+    "version": {
+      "$comment": "Document format version, not a project version. A closed set rather than a minimum, for the reason schemas/mechanism-index.schema.json already records: the authoring vocabulary has no `minimum` keyword, so a bare `type: integer` would admit 0 and negatives.",
+      "type": "integer",
+      "enum": [1]
+    },
+    "id": {
+      "$comment": "ONE `T-nnn` SPACE, SHARED WITH THE DELIVERING PROJECT'S OWN LOG, never renumbered and never reused after retirement (CLAUDE.md's identifier-schemes rule). The pattern fixes the shape; the uniqueness of an id ACROSS the two directories is not a property of one document and is checked by a registered test instead (M3R-011).",
+      "type": "string",
+      "pattern": "^T-[0-9]{3}$"
+    },
+    "project": {
+      "$comment": "Which delivery paid for this. A kernel-relevant entry travels upstream out of the project that learned it, so the entry has to say where it came from once it is no longer beside its own repository.",
+      "type": "string",
+      "minLength": 1,
+      "pattern": "\\S"
+    },
+    "date": {
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
+    },
+    "stage": {
+      "$comment": "Where in the pipeline it happened: a phase id, a review round, an exit test, the planning stage. Free text rather than an enum, because the stage vocabulary belongs to the delivery mode and a closed list here would reject a project running a pipeline this kernel does not define.",
+      "type": "string",
+      "minLength": 1,
+      "pattern": "\\S"
+    },
+    "kernel-relevant": {
+      "$comment": "TRUE means this entry constrains the kernel itself and ships upstream as a kernel pull request (R-091). It is a boolean rather than a prose field because it is the selector `tiphys tuition list --kernel-relevant` filters on and the condition the structural-consequence requirement below triggers off.",
+      "type": "boolean"
+    },
+    "what-happened": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "\\S"
+    },
+    "lesson": {
+      "$comment": "What a reader should DO differently, one item per lesson. minItems 1: an entry with no lesson is an incident report.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "pattern": "\\S"
+      }
+    },
+    "mechanisms": {
+      "$comment": "T-005's field, and the SOURCE of tuition/mechanism-index.yaml. The index is a PROJECTION of these entries rather than a second thing to maintain, so a mechanism is recorded here once and read from the index everywhere. Optional and possibly empty: many entries teach something about the process without constraining a mechanism, and an empty list says exactly that.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["mechanism", "rule", "evidence"],
+        "properties": {
+          "mechanism": {
+            "$comment": "The mechanism in the words a reader would search for. The index's `key` is DERIVED from this string (lowercase, runs outside [a-z0-9] collapsed to one hyphen, ends trimmed) and is never authored, so a key cannot drift from the mechanism it names.",
+            "type": "string",
+            "minLength": 1,
+            "pattern": "\\S"
+          },
+          "rule": {
+            "$comment": "What this project learned, stated as something to DO or NOT DO. An implementer who reads the 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. Projected into the index unchanged. 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": "Where the SAME rule exists as data (D-M3-26). The `destructive-git-operation` row is the worked example: its prose rule and `gates.manifest.json`'s `destructiveCommands` list are two views of one thing, and this field is what stops them drifting apart silently. The derived check mechanism-rule-evidence-resolves resolves both the path and the key against the real document, so a key M2 renames reddens here. Dependency direction is M3 reads M2, never the reverse.",
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["path", "key"],
+            "properties": {
+              "path": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "\\S"
+              },
+              "key": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "\\S"
+              }
+            }
+          },
+          "evidence": {
+            "$comment": "THE T-005 CHECKABILITY RULE, as a constraint rather than as advice: a rule with no citation to an investigation, review or tuition entry is not a rule. minItems 1 is what makes an unsupported mechanism a validation failure.",
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "pattern": "\\S"
+            }
+          }
+        }
+      }
+    },
+    "structural-consequence": {
+      "$comment": "The change to a kernel artifact this entry forces. REQUIRED AND NON-EMPTY when `kernel-relevant` is true, by the if/then below. `status` is the honest part: `applied` claims the change is in the tree and is checked against it by tuition-target-exists, `ticketed` names the record that carries it, and `proposed` claims nothing yet.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["target", "status", "change"],
+        "properties": {
+          "target": {
+            "$comment": "A kernel artifact path. Resolved against the repository by tuition-target-exists when `status` is `applied`.",
+            "type": "string",
+            "minLength": 1,
+            "pattern": "\\S"
+          },
+          "status": {
+            "type": "string",
+            "enum": ["proposed", "applied", "ticketed"]
+          },
+          "change": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "\\S"
+          },
+          "record": {
+            "$comment": "The decision record, plan section or ticket that carries a `ticketed` consequence. Optional in the keyword sense and expected in practice for that status; a `ticketed` consequence with no record is the shape a reader cannot follow, and it is left to review rather than encoded, because the record for a ticket raised in another project is not a path this schema can constrain.",
+            "type": "string",
+            "minLength": 1,
+            "pattern": "\\S"
+          }
+        }
+      }
+    },
+    "evidence": {
+      "$comment": "What establishes that the entry is true: reviews, verifications, work histories, captured runs, pull requests. minItems 1 for the same reason the mechanism's own evidence is required.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "pattern": "\\S"
+      }
+    }
+  },
+  "if": {
+    "type": "object",
+    "required": ["kernel-relevant"],
+    "properties": {
+      "kernel-relevant": { "const": true }
+    }
+  },
+  "then": {
+    "type": "object",
+    "required": ["structural-consequence"],
+    "properties": {
+      "structural-consequence": {
+        "type": "array",
+        "minItems": 1
+      }
+    }
+  }
+}