@tiphys/kernel 0.0.0 → 0.2.0

package/dist/src/gates/schemas/verifier-config.schema.json

@@ -0,0 +1,101 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tiphys.dev/schemas/verifier-config.schema.json",
+  "title": "Tiphys release-verification declaration",
+  "description": "The per-repository release-verification declaration (kernel plan M2, M2-P7 step 7; DR-0014). One document, committed at the repository root as release-verification.json, read from a COMMITTED ref (the merge base at the anti-widening call sites), never from the working tree. Silence is never permission: an absent verification field is error, not none, and mode none requires a non-empty reason. Mode-conditional requirements (none requires reason; adapter requires adapter, config and clock) need conditional composition, which is outside the closed keyword set of M2-D-04, so they are checked in code by src/gates/release.ts, which emits the same INVALID <pointer> <message> diagnostics. Expressed entirely in the closed keyword set.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "repository", "integrationRef", "verifications"],
+  "properties": {
+    "version": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "repository": {
+      "description": "The project's own identifier for itself (owner/name, or any project-declared identifier). Copied verbatim into the verification subject.",
+      "type": "string"
+    },
+    "integrationRef": {
+      "description": "The branch merges land on, normally main. Copied verbatim into the verification subject.",
+      "type": "string"
+    },
+    "verifications": {
+      "description": "The two M2 registry entries, keyed by gate id. M2 deliberately does not generalize to N charter-declared verifications (kernel plan M2 section 2 item 12); the charter field that will supersede this document is M3's reserved space.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "deploy": {
+          "$ref": "#/$defs/verification"
+        },
+        "migrations": {
+          "$ref": "#/$defs/verification"
+        }
+      }
+    }
+  },
+  "$defs": {
+    "verification": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mode"],
+      "properties": {
+        "mode": {
+          "description": "none is a POSITIVE declaration that this project has no such release state to verify, and it costs a reason. adapter names an executable that performs one bounded observation per invocation.",
+          "type": "string",
+          "enum": ["none", "adapter"]
+        },
+        "reason": {
+          "description": "Required when mode is none (checked in code). Surfaced in the gate record and the evidence bundle: disabling verification costs visibility.",
+          "type": "string"
+        },
+        "adapter": {
+          "description": "argv of the adapter executable. Committed configuration under scope audit, never assembled at run time from an environment variable: an adapter path that can be redirected at run time is a way to make a verifier report anything (investigation section 5.2).",
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string"
+          }
+        },
+        "config": {
+          "description": "Adapter-specific configuration, passed through verbatim in the request. The kernel never interprets it; JSON-pointer extraction, satisfying values and platform vocabulary live here and only here.",
+          "type": "object"
+        },
+        "clock": {
+          "$ref": "#/$defs/clock"
+        },
+        "credentials": {
+          "description": "Environment variable NAMES, never values. A named variable that is not resolvable is error before any adapter spawn. Values never appear in configuration or in any evidence record (M2-P7 criterion 11).",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[A-Z][A-Z0-9_]*$"
+          }
+        }
+      }
+    },
+    "clock": {
+      "description": "The kernel's clock, from configuration the kernel validated. The adapter never sleeps, never loops, never schedules and never decides what a timeout means. There are NO defaults here: the kernel's maximum deadline and default poll interval are numbers M2-P7 step 12 forbids inventing, so every project states its own.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["intervalMs", "deadlineMs", "attemptTimeoutMs"],
+      "properties": {
+        "intervalMs": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "deadlineMs": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "attemptTimeoutMs": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "maxAttempts": {
+          "type": "integer",
+          "minimum": 1
+        }
+      }
+    }
+  }
+}

package/dist/src/gates/schemas/witness-spec.schema.json

