@tiphys/kernel 0.0.0 → 0.1.0

package/dist/src/gates/red-witness.js

@@ -0,0 +1,390 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { refuseOpenForWrite, singleLine } from "../task.js";
+import { loadManifest } from "./manifest.js";
+import { exitCodeForStatus, makeGateResult, renderGateResult } from "./result.js";
+import { listWitnessSpecFiles, loadWitnessSpec, memberTouchedFiles, } from "../witness/spec.js";
+import { SPAWN_GREP, computePhaseDiff, evaluateWitness, gitIn, makeScratchRoot, readTestFilesAtHead, removeScratchRoot, resolveRepoRoot, shellSpawnsAndParses, } from "../witness/run.js";
+/**
+ * THE RED-WITNESS GATE (kernel plan M2, M2-P2 steps 6 and 7).
+ *
+ * Registered in gates.manifest.json as `red-witness`, applicability
+ * `required`, precondition `diff-touches` on `src/` and `bin/`, unitLabel
+ * `witnesses evaluated`. Invoked by the runner as
+ *
+ *   node src/gates/red-witness.ts --result <path> --evidence <dir>
+ *     --base <ref> --head <ref>
+ *
+ * plus `--baseline <ref>` when invoked directly: merge-time re-verification
+ * is a PARAMETER, not an enforcement (M2-D-08); it defaults to `--base`.
+ *
+ * WHAT THE GATE DECIDES.
+ *   - Every witness spec changed in the phase diff (the phase's OWN
+ *     witnesses) is evaluated by the harness.
+ *   - Every STORED witness any of whose dangerous-state members touches a
+ *     changed file is re-evaluated; one now green against any of its own
+ *     members is red with reason "witness no longer guards its behavior"
+ *     naming the witness and the measured rate (M2R-002, the N-401 shape).
+ *   - A changed source file under src/ or bin/ with no witness spec
+ *     covering it is RED, never not-applicable (step 7).
+ *   - `--base` absent is `error` (M2-C-3).
+ *
+ * DEPTH REQUIREMENT, documented rather than assumed (STATE.md CR-902
+ * carry-forward): the gate needs `--base` and `--head` resolvable with
+ * history (the diff is base...head, a merge-base diff) and an UNSHALLOW
+ * repository, because the harness scratch-clones it and git refuses to
+ * clone from a shallow source. Both are satisfied by `fetch-depth: 0` on
+ * the CI checkout, which is owned by the workflow's owner, not this phase.
+ * A shallow repository is `error` naming the requirement. On pull_request
+ * events the checkout HEAD is a synthetic merge commit, so the audited
+ * head is always taken from `--head`, never from the checkout.
+ */
+const USAGE = "usage: node src/gates/red-witness.ts --result <path> --evidence <dir> " +
+    "--base <ref> [--head <ref>] [--baseline <ref>] [--phase <id>]";
+function parseArgs(argv) {
+    const options = {};
+    const known = new Map([
+        ["--result", "result"],
+        ["--evidence", "evidence"],
+        ["--base", "base"],
+        ["--head", "head"],
+        ["--baseline", "baseline"],
+        ["--phase", "phase"],
+    ]);
+    for (let index = 0; index < argv.length; index += 2) {
+        const flag = argv[index];
+        const field = known.get(flag);
+        if (field === undefined) {
+            return { usageError: `unknown option ${flag}` };
+        }
+        const value = argv[index + 1];
+        if (value === undefined || value.startsWith("--")) {
+            return { usageError: `${flag} requires a value` };
+        }
+        options[field] = value;
+    }
+    return { options };
+}
+function now() {
+    return new Date().toISOString();
+}
+function errorOutcome(startedAt, detail) {
+    const result = makeGateResult({
+        gate: "red-witness",
+        status: "error",
+        units: 0,
+        unitLabel: "witnesses evaluated",
+        startedAt,
+        endedAt: now(),
+        detail,
+    });
+    return {
+        result,
+        exitCode: exitCodeForStatus(result.status),
+        evaluations: [],
+        reEvaluationMs: 0,
+    };
+}
+/** True when the repo-relative path is a phase-audited source path. */
+function isAuditedSource(path) {
+    return path.startsWith("src/") || path.startsWith("bin/");
+}
+/**
+ * Run the red-witness gate against a repository. Exported so tests can
+ * drive it without a subprocess; the CLI below is a thin shell over it.
+ */
+export function runRedWitnessGate(run) {
+    const startedAt = now();
+    const rootProbe = resolveRepoRoot(run.repoRoot);
+    if (rootProbe.root === undefined) {
+        return errorOutcome(startedAt, rootProbe.reason);
+    }
+    const repoRoot = rootProbe.root;
+    const shallow = gitIn(repoRoot, ["rev-parse", "--is-shallow-repository"]);
+    if (!shallow.ok) {
+        return errorOutcome(startedAt, shallow.reason);
+    }
+    if (shallow.stdout.trim() === "true") {
+        return errorOutcome(startedAt, "this repository is a shallow clone; the red-witness gate requires " +
+            "full history (fetch-depth: 0) because the phase diff is a " +
+            "merge-base diff and the harness scratch-clones the repository, " +
+            "which git refuses from a shallow source");
+    }
+    const diffOutcome = computePhaseDiff(repoRoot, run.base, run.head ?? "HEAD");
+    if (!diffOutcome.ok) {
+        return errorOutcome(startedAt, diffOutcome.reason);
+    }
+    const diff = diffOutcome.diff;
+    const manifestPath = join(repoRoot, "gates.manifest.json");
+    const manifest = loadManifest(manifestPath);
+    if (!manifest.ok) {
+        return errorOutcome(startedAt, `the destructiveCommands list could not be read (rule (e) needs it): ` +
+            `${manifest.reason}${manifest.diagnostics.length > 0 ? `: ${manifest.diagnostics.join("; ")}` : ""}`);
+    }
+    const behaviorsShown = gitIn(repoRoot, [
+        "show",
+        `${diff.headSha}:test/behaviors.json`,
+    ]);
+    if (!behaviorsShown.ok) {
+        return errorOutcome(startedAt, `test/behaviors.json could not be read at the audited head: ${behaviorsShown.reason}`);
+    }
+    let behaviors;
+    try {
+        behaviors = new Set(Object.keys(JSON.parse(behaviorsShown.stdout)));
+    }
+    catch (error) {
+        return errorOutcome(startedAt, `test/behaviors.json does not parse at the audited head: ${singleLine(String(error))}`);
+    }
+    const testFilesOutcome = readTestFilesAtHead(repoRoot, diff.headSha);
+    if (!testFilesOutcome.ok) {
+        return errorOutcome(startedAt, testFilesOutcome.reason);
+    }
+    // Rule (f)'s derivation: the spawn grep over the changed files' head
+    // contents (deleted files have no head content and cannot be touched by a
+    // member either). Shell scripts (*.sh) are screened by the shell
+    // spawn-and-parse derivation instead of the JS token grep (CR-H2), so a
+    // bin/ shell script that classifies another program's output (the V-2
+    // shape) is not invisible to the capture obligation.
+    const spawningChangedFiles = [];
+    for (const [path, file] of diff.files) {
+        if (file.status === "D") {
+            continue;
+        }
+        const shown = gitIn(repoRoot, ["show", `${diff.headSha}:${path}`]);
+        if (!shown.ok) {
+            continue;
+        }
+        const spawns = path.endsWith(".sh")
+            ? shellSpawnsAndParses(shown.stdout)
+            : SPAWN_GREP.test(shown.stdout);
+        if (spawns) {
+            spawningChangedFiles.push(path);
+        }
+    }
+    spawningChangedFiles.sort();
+    const witnessDir = join(repoRoot, "witness");
+    const listing = listWitnessSpecFiles(witnessDir);
+    if (!listing.ok) {
+        return errorOutcome(startedAt, listing.reason);
+    }
+    const reasons = [];
+    const specs = [];
+    const seenIds = new Map();
+    for (const path of listing.paths) {
+        const loaded = loadWitnessSpec(path);
+        const repoRelative = relative(repoRoot, path).split("\\").join("/");
+        if (!loaded.ok) {
+            reasons.push(`${loaded.reason}${loaded.diagnostics.length > 0 ? `: ${loaded.diagnostics.join("; ")}` : ""}`);
+            continue;
+        }
+        const previous = seenIds.get(loaded.spec.id);
+        if (previous !== undefined) {
+            reasons.push(`witness id ${loaded.spec.id} is declared by both ${previous} and ${repoRelative}`);
+            continue;
+        }
+        seenIds.set(loaded.spec.id, repoRelative);
+        specs.push({ spec: loaded.spec, path, repoRelative });
+    }
+    const readPatchAtHead = (patchPath) => {
+        const shown = gitIn(repoRoot, ["show", `${diff.headSha}:${patchPath}`]);
+        return shown.ok ? shown.stdout : undefined;
+    };
+    const own = specs.filter((entry) => diff.files.has(entry.repoRelative));
+    const stored = specs.filter((entry) => !diff.files.has(entry.repoRelative));
+    const triggeredStored = stored.filter((entry) => entry.spec.dangerousStates.some((member) => memberTouchedFiles(member, readPatchAtHead).some((file) => diff.files.has(file))));
+    // Coverage (step 7): source changed with no witness spec covering it is
+    // red, never not-applicable. Coverage semantics are decision D-P2-2 in
+    // the work history.
+    const covered = new Set();
+    for (const entry of specs) {
+        for (const member of entry.spec.dangerousStates) {
+            for (const file of memberTouchedFiles(member, readPatchAtHead)) {
+                covered.add(file);
+            }
+        }
+    }
+    const uncovered = [];
+    for (const [path, file] of diff.files) {
+        if (file.status === "D" || !isAuditedSource(path)) {
+            continue;
+        }
+        if (!covered.has(path)) {
+            uncovered.push(path);
+        }
+    }
+    uncovered.sort();
+    if (uncovered.length > 0) {
+        reasons.push(`source changed with no witness spec covering it: ${uncovered.join(", ")}`);
+    }
+    const evaluations = [];
+    let reEvaluationMs = 0;
+    const scratchRoot = makeScratchRoot();
+    try {
+        const baseInputs = {
+            repoRoot,
+            headSha: diff.headSha,
+            baselineRef: run.baseline ?? run.base,
+            diff,
+            destructiveCommands: manifest.manifest.destructiveCommands,
+            behaviors,
+            testFiles: testFilesOutcome.files,
+            spawningChangedFiles,
+            scratchRoot,
+        };
+        for (const entry of own) {
+            const inputs = { ...baseInputs, phaseOwn: true };
+            if (run.hooks !== undefined) {
+                inputs.hooks = run.hooks;
+            }
+            const evaluation = evaluateWitness(entry.spec, entry.repoRelative, inputs);
+            evaluations.push(evaluation);
+            if (evaluation.status !== "green") {
+                reasons.push(`witness ${evaluation.witness}: ${evaluation.status}: ${evaluation.reasons.join("; ")}`);
+            }
+        }
+        const reEvaluationStart = Date.now();
+        for (const entry of triggeredStored) {
+            const inputs = { ...baseInputs, phaseOwn: false };
+            if (run.hooks !== undefined) {
+                inputs.hooks = run.hooks;
+            }
+            const evaluation = evaluateWitness(entry.spec, entry.repoRelative, inputs);
+            evaluations.push(evaluation);
+            if (evaluation.status === "red") {
+                const rates = evaluation.members
+                    .filter((member) => member.rate !== undefined)
+                    .map((member) => `member ${String(member.index)} red ` +
+                    `${String(member.rate?.red)}/${String(member.rate?.total)}`)
+                    .join(", ");
+                reasons.push(`witness ${evaluation.witness} no longer guards its behavior ` +
+                    `(${rates === "" ? evaluation.reasons.join("; ") : rates})`);
+            }
+            else if (evaluation.status === "error") {
+                reasons.push(`witness ${evaluation.witness}: error: ${evaluation.reasons.join("; ")}`);
+            }
+        }
+        reEvaluationMs = Date.now() - reEvaluationStart;
+    }
+    finally {
+        removeScratchRoot(scratchRoot);
+    }
+    let status = "green";
+    if (evaluations.some((evaluation) => evaluation.status === "error")) {
+        status = "error";
+    }
+    else if (reasons.length > 0) {
+        status = "red";
+    }
+    const evidence = [];
+    if (run.evidenceDir !== undefined) {
+        const recordsPath = join(run.evidenceDir, "witness-records.json");
+        const refusal = refuseOpenForWrite(recordsPath);
+        if (refusal === undefined) {
+            try {
+                mkdirSync(run.evidenceDir, { recursive: true });
+                writeFileSync(recordsPath, `${JSON.stringify({
+                    base: diff.baseSha,
+                    head: diff.headSha,
+                    spawningChangedFiles,
+                    uncoveredSources: uncovered,
+                    reEvaluationMs,
+                    evaluations,
+                }, null, 2)}\n`);
+                evidence.push("witness-records.json");
+            }
+            catch {
+                // The record still carries the verdict; evidence is best-effort.
+            }
+        }
+    }
+    const detail = `${String(evaluations.length)} witness(es) evaluated ` +
+        `(${String(own.length)} own, ${String(triggeredStored.length)} stored ` +
+        `re-evaluated in ${String(reEvaluationMs)}ms); ` +
+        (reasons.length === 0
+            ? "every witness red against every declared dangerous state and green at head"
+            : reasons.join("; "));
+    const result = makeGateResult({
+        gate: "red-witness",
+        status,
+        units: evaluations.length,
+        unitLabel: "witnesses evaluated",
+        startedAt,
+        endedAt: now(),
+        detail,
+        evidence,
+    });
+    return {
+        result,
+        exitCode: exitCodeForStatus(result.status),
+        evaluations,
+        reEvaluationMs,
+    };
+}
+function main(argv) {
+    const parsed = parseArgs(argv);
+    if (parsed.options === undefined) {
+        process.stderr.write(`tiphys red-witness: ${parsed.usageError}\n${USAGE}\n`);
+        return 64;
+    }
+    const options = parsed.options;
+    if (options.result === undefined) {
+        process.stderr.write(`tiphys red-witness: --result is required\n${USAGE}\n`);
+        return 64;
+    }
+    let outcome;
+    if (options.base === undefined) {
+        // M2-C-3 (M2R-003): a required invocation parameter absent is error,
+        // never not-applicable and never a guess.
+        outcome = errorOutcome(now(), "--base was not supplied; the phase diff cannot be computed (M2-C-3)");
+    }
+    else {
+        const run = { repoRoot: process.cwd(), base: options.base };
+        if (options.head !== undefined) {
+            run.head = options.head;
+        }
+        if (options.baseline !== undefined) {
+            run.baseline = options.baseline;
+        }
+        if (options.evidence !== undefined) {
+            run.evidenceDir = options.evidence;
+        }
+        try {
+            outcome = runRedWitnessGate(run);
+        }
+        catch (error) {
+            // No throw may escape as exit 1: that is the RED code (the runner's
+            // own crash-discipline rule, applied to this gate).
+            outcome = errorOutcome(now(), `the red-witness gate failed: ${singleLine(error.message ?? String(error))}`);
+        }
+    }
+    const refusal = refuseOpenForWrite(options.result);
+    if (refusal !== undefined) {
+        process.stderr.write(`tiphys red-witness: ${refusal}\n`);
+        return 21;
+    }
+    try {
+        writeFileSync(options.result, renderGateResult(outcome.result));
+    }
+    catch (error) {
+        process.stderr.write(`tiphys red-witness: the result record could not be written: ${singleLine(String(error))}\n`);
+        return 21;
+    }
+    process.stdout.write(`red-witness: ${outcome.result.status} (${outcome.result.detail})\n`);
+    return outcome.exitCode;
+}
+const invokedDirectly = (() => {
+    const entry = process.argv[1];
+    if (entry === undefined) {
+        return false;
+    }
+    try {
+        return import.meta.url === pathToFileURL(resolve(entry)).href;
+    }
+    catch {
+        return false;
+    }
+})();
+if (invokedDirectly) {
+    process.exit(main(process.argv.slice(2)));
+}

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

