toolroll 0.9.41 → 0.9.43

package/dist/contracts/update-journal.d.ts

@@ -0,0 +1,254 @@
+/**
+ * The update journals and their small control records (docs/plans/zod-revamp.md, item 19): the desktop app's update
+ * (`desktop-update.json` and the retained `receipt.json`) and `toolroll update`'s (`toolroll-update.json`,
+ * `.last.json` and the stage's `update.json`), plus the request, stop, cancel and starting marks beside them.
+ *
+ * Every journal is Toolroll's own and carries `version: 1`, but the reader ignores keys it does not know: a rollback
+ * runs an older Toolroll against a journal a newer one wrote, and every field added since 0.8.0 was added under the
+ * same version. A newer version is refused plainly. Readers return the saved object itself once it parses, so a
+ * journal saved again keeps its keys, their order and anything a newer release added. Paths, ownership, identities
+ * and hashes are checked in plain code by the update modules after parsing, with their existing words.
+ */
+import { z } from "zod";
+import { type ContractIssue } from "./contract.js";
+/** What a reader made of a saved journal: the saved object itself, or path-named issues. */
+export type JournalRead<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    issues: ContractIssue[];
+};
+export declare const DESKTOP_UPDATE_PHASES: readonly ["prepared", "draining", "backing-up", "stopping", "installing", "verifying", "rolling-back", "releasing", "complete", "restored", "cancelled", "needs-attention"];
+/** An app bundle as the journal records it (`readDesktopBundle`'s identity). */
+export declare const desktopBundleSchema: z.ZodObject<{
+    path: z.ZodString;
+    hash: z.ZodString;
+    buildId: z.ZodString;
+    version: z.ZodString;
+    bundleId: z.ZodString;
+    schemaVersion: z.ZodNumber;
+    development: z.ZodCatch<z.ZodBoolean>;
+    providerBin: z.ZodString;
+    recoveryProtocol: z.ZodExactOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** The keys in the order the old reader checked them, so the first issue picks the same refusal it gave. */
+export declare const desktopUpdateJournalSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    id: z.ZodString;
+    stateDir: z.ZodString;
+    workDir: z.ZodString;
+    label: z.ZodString;
+    intended: z.ZodEnum<{
+        install: "install";
+        restore: "restore";
+    }>;
+    phase: z.ZodEnum<{
+        "backing-up": "backing-up";
+        cancelled: "cancelled";
+        complete: "complete";
+        draining: "draining";
+        installing: "installing";
+        "needs-attention": "needs-attention";
+        prepared: "prepared";
+        releasing: "releasing";
+        restored: "restored";
+        "rolling-back": "rolling-back";
+        stopping: "stopping";
+        verifying: "verifying";
+    }>;
+    old: z.ZodObject<{
+        path: z.ZodString;
+        hash: z.ZodString;
+        buildId: z.ZodString;
+        version: z.ZodString;
+        bundleId: z.ZodString;
+        schemaVersion: z.ZodNumber;
+        development: z.ZodCatch<z.ZodBoolean>;
+        providerBin: z.ZodString;
+        recoveryProtocol: z.ZodExactOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    next: z.ZodObject<{
+        path: z.ZodString;
+        hash: z.ZodString;
+        buildId: z.ZodString;
+        version: z.ZodString;
+        bundleId: z.ZodString;
+        schemaVersion: z.ZodNumber;
+        development: z.ZodCatch<z.ZodBoolean>;
+        providerBin: z.ZodString;
+        recoveryProtocol: z.ZodExactOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    databaseFile: z.ZodString;
+    configHash: z.ZodString;
+    wasRunning: z.ZodBoolean;
+    backupHash: z.ZodExactOptional<z.ZodString>;
+    backupPath: z.ZodExactOptional<z.ZodString>;
+    replacementOccurred: z.ZodExactOptional<z.ZodBoolean>;
+    codingCatalogExpected: z.ZodExactOptional<z.ZodBoolean>;
+    stoppedPids: z.ZodExactOptional<z.ZodArray<z.ZodNumber>>;
+    codingBackupPath: z.ZodExactOptional<z.ZodString>;
+    codingBackupHash: z.ZodExactOptional<z.ZodString>;
+    startedAt: z.ZodString;
+    updatedAt: z.ZodString;
+    detail: z.ZodCatch<z.ZodString>;
+    error: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    checkedAt: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    serviceInterrupted: z.ZodExactOptional<z.ZodBoolean>;
+    retryableRecovery: z.ZodExactOptional<z.ZodBoolean>;
+    waiting: z.ZodExactOptional<z.ZodObject<{
+        run: z.ZodNumber;
+        on: z.ZodString;
+        action: z.ZodNullable<z.ZodString>;
+        since: z.ZodString;
+    }, z.core.$strip>>;
+    codingOwnerReleased: z.ZodExactOptional<z.ZodObject<{
+        pid: z.ZodNumber;
+        nativePid: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type DesktopUpdateJournal = z.infer<typeof desktopUpdateJournalSchema>;
+export type DesktopUpdatePhase = DesktopUpdateJournal["phase"];
+export declare function readDesktopUpdateJournal(input: unknown): JournalRead<DesktopUpdateJournal>;
+/** The automatic-recovery guardian's record (`recovery.json`) as Update status reads it: each field is used only when
+ * it has its type, as before; the guardian itself owns the full record. */
+export declare const desktopRecoveryViewSchema: z.ZodObject<{
+    id: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    state: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    detail: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    attempts: z.ZodCatch<z.ZodOptional<z.ZodNumber>>;
+    repairs: z.ZodCatch<z.ZodOptional<z.ZodNumber>>;
+    updatedAt: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+}, z.core.$strip>;
+export type DesktopRecoveryView = z.infer<typeof desktopRecoveryViewSchema>;
+/** Update status's view of `recovery.json`; anything that is not an object reads as no guardian, as before. */
+export declare function readDesktopRecoveryView(input: unknown): DesktopRecoveryView | null;
+/** `request.json` (a restore) and `stop-request.json`, as `requestUpdateRestore` and `requestUpdateStop` write them. */
+export declare const updateRequestSchema: z.ZodObject<{
+    id: z.ZodExactOptional<z.ZodUnknown>;
+    action: z.ZodExactOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+/** Whether a saved request is `{ id, action }` for this update; anything else is not that request. */
+export declare function updateRequestIs(input: unknown, id: string, action: string): boolean;
+/** The service supervisor's status file, read for the service's process ids before a stop. */
+export declare const supervisorPidsSchema: z.ZodObject<{
+    supervisorPid: z.ZodExactOptional<z.ZodUnknown>;
+    controllerPid: z.ZodExactOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+export declare function supervisorPidsOf(input: unknown): number[];
+export declare const RUNTIME_UPDATE_STEPS: readonly ["verifying", "draining", "backing-up", "rehearsing", "switching", "restarting", "health"];
+export declare const RUNTIME_PHASES: readonly ["scheduled", "verifying", "draining", "backing-up", "rehearsing", "switching", "restarting", "health", "complete", "rolling-back", "restored", "refused", "cancelled", "needs-attention"];
+export declare const runtimeUpdateJournalSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    id: z.ZodString;
+    stateDir: z.ZodString;
+    stageDir: z.ZodString;
+    kind: z.ZodString;
+    databaseFile: z.ZodString;
+    from: z.ZodObject<{
+        version: z.ZodString;
+        dist: z.ZodString;
+    }, z.core.$strip>;
+    to: z.ZodObject<{
+        version: z.ZodString;
+        dist: z.ZodString;
+    }, z.core.$strip>;
+    when: z.ZodString;
+    at: z.ZodNullable<z.ZodString>;
+    actor: z.ZodCatch<z.ZodString>;
+    phase: z.ZodString;
+    detail: z.ZodCatch<z.ZodString>;
+    error: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    steps: z.ZodArray<z.ZodObject<{
+        phase: z.ZodString;
+        at: z.ZodString;
+    }, z.core.$strip>>;
+    startedAt: z.ZodString;
+    updatedAt: z.ZodString;
+    finishedAt: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    package: z.ZodExactOptional<z.ZodObject<{
+        sha512: z.ZodString;
+        repository: z.ZodString;
+        workflow: z.ZodString;
+    }, z.core.$strip>>;
+    notes: z.ZodCatch<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    backupPath: z.ZodExactOptional<z.ZodString>;
+    backupHash: z.ZodExactOptional<z.ZodString>;
+    codingBackupPath: z.ZodExactOptional<z.ZodString>;
+    codingBackupHash: z.ZodExactOptional<z.ZodString>;
+    restoreFrom: z.ZodExactOptional<z.ZodObject<{
+        path: z.ZodString;
+        hash: z.ZodString;
+        updateId: z.ZodString;
+        codingPath: z.ZodExactOptional<z.ZodString>;
+        codingHash: z.ZodExactOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    rehearsal: z.ZodExactOptional<z.ZodObject<{
+        tables: z.ZodNumber;
+        rows: z.ZodNumber;
+    }, z.core.$strip>>;
+    service: z.ZodExactOptional<z.ZodObject<{
+        unit: z.ZodString;
+        pids: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strip>>;
+    watches: z.ZodExactOptional<z.ZodArray<z.ZodObject<{
+        unit: z.ZodString;
+        pids: z.ZodArray<z.ZodNumber>;
+        loaded: z.ZodExactOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+    switched: z.ZodExactOptional<z.ZodObject<{
+        links: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            previous: z.ZodString;
+        }, z.core.$strip>>;
+        unit: z.ZodNullable<z.ZodObject<{
+            path: z.ZodString;
+            saved: z.ZodString;
+        }, z.core.$strip>>;
+        watches: z.ZodExactOptional<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            saved: z.ZodString;
+        }, z.core.$strip>>>;
+        databaseRestored: z.ZodExactOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    keptAside: z.ZodExactOptional<z.ZodString>;
+    keptAsideUnreadable: z.ZodExactOptional<z.ZodBoolean>;
+    kept: z.ZodExactOptional<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        unreadable: z.ZodBoolean;
+    }, z.core.$strip>>>;
+    restoredDatabase: z.ZodExactOptional<z.ZodBoolean>;
+    codingOwnerReleased: z.ZodExactOptional<z.ZodObject<{
+        pid: z.ZodNumber;
+        nativePid: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+    seen: z.ZodCatch<z.ZodOptional<z.ZodBoolean>>;
+    waiting: z.ZodExactOptional<z.ZodObject<{
+        run: z.ZodNumber;
+        on: z.ZodString;
+        action: z.ZodNullable<z.ZodString>;
+        since: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type RuntimeUpdateJournalRecord = z.infer<typeof runtimeUpdateJournalSchema>;
+export declare function readRuntimeUpdateJournal(input: unknown): JournalRead<RuntimeUpdateJournalRecord>;
+/** `updater-starting.json`: a launched or resuming updater on its way to `id`. Only `id` and `at` are read. */
+export declare const updaterStartingSchema: z.ZodObject<{
+    id: z.ZodExactOptional<z.ZodUnknown>;
+    state: z.ZodExactOptional<z.ZodUnknown>;
+    at: z.ZodExactOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+/** The mark's update id and start time when it has them; a mark without them is no updater starting, as before. */
+export declare function updaterStartingOf(input: unknown): {
+    id: unknown;
+    at: number;
+} | null;
+/** A staged release's `update.json` as pruning reads it: only `startedAt`, from a partial or older file alike. */
+export declare const stagedReleaseStartSchema: z.ZodObject<{
+    startedAt: z.ZodExactOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+/**
+ * When a staged release started, for pruning: `startedAt` as text (`""` when absent or when the file holds some other
+ * JSON value). `null` for JSON `null`, and the folder's mtime stands in, as it does for a file that is not JSON.
+ */
+export declare function stagedStartedAt(input: unknown): string | null;

package/dist/contracts/update-journal.js

@@ -0,0 +1,155 @@
+/**
+ * The update journals and their small control records (docs/plans/zod-revamp.md, item 19): the desktop app's update
+ * (`desktop-update.json` and the retained `receipt.json`) and `toolroll update`'s (`toolroll-update.json`,
+ * `.last.json` and the stage's `update.json`), plus the request, stop, cancel and starting marks beside them.
+ *
+ * Every journal is Toolroll's own and carries `version: 1`, but the reader ignores keys it does not know: a rollback
+ * runs an older Toolroll against a journal a newer one wrote, and every field added since 0.8.0 was added under the
+ * same version. A newer version is refused plainly. Readers return the saved object itself once it parses, so a
+ * journal saved again keeps its keys, their order and anything a newer release added. Paths, ownership, identities
+ * and hashes are checked in plain code by the update modules after parsing, with their existing words.
+ */
+import { z } from "zod";
+import { readVersioned } from "./contract.js";
+function journalOf(schema, input) {
+    const read = readVersioned(schema, input);
+    // Catch values only let legacy-unchecked information pass validation; never apply them to the saved object.
+    // Keep its original values, key order and keys a newer release added.
+    return read.ok ? { ok: true, value: input } : read;
+}
+/** A finished run an update waits on (or stopped waiting on). */
+const waitingSchema = z.object({ run: z.number(), on: z.string(), action: z.string().nullable(), since: z.string() });
+const releasedCodingOwnerSchema = z.object({ pid: z.number(), nativePid: z.number().nullable() });
+// ---- the desktop app's update ------------------------------------------------------------------------------------
+export const DESKTOP_UPDATE_PHASES = ["prepared", "draining", "backing-up", "stopping", "installing", "verifying", "rolling-back", "releasing", "complete", "restored", "cancelled", "needs-attention"];
+/** An app bundle as the journal records it (`readDesktopBundle`'s identity). */
+export const desktopBundleSchema = z.object({
+    path: z.string(), hash: z.string(), buildId: z.string(), version: z.string(), bundleId: z.string(),
+    schemaVersion: z.number(), development: z.boolean().catch(false), providerBin: z.string(), recoveryProtocol: z.number().exactOptional(),
+});
+/** The keys in the order the old reader checked them, so the first issue picks the same refusal it gave. */
+export const desktopUpdateJournalSchema = z.object({
+    version: z.literal(1),
+    id: z.string(), stateDir: z.string(), workDir: z.string(), label: z.string(),
+    intended: z.enum(["install", "restore"]), phase: z.enum(DESKTOP_UPDATE_PHASES),
+    old: desktopBundleSchema, next: desktopBundleSchema,
+    databaseFile: z.string(), configHash: z.string(), wasRunning: z.boolean(),
+    backupHash: z.string().exactOptional(), backupPath: z.string().exactOptional(),
+    replacementOccurred: z.boolean().exactOptional(),
+    codingCatalogExpected: z.boolean().exactOptional(),
+    stoppedPids: z.array(z.number()).exactOptional(),
+    codingBackupPath: z.string().exactOptional(), codingBackupHash: z.string().exactOptional(),
+    startedAt: z.string(), updatedAt: z.string(), detail: z.string().catch(""),
+    error: z.string().optional().catch(undefined), checkedAt: z.string().optional().catch(undefined),
+    serviceInterrupted: z.boolean().exactOptional(),
+    retryableRecovery: z.boolean().exactOptional(),
+    /** The finished run the update is waiting on (or stopped waiting on). Absent while it waits on ordinary work. */
+    waiting: waitingSchema.exactOptional(),
+    /** A stale coding owner record this update released after proving those processes gone. */
+    codingOwnerReleased: releasedCodingOwnerSchema.exactOptional(),
+});
+export function readDesktopUpdateJournal(input) {
+    return journalOf(desktopUpdateJournalSchema, input);
+}
+/** The automatic-recovery guardian's record (`recovery.json`) as Update status reads it: each field is used only when
+ * it has its type, as before; the guardian itself owns the full record. */
+export const desktopRecoveryViewSchema = z.object({
+    id: z.string().optional().catch(undefined), state: z.string().optional().catch(undefined), detail: z.string().optional().catch(undefined),
+    attempts: z.number().optional().catch(undefined), repairs: z.number().optional().catch(undefined), updatedAt: z.string().optional().catch(undefined),
+});
+/** Update status's view of `recovery.json`; anything that is not an object reads as no guardian, as before. */
+export function readDesktopRecoveryView(input) {
+    const read = desktopRecoveryViewSchema.safeParse(input);
+    return read.success ? read.data : null;
+}
+/** `request.json` (a restore) and `stop-request.json`, as `requestUpdateRestore` and `requestUpdateStop` write them. */
+export const updateRequestSchema = z.object({ id: z.unknown().exactOptional(), action: z.unknown().exactOptional() });
+/** Whether a saved request is `{ id, action }` for this update; anything else is not that request. */
+export function updateRequestIs(input, id, action) {
+    const read = updateRequestSchema.safeParse(input);
+    return read.success && read.data.id === id && read.data.action === action;
+}
+/** The service supervisor's status file, read for the service's process ids before a stop. */
+export const supervisorPidsSchema = z.object({ supervisorPid: z.unknown().exactOptional(), controllerPid: z.unknown().exactOptional() });
+export function supervisorPidsOf(input) {
+    const read = supervisorPidsSchema.safeParse(input);
+    if (!read.success)
+        return [];
+    return [read.data.supervisorPid, read.data.controllerPid].filter((pid) => Number.isSafeInteger(pid) && Number(pid) > 1);
+}
+// ---- toolroll update ---------------------------------------------------------------------------------------------
+export const RUNTIME_UPDATE_STEPS = ["verifying", "draining", "backing-up", "rehearsing", "switching", "restarting", "health"];
+export const RUNTIME_PHASES = ["scheduled", ...RUNTIME_UPDATE_STEPS, "complete", "rolling-back", "restored", "refused", "cancelled", "needs-attention"];
+const runtimeRefSchema = z.object({ version: z.string(), dist: z.string() });
+const unitSchema = z.object({ unit: z.string(), pids: z.array(z.number()) });
+const savedFileSchema = z.object({ path: z.string(), saved: z.string() });
+export const runtimeUpdateJournalSchema = z.object({
+    version: z.literal(1),
+    id: z.string(), stateDir: z.string(), stageDir: z.string(),
+    kind: z.string(),
+    databaseFile: z.string(),
+    from: runtimeRefSchema, to: runtimeRefSchema,
+    when: z.string(), at: z.string().nullable(), actor: z.string().catch(""),
+    phase: z.string(), detail: z.string().catch(""), error: z.string().optional().catch(undefined),
+    steps: z.array(z.object({ phase: z.string(), at: z.string() })),
+    startedAt: z.string(), updatedAt: z.string(), finishedAt: z.string().optional().catch(undefined),
+    package: z.object({ sha512: z.string(), repository: z.string(), workflow: z.string() }).exactOptional(),
+    notes: z.array(z.string()).optional().catch(undefined),
+    /** This run's own verified copies of the live database and coding catalog: what a failure restores. */
+    backupPath: z.string().exactOptional(), backupHash: z.string().exactOptional(),
+    codingBackupPath: z.string().exactOptional(), codingBackupHash: z.string().exactOptional(),
+    /** A rollback installs the update's earlier backups (checked against their recorded hashes). */
+    restoreFrom: z.object({ path: z.string(), hash: z.string(), updateId: z.string(), codingPath: z.string().exactOptional(), codingHash: z.string().exactOptional() }).exactOptional(),
+    rehearsal: z.object({ tables: z.number(), rows: z.number() }).exactOptional(),
+    /** The background service, recorded before it is stopped: its definition and the processes that must be gone. */
+    service: unitSchema.exactOptional(),
+    /** Each repo's watch daemon that runs this version, recorded the same way: switched with the service, and stopped and
+     * restarted with it only when launchd had it loaded before the update (`loaded` absent: 0.8.1 stopped every one). */
+    watches: z.array(unitSchema.extend({ loaded: z.boolean().exactOptional() })).exactOptional(),
+    /** Recorded before each change so a resumed or failed run knows what to put back. */
+    switched: z.object({
+        links: z.array(z.object({ path: z.string(), previous: z.string() })),
+        unit: savedFileSchema.nullable(),
+        watches: z.array(savedFileSchema).exactOptional(),
+        databaseRestored: z.boolean().exactOptional(),
+    }).exactOptional(),
+    /** What the live database held when a failed run restored its backup: nothing written is lost. The newest of `kept`. */
+    keptAside: z.string().exactOptional(),
+    /** The live database could not be read, so it was moved aside whole rather than copied. */
+    keptAsideUnreadable: z.boolean().exactOptional(),
+    /** Every copy kept aside, oldest first: a retried restore adds one and never drops the pointer to an earlier one. */
+    kept: z.array(z.object({ path: z.string(), unreadable: z.boolean() })).exactOptional(),
+    /** The restore put the backup back: a retried restore never puts it back again (what was written since belongs to
+     * the restored version and would be lost), and it keeps a fresh copy aside before every attempt until then. */
+    restoredDatabase: z.boolean().exactOptional(),
+    /** A stale coding owner record this run released after proving its processes gone. */
+    codingOwnerReleased: releasedCodingOwnerSchema.exactOptional(),
+    seen: z.boolean().optional().catch(undefined),
+    /** The finished run the update is waiting on (or stopped waiting on): what is in the way and the command that
+     * clears it. Absent while it waits on ordinary running work. */
+    waiting: waitingSchema.exactOptional(),
+});
+export function readRuntimeUpdateJournal(input) {
+    return journalOf(runtimeUpdateJournalSchema, input);
+}
+/** `updater-starting.json`: a launched or resuming updater on its way to `id`. Only `id` and `at` are read. */
+export const updaterStartingSchema = z.object({ id: z.unknown().exactOptional(), state: z.unknown().exactOptional(), at: z.unknown().exactOptional() });
+/** The mark's update id and start time when it has them; a mark without them is no updater starting, as before. */
+export function updaterStartingOf(input) {
+    const read = updaterStartingSchema.safeParse(input);
+    if (!read.success)
+        return null;
+    return { id: read.data.id, at: Date.parse(typeof read.data.at === "string" ? read.data.at : String(read.data.at ?? "")) };
+}
+/** A staged release's `update.json` as pruning reads it: only `startedAt`, from a partial or older file alike. */
+export const stagedReleaseStartSchema = z.object({ startedAt: z.unknown().exactOptional() });
+/**
+ * When a staged release started, for pruning: `startedAt` as text (`""` when absent or when the file holds some other
+ * JSON value). `null` for JSON `null`, and the folder's mtime stands in, as it does for a file that is not JSON.
+ */
+export function stagedStartedAt(input) {
+    const read = stagedReleaseStartSchema.safeParse(input);
+    if (read.success)
+        return String(read.data.startedAt ?? "");
+    return input === null || input === undefined ? null : "";
+}

package/dist/contracts/verification-view.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The gate view `verificationEvidence` returns as `bytes`: a sealed receipt exactly as sealed (either version), or,
+ * for a run from before receipts, the view of its legacy machine log header. Reused gates, failed-check repair and
+ * saved assessments read a view back through `readVerificationView`.
+ *
+ * A legacy view is built by Toolroll from the run's single-attempt log header (the "check log metadata"), its
+ * approved command and its candidate inventory; it is never saved, so its schema is strict. A sealed receipt is read
+ * by the receipt's own contract.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+import { type VerificationReceipt } from "./verification-receipt.js";
+export declare const LEGACY_GATE_SOURCE = "legacy machine log header";
+export declare const legacyGateViewSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    source: z.ZodLiteral<"legacy machine log header">;
+    run: z.ZodInt;
+    head: z.ZodString;
+    base: z.ZodNullable<z.ZodString>;
+    scopeDigest: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    command: z.ZodObject<{
+        id: z.ZodInt;
+        repo: z.ZodString;
+        command: z.ZodString;
+        timeoutMs: z.ZodInt;
+        digest: z.ZodString;
+        recoverySetupDigest: z.ZodNullable<z.ZodString>;
+        approvedBy: z.ZodString;
+        approvedAt: z.ZodString;
+        revokedAt: z.ZodNullable<z.ZodString>;
+        revokedBy: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    result: z.ZodUnion<readonly [z.ZodObject<{
+        configured: z.ZodLiteral<false>;
+    }, z.core.$strict>, z.ZodObject<{
+        configured: z.ZodLiteral<true>;
+        ran: z.ZodLiteral<false>;
+        attemptFailed: z.ZodLiteral<true>;
+        failure: z.ZodOptional<z.ZodEnum<{
+            "checkout-moved": "checkout-moved";
+            "cleanliness-unavailable": "cleanliness-unavailable";
+            "custody-lost": "custody-lost";
+            "dependency-missing": "dependency-missing";
+            "dependency-still-missing": "dependency-still-missing";
+            "own-install-failed": "own-install-failed";
+            "retry-spawn-failed": "retry-spawn-failed";
+            "retry-timed-out": "retry-timed-out";
+            "setup-changed-files": "setup-changed-files";
+            "setup-failed": "setup-failed";
+            "setup-stale": "setup-stale";
+            "spawn-failed": "spawn-failed";
+            "timed-out": "timed-out";
+            "tracked-files-changed": "tracked-files-changed";
+        }>>;
+    }, z.core.$strict>, z.ZodObject<{
+        configured: z.ZodLiteral<true>;
+        ran: z.ZodLiteral<true>;
+        exitCode: z.ZodInt;
+        setupReplayed: z.ZodOptional<z.ZodLiteral<true>>;
+    }, z.core.$strict>]>;
+    log: z.ZodObject<{
+        artifactId: z.ZodInt;
+        sha256: z.ZodString;
+        bytesStored: z.ZodInt;
+        bytesOriginal: z.ZodInt;
+        truncated: z.ZodBoolean;
+        redacted: z.ZodBoolean;
+        captureStatus: z.ZodNullable<z.ZodEnum<{
+            failed: "failed";
+            ok: "ok";
+        }>>;
+    }, z.core.$strict>;
+    candidate: z.ZodObject<{
+        artifactId: z.ZodInt;
+        sha256: z.ZodString;
+        bytesStored: z.ZodInt;
+        bytesOriginal: z.ZodInt;
+        truncated: z.ZodBoolean;
+        redacted: z.ZodBoolean;
+        captureStatus: z.ZodNullable<z.ZodEnum<{
+            failed: "failed";
+            ok: "ok";
+        }>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type LegacyGateView = z.infer<typeof legacyGateViewSchema>;
+/** What every view carries. */
+export type VerificationView = Pick<VerificationReceipt, "run" | "head" | "base" | "scopeDigest" | "command" | "result" | "log">;
+/**
+ * Read a view's bytes. The value is the object as written, once its shape is checked: its key order is part of what a
+ * reused gate compares and seals again.
+ */
+export declare function readVerificationView(bytes: string): ContractResult<VerificationView>;

package/dist/contracts/verification-view.js

@@ -0,0 +1,43 @@
+/**
+ * The gate view `verificationEvidence` returns as `bytes`: a sealed receipt exactly as sealed (either version), or,
+ * for a run from before receipts, the view of its legacy machine log header. Reused gates, failed-check repair and
+ * saved assessments read a view back through `readVerificationView`.
+ *
+ * A legacy view is built by Toolroll from the run's single-attempt log header (the "check log metadata"), its
+ * approved command and its candidate inventory; it is never saved, so its schema is strict. A sealed receipt is read
+ * by the receipt's own contract.
+ */
+import { z } from "zod";
+import { parseContract } from "./contract.js";
+import { readVerificationReceipt, receiptCommandSchema, receiptLogSchema, verifyCommandFactsSchema } from "./verification-receipt.js";
+export const LEGACY_GATE_SOURCE = "legacy machine log header";
+export const legacyGateViewSchema = z.strictObject({
+    version: z.literal(1),
+    source: z.literal(LEGACY_GATE_SOURCE),
+    run: z.int(),
+    head: z.string(),
+    base: z.string().nullable(),
+    /** Left out of the bytes when the run never recorded one. */
+    scopeDigest: z.string().nullable().optional(),
+    command: receiptCommandSchema,
+    result: verifyCommandFactsSchema,
+    log: receiptLogSchema,
+    /** The diff-stat artifact whose endpoints bound the candidate. */
+    candidate: receiptLogSchema,
+});
+/**
+ * Read a view's bytes. The value is the object as written, once its shape is checked: its key order is part of what a
+ * reused gate compares and seals again.
+ */
+export function readVerificationView(bytes) {
+    let input;
+    try {
+        input = JSON.parse(bytes);
+    }
+    catch {
+        return { ok: false, issues: [{ path: "payload", kind: "wrong-type", line: "payload: is not JSON" }] };
+    }
+    const legacy = typeof input === "object" && input !== null && input.source !== undefined;
+    const read = legacy ? parseContract(legacyGateViewSchema, input) : readVerificationReceipt(input);
+    return read.ok ? { ok: true, value: input } : read;
+}

package/dist/control-setup.d.ts

@@ -19,7 +19,7 @@ export declare function previewSetup(store: Store, repo: string, inputs: SetupIn
     fingerprint: string;
     command: string;
     seconds: number;
-    provider: import("./provider.js").ProviderId;
+    provider: "claude" | "codex" | "gemini" | "openrouter";
     model: string;
 };
 export declare function approveSetup(store: Store, repo: string, inputs: SetupInputs, fingerprint: string, by: string, token: string, now: Date): {

package/dist/desktop-update.d.ts

@@ -1,42 +1,9 @@
 import type { DatabaseSync } from "node:sqlite";
 import { type DesktopBundle } from "./desktop-bundle.js";
-import { type ReleasedCodingOwner } from "./coding-update.js";
-type Phase = "prepared" | "draining" | "backing-up" | "stopping" | "installing" | "verifying" | "rolling-back" | "releasing" | "complete" | "restored" | "cancelled" | "needs-attention";
-export type UpdateJournal = {
-    version: 1;
-    id: string;
-    stateDir: string;
-    workDir: string;
-    label: string;
-    databaseFile: string;
-    configHash: string;
-    old: DesktopBundle;
-    next: DesktopBundle;
-    phase: Phase;
-    intended: "install" | "restore";
-    startedAt: string;
-    updatedAt: string;
-    wasRunning: boolean;
-    backupHash?: string;
-    backupPath?: string;
-    codingBackupPath?: string;
-    codingBackupHash?: string;
-    codingCatalogExpected?: boolean;
-    detail: string;
-    error?: string;
-    checkedAt?: string;
-    serviceInterrupted?: boolean;
-    replacementOccurred?: boolean;
-    retryableRecovery?: boolean;
-    /** The finished run the update is waiting on (or stopped waiting on). Absent while it waits on ordinary work. */
-    waiting?: LingeringRun & {
-        since: string;
-    };
-    /** The service's supervisor and controller, recorded before it is stopped: the processes proved gone afterwards. */
-    stoppedPids?: number[];
-    /** A stale coding owner record this update released after proving those processes gone. */
-    codingOwnerReleased?: ReleasedCodingOwner;
-};
+import { type DesktopUpdateJournal, type DesktopUpdatePhase } from "./contracts/update-journal.js";
+type Phase = DesktopUpdatePhase;
+/** The update's journal (`desktop-update.json`, and `receipt.json` in its folder): src/contracts/update-journal.ts. */
+export type UpdateJournal = DesktopUpdateJournal;
 type ServiceState = {
     state: string;
     stale?: boolean;
@@ -125,25 +92,25 @@ export declare function prepareDesktopUpdate(stateDir: string, installed: string
 export declare function sqliteLock(file: string, busyTimeoutMs?: number): DatabaseSync | null;
 export declare const installationLock: (j: UpdateJournal) => DatabaseSync | null;
 export declare function desktopUpdateStatus(stateDir: string): {
-    version?: never;
+    error?: never;
     active: boolean;
     phase: string;
     detail: string;
     running: boolean;
     canResume: boolean;
     canCancel: boolean;
-    error?: never;
     automaticRecovery?: never;
     recoveryAttempts?: never;
     recoveryRepairs?: never;
     wasRunning?: never;
     backupPath?: never;
     updateId?: never;
+    version?: never;
     buildId?: never;
     workDir?: never;
 } | {
     active: boolean;
-    phase: Phase;
+    phase: "backing-up" | "cancelled" | "complete" | "draining" | "installing" | "needs-attention" | "prepared" | "releasing" | "restored" | "rolling-back" | "stopping" | "verifying";
     detail: string;
     error: string | null;
     running: boolean;