@@ -0,0 +1,110 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "tiphys:witness-spec",
+  "title": "Witness specification (kernel plan M2, M2-P2 step 2)",
+  "description": "One JSON document per behavior at witness/<behavior-id>.json, durable and repository-level (M2R-002, M2-D-14). Kind-specific member fields and the refusal rules (a) to (g) are enforced in src/witness/spec.ts and src/witness/run.ts because conditional composition is outside the closed keyword set (M2-D-04); the code emits the same INVALID <json-pointer> <message> contract.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "behavior", "tests", "class", "dangerousStates", "deterministic"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]*$"
+    },
+    "behavior": {
+      "description": "Must resolve by name in test/behaviors.json of the repository under audit (refusal rule (b)).",
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$"
+    },
+    "tests": {
+      "description": "Test names, run with --test-name-pattern BEFORE the positional test path (CLAUDE.md warning 7).",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "pattern": "\\S"
+      }
+    },
+    "class": {
+      "type": "string",
+      "enum": ["additive", "destructive", "classification"]
+    },
+    "dangerousStates": {
+      "description": "An ARRAY of one or more members; every member is applied, run and recorded separately, and the witness is green only when every member was red (rule (g) has something to require rather than something to bolt on).",
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/dangerousStateMember" }
+    },
+    "deterministic": {
+      "type": "boolean"
+    },
+    "repeats": {
+      "description": "Red repetitions per member. Default 5 when absent.",
+      "type": "integer",
+      "minimum": 1
+    },
+    "consumesExternalOutput": {
+      "description": "Required, not optional, when the phase diff touches a module that spawns a subprocess or parses another program's output (rule (f), derived; V-2, warning 10).",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["program", "captures", "provenance"],
+      "properties": {
+        "program": {
+          "type": "string",
+          "pattern": "\\S"
+        },
+        "captures": {
+          "description": "Repository-relative paths to REAL captured output files. Each must exist, be non-empty, and have its basename referenced from the named tests' sources (rule (c)).",
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "pattern": "\\S"
+          }
+        },
+        "provenance": {
+          "description": "Where and how the capture was taken (artifact path, date, command).",
+          "type": "string",
+          "pattern": "\\S"
+        }
+      }
+    }
+  },
+  "$defs": {
+    "dangerousStateMember": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind"],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "enum": ["baseline-ref", "patch", "mutation"]
+        },
+        "ref": {
+          "description": "baseline-ref only: the ref resolved against the FETCHED remote, never a stale local ref.",
+          "type": "string",
+          "pattern": "\\S"
+        },
+        "patch": {
+          "description": "patch only: repository-relative path of a patch file applied with git apply.",
+          "type": "string",
+          "pattern": "\\S"
+        },
+        "file": {
+          "description": "mutation only: repository-relative path of the file the substitution edits.",
+          "type": "string",
+          "pattern": "\\S"
+        },
+        "find": {
+          "description": "mutation only: literal text that must occur in the file; every occurrence is replaced.",
+          "type": "string",
+          "pattern": "[\\s\\S]"
+        },
+        "replace": {
+          "description": "mutation only: the replacement text.",
+          "type": "string"
+        }
+      }
+    }
+  }
+}

package/dist/src/gates/scope.d.ts

