@tiphys/kernel 0.0.0 → 0.1.0

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

@@ -0,0 +1,566 @@
+import type { GateEntry, GateManifest, RunParameter } from "./manifest.ts";
+import type { GateStatus } from "./result.ts";
+/**
+ * THE GATE RUNNER (kernel plan M2, M2-P1 step 7 and step 8).
+ *
+ * Runs the manifest's gates sequentially in the foreground as subprocesses,
+ * captures each one's stdout and stderr into the evidence directory,
+ * ingests each one's result record, and writes `summary.json`.
+ *
+ * C-3, STRUCTURALLY: `spawnSync` only, no `detached`, no `unref`, no flag
+ * anywhere that lets a gate outlive this process. C-2, STRUCTURALLY: nothing
+ * here reads a pid, probes a process, sends a signal or touches /proc; a
+ * gate's outcome is its RECORD plus its exit code, never its liveness.
+ *
+ * THE GATE SUBPROCESS CONTRACT, stated once because eight phases build
+ * against it:
+ *
+ *   invocation  <command...> --result <abs path> --evidence <abs dir>
+ *               plus one --<name> <value> for each parameter the gate
+ *               DECLARES in the manifest (base, head, phase)
+ *   cwd         the runner's working directory
+ *   output      exactly one GateResult JSON document at --result
+ *   exit codes  0 green, 1 red, 20 not-applicable, 21 error, 64 usage
+ *
+ * WHY PARAMETERS ARE DECLARED AND NOT INFERRED. Step 7 requires a gate
+ * "whose command requires --phase" to report `error` when `--phase` is
+ * absent. The runner can only know that from a declaration or by
+ * pattern-matching the gate's command line, and MECHANISMS.md's row
+ * "Deciding what another program will do by pattern-matching the text of a
+ * file it consumes" records four fix rounds paid for the second option. So
+ * the manifest declares it, the schema validates it, and the runner reads
+ * it. This adds one field to the plan's manifest field list and is declared
+ * as a deviation in the work history.
+ *
+ * INGEST IS ADVERSARIAL TOWARDS ITS OWN GATES. A gate is another program:
+ * it can exit 0 having written nothing, exit nonzero because Node threw,
+ * write a record for a different gate, write a record whose status
+ * contradicts its exit code, or write a green record having examined
+ * nothing. Every one of those is `error`, because `error` is what "I cannot
+ * tell you whether the property holds" is called (M2-C-3), and because
+ * every one of them otherwise reads as a pass.
+ *
+ * WHAT "APPLICABLE" MEANS, fixed in round 1 (CR-800). It used to mean "the
+ * runner spawned this gate", which is not the same thing and differed from it
+ * on the one path that matters: a gate that decides its OWN applicability and
+ * exits 20 with a `not-applicable` record was spawned, so it counted as
+ * applicable, so the aggregate anti-vacuity rule never fired, so a bundle in
+ * which zero gates were green exited 0 with the reason "every applicable gate
+ * is green". The two routes to `not-applicable`, runner-evaluated and
+ * gate-declared, were guarded differently, and the gate subprocess contract
+ * documented above is what tells every gate author the second route exists.
+ *
+ * So there are now two counts and they answer two different questions:
+ *
+ *   applicable  the gate was reached AND did not report `not-applicable`,
+ *               whichever side decided that. It is the denominator of "how
+ *               much of this manifest was in play".
+ *   verdict     the gate reached a GREEN OR RED verdict. It is the only
+ *               count the anti-vacuity rule consults, because it is the only
+ *               one that means work was actually done.
+ *
+ * The exit-0 success path is then structurally unable to describe an empty
+ * green bucket: it is guarded by `verdict > 0` and asserted again before the
+ * summary is written, so an internal inconsistency reports `error` rather
+ * than a green nobody measured (SC-011, M2-C-2, M2R-012).
+ *
+ * ONE RUN OWNS ITS EVIDENCE DIRECTORY (CR-803). Two runners pointed at one
+ * `--evidence` directory used to interleave on fixed per-gate paths: the
+ * later runner ingested the earlier one's records as its own, and a genuine
+ * red was converted to `error` while the surviving bundle was the other run's
+ * green. That is the declared hazard "a runner that writes a record for a
+ * gate it did not execute", and seven phases run this concurrently.
+ *
+ * The evidence directory is therefore CLAIMED with an O_EXCL create, the
+ * pattern src/lock.ts already carries and which MECHANISMS.md requires a
+ * third user to read first. Per that row's rule, a claim that cannot be taken
+ * fails LOUDLY and NAMES THE STUCK FILE; there is no steal, no age heuristic
+ * and no bounded wait, because an evidence directory is not a contended
+ * resource by design and a silent wait would be indistinguishable from an
+ * absence of contention. Every run also stamps a `runId` into its summary, so
+ * a bundle is attributable, and the summary is replaced atomically through a
+ * stage name carrying that runId, which no other run can collide with
+ * (MECHANISMS.md, "Atomic file replacement").
+ *
+ * THE RUNNER OBEYS ITS OWN CRASH DISCIPLINE (CR-801). It used to enforce on
+ * its gates the rule that Node's uncaught-exception exit code 1 collides with
+ * this phase's own RED code, while itself exiting 1 on an escaping throw,
+ * with no summary and, mid-bundle, a gate-authored green record left on disk.
+ * `runGates` now folds any escaping throw into `EXIT_GATE_ERROR` AND writes a
+ * summary marked aborted, so a consumer can always tell "a gate reported red"
+ * from "the runner died before it could report".
+ *
+ * M2-C-6 IS WIRED AT FOUR PLACES, all of them paths from outside: the
+ * manifest path (in `loadManifest`), the evidence directory, every
+ * `file-exists` and `file-absent` precondition target, and every gate's
+ * record file, which is probed BEFORE the gate is spawned as well as after
+ * it returns. Probing before the spawn is the load-bearing half: a gate
+ * handed a named pipe to write its record into would block in the kernel
+ * forever and the runner would wait on it forever, so the run has to be
+ * refused before the child exists.
+ */
+export interface RunOptions {
+    manifestPath: string;
+    evidenceDir: string;
+    base?: string;
+    head?: string;
+    phase?: string;
+    only?: string[];
+    /**
+     * M3-P2 step 4. When true, `manifestPath` names a canonical GATE REGISTRY
+     * (`gate-registry.yaml`, `schemas/gate-registry.schema.json`) rather than an
+     * M2-P1 gate manifest. The registry is a SUPERSET of the manifest, so it is
+     * projected down to one and every line below this point is the M2 runner
+     * unchanged: the same `runOneGate`, the same `ingestGateRun`, the same
+     * `makeGateResult`. That is deliberate and it is what makes M2-C-2 and
+     * M2-C-3 survive the promotion instead of being re-implemented beside it.
+     */
+    registry?: boolean;
+    /**
+     * Registry mode only: the assurance mode selecting entries, matched against
+     * each entry's `modes[]`. Defaults to `full`.
+     */
+    mode?: string;
+    /** Working directory for gate subprocesses and git. Defaults to cwd. */
+    cwd?: string;
+}
+/**
+ * A registry entry that declares a gate the runner CANNOT execute, because
+ * D-11 settles that it is verified by a clean-room checklist probe rather
+ * than by a script (R-043, R-044). It is reported rather than dropped, so
+ * that "the report accounts for every gate in the registry" is a property a
+ * reader can check from the run's own output instead of taking on trust.
+ */
+export interface DeclaredChecklistGate {
+    id: string;
+    probe: string;
+    applicability: "required" | "conditional";
+}
+export interface GateSummaryRow {
+    id: string;
+    status: GateStatus;
+    units: number;
+    unitLabel: string;
+    vacuous: boolean;
+    applicable: boolean;
+    detail: string;
+    record?: string;
+    stdout?: string;
+    stderr?: string;
+}
+export interface RunSummary {
+    /** Identity of THIS run. A bundle nobody can attribute is not evidence. */
+    runId: string;
+    manifest: string;
+    /** M3-P2: true when `manifest` above named a gate registry, not a manifest. */
+    registry?: boolean;
+    /** M3-P2: the assurance mode that selected these gates. Registry runs only. */
+    mode?: string;
+    /**
+     * M3-P2: registry entries selected by `mode` that the runner did not
+     * execute because they are `verified-by: clean-room-checklist`. Empty for a
+     * manifest run. `declared` in `counts` plus this array's length is the
+     * number of registry entries the mode selected, which is how a reader
+     * checks that the report accounts for every gate.
+     */
+    declaredByChecklist?: DeclaredChecklistGate[];
+    manifestSha256: string;
+    startedAt: string;
+    endedAt: string;
+    parameters: {
+        base?: string;
+        head?: string;
+        phase?: string;
+    };
+    only: string[];
+    manifestGates: number;
+    gates: GateSummaryRow[];
+    counts: {
+        declared: number;
+        applicable: number;
+        /** green + red: gates that reached a verdict. The anti-vacuity count. */
+        verdict: number;
+        green: number;
+        red: number;
+        "not-applicable": number;
+        error: number;
+        vacuous: number;
+    };
+    /** Named here as well as in the rows, because the reason line is one line. */
+    requiredNotApplicable: string[];
+    /** True when a throw escaped the run and this summary is a partial record. */
+    aborted: boolean;
+    exitCode: number;
+    reason: string;
+}
+export interface RunOutcome {
+    /**
+     * THIS run's identity, on every outcome including a refusal (CR-861). The
+     * runId used to live only inside `summary.json`, so a caller had no way to
+     * tell whether the summary it was reading was its own: after a refusal the
+     * previous run's green summary sat there, `aborted: false`, exit 0, with
+     * nothing to mark it stale. Attribution needs the caller to know the id it
+     * should expect, and this is where it gets it.
+     */
+    runId: string;
+    exitCode: number;
+    summary?: RunSummary;
+    /** Set when the run could not start at all (no summary to write). */
+    reason?: string;
+}
+export declare const NO_APPLICABLE_GATE = "no applicable gate";
+/** The default assurance mode when `--registry` is given without `--mode`. */
+export declare const DEFAULT_MODE = "full";
+export type RegistryLoad = {
+    ok: true;
+    manifest: GateManifest;
+    sha256: string;
+    body: string;
+    declaredByChecklist: DeclaredChecklistGate[];
+} | {
+    ok: false;
+    reason: string;
+    diagnostics: string[];
+};
+/**
+ * LOAD A CANONICAL GATE REGISTRY AND PROJECT IT ONTO AN M2 GATE MANIFEST
+ * (kernel plan M3, M3-P2 steps 2 and 4; R-094).
+ *
+ * The registry is a SUPERSET of the M2-P1 manifest, so the promotion is a
+ * projection and not a rewrite, and this function is the whole of it. Four
+ * things happen here and each one is load-bearing:
+ *
+ *   1. The path is operator-supplied, so it is READ through the delivered
+ *      `readRegularFileIfPresent` (M2-C-6). A named pipe reports the observed
+ *      type and never blocks.
+ *   2. The document is DECODED (YAML or JSON, `decodeDocument`) and then
+ *      VALIDATED against `schemas/gate-registry.schema.json` through the
+ *      M3-P1 Ajv engine. Decoding and validation are separate stages and
+ *      produce distinguishable diagnostics (DR-0013 YAML clause 3). The
+ *      registry schema is NOT validated by `src/gates/validate.ts`: it uses
+ *      `if`/`then`, which is outside M2-D-04's closed keyword set, which is
+ *      exactly why it lives in the shipped `schemas/` directory.
+ *   3. Entries are selected by MODE and by `verified-by`. A
+ *      `clean-room-checklist` entry has no process to run (D-11: R-043 and
+ *      R-044 are not computable from a diff), so it is reported as declared
+ *      rather than silently dropped.
+ *   4. The projected manifest is validated AGAIN, against the M2 manifest
+ *      schema, by `validateManifestDocument`. That second validation is the
+ *      superset claim turned into a check: if a projection is not a valid M2
+ *      manifest then the registry is not a superset of the manifest, and the
+ *      run refuses rather than proceeding on a document the M2 contract does
+ *      not recognise.
+ *
+ * Everything after this function is the M2 runner untouched, so M2-C-2 (never
+ * green by omission) and M2-C-3 (fail closed) apply to registry runs by
+ * CONSTRUCTION rather than by being remembered. A `--registry` path that
+ * built `GateResult` literals of its own would be the realistic way those two
+ * constraints get dropped by a promotion, and there is no such path.
+ */
+export declare function loadRegistry(path: string, mode: string): RegistryLoad;
+/**
+ * Which run parameters a gate cannot be evaluated without.
+ *
+ * Derived from two places and nowhere else: the gate's own `parameters`
+ * declaration, and the precondition kind, whose needs are a property of the
+ * kind rather than of the gate. `branch-matches` requires `--phase`
+ * unconditionally rather than only when the pattern happens to interpolate
+ * it, which is stricter than necessary and deliberately so: M2-C-3 says a
+ * check that cannot reach a verdict fails closed, and the cost of the strict
+ * reading is one flag on an invocation that already carries three.
+ */
+export declare function requiredParameters(entry: GateEntry): RunParameter[];
+/**
+ * A CRASH IS NOT A SKIP (M3-P11, delivery/plan/m3-p11-phase-spec.md:15).
+ *
+ * THE DEFECT THIS EXISTS FOR, root-caused by the M3-P9 hazard reviewer. The
+ * `command-exit-zero` evaluator below treated a command as "could not run"
+ * only when `spawnSync` set `error`, which is the LAUNCHER failing to spawn.
+ * A launcher that spawns perfectly well and runs a script that does not
+ * exist gets exit 1, which the evaluator read as "the precondition is
+ * unmet", so the gate printed `not-applicable`. Measured on this machine,
+ * node v26.6.0, four commands, one `spawnSync` each:
+ *
+ *   node missing-script.mjs        status 1     error undefined
+ *   node -e "process.exit(1)"      status 1     error undefined
+ *   ./noexec.sh (mode 644)         status null  error EACCES
+ *   ./badinterp.sh (bad shebang)   status null  error ENOENT
+ *
+ * Rows one and two are the whole problem: identical to `spawnSync`, opposite
+ * in meaning. Row two is a REAL declaration in this repository
+ * (`credential-token`'s precondition, gates.manifest.json), so "exit 1 means
+ * unmet" cannot simply be withdrawn; and rows three and four already reached
+ * `error` before this phase, so they are regression guards rather than the
+ * new behaviour.
+ *
+ * THE DISTINGUISHING EVIDENCE IS THEREFORE NOT THE EXIT CODE (spec step 2).
+ * It is whether the paths the command names can be run at all, established
+ * BEFORE the spawn, so that "could not run" is a fact about the filesystem
+ * rather than an inference from a number that two different situations
+ * produce identically.
+ *
+ * WHICH ARGV ELEMENTS ARE PROBED, stated as a rule rather than left to
+ * judgment, because MECHANISMS.md's row about deciding what another program
+ * will do by pattern-matching its input is exactly the trap here. An element
+ * is a PATH OPERAND when ALL FOUR hold:
+ *
+ *   1. it is not `command[0]` (the launcher, handled separately);
+ *   2. `namesNoPath` does not rule it out (it is not an option, not the code
+ *      value of one, and not a URL). Fix round 2 hoisted this into its own
+ *      function so this rule and the wider one below cannot drift apart.
+ *   3. it contains `/` (a bare word is not treated as a path HERE, so `.` and
+ *      `--pin-root src` are left alone; the wider rule below adds the one
+ *      further test that makes `node check.mjs` visible);
+ *   4. it contains no whitespace, and the element before it does not begin
+ *      with `-` (so an option's VALUE is never probed by THIS rule, whatever
+ *      the option is).
+ *
+ * WHAT THIS RULE DOES NOT COVER, so the next reader does not have to
+ * rediscover it: an interpreter invoked as `node --flag script.mjs` puts the
+ * script after an option and rule 4 skips it; an operand named by an
+ * environment variable or produced by a shell is invisible here; and a
+ * script that EXISTS but whose own body throws still exits 1 and is still
+ * read as unmet, because nothing outside the script can distinguish that
+ * from a deliberate refusal. Those residues are recorded in
+ * delivery/work-history/m3-p11.md rather than implied.
+ *
+ * FAIL CLOSED, LOUDLY (M2-C-3). An operand this rule probes and does not
+ * find is `error` naming the element and its resolved absolute path, never a
+ * quiet `not-applicable`. That is the right direction HERE, and only because
+ * rules 2 to 4 keep the set small: this probe runs before the spawn, so a
+ * false positive refuses a command that would have exited 0, and no exit code
+ * exists yet to tell you it would have. Round 2 hit exactly that with a URL
+ * operand.
+ *
+ * ------------------------------------------------------------------------
+ * FIX ROUND 1 (M3-P11), AND THE MECHANISM IT CLOSES.
+ *
+ * As first written, the paragraphs above established SOME of the
+ * preconditions of running and then let the exit code decide. That is one
+ * mechanism with two independent halves, and a clean-room hazard reviewer
+ * reproduced BOTH of them end to end through the packed CLI as a wrong
+ * verdict (`not-applicable` for a command that crashed), which is the exact
+ * defect this phase exists to close, surviving inside its own fix:
+ *
+ *   HALF A, the CONDITIONS tested per examined element were incomplete.
+ *   `classifyEntry` answers "does it exist and is it a regular file". It
+ *   does not answer "may this process OPEN it". A `chmod 000` script is
+ *   present and regular, the probe passed it, `node` launched fine (so
+ *   `spawnSync.error` stayed undefined), the open failed with EACCES, the
+ *   exit was 1, and 1 meant unmet. Existence and type are two of the
+ *   conditions for an open; permission is the third and it was untested.
+ *
+ *   HALF B, the SET of elements examined was a proper subset of the
+ *   path-shaped ones. Rules 2 and 4 above skip an operand that follows an
+ *   option (`node --flag script.mjs`) and one carrying whitespace, and both
+ *   were confirmed to produce the same wrong verdict.
+ *
+ * HALF A IS CLOSED OUTRIGHT, by asking the complete question. A path can be
+ * opened for reading exactly when `access(R_OK)` succeeds, which resolves
+ * every component's traversal permission and the file's own mode in one
+ * call, FOR THE CALLING PROCESS. That last clause is the point: the process
+ * that runs this probe is the process that will spawn the command, so the
+ * calling UID is the right UID to ask about, and `access` is therefore the
+ * correct primitive here even though the pre-existing executable check
+ * deliberately reads mode bits instead (that check wants a UID-independent
+ * answer; this one wants a UID-dependent one, and both are now applied to
+ * the launcher).
+ *
+ * HALF B IS NOT CLOSED BY WIDENING THIS RULE. This rule hard-refuses BEFORE
+ * the spawn, so a false positive here breaks a precondition that would have
+ * exited 0, and that is a worse direction to be wrong in than any silent skip.
+ * Half B is closed by a SECOND, wider rule (`commandPathCandidates` below)
+ * whose result is consulted only when the exit is nonzero, so an exit of 0
+ * remains its own proof and no working declaration can be affected.
+ *
+ * ------------------------------------------------------------------------
+ * FIX ROUND 2 (M3-P11) CORRECTED THAT SECOND RULE IN TWO WAYS, and the
+ * sentence round 1 wrote here is the one that had to go. Round 1 argued that
+ * after a nonzero exit a deliberately OVER-INCLUSIVE scan is the safe
+ * direction, because its false positive is only a loud `error` an operator
+ * can read. A delta verifier measured that trade and it does not hold:
+ * `decideAggregate` checks `counts.error > 0` before anything else, so one
+ * false error on one conditional gate fails the WHOLE bundle. The two
+ * corrections are documented on `commandPathCandidates` (which elements) and
+ * on `attributionGaps` (which moment).
+ */
+export interface CommandRunnability {
+    /** False when the command could not have run: this is `error`, not unmet. */
+    runnable: boolean;
+    /** Why not. Empty when runnable. */
+    reason: string;
+    /** Every element this probe examined, so its scope is data, not a claim. */
+    probed: string[];
+}
+/**
+ * The path operands of a command, by the four-part rule documented above,
+ * MINUS the elements `namesNoPath` rules out. This is the STRICT set: it is
+ * probed before the spawn and a failure here is a hard `error`, so it stays
+ * conservative and keeps the whitespace and after-an-option guards that the
+ * wider rule drops.
+ */
+export declare function commandPathOperands(command: string[]): string[];
+/**
+ * Every argv element that names a PATH THE COMMAND NEEDED, used only to decide
+ * whether a NONZERO exit is attributable to the command's own logic.
+ *
+ * ------------------------------------------------------------------------
+ * FIX ROUND 2 (M3-P11) REWROTE THIS RULE, AND WHY IS THE WHOLE POINT.
+ *
+ * Fix round 1 defined it as "contains `/`", at any position, launcher
+ * included. A delta verifier measured what that costs
+ * (delivery/verification/m3-p11-fix-round-1.md, findings 2a and 2b) and the
+ * cost is larger than round 1's own note conveyed: `decideAggregate` checks
+ * `counts.error > 0` FIRST, so ONE false error on ONE conditional gate fails
+ * the ENTIRE bundle. An honest, correctly written precondition could take a
+ * consumer's whole delivery down. That is a worse failure than the silent
+ * skip this phase set out to abolish, because a silent skip is wrong and
+ * quiet while this is wrong and total.
+ *
+ * THE MECHANISM: "contains a slash" was being used as a proxy for "is a path
+ * operand", and it is neither necessary nor sufficient.
+ *
+ *   NOT SUFFICIENT: inline code (`process.exit(existsSync("/marker")?0:1)`),
+ *   a URL, an `--opt=/value` pair, a date (`2026/08/14`), a regex and plain
+ *   division all contain `/` and none of them is a path.
+ *
+ *   NOT NECESSARY: `node check.mjs` names a real script with no `/` in it.
+ *
+ * So the rule now tests four things instead of one. An element at index >= 1
+ * is a path this command needed when ALL FOUR hold:
+ *
+ *   1. it does not itself begin with `-`. An option is not an operand, and
+ *      `--out=/tmp/x` is an option carrying a value, not a path: probing the
+ *      whole element was a GUARANTEED false error for every `--opt=/path`
+ *      form, since no file is ever named `--out=/tmp/x`.
+ *   2. the element before it is not in `CODE_VALUED_OPTIONS`. This is the
+ *      `node -e` case, and it is the one measured in finding 2a.
+ *   3. it is not URL-shaped.
+ *   4. it either contains `/`, or it carries a `SCRIPT_SUFFIXES` suffix and
+ *      no whitespace. The second disjunct is new in round 2 and is what
+ *      closes the bare-operand residue.
+ *
+ * The launcher (index 0) is deliberately NOT in this set. It is already
+ * probed, with the executable conditions on top, by `probeCommandRunnable`
+ * before the spawn, so including it here only duplicated that work.
+ *
+ * WHAT THIS RULE STILL GETS WRONG, stated rather than left to be discovered.
+ * A FALSE ERROR remains reachable for an element that is not a path, is not
+ * an option's value, and either contains `/` or ends in a script suffix: a
+ * bare date operand (`mytool 2026/08/14`), an operand-position regex, and a
+ * value passed to an option that takes a non-path value NOT in
+ * `CODE_VALUED_OPTIONS` (`awk -v expr=a/b`). A SILENT SKIP remains reachable
+ * for an operand with no `/` and no known suffix (`node check`, an
+ * extensionless script), for a path named through an environment variable or
+ * produced by a shell, and for an `--opt=/path` pair, which rule 1 now
+ * declines to probe. Both lists are shorter than round 1's; neither is empty.
+ * Full accounting, with the enumeration that produced it, in
+ * delivery/work-history/m3-p11.md.
+ */
+export declare function commandPathCandidates(command: string[]): string[];
+/**
+ * Can this command run at all? See the block comment above for the rule and
+ * for what it deliberately does not cover.
+ *
+ * The launcher is probed only when it names a path (contains `/`); a bare
+ * name is a PATH lookup and is left to `spawnSync`'s own `error`, which
+ * already reports it, rather than reimplementing PATH resolution here.
+ */
+export declare function probeCommandRunnable(command: string[], cwd: string): CommandRunnability;
+/**
+ * Every path-shaped argv element this process cannot open, with the reason.
+ * Empty means a nonzero exit is ATTRIBUTABLE to the command's own logic;
+ * non-empty means it is not, and M2-C-3 says a check that cannot reach a
+ * verdict fails closed rather than guessing one.
+ *
+ * FIX ROUND 2 MOVED THE CALL SITE, and the move is the fix for a second
+ * mechanism, independent of which elements are scanned. Round 1 ran this
+ * AFTER the spawn, on the nonzero arm only. The question it answers is "did
+ * the command have what it needed IN ORDER TO RUN", which is a question about
+ * the moment BEFORE the spawn, and answering it from the filesystem AFTER the
+ * spawn reads the command's own effects back as evidence about its inputs. A
+ * precondition script that legitimately decides "unmet" and deletes itself as
+ * its last act (a one-shot or bootstrap script) was therefore reported
+ * `error`, deterministically, no timing window needed: measured in
+ * delivery/verification/m3-p11-fix-round-1.md as finding 2b.
+ *
+ * So the scan now runs BEFORE the spawn and its result is CARRIED. The exit
+ * code still decides whether the result is consulted: an exit of 0 is its own
+ * proof that the command ran, so no declaration that succeeds can be affected
+ * by this at all, which is the property round 1 established and round 2 keeps.
+ */
+export declare function attributionGaps(command: string[], cwd: string): string[];
+export declare const M2_C_5_DETAIL = "M2-C-5 (a run that cannot name what it executed is not evidence)";
+/**
+ * Run the manifest's gates. Returns the aggregate exit code and, when the
+ * run got far enough to have one, the summary that was written.
+ */
+export interface AggregateCounts {
+    declared: number;
+    applicable: number;
+    verdict: number;
+    green: number;
+    red: number;
+    "not-applicable": number;
+    error: number;
+    vacuous: number;
+}
+/**
+ * THE ONE AGGREGATE DECISION, extracted so it can be EXERCISED rather than
+ * read (CR-800's fix round). CR-800 was a reading of these branch conditions
+ * that turned out not to hold, and the first test written for the fix
+ * asserted on the TEXT of this function, which is the guard-that-asserts-text
+ * class MECHANISMS.md records six instances of. A pure function over a counts
+ * object can be handed states the runner cannot currently produce, including
+ * the internally inconsistent ones the invariants below exist for, so the
+ * invariants are witnessed instead of quoted.
+ *
+ * AGGREGATE PRECEDENCE, fixed here so it is one rule and not a reading. A
+ * concrete failure outranks the vacuity check, because "3 gates reported
+ * error" tells the operator more than "no applicable gate" and both exit 21
+ * anyway. The vacuity check outranks a required not-applicable gate, because
+ * a bundle that examined nothing is not a report about any one gate (M2-C-2
+ * at the aggregate level, M2R-012).
+ */
+export declare function decideAggregate(counts: AggregateCounts, requiredNotApplicable: string[], rows: {
+    id: string;
+    status: GateStatus;
+}[]): {
+    exitCode: number;
+    reason: string;
+};
+export declare const RUN_CLAIM_FILE = ".tiphys-gate-run.json";
+/**
+ * RELEASE ONLY WHAT THIS RUN HOLDS (CR-860).
+ *
+ * The mechanism the finding names is: *cleanup that is valid only while the
+ * claim is held, performed from a frame that does not know whether the claim
+ * is held*. The instance was a release in an inner `finally` followed by a
+ * second, unconditional release in an outer `catch`, so a crashed run could
+ * unlink a claim that by then belonged to a DIFFERENT run, revoking a live
+ * run's exclusion. That is "release a lock you no longer hold", the classic
+ * claim-file defect.
+ *
+ * Two things close it, and both are here because the line deletion alone is
+ * the instance fix and this project fixes the mechanism:
+ *
+ *   1. THIS function reads the claim and unlinks ONLY when the runId is its
+ *      own, which is what `src/lock.ts` does when it verifies holdership
+ *      before mutating. A release from a frame that no longer holds the claim
+ *      is then a no-op rather than a revocation, whatever the call graph does.
+ *   2. The call graph is also fixed, in `runGates`: exactly one release, in
+ *      one `finally`, after every write into the directory. Depending on the
+ *      guard alone would leave the writes happening outside the claimed
+ *      region, which is the other half of the same finding.
+ *
+ * A claim this run does not hold is deliberately LEFT IN PLACE. Deleting
+ * another run's claim is the harm; leaving a stranded one costs a human one
+ * `rm`, and the refusal text says which file and why.
+ */
+export declare function releaseEvidenceDirectory(evidenceDir: string, runId: string): boolean;
+/**
+ * The public entry. It exists so that NO throw can escape the runner and be
+ * read as this phase's RED exit code by whatever consumes it (CR-801). The
+ * runner enforces exactly this rule on its gates; it now obeys it itself.
+ */
+export declare function runGates(options: RunOptions): RunOutcome;