@tiphys/kernel 0.1.0 → 0.2.0

package/gate-registry.yaml

@@ -181,6 +181,7 @@ gates:
       paths:
         - src/
         - bin/
+        - plugin/
 
   # NEW IN M3-P2, entry one of three.
   - id: agent-rules-drift
@@ -281,12 +282,31 @@ gates:
       question is whether any verdict DOCUMENT exists under `delivery/review/`
       and not whether that directory does; this repository has the directory and
       has never had a verdict document in it.
+      THE COMMIT UNDER AUDIT IS A PARAMETER, AND ITS ABSENCE WAS THE DR-0047
+      SWEEP'S ONE HIGH FINDING (CR-VS-001). Without it the check grouped by the
+      head THE VERDICT DOCUMENTS THEMSELVES DECLARE, and nothing compared that
+      to the commit the gate was running against or established that it named a
+      commit at all. Reproduced: two decorrelated APPROVE verdicts naming
+      `deadbeefdeadbeefdeadbeefdeadbeefdeadbeef`, a sha `git cat-file -t`
+      reports as not an object, gave `check-dual-review: green`, 2 units, exit
+      0, in a repository whose HEAD was a real commit and carried a further
+      commit of work no verdict mentioned. So ONE committed approving pair
+      turned this gate green for that phase at every later head, indefinitely.
+      The runner already had the mechanism: `scope` has declared
+      `parameters: [base, head]` since M2 and the runner appends the flags to
+      the gate command. This entry simply never declared it. With `--head` the
+      audited commit comes from the RUN and the declared head comes from the
+      EVIDENCE, and the second is measured against the first instead of
+      replacing it. With no `--head` the script falls back to the commit the
+      context's own HEAD resolves to, which is what keeps the direct workflow
+      step in `.github/workflows/gates.yml` correct.
     command: [node, scripts/check-dual-review.mjs, .]
     unitLabel: review verdicts examined for decorrelation
     applicability: conditional
     verified-by: script
     modes: [full, direct-pr]
     events: [pull_request]
+    parameters: [head]
     precondition:
       id: dual-review-verdicts-present
       kind: command-exit-zero
@@ -331,6 +351,122 @@ gates:
     modes: [full, direct-pr, local-only]
     events: [pull_request, push]
 