@@ -0,0 +1,131 @@
+interface PhaseDeclaration {
+    id: string;
+    branch: string;
+    filesToTouch: string[];
+    declaredExtras: string[];
+    citations: string[];
+}
+type MergeBaseResult = {
+    ok: true;
+    sha: string;
+} | {
+    ok: false;
+    reason: string;
+};
+declare function resolveMergeBase(cwd: string, base: string, head: string): MergeBaseResult;
+type RefResolution = {
+    ok: true;
+    sha: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Resolve any ref-ish string (a sha, a branch, `HEAD`, `HEAD~1`, ...) to the
+ * commit sha it names, or a reason it could not be resolved as a commit.
+ * Fix round 1 (CR-1030/CR-1045, W3): used to compare the CALLER-SUPPLIED
+ * `--head` against the commit this process actually has checked out, so a
+ * `--head` set short of the real tip is caught rather than silently
+ * narrowing the diff.
+ */
+declare function resolveRef(cwd: string, ref: string): RefResolution;
+type TrunkResolution = {
+    ok: true;
+    ref: string;
+    sha: string;
+} | {
+    ok: false;
+    reason: string;
+};
+declare function resolveTrunk(cwd: string): TrunkResolution;
+type AncestorCheck = {
+    ok: true;
+    isAncestor: boolean;
+} | {
+    ok: false;
+    reason: string;
+};
+/** `git merge-base --is-ancestor`: exit 0 is yes, exit 1 is no, anything else is error. */
+declare function isAncestorOf(cwd: string, ancestor: string, descendant: string): AncestorCheck;
+interface TouchedPath {
+    path: string;
+    status: string;
+}
+type DiffResult = {
+    ok: true;
+    paths: TouchedPath[];
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * `git diff --name-status <mergeBase> <head>`. Never `<base> <head>` and
+ * never against `main`'s tip: see the module comment on the anti-widening
+ * property. A rename or copy line (`R###` / `C###`) carries the old path
+ * and the new path tab-separated on one line; every other status carries
+ * exactly one path. Pinned against the captured shape in this phase's work
+ * history, not against a hand-written example (MECHANISMS.md, "Deciding
+ * what another program will do by pattern-matching the text of a file it
+ * consumes").
+ */
+declare function computeTouchedPaths(cwd: string, mergeBase: string, head: string): DiffResult;
+/** Best-effort branch name for a red detail line; never load-bearing for logic. */
+declare function currentBranch(cwd: string): string;
+type DeclarationLoad = {
+    ok: true;
+    declaration: PhaseDeclaration;
+    sha256: string;
+    path: string;
+} | {
+    ok: false;
+    kind: "missing";
+    path: string;
+} | {
+    ok: false;
+    kind: "error";
+    reason: string;
+};
+/**
+ * Read `<declarationsDir>/<phase>.json` out of the MERGE BASE commit, never
+ * out of the working tree and never out of `--head`. This is the one
+ * function the anti-widening property depends on.
+ */
+declare function loadDeclarationAtMergeBase(cwd: string, mergeBase: string, declarationsDir: string, phase: string): DeclarationLoad;
+/**
+ * The same object-database read at ANY commit (M3-P11 change B). The
+ * merge-base wrapper above keeps its name and its exported identity because
+ * the anti-widening property is a statement about THAT call, and a reader
+ * following the property should land on a function whose name says which
+ * side it reads.
+ */
+declare function loadDeclarationAtCommit(cwd: string, commit: string, declarationsDir: string, phase: string): DeclarationLoad;
+/** A declared entry is a literal path, or (trailing slash) a directory prefix. */
+declare function isAllowed(path: string, allowed: readonly string[]): boolean;
+declare function isPhaseOwnEvidence(path: string, phase: string): boolean;
+interface DeclarationDelta {
+    /** Entries present at the head and absent from the merge base. */
+    added: string[];
+    /** Entries present at the merge base and absent from the head. */
+    removed: string[];
+}
+/**
+ * Compare the merge-base declaration with the head's, field by field.
+ *
+ * THE ASYMMETRY IS THE POINT (DR-0031,
+ * delivery/plan/m3-p11-phase-spec.md:156). Reading the declaration from the
+ * head alone would let a phase grant itself scope, which removes the only
+ * check on scope there is; reading it from the merge base alone means a
+ * declaration amendment can never ride with the phase that needs it, and
+ * three of one day's ten pull requests existed for nothing else. So an
+ * ADDITION is allowed and reported as a loud NAMED diff for a reviewer to
+ * sign off, and a REMOVAL stays hard.
+ *
+ * `id` and `branch` are compared as scalars and any difference is a
+ * REMOVAL, never an addition: they are the two fields the anti-widening
+ * cross-checks are anchored to, and a phase that renames its own anchor has
+ * changed which declaration governs it.
+ */
+declare function compareDeclarations(base: PhaseDeclaration, head: PhaseDeclaration): DeclarationDelta;
+export declare function main(argv: string[]): number;
+export { compareDeclarations, computeTouchedPaths, currentBranch, isAllowed, isAncestorOf, isPhaseOwnEvidence, loadDeclarationAtCommit, loadDeclarationAtMergeBase, resolveMergeBase, resolveRef, resolveTrunk, };
+export type { DeclarationDelta, PhaseDeclaration, TouchedPath };