toolroll 0.9.71 → 0.9.73

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,29 @@ 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";
+import { checkoutIncludes } from "./teardown-git.js";
+import { RELEASE_REMOTE, releaseConfigProblem, releaseGitArgs, releaseGitEnv, releaseRemote, releaseTools } from "./release-git.js";
+export { RELEASE_PATH, RELEASE_REMOTE, releaseConfigProblem, releaseGitArgs, releaseGitEnv, releaseRemote, releaseTools } from "./release-git.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 +122,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),
@@ -149,6 +165,48 @@ export function stageGate(stage, owner) {
     const id = textOr(journal["id"]), phase = textOr(journal["phase"]);
     return id !== null && phase !== null && BEFORE_SWAP.includes(phase) && owner() === id ? { id, phase } : null;
 }
+/** The recorded repository for a gate checkout, from the plane's database; throws in plain words when there is none. */
+export function recordedReleaseRepo(database, checkout) {
+    const real = (path) => { try {
+        return realpathSync(path);
+    }
+    catch {
+        return null;
+    } };
+    const at = real(checkout);
+    if (at === null)
+        throw new Error(`${checkout} isn't there.`);
+    if (!existsSync(database))
+        throw new Error("The plane's database isn't here, so the release's repository can't be read from its records.");
+    const db = new (sqlite().DatabaseSync)(database, { readOnly: true });
+    let project = null, remote = null;
+    try {
+        const store = new Store(db);
+        project = store.listProjects().map(one => one.path).find(path => real(path) === at) ?? null;
+        remote = project === null ? null : store.projectRemote(project);
+    }
+    finally {
+        db.close();
+    }
+    if (project === null)
+        throw new Error(`${checkout} isn't one of the projects Toolroll records, so it can't be released from here.`);
+    if (remote === null)
+        throw new Error(`${project} has no recorded remote. Record it with \`toolroll repos add ${project} --remote <url>\` first.`);
+    const parsed = releaseRemote(remote);
+    if (parsed === null)
+        throw new Error(`${project}'s recorded remote (${remote}) isn't a GitHub repository over https or ssh.`);
+    const named = join(at, ".git");
+    let gitDir;
+    try {
+        if (!lstatSync(named).isDirectory())
+            throw new Error("not a folder");
+        gitDir = realpathSync(named);
+    }
+    catch {
+        throw new Error(`${project}'s Git directory isn't a plain folder, so the release won't read it.`);
+    }
+    return { checkout: at, gitDir, remote, ...parsed };
+}
 /** How many times, and how far apart, a merged branch's deletion is looked for after the push lost a race. */
 export const BRANCH_GONE_LOOKS = 5;
 export const BRANCH_GONE_PAUSE_MS = 2_000;