+  # NEW IN M4-P14, entry one of two (R-041, DR-0028, DR-0029, M4-P13).
+  - id: typecheck
+    $comment: >-
+      R-041, retargeted by M4-P13 under DR-0028. The kernel ships the gate
+      CLASS and no command; the project ships the command. This repository is
+      the project, so this is the kernel dogfooding the extension point rather
+      than being exempt from it (DR-0029: "the kernel becomes just another
+      project under the scheme, with its own registry"). The subject is the one
+      M4 has, package.json's build script, which CLAUDE.md already calls the
+      type gate. WHY IT IS NOT THE SAME THING AS THE `build` PREFLIGHT STEP:
+      preflight is an ordered local command with no record, no units and no
+      vacuity protection, so nothing downstream can tell a build that checked
+      the whole project from one that checked nothing. This entry produces a
+      GateResult whose `units` is the count of distinct paths `tsc --listFiles`
+      PRINTED, so a compiler that read no file is error rather than green.
+      WHY `--force` IS IN THE COMMAND: without it `tsc -b` is incremental and
+      the printed file list depends on the state of `dist/`, which would make
+      the unit count a property of the runner's working directory instead of
+      the code. `events: [pull_request]` alone, and it is derived rather than
+      assigned: `scripts/m2-exit-test.sh` declares the push arm's gate set once
+      in MAIN_ONLY_GATES and this id is not in it, so the push arm cannot run
+      it and test/gate-registry.test.ts asserts `events` against that harness.
+    command: [node, src/gates/gate-classes.ts, typecheck, --project, tsconfig.src.json, --project, tsconfig.test.json, --project, plugin/tsconfig.json]
+    unitLabel: source files type-checked
+    applicability: required
+    verified-by: script
+    modes: [full, direct-pr, local-only]
+    events: [pull_request]
+
+  # NEW IN M4-P14, entry two of two (DR-0029 part 2a, M4-P13).
+  - id: gate-classes
+    $comment: >-
+      DR-0029 part 2a made executable. A PHASE declares at least one gate in
+      each required class (`correctness`, `scope`, `review`), or declares an
+      escape that is DATA: `not-applicable` WITH a recorded reason, or
+      `not-yet-establishable` NAMING the phase that will establish it. The
+      requirement attaches to the phase and not to the project, because "this
+      project must have a correctness gate" is unsatisfiable on day zero while
+      "this phase either asserts correctness or declares when it will" is
+      satisfiable from the first commit. The property protected, in DR-0029's
+      words: you can start from nothing; you can never SILENTLY have nothing.
+      THE ESCAPES ARE PRINTED ON THE GREEN ARM, not merely permitted, which is
+      the same disclosure trade src/gates/scope.ts makes for a declaration
+      addition under M3-P11 change B: a reviewer who does not read the printed
+      line gets no protection from it. The PRECONDITION is branch-matches, the
+      same one `scope` carries and for the same reason: a phase declaration is
+      selected by phase id, and a non-phase branch has none, so the gate
+      reports not-applicable with an evaluated precondition rather than a
+      vacuous green (SC-011, M2-C-3). `events: [pull_request]` alone because
+      the push arm of scripts/m2-exit-test.sh passes no `--phase` at all, so
+      there is no declaration for it to select.
+    command: [node, src/gates/gate-classes.ts, gate-classes, --declarations, delivery/plan/phase-declarations, --registry, gate-registry.yaml]
+    unitLabel: declared gate classes checked
+    applicability: required
+    verified-by: script
+    modes: [full, direct-pr]
+    events: [pull_request]
+    parameters: [phase]
+    precondition:
+      id: gate-classes-branch-is-a-phase-branch
+      kind: branch-matches
+      pattern: claude/m[0-9]+-p[0-9]+-.*
+
+  # NEW IN M4-P12 (DR-0012, DR-0036, T-009, R-064, R-065a).
+  - id: merge-preconditions
+    $comment: >-
+      M4-P12. The artifact DR-0012's delegated grant has never had: one record
+      per condition, each carrying the HEAD SHA it was evaluated against, so
+      that "the six conditions held" stops being a sentence somebody wrote and
+      becomes a thing a reader can check. It is a PRECONDITION READER and not a
+      merge command: M4-D-09 puts the merge capability in the plugin at cutover
+      and DR-0036 keeps merge authority with the current process for the whole
+      of M4, so the orchestrator reads this record before merging, by hand.
+      CONDITIONS 1 AND 2 ARE COMPOSED, NOT REIMPLEMENTED. M4-P10 shipped
+      `dual-review-decorrelation` and `verdict-pair-approves` as derived checks
+      in src/checks.ts; this gate is a second caller of the same exported
+      primitives and runs those checks BY ID, so deregistering either one is
+      visible here as an `error` rather than absorbed as a pass.
+      `applicability: conditional`, AND THE PRECONDITION IS ANSWERED IN TWO
+      PLACES BECAUSE IT IS TWO QUESTIONS. The declared `command-exit-zero` block
+      is the SAME probe check-dual-review declares, and it answers the question
+      a registry precondition can answer: does this project have any committed
+      review verdict at all. The narrower question, whether a verdict names THIS
+      head, needs the run's `--head`, and a precondition command is spawned
+      without it (src/gates/run.ts:1524 appends the parameter flags to the GATE
+      command, not to the precondition's). So the gate answers that half itself
+      and emits its own PreconditionRecord with `met: false`, which is SC-011's
+      requirement that not-applicable ASSERT an evaluated precondition rather
+      than stand for silence. Both arms are not-applicable and each names which
+      question was unmet, so a reader is never told only that the gate did not
+      run.
+      `events: [pull_request]` ALONE, and it is derived rather than assigned:
+      scripts/m2-exit-test.sh declares the push arm's gate set once in
+      MAIN_ONLY_GATES and this id is not in it, so the push arm cannot run it,
+      and test/gate-registry.test.ts asserts `events` against that harness
+      rather than against a wish. It is ALSO in gates.manifest.json, because CI
+      invokes the runner with `--manifest`: a gate declared only here is
+      declared and never executed, which is a gate that cannot go red.
+      THE API IS PROBED, NEVER ASSUMED. CLAUDE.md standing warning 6 records
+      REST reachability here measured both ways on different days with the
+      cause unestablished, so the gate probes first and reports `error` with
+      units 0 when it cannot reach the API. Never `not-applicable`, never green:
+      M2-C-3, and the hazard this whole entry exists against is a merge
+      precondition check that is green because it could not look.
+    command: [node, src/gates/merge-preconditions.ts]
+    unitLabel: merge preconditions evaluated
+    applicability: conditional
+    verified-by: script
+    modes: [full, direct-pr]
+    events: [pull_request]
+    parameters: [head, phase]
+    precondition:
+      id: merge-preconditions-verdicts-present
+      kind: command-exit-zero
+      command: [node, scripts/check-dual-review.mjs, --precondition, .]
+
   # NEW IN M3-P2, entry two of three (R-043, D-11).
   - id: unit-tests-for-changed-service-methods
     $comment: >-

package/gates.manifest.json

@@ -171,7 +171,8 @@
         "kind": "diff-touches",
         "paths": [
           "src/",
-          "bin/"
+          "bin/",
+          "plugin/"
         ]
       }
     },
