toolroll 0.9.71 → 0.9.72

package/dist/release-adapters.js

@@ -6,8 +6,8 @@
  */
 import { execFile, spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { existsSync, readdirSync, readFileSync, realpathSync } from "node:fs";
-import { homedir } from "node:os";
+import { existsSync, lstatSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
 import { basename, delimiter, dirname, join } from "node:path";
 import { createRequire } from "node:module";
 import { parse as parseYaml } from "yaml";
@@ -17,14 +17,26 @@ const sqlite = () => createRequire(import.meta.url)("node:sqlite");
 import { activeUpdateWork } from "./desktop-update-gate.js";
 import { BEFORE_SWAP, gateOwner } from "./release-gate.js";
 import { findCliLinks, switchCliLinks } from "./release-links.js";
-import { databasePath } from "./store.js";
+import { databasePath, finishReleaseOperation, requireFreshReleaseApproval, openStore, releaseAuthorityOfTask, releaseCarries, releaseOperations, renewReleaseLease, reserveRelease, runReleaseOperation, Store, releaseIssuerGone, takeReleaseLease, } from "./store.js";
+import { acquireDeploymentLock } from "./deploy-lock.js";
+import { liveReleaseOf } from "./scope.js";
+import { proveCarry } from "./release-carry.js";
+import { randomBytes, randomUUID } from "node:crypto";
+import { deploymentGate } from "./deploy-gate.js";
+import { extractCommit } from "./commit-extract.js";
 /** A child process, its output kept whole; a missing program or a time limit is exit 127 or 124, never a throw. */
 export const exec = (command, args, options = {}) => new Promise(done => {
-    execFile(command, [...args], { cwd: options.cwd, env: options.env ?? process.env, timeout: options.timeoutMs ?? 120_000, maxBuffer: 64 * 1024 * 1024, encoding: "utf8" }, (error, stdout, stderr) => {
+    const child = execFile(command, [...args], { cwd: options.cwd, env: options.env ?? process.env, timeout: options.timeoutMs ?? 120_000, maxBuffer: 64 * 1024 * 1024, encoding: "utf8" }, (error, stdout, stderr) => {
         const failure = error;
         const code = failure === null ? 0 : failure.code === "ENOENT" ? 127 : failure.killed === true ? 124 : typeof failure.code === "number" ? failure.code : 1;
         done({ code, stdout: String(stdout ?? ""), stderr: String(stderr ?? "") });
     });
+    // `input`: written on the child's stdin, then closed (a secret that must never ride in argv).
+    child.stdin?.on("error", () => { });
+    if (options.input !== undefined)
+        child.stdin?.end(options.input);
+    else
+        child.stdin?.end();
 });
 /** Without NODE_OPTIONS, which a test runner or debugger may have left for this process. */
 const cleanEnv = (extra = {}) => {
@@ -107,6 +119,7 @@ export function gateStateOf(answer, accounts = []) {
         approval: approvedAt === null || approvedBy === null || approvedDigest === null ? null : {
             by: approvedBy, at: approvedAt, digest: approvedDigest, basis: textOr(scope["approvalBasis"]),
             role: textOr(account?.["role"]), active: account?.["revokedAt"] === null,
+            ...personAnswerOf(answer["personApproval"]),
         },
         result: resultRun === null || textOr(result["digest"]) === null ? null : {
             run: resultRun, head: textOr(result["head"]), receipt: String(result["digest"]), worktree: textOr(worktree),
@@ -190,10 +203,92 @@ export function releaseAdapters(options) {
         const gate = stageGate(stage, liveOwner);
         return gate === null ? { ok: false, message } : { ok: false, message, gate };
     };
-    const deployScript = (worktree, stage, runId, extra) => run(process.execPath, ["scripts/deploy-browser.mjs", "--run", String(runId), "--stage", stage, ...extra], {
-        cwd: worktree, env: cleanEnv({ TMPDIR: resolved(process.env["TMPDIR"] ?? "/tmp") }), timeoutMs: (options.deployMinutes ?? 30) * 60_000,
-    });
+    /** The deployment gate in this runtime (deploy-gate.ts): a person's approval, the passing check, the exact completed
+     * result. Its answer names the approved commit and the project it belongs to, from the plane's own records. */
+    const proveCandidate = (runId) => {
+        if (!existsSync(database))
+            return { ok: false, message: "The plane's database isn't here, so the candidate can't be proven." };
+        const db = new (sqlite().DatabaseSync)(database, { readOnly: true });
+        try {
+            return deploymentGate(new Store(db), { runId, evidenceRoot: join(dirname(database), "evidence"), now: (options.now ?? (() => new Date()))() });
+        }
+        catch (error) {
+            return { ok: false, message: `The candidate can't be proven: ${error.message}` };
+        }
+        finally {
+            db.close();
+        }
+    };
+    /** The run's recorded commit and project, for recovery (which needs no approval). */
+    const recordedCommit = (runId) => {
+        if (!existsSync(database))
+            return null;
+        const db = new (sqlite().DatabaseSync)(database, { readOnly: true });
+        try {
+            const store = new Store(db), run = store.getRun(runId), repo = run === null ? null : store.refById(run.taskRef)?.repo ?? null;
+            return run?.headRevision != null && repo != null ? { head: run.headRevision, repo } : null;
+        }
+        catch {
+            return null;
+        }
+        finally {
+            db.close();
+        }
+    };
+    /**
+     * The approved commit, written by this runtime into a fresh folder it owns (commit-extract.ts): every regular file of
+     * that full SHA, read byte for byte from the PROJECT's own Git directory as Toolroll records it (realpath, a real
+     * directory — never the candidate worktree's `.git` pointer or anything in that worktree), with no filter, attribute,
+     * replacement object, lazy fetch, hook or outside config, and no symlink or submodule. The deployment script runs
+     * from here, so nothing changed, flagged, swapped or untracked in the worktree, nor its Git pointer, changes what runs.
+     */
+    const extractApproved = async (repo, head) => {
+        let gitDir;
+        try {
+            const named = join(realpathSync(repo), ".git");
+            if (!lstatSync(named).isDirectory())
+                return { ok: false, message: `${repo}'s Git directory isn't a plain directory, so the approved commit can't be read from it.` };
+            gitDir = realpathSync(named);
+        }
+        catch {
+            return { ok: false, message: `${repo} has no Git directory to read the approved commit from.` };
+        }
+        const dir = realpathSync(mkdtempSync(join(resolved(tmpdir()), "toolroll-deployer-")));
+        const extracted = extractCommit(gitDir, head, dir);
+        if (!extracted.ok) {
+            rmSync(dir, { recursive: true, force: true });
+            return { ok: false, message: `The approved commit couldn't be prepared: ${extracted.message}` };
+        }
+        return { ok: true, dir, gitDir };
+    };
+    /** The approved commit's own deployment script, from the pristine extraction; the worktree is only its --source. */
+    const deployScript = async (worktree, stage, runId, commit, extra, input) => {
+        const extracted = await extractApproved(commit.repo, commit.head);
+        if (!extracted.ok)
+            return { code: 1, stdout: "", stderr: extracted.message };
+        try {
+            // The script node runs is the extraction's own regular file, by its real path inside the folder.
+            let script;
+            try {
+                script = realpathSync(join(extracted.dir, "scripts", "deploy-browser.mjs"));
+                if (!script.startsWith(extracted.dir + "/") || !lstatSync(script).isFile())
+                    throw new Error("outside");
+            }
+            catch {
+                return { code: 1, stdout: "", stderr: "The approved commit has no deployment script of its own." };
+            }
+            return await run(process.execPath, [script, "--run", String(runId), "--stage", stage, "--source", worktree,
+                "--head", commit.head, "--git-dir", extracted.gitDir, ...extra], {
+                cwd: extracted.dir, env: cleanEnv({ TMPDIR: resolved(process.env["TMPDIR"] ?? "/tmp") }), timeoutMs: (options.deployMinutes ?? 30) * 60_000, ...(input === undefined ? {} : { input }),
+            });
+        }
+        finally {
+            rmSync(extracted.dir, { recursive: true, force: true });
+        }
+    };
+    const release = storeReleaseAdapter(() => openStore(database), store => store.close(), options.now ?? (() => new Date()));
     return {
+        ...(existsSync(database) ? { release } : {}),
         now: options.now ?? (() => new Date()),
         sleep: options.sleep ?? sleep,
         say: options.say ?? (line => process.stdout.write(`${line}\n`)),
@@ -278,7 +373,7 @@ export function releaseAdapters(options) {
                 const added = await toolroll("task", "add", input.title, "--id", input.taskId, "--repo", input.checkout, "--checks", "full");
                 if (added["ok"] !== true)
                     throw new Error(`task add: ${refused(added)}`);
-                const scoped = await toolroll("task", "scope", input.taskId, "--candidate", input.candidate, "--goal", input.goal, "--acceptance", input.acceptance);
+                const scoped = await toolroll("task", "scope", input.taskId, "--candidate", input.candidate, "--goal", input.goal, "--acceptance", input.acceptance, ...(input.release === undefined ? [] : ["--release", `${input.release.version}:${input.release.pr}:${input.release.branch}`, ...(input.release.noCarry ? ["--no-carry"] : [])]));
                 if (scoped["ok"] !== true)
                     throw new Error(`task scope: ${refused(scoped)}`);
                 const digest = gateStateOf(await toolroll("task", "show", input.taskId)).scopeDigest;
@@ -308,10 +403,17 @@ export function releaseAdapters(options) {
                     db.close();
                 }
             },
-            async deploy({ run: runId, worktree, stage }) {
-                // The candidate's own deployment, from its own checkout: drain, backup, rehearsal, swap, health. Its last JSON
-                // line names the runtime it installed; the CLI names are moved to it by the release's link step.
-                const result = await deployScript(worktree, stage, runId, ["--yes"]);
+            async deploy({ run: runId, worktree, stage, operation }) {
+                // Approval policy §1.7: this runtime proves the candidate FIRST — a person approved it, its exact result passed
+                // the approved check and is complete, and the checkout is exactly that commit — before anything from the
+                // candidate's checkout runs. The candidate's own script never decides its own deployment.
+                const proven = proveCandidate(runId);
+                if (!proven.ok)
+                    return stopped(stage, proven.message);
+                // The approved commit's own deployment, extracted by this runtime: drain, backup, rehearsal, swap, health. Its
+                // last JSON line names the runtime it installed; the CLI names are moved to it by the release's link step.
+                // The operation the coordinator reserved, adopted by the deploy run with its secret on stdin (never in argv).
+                const result = await deployScript(worktree, stage, runId, proven, ["--yes", ...(operation === undefined ? [] : ["--operation", operation.id])], operation?.secret);
                 const runtime = deployedRuntime(result.stdout);
                 if (result.code !== 0 || runtime === null)
                     return stopped(stage, tail(result));
@@ -325,7 +427,11 @@ export function releaseAdapters(options) {
                 const running = (options.processes ?? processes)().filter(one => one.command.includes("deploy-browser.mjs") && one.command.includes(stage));
                 if (running.length > 0)
                     return { ok: false, message: `the deployment is still running (process ${running.map(one => one.pid).join(", ")}); let it finish, then rerun` };
-                const result = await deployScript(worktree, stage, runId, ["--phase", "recover"]);
+                // Recovery needs no approval, but it runs only the recorded commit's own script, extracted by this runtime.
+                const recorded = recordedCommit(runId);
+                if (recorded === null)
+                    return stopped(stage, `Run ${runId} names no commit to recover with.`);
+                const result = await deployScript(worktree, stage, runId, recorded, ["--phase", "recover"]);
                 if (result.code === 0)
                     return { ok: true };
                 // Killed while preparing, before it paused anything: nothing to undo (its journal is kept).
@@ -339,6 +445,34 @@ export function releaseAdapters(options) {
                     return { ok: true };
                 return stopped(stage, `${tail(result)} (the deployment journal is at ${String(journal["phase"] ?? "an unreadable phase")}; ${join(stage, "deployment.json")})`);
             },
+            async deploymentIdle(stage) {
+                // Whatever the stage: no deployment is running, and no update pause is held.
+                if ((options.processes ?? processes)().some(one => one.command.includes("deploy-browser.mjs")))
+                    return false;
+                if (liveOwner() !== null)
+                    return false;
+                if (stage === null)
+                    return false;
+                const journalFile = join(stage, "deployment.json");
+                // Never prepared: staging touched neither the service nor the update pause.
+                if (!existsSync(journalFile))
+                    return true;
+                // Its journal lock is free (nothing holds the journal), and it stopped where nothing changed, or finished.
+                try {
+                    acquireDeploymentLock(journalFile, 0).release();
+                }
+                catch {
+                    return false;
+                }
+                let phase;
+                try {
+                    phase = object(JSON.parse(readFileSync(journalFile, "utf8")))["phase"];
+                }
+                catch {
+                    return false;
+                }
+                return phase === "preparing" || phase === "released" || phase === "deployed";
+            },
             async cliLinks() { return findCliLinks(); },
             async switchLinks(links, bin, version) {
                 const answers = (path) => spawnSync(path, ["--version"], { encoding: "utf8", env: cleanEnv(), timeout: 30_000 }).stdout?.trim() === version;
@@ -361,8 +495,9 @@ export function releaseAdapters(options) {
                 // Oldest first, so a rerun's attempt is the last one listed for its name.
                 return runs.sort((a, b) => Number(a["id"]) - Number(b["id"])).map((one) => ({ name: String(one["name"]), status: String(one["status"]), conclusion: textOr(one["conclusion"]), app: textOr(one["app"]) }));
             },
-            async merge(repo, pr, head) {
-                const merged = object(await ghJson("gh api pulls merge", "api", "-X", "PUT", `repos/${repo}/pulls/${pr}/merge`, "-f", "merge_method=squash", "-f", `sha=${head}`));
+            async merge(repo, pr, head, message) {
+                // The squash commit's message lists every commit that landed after the approval (release-once.md).
+                const merged = object(await ghJson("gh api pulls merge", "api", "-X", "PUT", `repos/${repo}/pulls/${pr}/merge`, "-f", "merge_method=squash", "-f", `sha=${head}`, ...(message === undefined ? [] : ["-f", `commit_message=${message}`])));
                 if (typeof merged["sha"] !== "string")
                     throw new Error(`GitHub did not merge #${pr}: ${String(merged["message"] ?? "no merge commit")}`);
                 return merged["sha"];
@@ -510,3 +645,65 @@ export function bumpFormula(text, url, sha256) {
         throw new Error("the formula has no url and sha256 lines to update");
     return text.replace(/^(\s*url ")[^"]*(")/m, `$1${url}$2`).replace(/^(\s*sha256 ")[0-9a-f]{64}(")/m, `$1${sha256}$2`);
 }
+/** The plane's person-approval answer from `task show --json`, read strictly: anything malformed is no person. */
+function personAnswerOf(value) {
+    if (value === undefined)
+        return {};
+    const read = object(value);
+    if (read["ok"] === true && typeof read["method"] === "string")
+        return { person: { ok: true, method: read["method"] } };
+    return { person: { ok: false, why: typeof read["why"] === "string" ? read["why"] : "the plane's answer about who approved it can't be read" } };
+}
+/**
+ * The release's authority record through a store (release-once.md): what `toolroll release` reads and writes for its
+ * lease, its carries and its operations. `open` hands a store for each call and `done` lets it go.
+ */
+export function storeReleaseAdapter(open, done, now, runner) {
+    const withStore = (body) => { const store = open(); try {
+        return body(store);
+    }
+    finally {
+        done(store);
+    } };
+    return {
+        async authority(taskId) {
+            return withStore(store => {
+                const found = releaseAuthorityOfTask(store, taskId);
+                if (found === null)
+                    return null;
+                const a = found.authority;
+                return { id: a.id, generation: a.generation, state: a.state, tipSha: a.tipSha, tipTask: a.tipTask, version: a.version, pr: a.pr,
+                    landed: releaseCarries(store, a.id).flatMap(carry => carry.commits) };
+            });
+        },
+        async live(taskId, action) {
+            return withStore(store => { const live = liveReleaseOf(store, taskId, action, now()); return live.applies ? { applies: true, ok: live.ok, why: live.ok ? null : live.why } : { applies: false, ok: false, why: null }; });
+        },
+        async lease(authority, owner) { return withStore(store => takeReleaseLease(store, authority, owner, now())); },
+        async renew(authority, owner, epoch) { return withStore(store => renewReleaseLease(store, authority, owner, epoch, now())); },
+        async carry(authority, to, requestId, epoch) {
+            const store = open();
+            try {
+                const result = await proveCarry(store, { authority, to, requestId, epoch, now: now(), ...(runner === undefined ? {} : { runner }) });
+                return result.ok ? { ok: true, taskId: result.taskId } : { ok: false, message: result.message };
+            }
+            finally {
+                done(store);
+            }
+        },
+        async reserve(input) {
+            return withStore(store => {
+                const secret = randomBytes(32).toString("hex");
+                const result = reserveRelease(store, { ...input, operationId: randomUUID(), now: now(), secret });
+                return result.ok ? { ok: true, operation: result.operation.id, secret } : result;
+            });
+        },
+        async start(operation, epoch) { return withStore(store => runReleaseOperation(store, operation, epoch, now())); },
+        async finish(operation, outcome, facts, epoch) { return withStore(store => finishReleaseOperation(store, operation, outcome, facts, now(), epoch)); },
+        async needsApproval(authority, reason, epoch) { return withStore(store => requireFreshReleaseApproval(store, authority, reason, epoch, now())); },
+        async operations(authority) {
+            return withStore(store => releaseOperations(store, authority).map(op => ({ id: op.id, kind: op.kind, state: op.state, candidate: op.candidate, externalRef: op.externalRef, reservedAt: op.reservedAt,
+                direct: op.direct, issuerGone: releaseIssuerGone(op), stage: op.stage })));
+        },
+    };
+}

package/dist/release-authority.d.ts

@@ -0,0 +1,112 @@
+/**
+ * The release authority record, read (docs/plans/release-once.md, schema v135): one generation of a release a person
+ * approved, its carried commits and its deploy and merge operations. Kept apart from store.ts so the one live-release
+ * reader (scope.ts liveReleaseOf) can read it without a module cycle; every write is in store.ts.
+ */
+import { type ReleasePolicy, type ReleaseTerms } from "./contracts/release-terms.js";
+import type { Store } from "./store.js";
+export type ReleaseState = "open" | "deploying" | "merge-reserved" | "merged" | "revoked" | "expired" | "superseded";
+export declare const LIVE_RELEASE_STATES: readonly ReleaseState[];
+/** One generation of a release a person approved: the single source of truth for it. */
+export type ReleaseAuthority = {
+    id: number;
+    repo: string;
+    generation: number;
+    previous: number | null;
+    version: string;
+    pr: number;
+    branch: string;
+    base: string;
+    anchorTask: string;
+    anchorDigest: string;
+    approvedSha: string;
+    approvedTree: string;
+    artifactDigest: string | null;
+    tipSha: string;
+    tipTask: string;
+    policyJson: string;
+    policy: ReleasePolicy | null;
+    policyDigest: string;
+    verifyCommand: number;
+    verifyDigest: string;
+    accessDigest: string;
+    state: ReleaseState;
+    rev: number;
+    leaseOwner: string | null;
+    leaseEpoch: number;
+    leaseExpires: string | null;
+    expiresAt: string;
+    createdAt: string;
+    endedAt: string | null;
+    endedBy: string | null;
+};
+/** One later commit carried under an authority. */
+export type ReleaseCarry = {
+    id: number;
+    authority: number;
+    taskId: string;
+    scopeDigest: string;
+    requestId: string;
+    fromSha: string;
+    toSha: string;
+    toTree: string;
+    artifactDigest: string;
+    commits: {
+        sha: string;
+        files: {
+            path: string;
+            added: number;
+            deleted: number;
+        }[];
+    }[];
+    changedLines: number;
+    files: number;
+    churn: number;
+    runtime: string;
+    provedAt: string;
+};
+/** A deploy or merge that can't be undone, fenced by the lease epoch that reserved it. */
+export type ReleaseOperation = {
+    id: string;
+    authority: number;
+    kind: "deploy" | "merge";
+    taskId: string;
+    candidate: string;
+    epoch: number;
+    state: "reserved" | "running" | "succeeded" | "failed" | "unknown";
+    externalRef: string | null;
+    reservedAt: string;
+    finishedAt: string | null;
+    detail: string | null;
+    /** Reserved by a person's own deploy run, with no coordinator holding the release. */
+    direct: boolean;
+    /** The process that reserved, then issued, it (store.ts currentReleaseIssuer); null when none was recorded. */
+    issuer: {
+        pid: number;
+        started: string | null;
+        at: string;
+    } | null;
+    /** A direct deploy's staging folder. */
+    stage: string | null;
+};
+export declare function releaseAuthority(store: Store, id: number): ReleaseAuthority | null;
+/** The newest generation of a release, whatever its state. */
+export declare function newestReleaseGeneration(store: Store, repo: string, version: string, pr: number): ReleaseAuthority | null;
+/** The release authority a task belongs to — as an anchor (any generation) or as a carried commit — or null. */
+export declare function releaseAuthorityOfTask(store: Store, taskId: string): {
+    authority: ReleaseAuthority;
+    carry: ReleaseCarry | null;
+} | null;
+/** Whether a task belongs to any release authority (anchor or carried), from the records alone. */
+export declare function belongsToRelease(store: Store, taskId: string): boolean;
+export declare function releaseCarries(store: Store, authority: number): ReleaseCarry[];
+export declare function releaseCarryTo(store: Store, authority: number, toSha: string): ReleaseCarry | null;
+export declare function releaseOperations(store: Store, authority: number): ReleaseOperation[];
+export declare function releaseOperation(store: Store, id: string): ReleaseOperation | null;
+/** Operations nobody has settled yet: until each is reconciled, nothing new starts. */
+export declare function outstandingReleaseOperations(store: Store, authority: number): ReleaseOperation[];
+/**
+ * Why a person's seal of these release terms can't open a new generation now, in words, or null. A live generation is
+ * superseded by the new one — but never while one of its operations is unsettled, and never once its merge started.
+ */
+export declare function releaseSealProblem(store: Store, terms: ReleaseTerms): string | null;

package/dist/release-authority.js

@@ -0,0 +1,126 @@
+/**
+ * The release authority record, read (docs/plans/release-once.md, schema v135): one generation of a release a person
+ * approved, its carried commits and its deploy and merge operations. Kept apart from store.ts so the one live-release
+ * reader (scope.ts liveReleaseOf) can read it without a module cycle; every write is in store.ts.
+ */
+import { readReleasePolicy } from "./contracts/release-terms.js";
+export const LIVE_RELEASE_STATES = ["open", "deploying", "merge-reserved"];
+function readReleaseAuthority(row) {
+    const text = (key) => row[key] == null ? null : String(row[key]);
+    let policy = null;
+    try {
+        const parsed = readReleasePolicyStrict(String(row["policy_json"]));
+        policy = parsed;
+    }
+    catch {
+        policy = null;
+    }
+    const state = String(row["state"]);
+    return {
+        id: Number(row["id"]), repo: String(row["repo"]), generation: Number(row["generation"]), previous: row["previous"] == null ? null : Number(row["previous"]),
+        version: String(row["version"]), pr: Number(row["pr"]), branch: String(row["branch"]), base: String(row["base"]),
+        anchorTask: String(row["anchor_task"]), anchorDigest: String(row["anchor_digest"]), approvedSha: String(row["approved_sha"]), approvedTree: String(row["approved_tree"]),
+        artifactDigest: text("artifact_digest"), tipSha: String(row["tip_sha"]), tipTask: String(row["tip_task"]), policyJson: String(row["policy_json"]), policy,
+        policyDigest: String(row["policy_digest"]), verifyCommand: Number(row["verify_command"]), verifyDigest: String(row["verify_digest"]), accessDigest: String(row["access_digest"]),
+        state: ["open", "deploying", "merge-reserved", "merged", "revoked", "expired", "superseded"].includes(state) ? state : "revoked",
+        rev: Number(row["rev"]), leaseOwner: text("lease_owner"), leaseEpoch: Number(row["lease_epoch"]), leaseExpires: text("lease_expires"),
+        expiresAt: String(row["expires_at"]), createdAt: String(row["created_at"]), endedAt: text("ended_at"), endedBy: text("ended_by"),
+    };
+}
+/** A sealed policy read strictly; null when this runtime doesn't know it (and so refuses to carry under it). */
+function readReleasePolicyStrict(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+    const read = readReleasePolicy(parsed);
+    return read.ok && JSON.stringify(read.value) === json ? read.value : null;
+}
+function readReleaseCarry(row) {
+    let commits = [];
+    try {
+        const parsed = JSON.parse(String(row["commits_json"]));
+        if (Array.isArray(parsed))
+            commits = parsed;
+    }
+    catch {
+        commits = [];
+    }
+    return {
+        id: Number(row["id"]), authority: Number(row["authority"]), taskId: String(row["task_id"]), scopeDigest: String(row["scope_digest"]), requestId: String(row["request_id"]),
+        fromSha: String(row["from_sha"]), toSha: String(row["to_sha"]), toTree: String(row["to_tree"]), artifactDigest: String(row["artifact_digest"]), commits,
+        changedLines: Number(row["changed_lines"]), files: Number(row["files"]), churn: Number(row["churn"]), runtime: String(row["runtime"]), provedAt: String(row["proved_at"]),
+    };
+}
+function readReleaseOperation(row) {
+    const text = (key) => row[key] == null ? null : String(row[key]);
+    return {
+        id: String(row["id"]), authority: Number(row["authority"]), kind: row["kind"] === "merge" ? "merge" : "deploy", taskId: String(row["task_id"]), candidate: String(row["candidate"]),
+        epoch: Number(row["epoch"]), state: String(row["state"]), externalRef: text("external_ref"), reservedAt: String(row["reserved_at"]),
+        finishedAt: text("finished_at"), detail: text("detail"), direct: Number(row["direct"] ?? 0) === 1,
+        issuer: row["issuer_pid"] == null || row["issued_at"] == null ? null : { pid: Number(row["issuer_pid"]), started: text("issuer_started"), at: String(row["issued_at"]) },
+        stage: text("stage"),
+    };
+}
+export function releaseAuthority(store, id) {
+    const row = store.handle.prepare("SELECT * FROM release_authority WHERE id = ?").get(id);
+    return row === undefined ? null : readReleaseAuthority(row);
+}
+/** The newest generation of a release, whatever its state. */
+export function newestReleaseGeneration(store, repo, version, pr) {
+    const row = store.handle.prepare("SELECT * FROM release_authority WHERE repo = ? AND version = ? AND pr = ? ORDER BY generation DESC LIMIT 1").get(repo, version, pr);
+    return row === undefined ? null : readReleaseAuthority(row);
+}
+/** The release authority a task belongs to — as an anchor (any generation) or as a carried commit — or null. */
+export function releaseAuthorityOfTask(store, taskId) {
+    const carryRow = store.handle.prepare("SELECT * FROM release_carry WHERE task_id = ?").get(taskId);
+    if (carryRow !== undefined) {
+        const carry = readReleaseCarry(carryRow);
+        const authority = releaseAuthority(store, carry.authority);
+        return authority === null ? null : { authority, carry };
+    }
+    const row = store.handle.prepare("SELECT * FROM release_authority WHERE anchor_task = ? ORDER BY id DESC LIMIT 1").get(taskId);
+    return row === undefined ? null : { authority: readReleaseAuthority(row), carry: null };
+}
+/** Whether a task belongs to any release authority (anchor or carried), from the records alone. */
+export function belongsToRelease(store, taskId) {
+    return store.handle.prepare("SELECT 1 AS hit FROM release_authority WHERE anchor_task = ? UNION ALL SELECT 1 FROM release_carry WHERE task_id = ? LIMIT 1").get(taskId, taskId) !== undefined;
+}
+export function releaseCarries(store, authority) {
+    return store.handle.prepare("SELECT * FROM release_carry WHERE authority = ? ORDER BY id").all(authority).map(readReleaseCarry);
+}
+export function releaseCarryTo(store, authority, toSha) {
+    const row = store.handle.prepare("SELECT * FROM release_carry WHERE authority = ? AND to_sha = ?").get(authority, toSha);
+    return row === undefined ? null : readReleaseCarry(row);
+}
+export function releaseOperations(store, authority) {
+    return store.handle.prepare("SELECT * FROM release_operation WHERE authority = ? ORDER BY reserved_at, id").all(authority).map(readReleaseOperation);
+}
+export function releaseOperation(store, id) {
+    const row = store.handle.prepare("SELECT * FROM release_operation WHERE id = ?").get(id);
+    return row === undefined ? null : readReleaseOperation(row);
+}
+/** Operations nobody has settled yet: until each is reconciled, nothing new starts. */
+export function outstandingReleaseOperations(store, authority) {
+    return releaseOperations(store, authority).filter(one => one.state === "reserved" || one.state === "running" || one.state === "unknown");
+}
+/**
+ * Why a person's seal of these release terms can't open a new generation now, in words, or null. A live generation is
+ * superseded by the new one — but never while one of its operations is unsettled, and never once its merge started.
+ */
+export function releaseSealProblem(store, terms) {
+    const live = newestReleaseGeneration(store, terms.repo, terms.packageVersion, terms.pr);
+    if (live === null)
+        return null;
+    if (live.state === "merged")
+        return `Release ${terms.packageVersion} from pull request #${terms.pr} was already merged.`;
+    if (live.state === "merge-reserved")
+        return `The merge of release ${terms.packageVersion} already started; it can't be approved again.`;
+    if (LIVE_RELEASE_STATES.includes(live.state) && outstandingReleaseOperations(store, live.id).length > 0) {
+        return `Release ${terms.packageVersion} has a deploy that hasn't been settled yet. Run \`toolroll release ${live.branch}\` to finish or recover it first.`;
+    }
+    return null;
+}