@@ -158,9 +216,11 @@ export function releaseAdapters(options) {
     const { checkout } = options;
     const tap = options.tap ?? "ap9000/homebrew-toolroll";
     const formula = options.formula ?? "Formula/toolroll.rb";
-    const git = (...args) => run("git", ["-C", checkout, ...args]);
     const pause = options.sleep ?? ((ms) => new Promise(done => setTimeout(done, ms)));
-    const gh = (...args) => run("gh", args);
+    const tools = options.tools ?? releaseTools();
+    const gitEnv = releaseGitEnv();
+    // Never a PATH lookup or the checkout's Git config: gh by its absolute path, from a neutral folder, naming the repo.
+    const gh = (...args) => run(tools.gh, args, { cwd: "/", env: gitEnv });
     const ghJson = async (what, ...args) => JSON.parse(await must(gh(...args), what));
     const toolroll = async (...args) => {
         const result = await run("toolroll", [...args, "--json"], { env: cleanEnv(), timeoutMs: 120_000 });
@@ -173,6 +233,29 @@ export function releaseAdapters(options) {
     };
     const refused = (answer) => `${String(answer["message"] ?? answer["reason"] ?? "refused")}`;
     const database = options.database ?? databasePath(process.env, homedir());
+    let recorded = options.releaseRepo ?? null;
+    /** The recorded repository, read once (chat-management.md §0a.2). */
+    const releaseRepo = () => recorded ??= recordedReleaseRepo(database, checkout);
+    /**
+     * The coordinator's one way to run Git (§0a.2): on the recorded Git directory, hardened, with an allowlisted
+     * environment and the absolute Git. Before every command the checkout's own config is read with includes off and
+     * as plain files; one that includes a file, names a command or redirects a remote stops the release, naming it.
+     */
+    const git = async (...args) => {
+        const repo = releaseRepo();
+        const stop = (why) => new Error(`Toolroll won't run Git in ${repo.checkout} for a release: ${why}. Remove it from the project's Git config, then rerun.`);
+        if (options.releaseRepo === undefined && checkoutIncludes(repo.checkout))
+            throw stop("its Git config includes another file, or couldn't be read as a plain file");
+        const listing = await run(tools.git, [`--git-dir=${repo.gitDir}`, "--no-optional-locks", "config", "--list", "--no-includes", "--show-scope", "-z"], { cwd: "/", env: gitEnv });
+        if (listing.code !== 0)
+            throw stop("its Git config couldn't be read");
+        const setting = releaseConfigProblem(listing.stdout);
+        if (setting !== null)
+            throw stop(`its Git config sets ${setting}, which a release doesn't run with (it could run a command, or change where Git connects or what it sends)`);
+        return run(tools.git, [...releaseGitArgs(repo, tools), ...args], { cwd: repo.checkout, env: gitEnv });
+    };
+    /** The remote every fetch, look and push names: the recorded URL, defined only on the command line. */
+    const remoteUrl = () => RELEASE_REMOTE;
     const liveOwner = () => {
         if (!existsSync(database))
             return null;
@@ -190,24 +273,102 @@ 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`)),
         repo: {
-            async github() {
-                const slug = githubSlug(await must(git("remote", "get-url", "origin"), "git remote get-url origin"));
-                if (slug === null)
-                    throw new Error(`${checkout}'s origin is not a GitHub repository`);
-                return slug;
-            },
+            // The recorded owner/name, never the checkout's origin.
+            async github() { return releaseRepo().slug; },
             async sync(branch) {
-                await must(git("fetch", "--quiet", "origin", "+refs/heads/main:refs/remotes/origin/main"), "git fetch origin main");
+                await must(git("fetch", "--quiet", "--no-tags", remoteUrl(), "+refs/heads/main:refs/remotes/origin/main"), "git fetch main");
                 // A merged branch may be gone from GitHub; its commit is already here.
-                await git("fetch", "--quiet", "origin", `+refs/heads/${branch}:refs/remotes/origin/${branch}`);
+                await git("fetch", "--quiet", "--no-tags", remoteUrl(), `+refs/heads/${branch}:refs/remotes/origin/${branch}`);
                 const current = (await git("symbolic-ref", "--quiet", "--short", "HEAD")).stdout.trim();
                 if (current === "main") {
                     await must(git("merge", "--ff-only", "--quiet", "origin/main"), "git merge --ff-only origin/main");
@@ -221,17 +382,17 @@ export function releaseAdapters(options) {
                     throw new Error(`${checkout}'s local main has commits origin/main doesn't; the gate diffs from it, so fix it first`);
             },
             async remoteHead(branch) {
-                const out = await must(git("ls-remote", "origin", `refs/heads/${branch}`), "git ls-remote");
+                const out = await must(git("ls-remote", remoteUrl(), `refs/heads/${branch}`), "git ls-remote");
                 return out.trim().split(/\s+/)[0] || null;
             },
             async deleteBranch(branch, head) {
                 const ref = `refs/heads/${branch}`;
-                const current = (await must(git("ls-remote", "origin", ref), "git ls-remote")).trim().split(/\s+/)[0] || null;
+                const current = (await must(git("ls-remote", remoteUrl(), ref), "git ls-remote")).trim().split(/\s+/)[0] || null;
                 if (current === null)
                     return;
                 if (current !== head)
                     throw new Error(`${branch} moved after merging; its new head was not deleted.`);
-                const pushed = await git("push", `--force-with-lease=${ref}:${head}`, "origin", `:${ref}`);
+                const pushed = await git("push", "--no-verify", `--force-with-lease=${ref}:${head}`, remoteUrl(), `:${ref}`);
                 if (pushed.code === 0)
                     return;
                 // GitHub may delete a merged branch itself between the look and the push; gone is what was wanted. Its refs can
@@ -239,7 +400,7 @@ export function releaseAdapters(options) {
                 for (let look = 0; look < BRANCH_GONE_LOOKS; look++) {
                     if (look > 0)
                         await pause(BRANCH_GONE_PAUSE_MS);
-                    const after = (await must(git("ls-remote", "origin", ref), "git ls-remote")).trim().split(/\s+/)[0] || null;
+                    const after = (await must(git("ls-remote", remoteUrl(), ref), "git ls-remote")).trim().split(/\s+/)[0] || null;
                     if (after === null)
                         return;
                 }
@@ -278,7 +439,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 +469,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 +493,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 +511,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 +561,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 +711,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,118 @@
+/**
+ * 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. */
+/** "Carry release approvals when checks aren't sandboxed": a project setting, newest choice wins (a ledger row each);
+ * off by default. Turning it on is a person's own proven act (release-cli.ts); turning it off is anyone's. */
+export declare const UNSANDBOXED_CARRY_ACTION = "release unsandboxed carrying changed";
+export declare function carriesUnsandboxed(store: Store, repo: string): boolean;
+/** How far a check reaches, narrowest first. */
+export declare const CHECK_ACCESS_WIDTH: Readonly<Record<string, number>>;
+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;