@@ -184,6 +185,67 @@
       ],
       "unitLabel": "generated brief gate rows compared",
       "applicability": "required"
+    },
+    {
+      "id": "typecheck",
+      "command": [
+        "node",
+        "src/gates/gate-classes.ts",
+        "typecheck",
+        "--project",
+        "tsconfig.src.json",
+        "--project",
+        "tsconfig.test.json",
+        "--project",
+        "plugin/tsconfig.json"
+      ],
+      "unitLabel": "source files type-checked",
+      "applicability": "required"
+    },
+    {
+      "id": "gate-classes",
+      "command": [
+        "node",
+        "src/gates/gate-classes.ts",
+        "gate-classes",
+        "--declarations",
+        "delivery/plan/phase-declarations",
+        "--registry",
+        "gate-registry.yaml"
+      ],
+      "unitLabel": "declared gate classes checked",
+      "applicability": "required",
+      "parameters": [
+        "phase"
+      ],
+      "precondition": {
+        "id": "gate-classes-branch-is-a-phase-branch",
+        "kind": "branch-matches",
+        "pattern": "claude/m[0-9]+-p[0-9]+-.*"
+      }
+    },
+    {
+      "id": "merge-preconditions",
+      "command": [
+        "node",
+        "src/gates/merge-preconditions.ts"
+      ],
+      "unitLabel": "merge preconditions evaluated",
+      "applicability": "conditional",
+      "parameters": [
+        "head",
+        "phase"
+      ],
+      "precondition": {
+        "id": "merge-preconditions-verdicts-present",
+        "kind": "command-exit-zero",
+        "command": [
+          "node",
+          "scripts/check-dual-review.mjs",
+          "--precondition",
+          "."
+        ]
+      }
     }
   ],
   "destructiveCommands": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiphys/kernel",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Tiphys kernel: the fleet orchestration toolbelt, delivered as an npm package.",
   "type": "module",
   "license": "Apache-2.0",
@@ -14,6 +14,15 @@
   "bin": {
     "tiphys": "dist/bin/tiphys.js"
   },
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "files": [
     "dist",
     "!dist/node_modules",
@@ -29,10 +38,16 @@
     "templates",
     "tuition"
   ],
