@volter/twin-planetscale 0.1.0

package/dist/api/src/semantics/deploy-requests.js

@@ -0,0 +1,491 @@
+import { closeSession, executeSql, scopeImage } from "../../../src/planetscale-store.js";
+import { quoteSqlLiteral } from "../../../src/planetscale-row.js";
+import { tableKey } from "../../../src/planetscale-sql.js";
+import { heldAccesses } from "../token-gate.js";
+import { branchScope, branchesOf, removeBranch, storeCtx } from "./branches.js";
+import { actorOf, mintId, page } from "./shared.js";
+import { audit, callActor, SYSTEM } from "./audit.js";
+export const CHECK_AFTER = 30_000;
+export const RUN_FOR = 120_000;
+export const REVERT_WINDOW = 30 * 60_000;
+const later = (iso, ms) => new Date(Date.parse(iso) + ms).toISOString();
+const unprocessable = (ctx, message) => ctx.refuse({ status: 422, code: 'unprocessable_entity', message });
+const body = (ctx) => (ctx.body && typeof ctx.body === 'object' && !Array.isArray(ctx.body) ? ctx.body : {});
+/** A column's definition as SHOW CREATE TABLE prints it (`varchar(191) NOT NULL`), read off the branch's own table. */
+async function showCreate(ctx, scope, table) {
+    const run = await executeSql({ ...storeCtx(ctx), ...(scope ? { scope } : {}) }, `SHOW CREATE TABLE \`${table.replace(/`/g, '``')}\``, null);
+    await closeSession({ ...storeCtx(ctx), ...(scope ? { scope } : {}) }, run.session.id);
+    return String(run.outcome.rows?.[0]?.[1] ?? '');
+}
+const columnLine = (create, column) => {
+    const line = create.split('\n').find((l) => l.trim().startsWith(`\`${column}\` `));
+    return (line ?? '').trim().replace(/^`[^`]+`\s+/, '').replace(/,$/, '');
+};
+const q = (name) => `\`${name.replace(/`/g, '``')}\``;
+/** The branch's schema against the schema it was branched from: the deploy request's operations and lint errors. */
+async function diffOf(ctx, database, branch) {
+    const scope = branchScope(database, String(branch.name));
+    const now = new Map(scopeImage(ctx.root, scope).tables.map((t) => [tableKey(t.name), t]));
+    const before = new Map((branch._parent_schema ?? []).map((t) => [tableKey(t.name), t]));
+    const operations = [];
+    const lint = [];
+    for (const [key, t] of now) {
+        const prior = before.get(key);
+        if (!prior) {
+            const ddl = await showCreate(ctx, scope, t.name);
+            operations.push({ table: t.name, kind: 'create', added: [], dropped: [], ddl, apply: [ddl], can_drop_data: false });
+            continue;
+        }
+        const cols = new Map(t.columns.map((c) => [c.name.toLowerCase(), c]));
+        const priorCols = new Map(prior.columns.map((c) => [c.name.toLowerCase(), c]));
+        const dropped = prior.columns.filter((c) => !cols.has(c.name.toLowerCase())).map((c) => c.name);
+        const addedCols = t.columns.filter((c) => !priorCols.has(c.name.toLowerCase()));
+        const changed = t.columns.some((c) => priorCols.has(c.name.toLowerCase()) && JSON.stringify(priorCols.get(c.name.toLowerCase())) !== JSON.stringify(c))
+            || JSON.stringify([t.primaryKey, t.uniques, t.indexes ?? []]) !== JSON.stringify([prior.primaryKey, prior.uniques, prior.indexes ?? []]);
+        if (changed) {
+            lint.push(unsupportedChange(t.name));
+            continue;
+        }
+        if (!dropped.length && !addedCols.length)
+            continue;
+        const create = addedCols.length ? await showCreate(ctx, scope, t.name) : '';
+        const added = addedCols.map((c) => {
+            const i = t.columns.indexOf(c);
+            return { name: c.name, definition: columnLine(create, c.name), after: i > 0 ? t.columns[i - 1].name : null };
+        });
+        const drops = dropped.map((c) => `DROP COLUMN ${q(c)}`);
+        const adds = added.map((a) => `ADD COLUMN ${q(a.name)} ${a.definition}${a.after ? ` AFTER ${q(a.after)}` : ' FIRST'}`);
+        const apply = [...(drops.length ? [`ALTER TABLE ${q(t.name)} ${drops.join(', ')}`] : []), ...(adds.length ? [`ALTER TABLE ${q(t.name)} ${adds.join(', ')}`] : [])];
+        operations.push({ table: t.name, kind: 'alter', added, dropped, ddl: `ALTER TABLE ${q(t.name)} ${[...drops, ...adds].join(', ')}`, apply, can_drop_data: dropped.length > 0 });
+    }
+    for (const [key, t] of before)
+        if (!now.has(key))
+            operations.push({ table: t.name, kind: 'drop', added: [], dropped: [], ddl: `DROP TABLE ${q(t.name)}`, apply: [`DROP TABLE ${q(t.name)}`], can_drop_data: true });
+    return { operations, lint };
+}
+/** Whether every operation can be deployed with ALGORITHM=INSTANT: "Adding or dropping a column (with some exceptions)"
+ *  is; "Adding or dropping an index", a foreign key and a column's type are not
+ *  (https://planetscale.com/docs/vitess/schema-changes/deploy-requests, "Supported operations"). Where the page stops: it
+ *  does not list creating or dropping a table, which the twin reads as not instant. */
+const instantEligible = (ops) => ops.length > 0 && ops.every((o) => o.kind === 'alter');
+/** The lint error for a change the twin does not compute (a column's type or definition, a key, an index). */
+function unsupportedChange(table) {
+    return { lint_error: 'UNSUPPORTED_BY_TWIN', table_name: table, error_description: `The twin does not compute this change to ${table}: only created and dropped tables, and added and dropped columns` };
+}
+/** The spec's Deployment for a deploy request as it stands. */
+export function deploymentOf(dr) {
+    const ops = (dr._operations ?? []);
+    const state = String(dr.deployment_state);
+    const opState = ['complete', 'complete_pending_revert', 'complete_revert'].includes(state) ? 'complete'
+        : state === 'in_progress' ? 'in_progress' : state === 'queued' ? 'queued' : 'pending';
+    const at = String(dr.updated_at);
+    return {
+        id: String(dr._deployment_id), auto_cutover: dr._auto_cutover !== false, auto_delete_branch: dr._auto_delete_branch === true, created_at: String(dr.created_at),
+        cutover_at: dr._finished_at ?? null, cutover_expiring: false, deploy_check_errors: dr._lint?.length ? 'The deploy request is not deployable' : null,
+        finished_at: dr._finished_at ?? null, force_cutover_requested_at: null, queued_at: dr._queued_at ?? null,
+        ready_to_cutover_at: dr._finished_at ?? null, started_at: dr._started_at ?? null, state,
+        submitted_at: dr._queued_at ?? null, updated_at: at, into_branch: String(dr.into_branch),
+        deploy_request_number: Number(dr.number), deployable: dr._deployable === true, preceding_deployments: [],
+        deploy_operations: ops.map((o, i) => ({
+            id: `${String(dr._deployment_id)}-${i + 1}`, state: opState, keyspace_name: String(dr._database), table_name: o.table,
+            operation_name: o.kind === 'create' ? 'CREATE' : o.kind === 'drop' ? 'DROP' : 'ALTER', eta_seconds: 0,
+            progress_percentage: opState === 'complete' ? 100 : 0, deploy_error_docs_url: null, ddl_statement: o.ddl, syntax_highlighted_ddl: o.ddl,
+            created_at: String(dr.created_at), updated_at: at, throttled_at: null, can_drop_data: o.can_drop_data, table_locked: false,
+            table_recently_used: false, table_recently_used_at: null, removed_foreign_key_names: [], deploy_errors: null,
+        })),
+        deploy_operation_summaries: [], lint_errors: (dr._lint ?? []), sequential_diff_dependencies: [], lookup_vindex_operations: [],
+        throttler_configurations: null,
+        deployment_revert_request: state === 'complete_revert' ? { id: `${String(dr._deployment_id)}-revert`, state: 'complete', created_at: dr.closed_at } : null,
+        actor: dr.actor, cutover_actor: dr._finished_at ? dr.actor : null, cancelled_actor: null, schema_last_updated_at: at,
+        table_locked: false, locked_table_name: null, instant_ddl: dr._instant === true, instant_ddl_eligible: instantEligible(ops), queue_paused: false, queue_pause_reason: null,
+    };
+}
+const requestsOf = (ctx, database) => ctx.rowsRaw('DatabaseDeployRequest').filter((d) => d._database === database);
+/** The spec's DatabaseDeployRequest, with its deployment, from the stored row (a write's answer carries no bookkeeping). */
+const view = (ctx, dr) => {
+    const raw = ctx.rowsRaw('DatabaseDeployRequest').find((d) => d.id === dr.id) ?? dr;
+    return { ...ctx.get('DatabaseDeployRequest', String(dr.id)), deployment: deploymentOf(raw) };
+};
+function createdDatabase(ctx) {
+    const name = String(ctx.call.params.database ?? '');
+    const db = ctx.rowsRaw('Database').find((d) => d.name === name && !d._deleted_at);
+    return db ? { db } : { refused: ctx.notFound('Database', name, 'database') };
+}
+function requestOf(ctx) {
+    const { refused, db } = createdDatabase(ctx);
+    if (refused)
+        return { refused };
+    const dr = requestsOf(ctx, String(db.name)).find((d) => String(d.number) === String(ctx.call.params.number));
+    return dr ? { db, dr } : { refused: ctx.notFound('DatabaseDeployRequest', String(ctx.call.params.number), 'number') };
+}
+/** A deploy request's audit event. */
+async function drEvent(ctx, db, dr, action, actor) {
+    await audit(ctx, String(db._organization ?? ''), 'database_deploy_request', action, { type: 'DatabaseDeployRequest', id: String(dr.id), name: `#${String(dr.number)}` }, { actor, auditable: { type: 'Database', id: String(db.id), name: String(db.name) } });
+}
+/** Who is acting: the calling token's id, or the person a page names (screens pass it). */
+export const actingAs = (ctx) => /^([^:\s]+):/.exec(ctx.call.request.headers.get('authorization') ?? '')?.[1] ?? 'world';
+async function createDeployRequest(ctx) {
+    const { refused, db } = createdDatabase(ctx);
+    if (refused)
+        return refused;
+    const database = String(db.name);
+    const b = body(ctx);
+    const branchName = typeof b.branch === 'string' ? b.branch : '';
+    const intoName = typeof b.into_branch === 'string' ? b.into_branch : '';
+    if (!branchName || !intoName)
+        return unprocessable(ctx, 'branch and into_branch are required');
+    const branch = branchesOf(ctx, database).find((x) => x.name === branchName);
+    if (!branch)
+        return ctx.notFound('DatabaseBranch', branchName, 'branch');
+    const into = branchesOf(ctx, database).find((x) => x.name === intoName);
+    if (!into)
+        return ctx.notFound('DatabaseBranch', intoName, 'into_branch');
+    if (branch.id === into.id)
+        return unprocessable(ctx, 'A branch cannot be deployed into itself');
+    // a gated deployment (auto_cutover false, "Apply changes" by hand) is not modelled: complete_gated_deploy_request is the gap
+    if (b.auto_cutover === false)
+        return unprocessable(ctx, 'Gated deployments (auto_cutover false) are not modelled by the twin');
+    if (into.safe_migrations !== true)
+        return unprocessable(ctx, `Safe migrations must be enabled on ${intoName} before you can create a deploy request into it`);
+    if (requestsOf(ctx, database).some((d) => d.branch === branchName && d.state === 'open'))
+        return unprocessable(ctx, `An open deploy request already exists for ${branchName}`);
+    const { operations, lint } = await diffOf(ctx, database, branch);
+    const number = requestsOf(ctx, database).length + 1;
+    const id = mintId(ctx, 'DatabaseDeployRequest', 'dr', `${database}/${number}`);
+    const org = String(ctx.call.params.organization);
+    const at = ctx.occurredAt;
+    const notes = typeof b.notes === 'string' ? b.notes : '';
+    const record = await ctx.write('DatabaseDeployRequest', id, {
+        id, number, actor: actorOf(ctx), closed_by: null, branch: branchName, branch_id: String(branch.id), branch_deleted: false,
+        branch_deleted_by: null, branch_deleted_at: null, into_branch: intoName, into_branch_sharded: false, into_branch_shard_count: 1,
+        into_branch_keyspace_count: 1, approved: false, state: 'open', deployment_state: 'pending', num_comments: 0,
+        html_url: `https://app.planetscale.com/${org}/${database}/deploy-requests/${number}`, notes, html_body: notes ? `<p>${notes.replace(/[<&>]/g, (c) => ({ '<': '&lt;', '&': '&amp;', '>': '&gt;' })[c])}</p>` : '',
+        created_at: at, updated_at: at, closed_at: null, deployed_at: null,
+        _database: database, _deployment_id: mintId(ctx, 'DatabaseDeployRequest', 'dp', `${database}/${number}/deployment`), _creator: actingAs(ctx),
+        _operations: operations, _lint: lint, _deployable: lint.length === 0 && operations.length > 0,
+        // "When enabled, will delete the branch once the DR successfully completes" (the spec's auto_delete_branch)
+        _auto_cutover: b.auto_cutover !== false, _auto_delete_branch: b.auto_delete_branch === true,
+    }, 'deploy_request.create');
+    await drEvent(ctx, db, record, 'created', callActor(ctx));
+    return ctx.reply(view(ctx, record), 201);
+}
+async function getDeployRequest(ctx) {
+    const { refused, dr } = requestOf(ctx);
+    return refused ?? ctx.reply(view(ctx, dr));
+}
+async function getDeployment(ctx) {
+    const { refused, dr } = requestOf(ctx);
+    return refused ?? ctx.reply(deploymentOf(dr));
+}
+async function listDeployOperations(ctx) {
+    const { refused, dr } = requestOf(ctx);
+    return refused ?? page(ctx, deploymentOf(dr).deploy_operations);
+}
+/** list_deploy_requests, newest first (the twin's order), filtered by `state`, `branch` and `into_branch`. */
+async function listDeployRequests(ctx) {
+    const { refused, db } = createdDatabase(ctx);
+    if (refused)
+        return refused;
+    const p = new URL(ctx.call.request.url).searchParams;
+    const rows = requestsOf(ctx, String(db.name)).filter((d) => (!p.get('state') || d.state === p.get('state'))
+        && (!p.get('branch') || d.branch === p.get('branch')) && (!p.get('into_branch') || d.into_branch === p.get('into_branch')));
+    return page(ctx, [...rows].sort((a, b) => Number(b.number) - Number(a.number)).map((d) => view(ctx, d)));
+}
+/** The reviews of a deploy request (bookkeeping `_deploy_review` records), oldest first. */
+export const reviewsOf = (ctx, dr) => ctx.tree().filter((r) => r.type === '_deploy_review').map((r) => ({ ...ctx.own(r), id: String(r.id) })).filter((r) => r.deploy_request === dr.id);
+/**
+ * Record a review. `reviewer` is who approves: a token's id, or `person:<email>` from the deploy request's page;
+ * `actor` is the spec's actor object. With approval required, a creator cannot approve its own request, nor a person the
+ * token that created it (`_created_by` on the token, set on the service tokens page).
+ */
+export async function recordReview(ctx, db, dr, reviewer, actor, state, text, auditActor) {
+    if (dr.state !== 'open')
+        return unprocessable(ctx, 'The deploy request is closed');
+    if (state === 'approved' && db.require_approval_for_deploy === true) {
+        if (reviewer === dr._creator)
+            return unprocessable(ctx, 'You cannot approve your own deploy request');
+        const creatorToken = ctx.rowsRaw('ServiceToken').find((t) => t.id === dr._creator);
+        if (creatorToken && reviewer === `person:${String(creatorToken._created_by ?? '')}`)
+            return unprocessable(ctx, 'You cannot approve a deploy request created by a service token you created');
+    }
+    const at = ctx.occurredAt;
+    const id = `${String(dr.id)}-review-${reviewsOf(ctx, dr).length + 1}`;
+    const review = { id, body: text, html_body: text ? `<p>${text}</p>` : '', state, created_at: at, updated_at: at, actor, deploy_request: dr.id };
+    await ctx.record('_deploy_review', review, id);
+    if (state === 'approved' && dr.approved !== true)
+        await ctx.write('DatabaseDeployRequest', String(dr.id), { ...ctx.own(dr), approved: true, updated_at: at }, 'deploy_request.approve');
+    if (state === 'approved')
+        await audit(ctx, String(db._organization ?? ''), 'deploy_request_review', 'approved', { type: 'DeployRequestReview', id, name: `#${String(dr.number)}` }, { actor: auditActor, auditable: { type: 'Database', id: String(db.id), name: String(db.name) } });
+    const { deploy_request: _dr, ...answer } = review;
+    return answer;
+}
+async function reviewDeployRequest(ctx) {
+    const { refused, db, dr } = requestOf(ctx);
+    if (refused)
+        return refused;
+    const b = body(ctx);
+    const state = b.state === undefined ? 'commented' : String(b.state);
+    if (state !== 'approved' && state !== 'commented')
+        return unprocessable(ctx, 'state must be approved or commented');
+    const held = heldAccesses(ctx, String(db.name));
+    if (held && state === 'approved' && !held.has('approve_deploy_request'))
+        return ctx.refuse({ status: 403, code: 'forbidden', message: 'Forbidden: approving needs approve_deploy_request' });
+    const out = await recordReview(ctx, db, dr, actingAs(ctx), actorOf(ctx), state, typeof b.body === 'string' ? b.body : '', callActor(ctx));
+    return out instanceof Response ? out : ctx.reply(out, 201);
+}
+async function listReviews(ctx) {
+    const { refused, dr } = requestOf(ctx);
+    if (refused)
+        return refused;
+    return page(ctx, reviewsOf(ctx, dr).map(({ deploy_request: _d, ...r }) => r));
+}
+/** queue_deploy_request: a deployable request, approved where the database requires it, joins the serial queue. */
+async function queueDeployRequest(ctx) {
+    const { refused, db, dr } = requestOf(ctx);
+    if (refused)
+        return refused;
+    if (dr.state !== 'open')
+        return unprocessable(ctx, 'The deploy request is closed');
+    if (dr.deployment_state !== 'ready')
+        return unprocessable(ctx, dr.deployment_state === 'pending' ? 'The deploy request is still being checked' : `The deploy request cannot be deployed from ${String(dr.deployment_state)}`);
+    if (db.require_approval_for_deploy === true && dr.approved !== true)
+        return unprocessable(ctx, 'The deploy request must be approved before it can be deployed');
+    const b = body(ctx);
+    // "Instant deployments will apply schema changes faster, however, these schema changes must be auto-applied and
+    // cannot be reverted"; "all schema changes in the deploy request must be instantly deployable" (the deploy-requests page)
+    const instant = b.instant_ddl === true;
+    if (instant && !instantEligible((dr._operations ?? [])))
+        return unprocessable(ctx, 'The deploy request is not instantly deployable');
+    const refusal = ctx.legal('DatabaseDeployRequest', 'deployment_state', 'queue_deploy_request', 'ready', 'queued', String(dr.id));
+    if (refusal)
+        return ctx.refuse(refusal);
+    const at = ctx.occurredAt;
+    const record = await ctx.write('DatabaseDeployRequest', String(dr.id), { ...ctx.own(dr), deployment_state: 'queued', updated_at: at, _queued_at: at, ...(instant ? { _instant: true } : {}) }, 'deploy_request.queue');
+    return ctx.reply(view(ctx, record));
+}
+async function closeDeployRequest(ctx) {
+    const { refused, dr } = requestOf(ctx);
+    if (refused)
+        return refused;
+    if (body(ctx).state !== 'closed')
+        return unprocessable(ctx, 'state must be closed');
+    if (dr.state !== 'open')
+        return unprocessable(ctx, 'The deploy request is already closed');
+    if (['queued', 'in_progress', 'complete_pending_revert'].includes(String(dr.deployment_state)))
+        return unprocessable(ctx, 'A deploy request being deployed cannot be closed');
+    const refusal = ctx.legal('DatabaseDeployRequest', 'state', 'close_deploy_request', 'open', 'closed', String(dr.id));
+    if (refusal)
+        return ctx.refuse(refusal);
+    const at = ctx.occurredAt;
+    const record = await ctx.write('DatabaseDeployRequest', String(dr.id), { ...ctx.own(dr), state: 'closed', closed_at: at, closed_by: actorOf(ctx), updated_at: at }, 'deploy_request.close');
+    await drEvent(ctx, ctx.rowsRaw('Database').find((d) => d.name === dr._database), record, 'closed', callActor(ctx));
+    return ctx.reply(view(ctx, record));
+}
+/** Run statements against the base branch through the pack root's SQL, in one session closed after. */
+async function runOnBase(ctx, database, into, at, statements) {
+    const scope = branchScope(database, into);
+    const sctx = { ...storeCtx(ctx, at), ...(scope ? { scope } : {}) };
+    let session = null;
+    for (const sql of statements)
+        session = (await executeSql(sctx, sql, session)).session.id;
+    if (session)
+        await closeSession(sctx, session);
+}
+/** Deploy a request's diff to its base at `at`, saving what a revert needs (each dropped column's values by primary key,
+ *  each dropped table's definition and rows). */
+export async function applyDeploy(ctx, dr, at) {
+    const database = String(dr._database);
+    const into = String(dr.into_branch);
+    const scope = branchScope(database, into);
+    const image = scopeImage(ctx.root, scope);
+    const saved = [];
+    const statements = [];
+    for (const op of (dr._operations ?? [])) {
+        const table = image.tables.find((t) => tableKey(t.name) === tableKey(op.table));
+        const rows = image.rows.find((r) => tableKey(r.table) === tableKey(op.table))?.rows ?? [];
+        if (op.kind === 'drop' && table)
+            saved.push(await savedDroppedTable(ctx, scope, op.table, table.name, rows));
+        if (op.kind === 'alter' && table && op.dropped.length) {
+            const create = await showCreate(ctx, scope, table.name);
+            saved.push({
+                table: op.table, kind: 'columns', primaryKey: table.primaryKey,
+                columns: op.dropped.map((c) => {
+                    const i = table.columns.findIndex((x) => x.name.toLowerCase() === c.toLowerCase());
+                    const def = table.columns[i];
+                    return { name: def.name, definition: columnLine(create, def.name), after: i > 0 ? table.columns[i - 1].name : null, nullable: def.nullable !== false, hasDefault: def.defaultValue !== undefined || def.defaultCurrentTimestamp !== undefined };
+                }),
+                rows: rows.map((r) => ({ key: Object.fromEntries(table.primaryKey.map((k) => [k, r.cells[k] ?? null])), values: Object.fromEntries(op.dropped.map((c) => [c, r.cells[table.columns.find((x) => x.name.toLowerCase() === c.toLowerCase()).name] ?? null])) })),
+            });
+        }
+        statements.push(...op.apply);
+    }
+    await runOnBase(ctx, database, into, at, statements);
+    return { ...ctx.own(dr), _saved: saved };
+}
+/** What a revert needs of a table the deploy drops: its definition and its rows. */
+async function savedDroppedTable(ctx, scope, table, name, rows) {
+    return { table, kind: 'drop', create: await showCreate(ctx, scope, name), rows: rows.map((r) => r.cells) };
+}
+/** A dropped table put back as it was: "the status of the two tables is flipped, bringing the former table back"
+ *  (https://planetscale.com/docs/vitess/schema-changes/safe-migrations, "Schema revert"). */
+function revertDroppedTable(table, saved) {
+    const s = saved.find((x) => x.kind === 'drop' && x.table === table);
+    if (!s)
+        return [];
+    return [String(s.create), ...s.rows.map((cells) => {
+            const cols = Object.keys(cells);
+            return `INSERT INTO ${q(table)} (${cols.map(q).join(', ')}) VALUES (${cols.map((c) => quoteSqlLiteral(cells[c] ?? null)).join(', ')})`;
+        })];
+}
+/** The statements that undo a deployment, or the reason the page says the revert fails. */
+function revertPlan(ctx, dr) {
+    const database = String(dr._database);
+    const image = scopeImage(ctx.root, branchScope(database, String(dr.into_branch)));
+    const statements = [];
+    const saved = (dr._saved ?? []);
+    for (const op of [...(dr._operations ?? [])].reverse()) {
+        if (op.kind === 'create') {
+            statements.push(`DROP TABLE ${q(op.table)}`);
+            continue;
+        }
+        if (op.kind === 'drop') {
+            statements.push(...revertDroppedTable(op.table, saved));
+            continue;
+        }
+        // an altered table: drop what the deploy added (its data is not retained), re-add what it dropped with the values
+        // the rows had; rows inserted since take the column's default, or NULL
+        const s = saved.find((x) => x.kind === 'columns' && x.table === op.table);
+        const current = image.rows.find((r) => tableKey(r.table) === tableKey(op.table))?.rows ?? [];
+        const pk = (s?.primaryKey ?? []);
+        const keyOf = (cells) => JSON.stringify(pk.map((k) => cells[k] ?? null));
+        const known = new Set((s?.rows ?? []).map((r) => keyOf(r.key)));
+        const inserted = current.some((r) => !known.has(keyOf(r.cells)));
+        for (const c of (s?.columns ?? [])) {
+            if (!c.nullable && !c.hasDefault && inserted)
+                return { refused: `The revert cannot proceed: ${op.table}.${c.name} was NOT NULL without a DEFAULT and rows have been inserted since the deployment` };
+        }
+        const drops = op.added.map((a) => `DROP COLUMN ${q(a.name)}`);
+        const adds = (s?.columns ?? []).map((c) => `ADD COLUMN ${q(c.name)} ${c.definition}${c.after ? ` AFTER ${q(c.after)}` : ' FIRST'}`);
+        if (drops.length)
+            statements.push(`ALTER TABLE ${q(op.table)} ${drops.join(', ')}`);
+        if (adds.length)
+            statements.push(`ALTER TABLE ${q(op.table)} ${adds.join(', ')}`);
+        for (const r of (s?.rows ?? [])) {
+            if (!current.some((x) => keyOf(x.cells) === keyOf(r.key)))
+                continue;
+            const sets = Object.entries(r.values).map(([c, v]) => `${q(c)} = ${quoteSqlLiteral(v)}`).join(', ');
+            if (sets)
+                statements.push(`UPDATE ${q(op.table)} SET ${sets} WHERE ${pk.map((k) => `${q(k)} = ${quoteSqlLiteral(r.key[k] ?? null)}`).join(' AND ')}`);
+        }
+    }
+    return { statements };
+}
+async function completeRevert(ctx) {
+    const { refused, dr } = requestOf(ctx);
+    if (refused)
+        return refused;
+    if (dr.deployment_state !== 'complete_pending_revert')
+        return unprocessable(ctx, 'Only a deployment within its 30-minute revert window can be reverted');
+    const refusal = ctx.legal('DatabaseDeployRequest', 'deployment_state', 'complete_revert', 'complete_pending_revert', 'complete_revert', String(dr.id));
+    if (refusal)
+        return ctx.refuse(refusal);
+    const closing = ctx.legal('DatabaseDeployRequest', 'state', 'complete_revert', 'open', 'closed', String(dr.id));
+    if (closing)
+        return ctx.refuse(closing);
+    const plan = revertPlan(ctx, dr);
+    if ('refused' in plan)
+        return unprocessable(ctx, plan.refused);
+    const at = ctx.occurredAt;
+    await runOnBase(ctx, String(dr._database), String(dr.into_branch), at, plan.statements);
+    const record = await ctx.write('DatabaseDeployRequest', String(dr.id), {
+        ...ctx.own(dr), deployment_state: 'complete_revert', state: 'closed', closed_at: at, closed_by: actorOf(ctx), updated_at: at, _saved: [],
+    }, 'deploy_request.revert');
+    await drEvent(ctx, ctx.rowsRaw('Database').find((d) => d.name === dr._database), record, 'closed', callActor(ctx));
+    return ctx.reply(view(ctx, record));
+}
+/** What the World clock does to deploy requests (semantics/time.ts calls it): a check finishes, the serial queue starts
+ *  the next deploy when none runs, a deploy finishes into its revert window, and the window closes. */
+/** A deployment made permanent: the request's closing event, and its branch deleted when it asked for that. */
+async function completed(ctx, id) {
+    const dr = ctx.rowsRaw('DatabaseDeployRequest').find((d) => d.id === id);
+    const db = ctx.rowsRaw('Database').find((d) => d.name === dr._database);
+    if (db)
+        await drEvent(ctx, db, dr, 'closed', SYSTEM);
+    if (dr._auto_delete_branch !== true)
+        return;
+    const branch = branchesOf(ctx, String(dr._database)).find((b) => b.name === dr.branch);
+    if (branch)
+        await removeBranch(ctx, String(dr._database), branch, SYSTEM);
+}
+export async function catchUpDeployRequests(ctx) {
+    const now = Date.parse(ctx.occurredAt);
+    for (;;) {
+        const events = [];
+        const all = ctx.rowsRaw('DatabaseDeployRequest');
+        for (const dr of all) {
+            if (dr.deployment_state === 'pending')
+                events.push({ at: later(String(dr.created_at), CHECK_AFTER), dr, kind: 'check' });
+            if (dr.deployment_state === 'in_progress')
+                events.push({ at: later(String(dr._started_at), RUN_FOR), dr, kind: 'finish' });
+            if (dr.deployment_state === 'complete_pending_revert')
+                events.push({ at: later(String(dr._finished_at), REVERT_WINDOW), dr, kind: 'window' });
+            if (dr.deployment_state === 'queued') {
+                const running = all.filter((x) => x._database === dr._database && x.into_branch === dr.into_branch && x.deployment_state === 'in_progress');
+                const ahead = all.some((x) => x._database === dr._database && x.into_branch === dr.into_branch && x.deployment_state === 'queued' && String(x._queued_at) < String(dr._queued_at));
+                if (!running.length && !ahead) {
+                    const lastFinish = all.filter((x) => x._database === dr._database && x.into_branch === dr.into_branch && typeof x._finished_at === 'string').map((x) => String(x._finished_at)).sort().at(-1);
+                    events.push({ at: [String(dr._queued_at), lastFinish ?? ''].sort().at(-1), dr, kind: 'start' });
+                }
+            }
+        }
+        const next = events.filter((e) => Date.parse(e.at) <= now).sort((a, b) => a.at.localeCompare(b.at))[0];
+        if (!next)
+            return;
+        const at = await ctx.at(next.at);
+        const dr = next.dr;
+        const id = String(dr.id);
+        if (next.kind === 'check') {
+            const to = (dr._operations ?? []).length === 0 && !(dr._lint ?? []).length ? 'no_changes' : 'ready';
+            if (at.legal('DatabaseDeployRequest', 'deployment_state', 'check', 'pending', to, id, 'time'))
+                return;
+            await at.write('DatabaseDeployRequest', id, { ...at.own(dr), deployment_state: to, updated_at: next.at }, 'deploy_request.check');
+        }
+        else if (next.kind === 'start') {
+            if (at.legal('DatabaseDeployRequest', 'deployment_state', 'start', 'queued', 'in_progress', id, 'time'))
+                return;
+            await at.write('DatabaseDeployRequest', id, { ...at.own(dr), deployment_state: 'in_progress', updated_at: next.at, _started_at: next.at }, 'deploy_request.start');
+        }
+        else if (next.kind === 'finish') {
+            const instant = dr._instant === true;
+            const to = instant ? 'complete' : 'complete_pending_revert';
+            if (at.legal('DatabaseDeployRequest', 'deployment_state', 'finish', 'in_progress', to, id, 'time'))
+                return;
+            if (instant && at.legal('DatabaseDeployRequest', 'state', 'finish', 'open', 'closed', id, 'time'))
+                return;
+            const applied = await applyDeploy(at, dr, next.at);
+            await at.write('DatabaseDeployRequest', id, { ...applied, deployment_state: to, deployed_at: next.at, updated_at: next.at, _finished_at: next.at, ...(instant ? { state: 'closed', closed_at: next.at, _saved: [] } : {}) }, 'deploy_request.deploy');
+            if (instant)
+                await completed(at, id);
+        }
+        else {
+            if (at.legal('DatabaseDeployRequest', 'deployment_state', 'close_window', 'complete_pending_revert', 'complete', id, 'time'))
+                return;
+            if (at.legal('DatabaseDeployRequest', 'state', 'close_window', 'open', 'closed', id, 'time'))
+                return;
+            await at.write('DatabaseDeployRequest', id, { ...at.own(dr), deployment_state: 'complete', state: 'closed', closed_at: next.at, updated_at: next.at, _saved: [] }, 'deploy_request.complete');
+            await completed(at, id);
+        }
+    }
+}
+export const deployRequestSemantics = {
+    create_deploy_request: createDeployRequest,
+    get_deploy_request: getDeployRequest,
+    list_deploy_requests: listDeployRequests,
+    get_deployment: getDeployment,
+    list_deploy_operations: listDeployOperations,
+    review_deploy_request: reviewDeployRequest,
+    list_deploy_request_reviews: listReviews,
+    queue_deploy_request: queueDeployRequest,
+    close_deploy_request: closeDeployRequest,
+    complete_revert: completeRevert,
+};