@davidahmann/mill 0.1.4

package/dist/runtime/state.js

@@ -0,0 +1,1017 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { access, chmod, copyFile, lstat, mkdir, readdir, rename, rm, writeFile, } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { backup, DatabaseSync } from "node:sqlite";
+import { ExitCode, MillError } from "../errors.js";
+import { isWithin } from "../security/safe-path.js";
+import { acquireExclusiveLease } from "./lease.js";
+export function publicRunRecord(run) {
+    const publicRun = { ...run };
+    delete publicRun.worktreePath;
+    delete publicRun.contextJson;
+    delete publicRun.controlJson;
+    delete publicRun.activeProcessId;
+    delete publicRun.activeProcessGroup;
+    delete publicRun.activeProcessIdentity;
+    delete publicRun.deliveryJson;
+    delete publicRun.remoteFeedbackJson;
+    return publicRun;
+}
+const terminal = new Set(["closed", "cancelled", "failed", "stale"]);
+export function isTerminalRun(status) {
+    return terminal.has(status);
+}
+export function isPurgeSafeRun(status) {
+    return status === "reviewed" || isTerminalRun(status);
+}
+const transitions = {
+    approved: ["ready", "blocked", "cancelled", "failed"],
+    ready: ["running", "blocked", "cancelled", "failed", "stale"],
+    running: ["committed", "blocked", "cancelled", "failed", "stale"],
+    committed: ["verified", "blocked", "cancelled", "failed", "stale"],
+    verified: ["reviewed", "blocked", "cancelled", "failed", "stale"],
+    reviewed: ["proposing", "cancelled", "failed", "stale"],
+    proposing: [
+        "effect_unknown",
+        "awaiting_ci",
+        "blocked",
+        "cancelled",
+        "failed",
+        "stale",
+    ],
+    effect_unknown: [
+        "proposing",
+        "awaiting_ci",
+        "blocked",
+        "cancelled",
+        "failed",
+        "stale",
+    ],
+    awaiting_ci: [
+        "awaiting_human",
+        "blocked",
+        "effect_unknown",
+        "cancelled",
+        "failed",
+        "stale",
+    ],
+    awaiting_human: ["merged", "blocked", "failed", "stale"],
+    merged: ["post_merge_verified", "blocked", "failed", "stale"],
+    post_merge_verified: ["closed", "blocked", "failed", "stale"],
+    closed: [],
+    blocked: [
+        "ready",
+        "running",
+        "committed",
+        "verified",
+        "proposing",
+        "awaiting_ci",
+        "awaiting_human",
+        "merged",
+        "post_merge_verified",
+        "cancelled",
+        "failed",
+        "stale",
+    ],
+    cancelled: [],
+    failed: [],
+    stale: [],
+};
+function stateRoot() {
+    const configured = process.env.MILL_STATE_HOME;
+    if (configured !== undefined) {
+        if (!path.isAbsolute(configured)) {
+            throw new MillError("INVALID_STATE_HOME", "MILL_STATE_HOME must be absolute.", ExitCode.configuration);
+        }
+        return configured;
+    }
+    if (process.platform === "darwin") {
+        return path.join(homedir(), "Library", "Application Support", "mill");
+    }
+    const xdg = process.env.XDG_STATE_HOME;
+    return xdg !== undefined && path.isAbsolute(xdg)
+        ? path.join(xdg, "mill")
+        : path.join(homedir(), ".local", "state", "mill");
+}
+function namespace(repositoryId, commonDirectory) {
+    return createHash("sha256")
+        .update(`${repositoryId}\0${path.resolve(commonDirectory)}`, "utf8")
+        .digest("hex");
+}
+export function repositoryStateDirectory(repositoryId, commonDirectory) {
+    return path.join(stateRoot(), "repositories", namespace(repositoryId, commonDirectory));
+}
+function fromRow(row) {
+    return {
+        id: row.id,
+        repositoryId: row.repository_id,
+        taskId: row.task_id,
+        taskDigest: row.task_digest,
+        configDigest: row.config_digest,
+        status: row.status,
+        baseCommit: row.base_commit,
+        ...(row.worktree_path === null ? {} : { worktreePath: row.worktree_path }),
+        ...(row.context_digest === null
+            ? {}
+            : { contextDigest: row.context_digest }),
+        ...(row.context_json === null ? {} : { contextJson: row.context_json }),
+        ...(row.control_json === null ? {} : { controlJson: row.control_json }),
+        ...(row.candidate_commit === null
+            ? {}
+            : { candidateCommit: row.candidate_commit }),
+        ...(row.candidate_tree === null
+            ? {}
+            : { candidateTree: row.candidate_tree }),
+        deadlineAt: row.deadline_at,
+        ...(row.active_process_id === null
+            ? {}
+            : { activeProcessId: row.active_process_id }),
+        ...(row.active_pid === null ? {} : { activePid: row.active_pid }),
+        ...(row.active_process_group === null
+            ? {}
+            : { activeProcessGroup: row.active_process_group }),
+        ...(row.active_process_identity === null
+            ? {}
+            : { activeProcessIdentity: row.active_process_identity }),
+        cancelRequested: row.cancel_requested === 1,
+        repairCount: row.repair_count,
+        attemptCount: row.attempt_count,
+        ...(row.block_code === null ? {} : { blockCode: row.block_code }),
+        ...(row.validation_json === null
+            ? {}
+            : { validationJson: row.validation_json }),
+        ...(row.review_json === null ? {} : { reviewJson: row.review_json }),
+        ...(row.delivery_json === null ? {} : { deliveryJson: row.delivery_json }),
+        ...(row.remote_feedback_json === null
+            ? {}
+            : { remoteFeedbackJson: row.remote_feedback_json }),
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+export class StateStore {
+    directory;
+    databasePath;
+    worktreesDirectory;
+    #database;
+    #closed = false;
+    constructor(directory, database) {
+        this.directory = directory;
+        this.databasePath = path.join(directory, "state.sqlite3");
+        this.worktreesDirectory = path.join(directory, "worktrees");
+        this.#database = database;
+    }
+    static async open(repositoryId, commonDirectory) {
+        const directory = repositoryStateDirectory(repositoryId, commonDirectory);
+        await mkdir(path.join(directory, "worktrees"), {
+            recursive: true,
+            mode: 0o700,
+        });
+        await chmod(directory, 0o700);
+        await chmod(path.join(directory, "worktrees"), 0o700);
+        const databasePath = path.join(directory, "state.sqlite3");
+        const database = new DatabaseSync(databasePath, {
+            timeout: 5_000,
+            allowExtension: false,
+            enableDoubleQuotedStringLiterals: false,
+        });
+        database.exec(`
+      PRAGMA journal_mode = WAL;
+      PRAGMA synchronous = FULL;
+      PRAGMA foreign_keys = ON;
+      PRAGMA trusted_schema = OFF;
+      CREATE TABLE IF NOT EXISTS metadata (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+      ) STRICT;
+      INSERT OR IGNORE INTO metadata(key, value) VALUES ('schema_version', '2');
+      CREATE TABLE IF NOT EXISTS runs (
+        id TEXT PRIMARY KEY,
+        repository_id TEXT NOT NULL,
+        task_id TEXT NOT NULL,
+        task_digest TEXT NOT NULL,
+        config_digest TEXT NOT NULL,
+        status TEXT NOT NULL,
+        base_commit TEXT NOT NULL,
+        worktree_path TEXT,
+        context_digest TEXT,
+        context_json TEXT,
+        control_json TEXT,
+        candidate_commit TEXT,
+        candidate_tree TEXT,
+        deadline_at TEXT NOT NULL,
+        active_process_id TEXT,
+        active_pid INTEGER,
+        active_process_group INTEGER,
+        active_process_identity TEXT,
+        cancel_requested INTEGER NOT NULL DEFAULT 0 CHECK(cancel_requested IN (0, 1)),
+        repair_count INTEGER NOT NULL DEFAULT 0 CHECK(repair_count BETWEEN 0 AND 1),
+        attempt_count INTEGER NOT NULL DEFAULT 0 CHECK(attempt_count BETWEEN 0 AND 2),
+        block_code TEXT,
+        validation_json TEXT,
+        review_json TEXT,
+        delivery_json TEXT,
+        remote_feedback_json TEXT,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      ) STRICT;
+      CREATE TABLE IF NOT EXISTS run_events (
+        sequence INTEGER PRIMARY KEY AUTOINCREMENT,
+        run_id TEXT NOT NULL REFERENCES runs(id),
+        occurred_at TEXT NOT NULL,
+        type TEXT NOT NULL,
+        data_json TEXT NOT NULL
+      ) STRICT;
+      CREATE TABLE IF NOT EXISTS baseline_qualifications (
+        approval_digest TEXT PRIMARY KEY,
+        repository_id TEXT NOT NULL,
+        task_digest TEXT NOT NULL,
+        config_digest TEXT NOT NULL,
+        base_commit TEXT NOT NULL,
+        evidence_digest TEXT NOT NULL,
+        created_at TEXT NOT NULL
+      ) STRICT;
+      CREATE TABLE IF NOT EXISTS worker_invocations (
+        id TEXT PRIMARY KEY,
+        run_id TEXT NOT NULL REFERENCES runs(id),
+        phase TEXT NOT NULL,
+        envelope_digest TEXT NOT NULL,
+        envelope_json TEXT NOT NULL,
+        created_at TEXT NOT NULL
+      ) STRICT;
+      CREATE TABLE IF NOT EXISTS worker_invocation_events (
+        sequence INTEGER PRIMARY KEY AUTOINCREMENT,
+        invocation_id TEXT NOT NULL REFERENCES worker_invocations(id),
+        occurred_at TEXT NOT NULL,
+        type TEXT NOT NULL,
+        data_json TEXT NOT NULL
+      ) STRICT;
+      CREATE TRIGGER IF NOT EXISTS run_events_no_update
+        BEFORE UPDATE ON run_events BEGIN SELECT RAISE(ABORT, 'run events are append-only'); END;
+      CREATE TRIGGER IF NOT EXISTS run_events_no_delete
+        BEFORE DELETE ON run_events BEGIN SELECT RAISE(ABORT, 'run events are append-only'); END;
+      CREATE TRIGGER IF NOT EXISTS worker_invocations_no_update
+        BEFORE UPDATE ON worker_invocations BEGIN SELECT RAISE(ABORT, 'worker invocations are immutable'); END;
+      CREATE TRIGGER IF NOT EXISTS worker_invocations_no_delete
+        BEFORE DELETE ON worker_invocations BEGIN SELECT RAISE(ABORT, 'worker invocations are immutable'); END;
+      CREATE TRIGGER IF NOT EXISTS worker_invocation_events_no_update
+        BEFORE UPDATE ON worker_invocation_events BEGIN SELECT RAISE(ABORT, 'worker invocation events are append-only'); END;
+      CREATE TRIGGER IF NOT EXISTS worker_invocation_events_no_delete
+        BEFORE DELETE ON worker_invocation_events BEGIN SELECT RAISE(ABORT, 'worker invocation events are append-only'); END;
+    `);
+        const runColumns = database
+            .prepare("PRAGMA table_info(runs)")
+            .all();
+        for (const column of [
+            "active_process_id TEXT",
+            "active_process_group INTEGER",
+            "active_process_identity TEXT",
+            "delivery_json TEXT",
+            "remote_feedback_json TEXT",
+        ]) {
+            const name = column.split(" ")[0];
+            if (!runColumns.some((candidate) => candidate.name === name)) {
+                database.exec(`ALTER TABLE runs ADD COLUMN ${column}`);
+            }
+        }
+        const version = database
+            .prepare("SELECT value FROM metadata WHERE key = 'schema_version'")
+            .get();
+        if (version?.value !== "1" && version?.value !== "2") {
+            database.close();
+            throw new MillError("UNSUPPORTED_STATE_SCHEMA", "Operational state uses an unsupported schema version.", ExitCode.configuration);
+        }
+        if (version.value === "1") {
+            database
+                .prepare("UPDATE metadata SET value = '2' WHERE key = 'schema_version'")
+                .run();
+        }
+        await chmod(databasePath, 0o600);
+        return new StateStore(directory, database);
+    }
+    close() {
+        if (!this.#closed) {
+            this.#database.close();
+            this.#closed = true;
+        }
+    }
+    createRun(input) {
+        const id = randomUUID();
+        const now = new Date().toISOString();
+        this.#transaction(() => {
+            this.#database
+                .prepare(`INSERT INTO runs(
+            id, repository_id, task_id, task_digest, config_digest, status,
+            base_commit, deadline_at, created_at, updated_at
+          ) VALUES (?, ?, ?, ?, ?, 'approved', ?, ?, ?, ?)`)
+                .run(id, input.repositoryId, input.taskId, input.taskDigest, input.configDigest, input.baseCommit, input.deadlineAt, now, now);
+            this.#event(id, "run.created", { status: "approved" });
+        });
+        return this.getRun(id);
+    }
+    getRun(id) {
+        const row = this.#database
+            .prepare("SELECT * FROM runs WHERE id = ?")
+            .get(id);
+        if (row === undefined) {
+            throw new MillError("RUN_NOT_FOUND", `Run not found: ${id}`, ExitCode.data);
+        }
+        return fromRow(row);
+    }
+    latestRun() {
+        const row = this.#database
+            .prepare("SELECT * FROM runs ORDER BY created_at DESC LIMIT 1")
+            .get();
+        return row === undefined ? undefined : fromRow(row);
+    }
+    runs() {
+        return this.#database
+            .prepare("SELECT * FROM runs ORDER BY created_at")
+            .all().map(fromRow);
+    }
+    transition(id, to, eventType, details = {}) {
+        this.#transaction(() => {
+            const current = this.getRun(id);
+            if (!transitions[current.status].includes(to)) {
+                throw new MillError("INVALID_RUN_TRANSITION", `Cannot transition run from ${current.status} to ${to}.`, ExitCode.configuration);
+            }
+            if (to === "running" && current.cancelRequested) {
+                throw new MillError("OPERATOR_CANCELLED", "A cancelled run cannot start or resume execution.", ExitCode.temporary);
+            }
+            if (to === "cancelled" && current.activeProcessId !== undefined) {
+                throw new MillError("CANCELLATION_IN_PROGRESS", "The active execution must exit or be reconciled before cancellation is terminal.", ExitCode.temporary);
+            }
+            const now = new Date().toISOString();
+            this.#database
+                .prepare("UPDATE runs SET status = ?, block_code = ?, updated_at = ? WHERE id = ?")
+                .run(to, typeof details.code === "string" ? details.code : null, now, id);
+            this.#event(id, eventType, { from: current.status, to, ...details });
+        });
+        return this.getRun(id);
+    }
+    setWorkspace(id, worktreePath, contextDigest, contextJson, controlJson) {
+        this.#transaction(() => {
+            const current = this.getRun(id);
+            if (current.status !== "ready" ||
+                current.worktreePath !== undefined ||
+                current.contextDigest !== undefined ||
+                current.contextJson !== undefined ||
+                current.controlJson !== undefined) {
+                throw new MillError("INVALID_RUN_TRANSITION", "A workspace can be bound exactly once while the run is ready.", ExitCode.configuration);
+            }
+            this.#database
+                .prepare("UPDATE runs SET worktree_path = ?, context_digest = ?, context_json = ?, control_json = ?, updated_at = ? WHERE id = ?")
+                .run(worktreePath, contextDigest, contextJson, controlJson, new Date().toISOString(), id);
+            this.#event(id, "workspace.created", { contextDigest });
+        });
+    }
+    commitCandidate(id, commit, tree, invocationId) {
+        this.#transaction(() => {
+            const current = this.getRun(id);
+            if (current.cancelRequested) {
+                throw new MillError("OPERATOR_CANCELLED", "A cancelled run cannot publish a candidate commit.", ExitCode.temporary);
+            }
+            if (current.status !== "running") {
+                throw new MillError("INVALID_RUN_TRANSITION", `Cannot commit a candidate from ${current.status}.`, ExitCode.configuration);
+            }
+            if (invocationId !== undefined) {
+                const invocation = this.#database
+                    .prepare("SELECT run_id, phase FROM worker_invocations WHERE id = ?")
+                    .get(invocationId);
+                if (invocation?.run_id !== id ||
+                    (invocation.phase !== "build" && invocation.phase !== "repair") ||
+                    this.workerInvocationStatus(invocationId) !== "launch_started") {
+                    throw new MillError("WORKER_INVOCATION_SETTLEMENT_CONFLICT", "Candidate publication requires its one started mutating worker invocation.", ExitCode.configuration);
+                }
+            }
+            this.#database
+                .prepare(`UPDATE runs SET candidate_commit = ?, candidate_tree = ?,
+           validation_json = NULL, review_json = NULL,
+           remote_feedback_json = NULL, status = 'committed',
+           block_code = NULL, updated_at = ? WHERE id = ?`)
+                .run(commit, tree, new Date().toISOString(), id);
+            this.#event(id, "candidate.committed", {
+                from: current.status,
+                to: "committed",
+                commit,
+                tree,
+            });
+            if (invocationId !== undefined) {
+                this.#invocationEvent(invocationId, "settled", {
+                    outcome: "completed",
+                    candidateCommit: commit,
+                    candidateTree: tree,
+                });
+            }
+        });
+        return this.getRun(id);
+    }
+    completeValidation(id, value, passed) {
+        this.#transaction(() => {
+            const current = this.getRun(id);
+            if (current.cancelRequested) {
+                throw new MillError("OPERATOR_CANCELLED", "A cancelled run cannot publish validation evidence.", ExitCode.temporary);
+            }
+            if (current.status !== "committed") {
+                throw new MillError("INVALID_RUN_TRANSITION", `Cannot record validation from ${current.status}.`, ExitCode.configuration);
+            }
+            const status = passed ? "verified" : "blocked";
+            const code = passed ? null : "VALIDATION_FAILED";
+            this.#database
+                .prepare("UPDATE runs SET validation_json = ?, status = ?, block_code = ?, updated_at = ? WHERE id = ?")
+                .run(value, status, code, new Date().toISOString(), id);
+            this.#event(id, passed ? "validation.passed" : "validation.failed", {
+                from: current.status,
+                to: status,
+                ...(code === null ? {} : { code }),
+            });
+        });
+        return this.getRun(id);
+    }
+    completeReview(id, value, findings, nonConverged, invocationId, completionDetails = {}) {
+        this.#transaction(() => {
+            const current = this.getRun(id);
+            if (current.cancelRequested) {
+                throw new MillError("OPERATOR_CANCELLED", "A cancelled run cannot publish review evidence.", ExitCode.temporary);
+            }
+            if (current.status !== "verified") {
+                throw new MillError("INVALID_RUN_TRANSITION", `Cannot record review from ${current.status}.`, ExitCode.configuration);
+            }
+            const invocation = this.#database
+                .prepare("SELECT run_id, phase FROM worker_invocations WHERE id = ?")
+                .get(invocationId);
+            if (invocation?.run_id !== id ||
+                invocation.phase !== "review" ||
+                this.workerInvocationStatus(invocationId) !== "launch_started") {
+                throw new MillError("WORKER_INVOCATION_SETTLEMENT_CONFLICT", "Review publication requires its one started reviewer invocation.", ExitCode.configuration);
+            }
+            const status = findings === 0 ? "reviewed" : "blocked";
+            const code = findings === 0
+                ? null
+                : nonConverged
+                    ? "REVIEW_NON_CONVERGENCE"
+                    : "REVIEW_FINDINGS";
+            this.#database
+                .prepare("UPDATE runs SET review_json = ?, status = ?, block_code = ?, updated_at = ? WHERE id = ?")
+                .run(value, status, code, new Date().toISOString(), id);
+            this.#event(id, "review.completed", {
+                ...completionDetails,
+                candidateCommit: current.candidateCommit ?? null,
+                findings,
+            });
+            this.#event(id, findings === 0 ? "review.passed" : "review.blocked", {
+                from: current.status,
+                to: status,
+                findings,
+                ...(code === null ? {} : { code }),
+            });
+            this.#invocationEvent(invocationId, "settled", {
+                outcome: "completed",
+                candidateCommit: current.candidateCommit ?? null,
+                findings,
+            });
+        });
+        return this.getRun(id);
+    }
+    setDelivery(id, deliveryJson, eventType, details = {}) {
+        this.#transaction(() => {
+            this.getRun(id);
+            this.#database
+                .prepare("UPDATE runs SET delivery_json = ?, updated_at = ? WHERE id = ?")
+                .run(deliveryJson, new Date().toISOString(), id);
+            this.#event(id, eventType, details);
+        });
+        return this.getRun(id);
+    }
+    setRemoteFeedback(id, feedbackJson) {
+        this.#transaction(() => {
+            this.getRun(id);
+            this.#database
+                .prepare("UPDATE runs SET remote_feedback_json = ?, updated_at = ? WHERE id = ?")
+                .run(feedbackJson, new Date().toISOString(), id);
+            this.#event(id, "remote.feedback_recorded", {});
+        });
+        return this.getRun(id);
+    }
+    replaceBlocker(id, code, eventType, details = {}) {
+        this.#transaction(() => {
+            const current = this.getRun(id);
+            if (current.status !== "blocked") {
+                throw new MillError("INVALID_RUN_TRANSITION", `Cannot replace a blocker while run is ${current.status}.`, ExitCode.configuration);
+            }
+            this.#database
+                .prepare("UPDATE runs SET block_code = ?, updated_at = ? WHERE id = ?")
+                .run(code, new Date().toISOString(), id);
+            this.#event(id, eventType, {
+                from: current.blockCode ?? null,
+                to: code,
+                ...details,
+            });
+        });
+        return this.getRun(id);
+    }
+    beginRepair(id) {
+        this.#transaction(() => {
+            const current = this.getRun(id);
+            if (current.cancelRequested) {
+                throw new MillError("OPERATOR_CANCELLED", "A cancelled run cannot begin a repair execution.", ExitCode.temporary);
+            }
+            if (current.status !== "blocked" || current.repairCount >= 1) {
+                throw new MillError("REPAIR_BUDGET_EXHAUSTED", "The single systemic repair budget is exhausted or the run is not blocked.", ExitCode.configuration);
+            }
+            this.#database
+                .prepare("UPDATE runs SET repair_count = repair_count + 1, status = 'running', block_code = NULL, updated_at = ? WHERE id = ?")
+                .run(new Date().toISOString(), id);
+            this.#event(id, "repair.started", {
+                from: current.status,
+                to: "running",
+                repairCount: current.repairCount + 1,
+            });
+        });
+        return this.getRun(id);
+    }
+    beginReviewAttempt(id, maximum) {
+        let attempt = 0;
+        this.#transaction(() => {
+            const current = this.getRun(id);
+            if (current.cancelRequested) {
+                throw new MillError("OPERATOR_CANCELLED", "A cancelled run cannot begin a review attempt.", ExitCode.temporary);
+            }
+            if (current.status !== "verified") {
+                throw new MillError("INVALID_RUN_TRANSITION", `Cannot begin review from ${current.status}.`, ExitCode.configuration);
+            }
+            if (current.candidateCommit === undefined) {
+                throw new MillError("CANDIDATE_MISSING", "A review attempt requires an exact committed candidate.", ExitCode.configuration);
+            }
+            const row = this.#database
+                .prepare(`SELECT COUNT(*) AS count FROM run_events
+           WHERE run_id = ? AND type = 'review.started'
+             AND json_extract(data_json, '$.candidateCommit') = ?`)
+                .get(id, current.candidateCommit);
+            if (row.count >= maximum) {
+                throw new MillError("REVIEW_RETRY_BUDGET_EXHAUSTED", "The bounded review attempt budget is exhausted.", ExitCode.configuration);
+            }
+            attempt = row.count + 1;
+            this.#event(id, "review.started", {
+                candidateCommit: current.candidateCommit,
+                attempt,
+            });
+        });
+        return attempt;
+    }
+    recordBaselineQualification(input) {
+        this.#transaction(() => {
+            this.#database
+                .prepare(`INSERT OR IGNORE INTO baseline_qualifications(
+            approval_digest, repository_id, task_digest, config_digest,
+            base_commit, evidence_digest, created_at
+          ) VALUES (?, ?, ?, ?, ?, ?, ?)`)
+                .run(input.approvalDigest, input.repositoryId, input.taskDigest, input.configDigest, input.baseCommit, input.evidenceDigest, new Date().toISOString());
+            const stored = this.#database
+                .prepare(`SELECT repository_id, task_digest, config_digest, base_commit,
+                  evidence_digest
+           FROM baseline_qualifications WHERE approval_digest = ?`)
+                .get(input.approvalDigest);
+            if (stored?.repository_id !== input.repositoryId ||
+                stored.task_digest !== input.taskDigest ||
+                stored.config_digest !== input.configDigest ||
+                stored.base_commit !== input.baseCommit ||
+                stored.evidence_digest !== input.evidenceDigest) {
+                throw new MillError("QUALIFICATION_IDENTITY_COLLISION", "Baseline qualification identity conflicts with stored state.", ExitCode.io);
+            }
+        });
+    }
+    hasBaselineQualification(input) {
+        const row = this.#database
+            .prepare(`SELECT 1 AS present FROM baseline_qualifications
+         WHERE approval_digest = ? AND repository_id = ? AND task_digest = ?
+           AND config_digest = ? AND base_commit = ?`)
+            .get(input.approvalDigest, input.repositoryId, input.taskDigest, input.configDigest, input.baseCommit);
+        return row?.present === 1;
+    }
+    beginBuilderAttempt(id, maximum) {
+        if (this.getRun(id).cancelRequested) {
+            throw new MillError("OPERATOR_CANCELLED", "A cancelled run cannot consume another builder attempt.", ExitCode.temporary);
+        }
+        const result = this.#database
+            .prepare(`UPDATE runs SET attempt_count = attempt_count + 1, updated_at = ?
+         WHERE id = ? AND attempt_count < ? AND cancel_requested = 0`)
+            .run(new Date().toISOString(), id, maximum);
+        if (result.changes !== 1) {
+            if (this.getRun(id).cancelRequested) {
+                throw new MillError("OPERATOR_CANCELLED", "A cancelled run cannot consume another builder attempt.", ExitCode.temporary);
+            }
+            throw new MillError("BUILDER_RETRY_BUDGET_EXHAUSTED", "The builder retry budget is exhausted.", ExitCode.configuration);
+        }
+    }
+    setActiveProcess(id, process) {
+        if (process !== null &&
+            (!/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u.test(process.id) ||
+                !Number.isSafeInteger(process.pid) ||
+                process.pid <= 0 ||
+                process.processGroup !== process.pid ||
+                !/^sha256:[a-f0-9]{64}$/u.test(process.identity))) {
+            throw new MillError("INVALID_PROCESS_IDENTITY", "An active PID and its opaque process-start identity must be stored together.", ExitCode.configuration);
+        }
+        if (process === null) {
+            this.#database
+                .prepare("UPDATE runs SET active_process_id = NULL, active_pid = NULL, active_process_group = NULL, active_process_identity = NULL, updated_at = ? WHERE id = ?")
+                .run(new Date().toISOString(), id);
+            return;
+        }
+        const result = this.#database
+            .prepare(`UPDATE runs SET active_process_id = ?, active_pid = ?,
+         active_process_group = ?, active_process_identity = ?, updated_at = ?
+         WHERE id = ? AND cancel_requested = 0 AND active_process_id IS NULL`)
+            .run(process.id, process.pid, process.processGroup, process.identity, new Date().toISOString(), id);
+        if (result.changes !== 1) {
+            throw new MillError("ACTIVE_PROCESS_BINDING_REJECTED", "Cancellation or another active execution won before process binding.", ExitCode.temporary);
+        }
+    }
+    clearActiveProcess(id, processId) {
+        this.#database
+            .prepare(`UPDATE runs SET active_process_id = NULL, active_pid = NULL,
+         active_process_group = NULL, active_process_identity = NULL,
+         updated_at = ? WHERE id = ? AND active_process_id = ?`)
+            .run(new Date().toISOString(), id, processId);
+    }
+    requestCancellation(id) {
+        this.#transaction(() => {
+            const run = this.getRun(id);
+            if (terminal.has(run.status))
+                return;
+            this.#database
+                .prepare("UPDATE runs SET cancel_requested = 1, updated_at = ? WHERE id = ?")
+                .run(new Date().toISOString(), id);
+            this.#event(id, "run.cancellation_requested", {});
+        });
+        return this.getRun(id);
+    }
+    async backup() {
+        const destination = path.join(this.directory, `state-backup-${new Date().toISOString().replaceAll(/[:.]/gu, "-")}.sqlite3`);
+        await backup(this.#database, destination);
+        await chmod(destination, 0o600);
+        return destination;
+    }
+    events(id) {
+        return this.#database
+            .prepare("SELECT sequence, occurred_at, type, data_json FROM run_events WHERE run_id = ? ORDER BY sequence")
+            .all(id)
+            .map((row) => {
+            const item = row;
+            return {
+                sequence: item.sequence,
+                occurredAt: item.occurred_at,
+                type: item.type,
+                data: JSON.parse(item.data_json),
+            };
+        });
+    }
+    recordEvent(id, type, data) {
+        this.#transaction(() => this.#event(id, type, data));
+    }
+    admitWorkerInvocation(input) {
+        let disposition = "existing";
+        this.#transaction(() => {
+            this.getRun(input.runId);
+            const result = this.#database
+                .prepare(`INSERT OR IGNORE INTO worker_invocations(
+            id, run_id, phase, envelope_digest, envelope_json, created_at
+          ) VALUES (?, ?, ?, ?, ?, ?)`)
+                .run(input.invocationId, input.runId, input.phase, input.envelopeDigest, input.envelopeJson, new Date().toISOString());
+            const stored = this.#database
+                .prepare(`SELECT run_id, phase, envelope_digest, envelope_json
+           FROM worker_invocations WHERE id = ?`)
+                .get(input.invocationId);
+            if (stored?.run_id !== input.runId ||
+                stored.phase !== input.phase ||
+                stored.envelope_digest !== input.envelopeDigest ||
+                stored.envelope_json !== input.envelopeJson) {
+                throw new MillError("WORKER_INVOCATION_IDENTITY_CONFLICT", "Worker invocation identity was reused with a different immutable envelope.", ExitCode.configuration);
+            }
+            if (result.changes === 1) {
+                disposition = "created";
+                this.#invocationEvent(input.invocationId, "admitted", {
+                    envelopeDigest: input.envelopeDigest,
+                });
+                this.#event(input.runId, "worker.admitted", {
+                    invocationId: input.invocationId,
+                    phase: input.phase,
+                    envelopeDigest: input.envelopeDigest,
+                });
+            }
+        });
+        return disposition;
+    }
+    workerInvocationStatus(invocationId) {
+        const exists = this.#database
+            .prepare("SELECT 1 AS present FROM worker_invocations WHERE id = ?")
+            .get(invocationId);
+        if (exists?.present !== 1) {
+            throw new MillError("WORKER_INVOCATION_NOT_FOUND", "Worker invocation admission was not found.", ExitCode.data);
+        }
+        const events = this.#database
+            .prepare(`SELECT type FROM worker_invocation_events
+         WHERE invocation_id = ? ORDER BY sequence`)
+            .all(invocationId);
+        if (events.some((event) => event.type === "reconciled")) {
+            return "reconciled";
+        }
+        if (events.some((event) => event.type === "uncertain"))
+            return "uncertain";
+        if (events.some((event) => event.type === "settled"))
+            return "settled";
+        if (events.some((event) => event.type === "launch_started")) {
+            return "launch_started";
+        }
+        return "admitted";
+    }
+    markWorkerLaunchStarted(invocationId) {
+        this.#transaction(() => {
+            const status = this.workerInvocationStatus(invocationId);
+            if (status !== "admitted") {
+                throw new MillError("WORKER_INVOCATION_POSSIBLY_STARTED", "A worker invocation with this identity may already have started and cannot be replayed.", ExitCode.temporary, { status });
+            }
+            this.#invocationEvent(invocationId, "launch_started", {});
+        });
+    }
+    settleWorkerInvocation(invocationId, outcome, details = {}) {
+        this.#transaction(() => {
+            const status = this.workerInvocationStatus(invocationId);
+            if (status !== "launch_started") {
+                throw new MillError("WORKER_INVOCATION_SETTLEMENT_CONFLICT", "Worker settlement requires exactly one started, unsettled invocation.", ExitCode.configuration, { status });
+            }
+            this.#invocationEvent(invocationId, outcome === "uncertain" ? "uncertain" : "settled", { outcome, ...details });
+        });
+    }
+    recordWorkerProcessExit(runId, invocationId, processId) {
+        this.#transaction(() => {
+            this.getRun(runId);
+            const invocation = this.#database
+                .prepare("SELECT run_id FROM worker_invocations WHERE id = ?")
+                .get(invocationId);
+            if (invocation?.run_id !== runId ||
+                this.workerInvocationStatus(invocationId) !== "launch_started") {
+                throw new MillError("WORKER_PROCESS_EXIT_CONFLICT", "Process exit evidence requires its one started, unsettled worker invocation.", ExitCode.configuration);
+            }
+            const active = this.#database
+                .prepare("SELECT active_process_id FROM runs WHERE id = ?")
+                .get(runId);
+            if ((processId !== undefined && active.active_process_id !== processId) ||
+                (processId === undefined && active.active_process_id !== null)) {
+                throw new MillError("WORKER_PROCESS_EXIT_CONFLICT", "Process exit evidence does not match the active worker identity.", ExitCode.configuration);
+            }
+            this.#invocationEvent(invocationId, "process_exited", {
+                processId: processId ?? null,
+            });
+            this.#database
+                .prepare(`UPDATE runs SET active_process_id = NULL, active_pid = NULL,
+           active_process_group = NULL, active_process_identity = NULL,
+           updated_at = ? WHERE id = ?`)
+                .run(new Date().toISOString(), runId);
+            this.#event(runId, "worker.process_exited", { invocationId });
+        });
+    }
+    unresolvedMutatingWorkerInvocations(runId) {
+        this.getRun(runId);
+        const rows = this.#database
+            .prepare(`SELECT id, phase FROM worker_invocations
+         WHERE run_id = ? AND phase IN ('build', 'repair')
+         ORDER BY created_at, id`)
+            .all(runId);
+        return rows.flatMap((row) => {
+            const status = this.workerInvocationStatus(row.id);
+            if (status !== "launch_started" && status !== "uncertain")
+                return [];
+            const uncertain = this.#database
+                .prepare(`SELECT data_json FROM worker_invocation_events
+           WHERE invocation_id = ? AND type = 'uncertain'
+           ORDER BY sequence DESC LIMIT 1`)
+                .get(row.id);
+            const observedExit = this.#database
+                .prepare(`SELECT 1 AS present FROM worker_invocation_events
+           WHERE invocation_id = ? AND type = 'process_exited' LIMIT 1`)
+                .get(row.id);
+            let processExited = observedExit?.present === 1;
+            if (uncertain !== undefined) {
+                try {
+                    const details = JSON.parse(uncertain.data_json);
+                    processExited = processExited || details.processExited === true;
+                }
+                catch {
+                    // Preserve separately journaled process-exit evidence.
+                }
+            }
+            return [
+                {
+                    invocationId: row.id,
+                    phase: row.phase,
+                    status,
+                    processExited,
+                },
+            ];
+        });
+    }
+    reconcileWorkerInvocation(runId, invocationId, reason) {
+        this.#transaction(() => {
+            this.getRun(runId);
+            const invocation = this.#database
+                .prepare(`SELECT run_id, phase FROM worker_invocations WHERE id = ?`)
+                .get(invocationId);
+            if (invocation?.run_id !== runId ||
+                (invocation.phase !== "build" && invocation.phase !== "repair")) {
+                throw new MillError("WORKER_INVOCATION_RECONCILIATION_CONFLICT", "Worker invocation is not a mutating admission for this run.", ExitCode.configuration);
+            }
+            const status = this.workerInvocationStatus(invocationId);
+            if (status !== "launch_started" && status !== "uncertain") {
+                throw new MillError("WORKER_INVOCATION_RECONCILIATION_CONFLICT", "Only an unresolved mutating worker invocation can be reconciled.", ExitCode.configuration, { status });
+            }
+            this.#invocationEvent(invocationId, "reconciled", { reason });
+            this.#event(runId, "worker.reconciled", {
+                invocationId,
+                phase: invocation.phase,
+                reason,
+            });
+        });
+    }
+    #transaction(action) {
+        try {
+            this.#database.exec("BEGIN IMMEDIATE");
+            action();
+            this.#database.exec("COMMIT");
+        }
+        catch (error) {
+            try {
+                this.#database.exec("ROLLBACK");
+            }
+            catch {
+                // Preserve the original state error.
+            }
+            if (error instanceof MillError)
+                throw error;
+            throw new MillError("STATE_WRITE_FAILED", "Operational state transaction failed.", ExitCode.io, { cause: String(error) });
+        }
+    }
+    #event(id, type, data) {
+        this.#database
+            .prepare("INSERT INTO run_events(run_id, occurred_at, type, data_json) VALUES (?, ?, ?, ?)")
+            .run(id, new Date().toISOString(), type, JSON.stringify(data));
+    }
+    #invocationEvent(invocationId, type, data) {
+        this.#database
+            .prepare(`INSERT INTO worker_invocation_events(
+          invocation_id, occurred_at, type, data_json
+        ) VALUES (?, ?, ?, ?)`)
+            .run(invocationId, new Date().toISOString(), type, JSON.stringify(data));
+    }
+}
+export async function acquireWriterLease(store) {
+    const leasePath = path.join(store.directory, "writer-lease.sqlite3");
+    return await acquireExclusiveLease({
+        path: leasePath,
+        activeCode: "WRITER_ALREADY_ACTIVE",
+        activeMessage: "Another Mill writer is active for this repository.",
+        unavailableCode: "WRITER_LEASE_UNAVAILABLE",
+        unavailableMessage: "The repository writer lease could not be acquired safely.",
+    });
+}
+export async function restoreStateBackup(repositoryId, commonDirectory, backupPath) {
+    const directory = repositoryStateDirectory(repositoryId, commonDirectory);
+    const resolvedBackup = path.resolve(backupPath);
+    if (!isWithin(directory, resolvedBackup)) {
+        throw new MillError("INVALID_STATE_BACKUP", "State backup must be a Mill-owned file in this repository namespace.", ExitCode.configuration);
+    }
+    const information = await lstat(resolvedBackup);
+    if (!information.isFile() || information.isSymbolicLink()) {
+        throw new MillError("INVALID_STATE_BACKUP", "State backup is not a regular file.", ExitCode.configuration);
+    }
+    const databasePath = path.join(directory, "state.sqlite3");
+    const temporaryPath = path.join(directory, `restore-${randomUUID()}.sqlite3`);
+    const expectedWorktrees = new Set();
+    let quarantineManifest;
+    const moved = [];
+    try {
+        await copyFile(resolvedBackup, temporaryPath, constants.COPYFILE_EXCL);
+        await chmod(temporaryPath, 0o600);
+        let candidate;
+        try {
+            candidate = new DatabaseSync(temporaryPath, {
+                readOnly: true,
+                allowExtension: false,
+                enableDoubleQuotedStringLiterals: false,
+            });
+            candidate.exec("PRAGMA trusted_schema = OFF; PRAGMA foreign_keys = ON;");
+            const integrity = candidate.prepare("PRAGMA integrity_check").get();
+            const version = candidate
+                .prepare("SELECT value FROM metadata WHERE key = 'schema_version'")
+                .get();
+            const requiredObjects = candidate
+                .prepare(`SELECT name FROM sqlite_schema
+           WHERE (type = 'table' AND name IN ('metadata', 'runs', 'run_events'))
+              OR (type = 'table' AND name = 'baseline_qualifications')
+              OR (type = 'table' AND name IN ('worker_invocations', 'worker_invocation_events'))
+              OR (type = 'trigger' AND name IN (
+                'run_events_no_update', 'run_events_no_delete',
+                'worker_invocations_no_update', 'worker_invocations_no_delete',
+                'worker_invocation_events_no_update', 'worker_invocation_events_no_delete'
+              ))`)
+                .all();
+            const worktrees = candidate
+                .prepare("SELECT worktree_path FROM runs WHERE worktree_path IS NOT NULL")
+                .all();
+            if (integrity?.integrity_check !== "ok" ||
+                (version?.value !== "1" && version?.value !== "2") ||
+                new Set(requiredObjects.map((object) => object.name)).size !==
+                    (version.value === "1" ? 6 : 12)) {
+                throw new Error("backup integrity, schema version, or objects invalid");
+            }
+            const worktreesDirectory = path.join(directory, "worktrees");
+            for (const row of worktrees) {
+                const resolved = path.resolve(row.worktree_path);
+                if (!isWithin(worktreesDirectory, resolved)) {
+                    throw new Error("backup references a worktree outside Mill state");
+                }
+                expectedWorktrees.add(resolved);
+            }
+        }
+        catch (error) {
+            throw new MillError("INVALID_STATE_BACKUP", "State backup failed integrity and schema validation.", ExitCode.data, { cause: String(error) });
+        }
+        finally {
+            candidate?.close();
+        }
+        const worktreesDirectory = path.join(directory, "worktrees");
+        const entries = await readdir(worktreesDirectory, { withFileTypes: true });
+        const orphaned = entries
+            .map((entry) => ({
+            entry,
+            original: path.join(worktreesDirectory, entry.name),
+        }))
+            .filter(({ original }) => !expectedWorktrees.has(path.resolve(original)));
+        if (orphaned.length > 0) {
+            for (const { entry } of orphaned) {
+                if (!entry.isDirectory() || entry.isSymbolicLink()) {
+                    throw new MillError("UNSAFE_ORPHANED_WORKTREE", "Restore found an unclassified entry in the Mill worktree directory.", ExitCode.configuration, { name: entry.name });
+                }
+            }
+            const quarantineId = `restore-${new Date()
+                .toISOString()
+                .replaceAll(/[:.]/gu, "-")}-${randomUUID()}`;
+            const quarantineDirectory = path.join(directory, "quarantine", quarantineId);
+            await mkdir(quarantineDirectory, { recursive: true, mode: 0o700 });
+            await chmod(quarantineDirectory, 0o700);
+            quarantineManifest = path.join(quarantineDirectory, "manifest.json");
+            const planned = orphaned.map(({ entry, original }) => ({
+                original,
+                quarantined: path.join(quarantineDirectory, entry.name),
+            }));
+            await writeFile(quarantineManifest, `${JSON.stringify({
+                schemaVersion: "1",
+                repositoryId,
+                backupPath: resolvedBackup,
+                protocol: "database_swap_commit_point",
+                worktrees: planned,
+            }, null, 2)}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
+            for (const item of planned) {
+                await rename(item.original, item.quarantined);
+                moved.push(item);
+            }
+        }
+        await rm(`${databasePath}-wal`, { force: true });
+        await rm(`${databasePath}-shm`, { force: true });
+        await rename(temporaryPath, databasePath);
+        return {
+            quarantinedCount: moved.length,
+            ...(quarantineManifest === undefined ? {} : { quarantineManifest }),
+        };
+    }
+    catch (error) {
+        for (const item of moved.toReversed()) {
+            try {
+                await rename(item.quarantined, item.original);
+            }
+            catch {
+                // The recovery manifest preserves attended recovery evidence.
+            }
+        }
+        throw error;
+    }
+    finally {
+        await rm(temporaryPath, { force: true });
+    }
+}
+export async function purgeRepositoryState(repositoryId, commonDirectory) {
+    const directory = repositoryStateDirectory(repositoryId, commonDirectory);
+    try {
+        await access(directory);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    await rm(directory, { recursive: true });
+}
+//# sourceMappingURL=state.js.map