+  "workspaces": [
+    "plugin"
+  ],
+  "overrides": {
+    "@tiphys/kernel": "file:."
+  },
   "scripts": {
-    "build": "tsc -b tsconfig.src.json tsconfig.test.json && npm run build:schemas && npm run build:runtime-deps",
+    "build": "tsc -b tsconfig.src.json tsconfig.test.json plugin/tsconfig.json && npm run build:schemas && npm run build:runtime-deps",
     "build:schemas": "node --input-type=module -e \"import { cpSync } from 'node:fs'; cpSync('src/gates/schemas', 'dist/src/gates/schemas', { recursive: true });\"",
-    "build:runtime-deps": "node --input-type=module -e \"import { cpSync, readFileSync } from 'node:fs'; const lock = JSON.parse(readFileSync('node_modules/.package-lock.json', 'utf8')); for (const [path, entry] of Object.entries(lock.packages ?? {})) { if (!path.startsWith('node_modules/') || entry?.dev === true) continue; cpSync(path, 'dist/' + path, { recursive: true }); }\"",
+    "build:runtime-deps": "node --input-type=module -e \"import { cpSync, readFileSync } from 'node:fs'; const lock = JSON.parse(readFileSync('node_modules/.package-lock.json', 'utf8')); for (const [path, entry] of Object.entries(lock.packages ?? {})) { if (!path.startsWith('node_modules/') || entry?.dev === true || entry?.link === true) continue; cpSync(path, 'dist/' + path, { recursive: true }); }\"",
     "test": "node --test \"test/**/*.test.ts\"",
     "gate:suite": "node src/gates/suite.ts --pin-root src --pin-root bin --pin-root test",
     "prepack": "npm run build",

package/roles/implementer.md

@@ -394,6 +394,9 @@ Then the gates `full` mode selects, run by `tiphys gates run --registry gate-reg
 | `check-agents-references` | script | required | references resolved |
 | `check-dual-review` | script | conditional | review verdicts examined for decorrelation |
 | `license` | script | required | production packages licensed |
+| `typecheck` | script | required | source files type-checked |
+| `gate-classes` | script | required | declared gate classes checked |
+| `merge-preconditions` | script | conditional | merge preconditions evaluated |
 | `unit-tests-for-changed-service-methods` | clean-room-checklist (probe `unit-tests-for-changed-service-methods`) | conditional | changed service methods checked |
 | `fixtures-for-changed-component-states` | clean-room-checklist (probe `fixtures-for-changed-component-states`) | conditional | changed component states checked |
 

package/schemas/README.md

@@ -46,6 +46,7 @@ test (`test/schemas.test.ts`).
 | `const` | |
 | `items` | |
 | `minItems` | |
+| `uniqueItems` | boolean only; used by five shipped schemas here and MISSING FROM THIS TABLE from the day M3-P1 wrote both halves until the DR-0047 sweep, because nothing asserted the two agreed |
 | `minLength` | |
 | `pattern` | |
 | `$ref` | local references only; a remote reference fails compilation |

package/schemas/assurance-modes.schema.json

@@ -248,7 +248,7 @@
       ],
       "properties": {
         "max-fix-rounds-after-review": {
-          "description": "How many fix rounds may follow the first dual review before the bound fires. DR-0012: \"more than two fix rounds after its first dual review\", so two.",
+          "description": "How many fix rounds may follow the first dual review before the bound fires. DR-0012 set two; DR-0035 replaced the single bound with a table running from one round (a zero or small subject) to three (a large subject at high impact), so what a mode records here is that table's CEILING rather than one phase's budget.",
           "type": "integer"
         },
         "recurrence-of-high-in-one-component": {

package/schemas/charter.schema.json

@@ -151,6 +151,25 @@
         }
       ]
     },
+    "review-families": {
+      "$comment": "DR-0038's DECLARATION, and it is a declaration rather than the exception itself (M4-D-28, kernel plan M4 section 4.2.6). DR-0012 condition 1 requires two clean-room reviews produced on different model FAMILIES. A project with one family available can satisfy that only by recording something false, and the shipped check makes it worse: it compares canonicalised STRINGS, so two models of one family compare as distinct and the pair reports decorrelated. This field is where a project states WHICH families its environment actually has. The schema does not encode the exception: single-family is `available.length === 1`, and what that then means is `dual-review-decorrelation`'s business. OPTIONAL, AND ITS ABSENCE IS NOT PERMISSION: an absent `review-families` leaves the cross-family requirement applying unchanged, so a same-family pair stays red (src/gates/release.ts:1037 states the same rule for the sibling case). WHY THE CHARTER AND NOT assurance-modes.yaml: DR-0029's split asks whether a fact is process or predicate, and 'which model families exist in this environment' is a fact about the PROJECT's environment, so it belongs to the project's own declaration; the assurance-mode vocabularies are closed by DR-0020 and bound to a derived check.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["available", "reason"],
+      "properties": {
+        "available": {
+          "$comment": "The model families this environment can actually dispatch a clean-room review on. NOT an enum: no closed vocabulary of model families can be kept current, and a stale enum here would refuse a true declaration. The check canonicalises each entry the same way it canonicalises a verdict's `produced-by`, so the two are comparable.",
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "reason": {
+          "$comment": "Investigation defence 2, the same rule release-verification mode none is held to: narrowing an owner-reserved merge condition costs a stated reason. A declaration nobody has to justify is the shape DR-0038 exists to replace.",
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
     "retention": {
       "$comment": "Consumed by M3-P8 for R-098.",
       "type": "object",

package/schemas/cutover-state.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tiphys.dev/schemas/cutover-state.schema.json",
+  "title": "Cutover state",
+  "description": "The fleet's cutover.json: the five freeze switches and what each of them records. Kernel plan M4, M4-P25 acceptance criterion 4.",
+  "$comment": "THE WIRE NAMES ARE camelCase AND THAT IS ESTABLISHED, NOT CHOSEN HERE. The M4 plan section spells the fields flipped-at, flipped-by, reason and restore-to; the document M4-P26 already writes and reads spells them flippedAt, flippedBy, reason and restoreTo (src/cutover.ts:98 declares the interface and src/cutover.ts:152 validates it). A schema that pinned the kebab spelling would refuse every document the shipped writer produces, so this pins what the document uses and the plan's spelling is read as prose naming the four fields rather than as their serialised keys.",
+  "type": "object",
+  "required": ["switches"],
+  "properties": {
+    "switches": {
+      "type": "object",
+      "description": "One record per switch. The five names are a CLOSED list: a sixth name is a plan revision, not a document edit, because every rollback trigger enumerates them.",
+      "required": [
+        "planning-and-scope",
+        "review-and-arbitration",
+        "credentials-and-refs",
+        "salvage-and-recovery",
+        "closeout"
+      ],
+      "properties": {
+        "planning-and-scope": { "$ref": "#/$defs/switchRecord" },
+        "review-and-arbitration": { "$ref": "#/$defs/switchRecord" },
+        "credentials-and-refs": { "$ref": "#/$defs/switchRecord" },
+        "salvage-and-recovery": { "$ref": "#/$defs/switchRecord" },
+        "closeout": { "$ref": "#/$defs/switchRecord" }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": true,
+  "$defs": {
+    "switchRecord": {
+      "$comment": "additionalProperties is TRUE here and at the document level, against the schemas/README.md preference for false at every object level, and the deviation is deliberate rather than an omission. M4-P26 shipped a rollback that CARRIES document keys it does not own, at both levels, and registered that behaviour as a guarded test (test/cutover.test.ts:974). Closing either level would make the shipped writer refuse its own preserved keys, so this document is open by decision and the closed half is the switch NAME list one level up, which is the vocabulary that actually has to be closed.",
+      "type": "object",
+      "required": ["state", "flippedAt", "flippedBy", "reason", "restoreTo"],
+      "properties": {
+        "state": {
+          "description": "Which process holds the authority this switch governs.",
+          "enum": ["current", "kernel"]
+        },
+        "flippedAt": {
+          "description": "When the switch was last written, as an ISO 8601 instant.",
+          "type": "string",
+          "minLength": 1
+        },
+        "flippedBy": {
+          "description": "Who or what performed the write.",
+          "type": "string",
+          "minLength": 1
+        },
+        "reason": {
+          "description": "Why the switch was written.",
+          "type": "string",
+          "minLength": 1
+        },
+        "restoreTo": {
+          "description": "The value the switch held BEFORE the write. It is what makes rollback a matter of reading a recorded value rather than reconstructing an intent, and a record without it cannot be rolled back at all.",
+          "enum": ["current", "kernel"]
+        }
+      },
+      "additionalProperties": true
+    }
+  }
+}

package/schemas/executor-record.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tiphys.dev/schemas/executor-record.schema.json",
+  "title": "Tiphys executor launch record",
+  "description": "tasks/<id>/executor.json, the record an ExecutorAdapter writes at launch (DR-0006 for the format, PR-207 for the shape, M4-P3 for the contract). Until M4-P3 this document was written by the kernel and validated by nothing, which is the state delivery/plan/m4-intake.md:272 names. It is written BEFORE the payload starts, which is what makes a failure to write it provably a launch failure and therefore safe to roll back.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["adapter", "launchedAt"],
+  "properties": {
+    "adapter": {
+      "$comment": "The adapter that wrote this record, by its own `name`. REQUIRED: a launch record that does not say what launched it cannot be attributed, and attribution is the whole reason an operator opens this file.",
+      "type": "string",
+      "minLength": 1
+    },
+    "launchedAt": {
+      "$comment": "RFC 3339 UTC, the same spelling every other Tiphys record uses, so two records from two machines sort. Written from `new Date().toISOString()`.",
+      "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$"
+    },
+    "deadline": {
+      "$comment": "PR-207. The absolute instant by which the task must have completed, present ONLY when --deadline was passed. Recorded as an instant rather than as raw seconds so the watcher compares it against the clock directly instead of re-deriving it from launchedAt.",
+      "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$"
+    },
+    "requestedTier": {
+      "$comment": "M4-P3 criterion 6. THE DECLARED TIER THE REQUEST CARRIED, VERBATIM, AND NEVER A MODEL NAME. Whatever role-model-config.yaml declares crosses the seam unaltered; the tier-to-model mapping lives in the plugin and never in src/, which is what keeps a harness that is not the one named possible at all (delivery/plan/m4-intake.md:377). The schema does not enum this value, because the vocabulary belongs to the plugin and an enum here would be that mapping's first half.",
+      "type": "string",
+      "minLength": 1
+    },
+    "requestedRole": {
+      "$comment": "M4-P3 criterion 6. The role the request carried, verbatim. Not enumerated here for the same reason requestedTier is not: roles/ is a shipped directory and the role-to-brief mapping is the plugin's.",
+      "type": "string",
+      "minLength": 1
+    }
+  }
+}