@@ -0,0 +1,283 @@
+import type { GateStatus } from "./result.ts";
+import type { SchemaDocument } from "./validate.ts";
+/**
+ * THE RELEASE-VERIFICATION CONTRACT (kernel plan M2, M2-P7 step 3; DR-0014;
+ * delivery/verification/release-verification-interface.md).
+ *
+ * ONE post-merge verification contract with two registry entries (`deploy`
+ * and `migrations`). The kernel owns the SUBJECT, the CLOCK, the LOOP and
+ * the OUTCOME MAPPING; an adapter owns the platform mapping and nothing
+ * else. An adapter is an executable named by committed configuration,
+ * spawned as a subprocess with a request file path in argv, performing ONE
+ * bounded observation per invocation and writing its response to a
+ * kernel-supplied record path. It returns an OUTCOME, never a status path:
+ * JSON-pointer extraction exists only inside the http-json adapter's own
+ * configuration, and the kernel never learns what a statusPath is.
+ *
+ * WHY THE BOUNDARY IS A PROCESS (M2-D-07, investigation section 5): it
+ * works for any language, and it makes the per-attempt timeout ENFORCEABLE
+ * rather than promised. The kernel terminates an attempt that overruns
+ * (`spawnSync`'s `timeout` and `killSignal` options) and records that
+ * attempt as `error`, so an adapter that hangs cannot hang the kernel.
+ *
+ * C-2 EXEMPTION, STATED WHERE THE TERMINATION HAPPENS AND NOWHERE ELSE.
+ * C-2 forbids pid, process liveness, signals and /proc FOR IDENTITY OR
+ * EXCLUSION. The per-attempt termination above is neither: it is a timeout
+ * bound on a child this kernel itself spawned and still holds the handle
+ * of, it probes nothing, identifies nothing and excludes nothing, and no
+ * pid is ever read, recorded or compared. That is the one place any kill
+ * may appear in this module or its adapters, and it appears as a spawn
+ * option, not as a process.kill call.
+ *
+ * NO FAILURE VOCABULARY SHIPS (plan step 2, T-003 lesson 4). No
+ * non-success platform state was ever captured, so none is named anywhere
+ * in this module or its adapters. The safe rule instead: one satisfying
+ * value per configured adapter; every other observed value is recorded
+ * verbatim and treated as `pending` until the deadline, at which point it
+ * becomes red naming the last observed value. Unknown never becomes green.
+ *
+ * NEVER auto-background (C-3): the loop is a foreground await, every spawn
+ * is spawnSync, nothing is detached and nothing is unref'd.
+ */
+/** The one declaration path (design decision D-p7-1 in the work history). */
+export declare const DECLARATION_PATH = "release-verification.json";
+/** The contract versions this kernel accepts (fail-closed rule 6). */
+export declare const ACCEPTED_CONTRACT_VERSIONS: readonly string[];
+/**
+ * The subject: what the kernel knows for certain the moment a merge
+ * happens. Platform vocabulary (deployment id, workflow run id, migration
+ * set) is the adapter's, and the kernel never learns it.
+ */
+export interface ReleaseSubject {
+    repository: string;
+    integrationRef: string;
+    mergedSha: string;
+    mergedAt: string;
+    phaseId: string;
+}
+export declare const SUBJECT_FIELDS: readonly (keyof ReleaseSubject)[];
+/**
+ * The outcome vocabulary, six values. There is deliberately no `unknown`,
+ * no `skipped` and no `warn`: a soft state is where a false green hides
+ * (M2-C-3).
+ */
+export type VerificationOutcome = "satisfied" | "failed" | "pending" | "absent" | "not-applicable" | "error";
+export declare const VERIFICATION_OUTCOMES: readonly VerificationOutcome[];
+/**
+ * THE TOTAL MAPPING to GateResult status, implemented in exactly one place
+ * (plan step 3). `satisfied` is green with `units` 1 per verification
+ * satisfied (or the adapter's own examined count, D-p7-3). `pending` and
+ * `absent` are NEVER terminal: they are loop states, and the two entries
+ * below are reachable only through the deadline conversion in
+ * `runVerification`, which turns both into red with TEXTUALLY DISTINCT
+ * reasons: `deadline reached, last observed <value>` for pending and
+ * `deadline reached, no release object for subject` for absent. An adapter
+ * cannot make pending mean pass.
+ */
+export declare const OUTCOME_TO_STATUS: Readonly<Record<VerificationOutcome, GateStatus>>;
+export declare const DEADLINE_REASON_ABSENT = "deadline reached, no release object for subject";
+export declare function deadlineReasonPending(lastObserved: string): string;
+/** The kernel's clock. No defaults anywhere: the numbers are the project's. */
+export interface VerificationClock {
+    intervalMs: number;
+    deadlineMs: number;
+    attemptTimeoutMs: number;
+    maxAttempts?: number;
+}
+/** What the adapter wrote, after the seven rules accepted it. */
+export interface AdapterResponse {
+    contractVersion: string;
+    adapter: string;
+    subject: ReleaseSubject;
+    outcome: VerificationOutcome;
+    resolved?: {
+        kind: string;
+        id: string;
+        createdAt?: unknown;
+    } & Record<string, unknown>;
+    observedAt: string;
+    observation?: {
+        raw?: unknown;
+        detail: string;
+    };
+    reason?: string;
+    units?: number;
+    precondition?: {
+        id: string;
+        evidence?: string[];
+    };
+    transport?: {
+        httpStatus?: number;
+    };
+}
+/** One attempt's record: number, instant, outcome, identity, transport. */
+export interface AttemptRecord {
+    attempt: number;
+    at: string;
+    outcome: VerificationOutcome | "invalid";
+    detail: string;
+    resolved?: unknown;
+    transport: {
+        exitCode: number | null;
+        signal: string | null;
+        terminatedByTimeout: boolean;
+        httpStatus?: number;
+    };
+    /**
+     * The older-than-the-merge observation (investigation guarantee 9,
+     * section 8 item 8): recorded, deliberately NOT promoted to an error
+     * until one real counter-example settles whether a platform reuses or
+     * backdates a record on redeploy.
+     */
+    releaseObjectOlderThanMerge?: boolean;
+}
+export type VerificationVerdict = {
+    kind: "satisfied";
+    units: number;
+    detail: string;
+    resolved: unknown;
+} | {
+    kind: "failed";
+    reason: string;
+} | {
+    kind: "not-applicable";
+    declared: boolean;
+    reason: string;
+    preconditionId: string;
+    evidence: string[];
+} | {
+    kind: "error";
+    reason: string;
+} | {
+    kind: "deadline";
+    lastOutcome: "pending" | "absent";
+    reason: string;
+};
+export interface VerificationRun {
+    verdict: VerificationVerdict;
+    attempts: AttemptRecord[];
+    /** Paths relative to evidenceDir, in creation order. */
+    evidence: string[];
+}
+export declare function responseSchema(): SchemaDocument;
+export declare function declarationSchema(): SchemaDocument;
+/**
+ * THE SEVEN FAIL-CLOSED RULES on an adapter response (plan step 3), each
+ * corresponding to a way a verifier can be fooled. Rule 1 (exit 0 with no
+ * response written) is enforced by the caller, which owns the file's
+ * existence; rules 2 to 7 are here. The subject echo (rule 3) is checked
+ * field by field BEFORE the outcome is read, so an adapter that verified
+ * something else cannot have its outcome looked at for this subject.
+ */
+export type ResponseValidation = {
+    ok: true;
+    response: AdapterResponse;
+} | {
+    ok: false;
+    rule: number;
+    reason: string;
+};
+export declare function validateAdapterResponse(body: string, subject: ReleaseSubject): ResponseValidation;
+/**
+ * The encoded forms of a credential value the kernel can derive from the
+ * value alone (CR-P7H-3). Redacting only the verbatim bytes let a trivially
+ * reversible copy through: an adapter emitting the token as a standalone
+ * base64 blob (an HTTP Basic `Authorization: Basic <base64(token)>` of the
+ * token) leaked a recoverable secret into the stderr evidence. Each form here
+ * is a DETERMINISTIC, enumerable transform of the same value, so the set is
+ * bounded and cheap.
+ *
+ * WHAT THIS DOES NOT COVER, stated so a green is auditable rather than
+ * silently partial (never soften a work history): forms that fold in bytes
+ * the kernel does not hold, e.g. base64 of `"user:" + value` for a full Basic
+ * credential PAIR (the username is the project's, not the kernel's), or a
+ * value re-encoded by a transport the kernel never sees (gzip, hex, a second
+ * base64 round). Those are residue the reference adapters do not produce; a
+ * third-party adapter that composes a credential with unknown surrounding
+ * bytes owns that redaction, and the guarantee scoped here is the value and
+ * its own single-step base64 and percent encodings.
+ */
+export declare function secretForms(value: string): string[];
+/**
+ * Replace every resolved credential VALUE, and its enumerable encoded forms
+ * (see secretForms), with a named placeholder, everywhere in the text.
+ */
+export declare function redactSecrets(text: string, secrets: readonly {
+    name: string;
+    value: string;
+}[]): string;
+export interface RunVerificationOptions {
+    verification: string;
+    subject: ReleaseSubject;
+    adapter: string[];
+    config: unknown;
+    clock: VerificationClock;
+    /** Absolute directory the attempt evidence is written into. */
+    evidenceDir: string;
+    /** Resolved credential values, for redaction only. Never written. */
+    secrets?: readonly {
+        name: string;
+        value: string;
+    }[];
+}
+/**
+ * THE KERNEL-OWNED LOOP. One bounded adapter observation per attempt, one
+ * record per attempt, foreground polling (C-3), verdict at the deadline.
+ * `pending` and `absent` loop; everything else is terminal, including every
+ * fail-closed violation (design decision D-p7-5: a broken adapter cannot
+ * reach a verdict, and M2-C-3 makes that `error` now, not red later).
+ */
+export declare function runVerification(options: RunVerificationOptions): Promise<VerificationRun>;
+export interface DeclaredVerification {
+    mode: "none" | "adapter";
+    reason?: string;
+    adapter?: string[];
+    config?: unknown;
+    clock?: VerificationClock;
+    credentials?: string[];
+}
+export interface Declaration {
+    version: number;
+    repository: string;
+    integrationRef: string;
+    verifications: {
+        deploy?: DeclaredVerification;
+        migrations?: DeclaredVerification;
+    };
+}
+export type DeclarationLoad = {
+    ok: true;
+    declaration: Declaration;
+    /** sha256 hex of the blob bytes read from the governing ref. */
+    sha256: string;
+    /** The resolved commit sha of the governing ref. */
+    ref: string;
+    refSha: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Read the declaration from a COMMITTED ref, never from the working tree
+ * (design decision D-p7-2; the anti-widening rule of plan step 7, same as
+ * the scope auditor's: a phase must not be able to switch off, inside its
+ * own branch, the check that would have caught it). The record carries the
+ * declaration blob's sha256 so a reviewer can see which text authorized
+ * whatever happened.
+ */
+export declare function loadDeclaration(ref: string, cwd: string): DeclarationLoad;
+/**
+ * THE GATE ENTRY, shared by the two thin entry points. The manifest keeps
+ * two static entries exactly as section 1.4 declares them; this function is
+ * what each names. Returns the process exit code.
+ *
+ * The governing ref is `--base` when supplied (the anti-widening read),
+ * else HEAD: always a COMMITTED state, so the subject's mergedSha and
+ * mergedAt are the resolved commit's, and an uncommitted edit can neither
+ * enable, disable nor reconfigure a verification. R-032's blocking half:
+ * the verdict record this gate writes is keyed to that sha in its detail
+ * line, and the consumption contract is that THE NEXT DISPATCH REQUIRES A
+ * GREEN VERDICT RECORD FOR THE MERGED SHA; the enforcement is wired at M4
+ * with the pilot (M2-D-11), and M2 adds no dispatch block to spawn.
+ */
+export declare function runReleaseGate(name: "deploy" | "migrations", args: string[]): Promise<number>;