@jevitate/cli 0.28.0 → 0.29.0

package/dist/journey-verify-checkpoint.d.ts

@@ -0,0 +1,656 @@
+import { z } from "zod";
+import { type Journey, type JourneyAssertionSite, type JourneyMutation, type MutationFailedSite, type MutationPlan, type MutationProofVerdict, type MutationRunResult, type ReplayPace, type TargetedProof } from "@jevitate/journey";
+/**
+ * #787: the durable progress of `journey verify --mutate`, one small file per Journey and journey
+ * store under `<project>/.jevitate/logs/verify-progress/`, replaced atomically as the proof moves.
+ * A "pair" here is one planned mutation with all its replays (first, relaxed, control, targeted),
+ * since that is the unit of work a proof finishes: `pairs` in the plan are site↔mutation links.
+ *
+ * What it stores is what a resumed verdict needs and nothing the app or the operator wrote: outcome
+ * classes, structured failed sites, site keys, mutation ids, timings and counts. Never a `reason`, a
+ * blocked write's path, hook text, a parameter value or a Journey value. Hooks, params, origins and
+ * browser settings are bound by HMAC-SHA-256 under a random key kept in `~/.jevitate/` (0600), never in
+ * the project: a plain hash of a short secret parameter could be guessed offline from this file. The
+ * same key signs the file, so a change by someone who can write to `.jevitate/` but cannot read the
+ * home key refuses the resume. The MAC proves the file came from this user's own runs; it does not
+ * stop that user's own processes, which can read the key, nor a rollback to an older genuine file.
+ */
+/** How old a reused result may be. An app changes under an old result, and nothing here can see that. */
+export declare const CHECKPOINT_MAX_AGE_MS: number;
+/** What a refused targeted proof says when its own wording, which is not stored, is gone. */
+export declare const REFUSAL_NOT_KEPT = "refused before the resume; its wording is not kept in the checkpoint";
+/** What a retry's error says on a reused pair: errors can quote the app, so only their count is stored. */
+export declare const RETRY_REASON_NOT_KEPT = "not kept in the checkpoint";
+/**
+ * The replay kinds this build knows how to re-check. A kind is a record's name, not a field, so a new kind of
+ * replay in the proof adds a name here and a `runReplay` call; a file naming any other kind is refused.
+ */
+export declare const REPLAY_RECORD_KINDS: readonly string[];
+/** Why a replay may have decided another, by class: no site, request or page text. */
+declare const ISOLATION_NOTES: readonly ["write-open", "independence-write-open", "control-write-open", "base-write-open", "state-crossed", "state-stuck", "independence-errored", "siblings-undecided"];
+export type IsolationNote = (typeof ISOLATION_NOTES)[number];
+declare const pairRecord: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        skip: "skip";
+        "block-write": "block-write";
+        "stale-value": "stale-value";
+        "swap-param": "swap-param";
+        "truncate-param": "truncate-param";
+        "guard-param": "guard-param";
+    }>;
+    step: z.ZodNumber;
+    param: z.ZodOptional<z.ZodString>;
+    source: z.ZodOptional<z.ZodEnum<{
+        reviewed: "reviewed";
+        option: "option";
+        generated: "generated";
+    }>>;
+    outcome: z.ZodEnum<{
+        error: "error";
+        failed: "failed";
+        passed: "passed";
+        "not-applied": "not-applied";
+    }>;
+    failedSites: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        where: z.ZodLiteral<"step">;
+        step: z.ZodNumber;
+        postcondition: z.ZodBoolean;
+    }, z.core.$strict>, z.ZodObject<{
+        where: z.ZodLiteral<"step-request">;
+        step: z.ZodNumber;
+        checkIndex: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        where: z.ZodLiteral<"end-state">;
+        index: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        where: z.ZodLiteral<"unevaluable">;
+    }, z.core.$strict>], "where">>;
+    waitsCut: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    relaxed: z.ZodOptional<z.ZodObject<{
+        outcome: z.ZodEnum<{
+            error: "error";
+            failed: "failed";
+            passed: "passed";
+            "not-applied": "not-applied";
+        }>;
+        failedSites: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            where: z.ZodLiteral<"step">;
+            step: z.ZodNumber;
+            postcondition: z.ZodBoolean;
+        }, z.core.$strict>, z.ZodObject<{
+            where: z.ZodLiteral<"step-request">;
+            step: z.ZodNumber;
+            checkIndex: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            where: z.ZodLiteral<"end-state">;
+            index: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            where: z.ZodLiteral<"unevaluable">;
+        }, z.core.$strict>], "where">>;
+        waitsCut: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        atBaseTime: z.ZodOptional<z.ZodObject<{
+            outcome: z.ZodEnum<{
+                error: "error";
+                failed: "failed";
+                passed: "passed";
+                "not-applied": "not-applied";
+            }>;
+            failedSites: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                where: z.ZodLiteral<"step">;
+                step: z.ZodNumber;
+                postcondition: z.ZodBoolean;
+            }, z.core.$strict>, z.ZodObject<{
+                where: z.ZodLiteral<"step-request">;
+                step: z.ZodNumber;
+                checkIndex: z.ZodNumber;
+            }, z.core.$strict>, z.ZodObject<{
+                where: z.ZodLiteral<"end-state">;
+                index: z.ZodNumber;
+            }, z.core.$strict>, z.ZodObject<{
+                where: z.ZodLiteral<"unevaluable">;
+            }, z.core.$strict>], "where">>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    control: z.ZodOptional<z.ZodEnum<{
+        error: "error";
+        failed: "failed";
+        passed: "passed";
+        "not-applied": "not-applied";
+    }>>;
+    controlSkipped: z.ZodOptional<z.ZodLiteral<true>>;
+    atBaseTime: z.ZodOptional<z.ZodObject<{
+        outcome: z.ZodEnum<{
+            error: "error";
+            failed: "failed";
+            passed: "passed";
+            "not-applied": "not-applied";
+        }>;
+        failedSites: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            where: z.ZodLiteral<"step">;
+            step: z.ZodNumber;
+            postcondition: z.ZodBoolean;
+        }, z.core.$strict>, z.ZodObject<{
+            where: z.ZodLiteral<"step-request">;
+            step: z.ZodNumber;
+            checkIndex: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            where: z.ZodLiteral<"end-state">;
+            index: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            where: z.ZodLiteral<"unevaluable">;
+        }, z.core.$strict>], "where">>;
+    }, z.core.$strict>>;
+    targeted: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        site: z.ZodString;
+        relaxedSites: z.ZodArray<z.ZodString>;
+        outcome: z.ZodEnum<{
+            error: "error";
+            failed: "failed";
+            passed: "passed";
+            "not-applied": "not-applied";
+        }>;
+        failedSites: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            where: z.ZodLiteral<"step">;
+            step: z.ZodNumber;
+            postcondition: z.ZodBoolean;
+        }, z.core.$strict>, z.ZodObject<{
+            where: z.ZodLiteral<"step-request">;
+            step: z.ZodNumber;
+            checkIndex: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            where: z.ZodLiteral<"end-state">;
+            index: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            where: z.ZodLiteral<"unevaluable">;
+        }, z.core.$strict>], "where">>;
+        refused: z.ZodOptional<z.ZodEnum<{
+            other: "other";
+            "relaxation-bound": "relaxation-bound";
+        }>>;
+        control: z.ZodOptional<z.ZodEnum<{
+            error: "error";
+            failed: "failed";
+            passed: "passed";
+            "not-applied": "not-applied";
+        }>>;
+        declared: z.ZodOptional<z.ZodLiteral<true>>;
+    }, z.core.$strict>>>;
+    retries: z.ZodNumber;
+    finishedAt: z.ZodString;
+    replays: z.ZodArray<z.ZodObject<{
+        kind: z.ZodString;
+        outcome: z.ZodEnum<{
+            error: "error";
+            failed: "failed";
+            passed: "passed";
+            "not-applied": "not-applied";
+        }>;
+        failedSites: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            where: z.ZodLiteral<"step">;
+            step: z.ZodNumber;
+            postcondition: z.ZodBoolean;
+        }, z.core.$strict>, z.ZodObject<{
+            where: z.ZodLiteral<"step-request">;
+            step: z.ZodNumber;
+            checkIndex: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            where: z.ZodLiteral<"end-state">;
+            index: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            where: z.ZodLiteral<"unevaluable">;
+        }, z.core.$strict>], "where">>;
+        reachedMs: z.ZodArray<z.ZodNullable<z.ZodNumber>>;
+        endStateReachedMs: z.ZodOptional<z.ZodNumber>;
+        writesInFlightAtClose: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+declare const bodySchema: z.ZodObject<{
+    schema: z.ZodLiteral<2>;
+    journeyId: z.ZodString;
+    journeyHash: z.ZodString;
+    planDigest: z.ZodString;
+    bindings: z.ZodObject<{
+        params: z.ZodString;
+        hook: z.ZodString;
+        origin: z.ZodString;
+        browser: z.ZodString;
+    }, z.core.$strict>;
+    build: z.ZodObject<{
+        version: z.ZodString;
+        commit: z.ZodString;
+        builtAt: z.ZodString;
+        tree: z.ZodString;
+    }, z.core.$strict>;
+    total: z.ZodNumber;
+    completed: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            skip: "skip";
+            "block-write": "block-write";
+            "stale-value": "stale-value";
+            "swap-param": "swap-param";
+            "truncate-param": "truncate-param";
+            "guard-param": "guard-param";
+        }>;
+        step: z.ZodNumber;
+        param: z.ZodOptional<z.ZodString>;
+        source: z.ZodOptional<z.ZodEnum<{
+            reviewed: "reviewed";
+            option: "option";
+            generated: "generated";
+        }>>;
+        outcome: z.ZodEnum<{
+            error: "error";
+            failed: "failed";
+            passed: "passed";
+            "not-applied": "not-applied";
+        }>;
+        failedSites: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            where: z.ZodLiteral<"step">;
+            step: z.ZodNumber;
+            postcondition: z.ZodBoolean;
+        }, z.core.$strict>, z.ZodObject<{
+            where: z.ZodLiteral<"step-request">;
+            step: z.ZodNumber;
+            checkIndex: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            where: z.ZodLiteral<"end-state">;
+            index: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            where: z.ZodLiteral<"unevaluable">;
+        }, z.core.$strict>], "where">>;
+        waitsCut: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        relaxed: z.ZodOptional<z.ZodObject<{
+            outcome: z.ZodEnum<{
+                error: "error";
+                failed: "failed";
+                passed: "passed";
+                "not-applied": "not-applied";
+            }>;
+            failedSites: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                where: z.ZodLiteral<"step">;
+                step: z.ZodNumber;
+                postcondition: z.ZodBoolean;
+            }, z.core.$strict>, z.ZodObject<{
+                where: z.ZodLiteral<"step-request">;
+                step: z.ZodNumber;
+                checkIndex: z.ZodNumber;
+            }, z.core.$strict>, z.ZodObject<{
+                where: z.ZodLiteral<"end-state">;
+                index: z.ZodNumber;
+            }, z.core.$strict>, z.ZodObject<{
+                where: z.ZodLiteral<"unevaluable">;
+            }, z.core.$strict>], "where">>;
+            waitsCut: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            atBaseTime: z.ZodOptional<z.ZodObject<{
+                outcome: z.ZodEnum<{
+                    error: "error";
+                    failed: "failed";
+                    passed: "passed";
+                    "not-applied": "not-applied";
+                }>;
+                failedSites: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    where: z.ZodLiteral<"step">;
+                    step: z.ZodNumber;
+                    postcondition: z.ZodBoolean;
+                }, z.core.$strict>, z.ZodObject<{
+                    where: z.ZodLiteral<"step-request">;
+                    step: z.ZodNumber;
+                    checkIndex: z.ZodNumber;
+                }, z.core.$strict>, z.ZodObject<{
+                    where: z.ZodLiteral<"end-state">;
+                    index: z.ZodNumber;
+                }, z.core.$strict>, z.ZodObject<{
+                    where: z.ZodLiteral<"unevaluable">;
+                }, z.core.$strict>], "where">>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+        control: z.ZodOptional<z.ZodEnum<{
+            error: "error";
+            failed: "failed";
+            passed: "passed";
+            "not-applied": "not-applied";
+        }>>;
+        controlSkipped: z.ZodOptional<z.ZodLiteral<true>>;
+        atBaseTime: z.ZodOptional<z.ZodObject<{
+            outcome: z.ZodEnum<{
+                error: "error";
+                failed: "failed";
+                passed: "passed";
+                "not-applied": "not-applied";
+            }>;
+            failedSites: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                where: z.ZodLiteral<"step">;
+                step: z.ZodNumber;
+                postcondition: z.ZodBoolean;
+            }, z.core.$strict>, z.ZodObject<{
+                where: z.ZodLiteral<"step-request">;
+                step: z.ZodNumber;
+                checkIndex: z.ZodNumber;
+            }, z.core.$strict>, z.ZodObject<{
+                where: z.ZodLiteral<"end-state">;
+                index: z.ZodNumber;
+            }, z.core.$strict>, z.ZodObject<{
+                where: z.ZodLiteral<"unevaluable">;
+            }, z.core.$strict>], "where">>;
+        }, z.core.$strict>>;
+        targeted: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            site: z.ZodString;
+            relaxedSites: z.ZodArray<z.ZodString>;
+            outcome: z.ZodEnum<{
+                error: "error";
+                failed: "failed";
+                passed: "passed";
+                "not-applied": "not-applied";
+            }>;
+            failedSites: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                where: z.ZodLiteral<"step">;
+                step: z.ZodNumber;
+                postcondition: z.ZodBoolean;
+            }, z.core.$strict>, z.ZodObject<{
+                where: z.ZodLiteral<"step-request">;
+                step: z.ZodNumber;
+                checkIndex: z.ZodNumber;
+            }, z.core.$strict>, z.ZodObject<{
+                where: z.ZodLiteral<"end-state">;
+                index: z.ZodNumber;
+            }, z.core.$strict>, z.ZodObject<{
+                where: z.ZodLiteral<"unevaluable">;
+            }, z.core.$strict>], "where">>;
+            refused: z.ZodOptional<z.ZodEnum<{
+                other: "other";
+                "relaxation-bound": "relaxation-bound";
+            }>>;
+            control: z.ZodOptional<z.ZodEnum<{
+                error: "error";
+                failed: "failed";
+                passed: "passed";
+                "not-applied": "not-applied";
+            }>>;
+            declared: z.ZodOptional<z.ZodLiteral<true>>;
+        }, z.core.$strict>>>;
+        retries: z.ZodNumber;
+        finishedAt: z.ZodString;
+        replays: z.ZodArray<z.ZodObject<{
+            kind: z.ZodString;
+            outcome: z.ZodEnum<{
+                error: "error";
+                failed: "failed";
+                passed: "passed";
+                "not-applied": "not-applied";
+            }>;
+            failedSites: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                where: z.ZodLiteral<"step">;
+                step: z.ZodNumber;
+                postcondition: z.ZodBoolean;
+            }, z.core.$strict>, z.ZodObject<{
+                where: z.ZodLiteral<"step-request">;
+                step: z.ZodNumber;
+                checkIndex: z.ZodNumber;
+            }, z.core.$strict>, z.ZodObject<{
+                where: z.ZodLiteral<"end-state">;
+                index: z.ZodNumber;
+            }, z.core.$strict>, z.ZodObject<{
+                where: z.ZodLiteral<"unevaluable">;
+            }, z.core.$strict>], "where">>;
+            reachedMs: z.ZodArray<z.ZodNullable<z.ZodNumber>>;
+            endStateReachedMs: z.ZodOptional<z.ZodNumber>;
+            writesInFlightAtClose: z.ZodNumber;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    phase: z.ZodEnum<{
+        base: "base";
+        independence: "independence";
+        pairs: "pairs";
+        disagreements: "disagreements";
+        closing: "closing";
+    }>;
+    independence: z.ZodNullable<z.ZodEnum<{
+        passed: "passed";
+        "hold-breaks-claim": "hold-breaks-claim";
+    }>>;
+    currentPair: z.ZodNullable<z.ZodString>;
+    replay: z.ZodNumber;
+    startedAt: z.ZodString;
+    updatedAt: z.ZodString;
+    state: z.ZodEnum<{
+        running: "running";
+        interrupted: "interrupted";
+        finished: "finished";
+    }>;
+    verdict: z.ZodOptional<z.ZodEnum<{
+        inconclusive: "inconclusive";
+        proven: "proven";
+        insensitive: "insensitive";
+    }>>;
+    errorGap: z.ZodOptional<z.ZodLiteral<true>>;
+    reusedPairs: z.ZodNumber;
+    taint: z.ZodObject<{
+        restoreFailed: z.ZodBoolean;
+        notIsolatedBy: z.ZodNullable<z.ZodString>;
+        isolation: z.ZodNullable<z.ZodEnum<{
+            "write-open": "write-open";
+            "independence-write-open": "independence-write-open";
+            "control-write-open": "control-write-open";
+            "base-write-open": "base-write-open";
+            "state-crossed": "state-crossed";
+            "state-stuck": "state-stuck";
+            "independence-errored": "independence-errored";
+            "siblings-undecided": "siblings-undecided";
+        }>>;
+    }, z.core.$strict>;
+    verifier: z.ZodObject<{
+        pid: z.ZodNumber;
+        startToken: z.ZodString;
+        host: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type CheckpointBody = z.infer<typeof bodySchema>;
+export type CheckpointPair = z.infer<typeof pairRecord>;
+export type CheckpointReplay = CheckpointPair["replays"][number];
+/** Why a resume was refused. Each is checked before any browser opens, but for `base-failed`, `pace` and `isolation`, which need the re-measured base. */
+export type ResumeRefusalReason = "no-checkpoint" | "not-regular-file" | "corrupt" | "integrity" | "key-unavailable" | "finished" | "live-verifier" | "other-host" | "journey-hash" | "mutation-plan" | "params" | "hook" | "origin" | "browser" | "cli-build" | "too-old" | "unknown-record" | "not-writable" | "base-failed" | "pace" | "isolation";
+/**
+ * A resume that will not run. It never starts over, and a plain `--mutate` is the way to begin again.
+ * Refused before its claim, the checkpoint stays as it was. `base-failed`, `pace` and `isolation` come
+ * after the claim wrote it: its finished results stand, but it no longer says `finished`, and an
+ * `independence-errored` note is gone. That is harmless: the next resume runs the independence replay again.
+ */
+export declare class JourneyVerifyResumeRefusedError extends Error {
+    readonly reason: ResumeRefusalReason;
+    readonly code = "E_JOURNEY_VERIFY_RESUME_REFUSED";
+    constructor(reason: ResumeRefusalReason, detail: string);
+}
+/** What a proof's checkpoint is bound to, from the command that runs it. Everything but `build` is only ever digested. */
+export interface ProofCheckpointRequest {
+    readonly path: string;
+    readonly keyFile: string;
+    readonly resume: boolean;
+    readonly build: CheckpointBody["build"];
+    readonly config: {
+        readonly hook: unknown;
+        readonly origin: unknown;
+        readonly browser: unknown;
+    };
+    /** A short, value-free line for the operator: why this run keeps no progress, or what it replaced or reused. */
+    readonly onNotice?: (text: string) => void;
+}
+/** What the hooks' results can depend on that this process can see: their text and limits, and the fixture files' bytes. A script a hook runs is not read. */
+export declare function hookBindingOf(flags: {
+    readonly fixtures?: string;
+    readonly before?: string;
+    readonly after?: string;
+    readonly allowShellHooks?: boolean;
+    readonly hookTimeoutMs?: string;
+    readonly fixtureIdentity?: readonly string[];
+}, environmentFixtures: string | undefined): unknown;
+/** The browser's settings and the session a replay starts from: the file's bytes too, since the same path can hold another login. */
+export declare function browserBindingOf(browser: unknown, emulation: unknown, storageState: string | undefined, secretFields: readonly string[] | undefined): unknown;
+/** `<project or home>/logs/verify-progress/<id>.<store>.json`. The store's digest keeps two stores' same-named Journeys apart. */
+export declare function verifyCheckpointPath(dataRoot: string, journeysDir: string, id: string): string;
+/** `~/.jevitate/verify-checkpoint.key`: outside every project, so no repo or artifact can carry it. */
+export declare function checkpointKeyPath(): string;
+/** A deterministic text for a value: object keys sorted, `undefined` dropped, as JSON has it. */
+export declare function canonicalJson(value: unknown): string;
+/** The plan's ids and shape. It holds names and never a value, so it is a plain hash: a reader with no key can compare it. */
+export declare function mutationPlanDigest(plan: MutationPlan): string;
+export type VerifierState = "live" | "exited" | "stale";
+/** This process, by pid and the kernel's start time for it: a reused pid has another start time. */
+export declare function currentVerifierIdentity(): CheckpointBody["verifier"];
+/**
+ * live: the recorded process runs, with the recorded start token, and its proof has not ended. exited:
+ * the proof ended, or the process is gone. stale: a process runs under that pid with another start token
+ * (the pid was reused), or the record is from another host, where this one cannot check it.
+ * Where the platform gives no start time (token "0"), a running pid counts as live: age ends that.
+ */
+export declare function verifierStateOf(body: Pick<CheckpointBody, "state" | "verifier">, startOf?: (pid: number) => string | undefined): VerifierState;
+/** True when a live verifier is still writing this receipt: `logs prune` leaves it, however old. */
+export declare function isLiveVerifyReceipt(path: string): boolean;
+/**
+ * The one isolation note a resume can answer: it says the independence replay gave no reading, not that
+ * state crossed. A resume never reuses that replay's answer and runs it against the base it re-measures,
+ * so dropping the note leaves that fresh run to decide; if it errors too, the note comes back.
+ */
+export declare const isRepairableIsolation: (taint: CheckpointBody["taint"]) => boolean;
+export interface ResumeState {
+    readonly pairs: ReadonlyMap<string, CheckpointPair>;
+    readonly restoreFailed: boolean;
+    readonly notIsolatedBy: string | null;
+    /** Why a replay may have decided another. Absent or null with `notIsolatedBy` set: a replay closed with a write open. */
+    readonly isolation?: IsolationNote | null;
+}
+/** One proof's writer. A failed write never ends a proof: the next one writes everything again. */
+export declare class ProofCheckpointSession {
+    #private;
+    readonly path: string;
+    readonly key: Buffer;
+    readonly onNotice: (text: string) => void;
+    constructor(path: string, key: Buffer, body: CheckpointBody, onNotice: (text: string) => void);
+    get body(): CheckpointBody;
+    replayStarted(replay: number): void;
+    independence(independence: NonNullable<CheckpointBody["independence"]>): void;
+    phase(phase: CheckpointBody["phase"]): void;
+    startPair(id: string): void;
+    /** A pair run again after it errored takes its own place, so `completed` stays in the plan's order. */
+    finishPair(pair: CheckpointPair): void;
+    /**
+     * Written the moment it happens: a taint that dies with the process could turn a resumed proof `proven`.
+     * So if it cannot be written (a full disk), the older file without it must not stay resumable. A later
+     * write that succeeds carries the taint, since each write holds the whole body.
+     */
+    taint(change: Partial<CheckpointBody["taint"]>): void;
+    finish(verdict: MutationProofVerdict, errorGap: boolean): void;
+    /** The proof ended with no verdict, in a process that may go on (an MCP server), so its pid no longer says anything. */
+    interrupted(): void;
+}
+export interface OpenedCheckpoint {
+    readonly session?: ProofCheckpointSession;
+    readonly resume?: ResumeState;
+}
+/**
+ * Claims the checkpoint for this run, before any browser. A resume returns the results it may reuse or
+ * refuses by name. A fresh run replaces an ended checkpoint and leaves a live verifier's alone, going
+ * on without progress of its own, since a proof that ran before this file existed must still run.
+ */
+export declare function openProofCheckpoint(req: ProofCheckpointRequest, proof: {
+    readonly journey: Journey;
+    readonly journeyHash: string;
+    readonly plan: MutationPlan;
+    readonly params: Readonly<Record<string, string>>;
+    readonly sites: readonly JourneyAssertionSite[];
+}): Promise<OpenedCheckpoint>;
+/** A finished pair's result as `journey-verify` reports it, field by field: anything not named here cannot reach the file. */
+export interface FinishedPair {
+    readonly id: string;
+    readonly kind: JourneyMutation["kind"];
+    readonly step: number;
+    readonly param?: string;
+    readonly source?: JourneyMutation["source"];
+    readonly outcome: MutationRunResult["outcome"];
+    readonly failedSites: readonly MutationFailedSite[];
+    readonly waitsCut?: readonly string[];
+    readonly relaxed?: {
+        readonly outcome: MutationRunResult["outcome"];
+        readonly failedSites: readonly MutationFailedSite[];
+        readonly waitsCut?: readonly string[];
+        readonly atBaseTime?: MutationRunResult["atBaseTime"];
+    };
+    readonly control?: MutationRunResult["outcome"];
+    readonly controlSkipped?: true;
+    readonly atBaseTime?: MutationRunResult["atBaseTime"];
+    readonly targeted?: readonly TargetedProof[];
+    readonly retries?: readonly unknown[];
+}
+export declare function checkpointPairOf(pair: FinishedPair, replays: readonly CheckpointReplay[]): CheckpointPair;
+/** One replay in the file's form, by kind. Named fields only, so a `reason` on the run cannot reach the file. */
+export declare function checkpointReplayOf(kind: string, run: {
+    readonly outcome: MutationRunResult["outcome"];
+    readonly failedSites: readonly MutationFailedSite[];
+    readonly reachedMs?: readonly (number | undefined)[];
+    readonly endStateReachedMs?: number;
+}, writesInFlightAtClose: number): CheckpointReplay;
+/** The result `classifyMutation` and `mutationProofVerdict` read, as the uninterrupted proof gave them. */
+export declare function reusedProofFields(pair: CheckpointPair): Pick<MutationRunResult, "outcome" | "failedSites"> & Partial<Pick<MutationRunResult, "waitsCut" | "relaxed" | "targeted" | "control" | "atBaseTime">>;
+/**
+ * The reused results against a base measured just now. A reused replay was paced to the base of its own
+ * run. Under the rule (`evidenceRefusal`) its failure is evidence only if it got there no sooner than an
+ * unmutated replay passes that site, and the replay that says so now is the re-measured one. So each
+ * reused failure is read again against the new pace, by the same functions the proof uses: reached
+ * sooner than the new base, or newly thin with no control that answered for it, refuses the whole resume.
+ * A failed replay already cut needs nothing: it counts for nothing either way. A faster base only
+ * leaves a reused replay more room. Every record goes through the same loop whatever its kind, controls
+ * included. Writes left open are compared as the proof compares them.
+ */
+export declare function resumeRefusalAgainstBase(state: ResumeState, plan: MutationPlan, sites: readonly JourneyAssertionSite[], pace: ReplayPace, baseWritesInFlightAtClose: number): JourneyVerifyResumeRefusedError | undefined;
+export interface VerifyProgressStatus {
+    readonly journeyId: string;
+    readonly path: string;
+    /** valid: the keyed check passed. unverified: readable, but this user has no key to check it with. */
+    readonly receipt: "none" | "valid" | "unverified" | "corrupt" | "integrity-failed" | "not-regular-file";
+    readonly detail?: string;
+    readonly verifier: VerifierState | "none";
+    readonly resume: {
+        readonly possible: boolean;
+        readonly refusal?: ResumeRefusalReason;
+    };
+    readonly progress?: {
+        readonly state: CheckpointBody["state"];
+        readonly verdict?: MutationProofVerdict;
+        readonly phase: CheckpointBody["phase"];
+        /** Pairs finished that a resume keeps. */
+        readonly completed: number;
+        /** Pairs that ran but that a resume would run again: errored, or short of a control. Zero once a proof takes no resume. */
+        readonly toRunAgain: number;
+        readonly total: number;
+        readonly currentPair: string | null;
+        readonly replay: number;
+        readonly reusedPairs: number;
+        readonly journeyHash: string;
+        readonly planDigest: string;
+        readonly startedAt: string;
+        readonly updatedAt: string;
+        readonly lastResultClass: MutationRunResult["outcome"] | null;
+        readonly completedPairs: readonly {
+            readonly id: string;
+            readonly resultClass: MutationRunResult["outcome"];
+            readonly finishedAt: string;
+        }[];
+        readonly verifierPid: number;
+        readonly verifierStartToken: string;
+        readonly build: CheckpointBody["build"];
+        readonly taint: {
+            readonly restoreFailed: boolean;
+            readonly notIsolated: boolean;
+        };
+    };
+}
+/**
+ * `journey verify <id> --status`: reads the file and asks the OS about one pid. No browser, no hook, no
+ * Journey and nothing of the app's. A key is read when there is one and never created. `resume` answers
+ * what can be answered without the run's flags, so `possible: true` still leaves the config checks.
+ */
+export declare function readVerifyProgress(path: string, keyFile: string, journeyId: string): VerifyProgressStatus;
+/** One human line for `--status`. */
+export declare function verifyProgressLine(s: VerifyProgressStatus): string;
+export {};