@volter/twin-planetscale 0.1.0

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

@@ -0,0 +1,493 @@
+// Deploy requests: a development branch's schema changes, reviewed and deployed into a branch with safe migrations.
+// From PlanetScale's pages (https://planetscale.com/docs/vitess/schema-changes/deploy-requests, /branching,
+// /safe-migrations):
+// - "Before you can create a deploy request, the branch you are merging into must have safe migrations enabled."
+// - "The deploy request includes a schema diff so that you can review the schema changes introduced by the deploy request
+//   against the base branch"; PlanetScale "will check if the request is deployable".
+// - "By default, deploy requests on a branch run through a serial deploy queue: only one deploy runs at a time, and later
+//   requests wait until earlier ones finish."
+// - "You can revert a deployment for up to 30 minutes after the deploying. After the 30 minute period is up, the deployment
+//   becomes permanent"; "Any data that was written to the original schema in the time between deploying and reverting
+//   will remain in your database after the revert"; "If any data was written to those newly introduced fields between
+//   deployment and reverting, that data will not be retained upon revert"; a revert fails for "a `NOT NULL` column
+//   without a `DEFAULT` value, combined with an `ALTER TABLE DROP COLUMN` statement for that column. If you insert some
+//   rows between the deployment and the revert attempt".
+// - With "Require administrator approval for deploy requests", "you will not be able to approve your own deploy
+//   requests"; "a service token cannot approve a deploy request created by the same service token. Also, users can't
+//   approve a deploy request created by a service token that they created"
+//   (https://planetscale.com/docs/api/reference/service-tokens).
+//
+// Where the pages stop and the twin decides: the diff is of the branch's schema against its parent's schema when the
+// branch was made (`_parent_schema`), per table: created, dropped, columns added, columns dropped; any other change (a
+// column's definition, a key, an index) is a lint error saying the twin does not compute it, and the request is not
+// deployable. The deployability check takes 30 seconds and a deploy 2 minutes on the World clock; a deploy applies the
+// diff to the base branch through the pack root's SQL (so `main` keeps its deploy plans), saving what a revert needs. The
+// request stays `open` through its revert window and closes when the deployment is `complete` or reverted (the pages
+// say a revert closes it). A revert the page says fails is refused with 422, its state kept.
+import type { SemanticsContext } from '@volter/world-core';
+import { closeSession, executeSql, scopeImage } from '../../../src/planetscale-store.ts';
+import { quoteSqlLiteral } from '../../../src/planetscale-row.ts';
+import type { TableDef } from '../../../src/planetscale-sql.ts';
+import { tableKey } from '../../../src/planetscale-sql.ts';
+import { heldAccesses } from '../token-gate.ts';
+import { branchScope, branchesOf, removeBranch, storeCtx } from './branches.ts';
+import { actorOf, mintId, page } from './shared.ts';
+import { audit, callActor, SYSTEM, type AuditActor } from './audit.ts';
+
+type Row = Record<string, unknown>;
+
+export const CHECK_AFTER = 30_000;
+export const RUN_FOR = 120_000;
+export const REVERT_WINDOW = 30 * 60_000;
+
+const later = (iso: string, ms: number): string => new Date(Date.parse(iso) + ms).toISOString();
+const unprocessable = (ctx: SemanticsContext, message: string): Response => ctx.refuse({ status: 422, code: 'unprocessable_entity', message });
+const body = (ctx: SemanticsContext): Row => (ctx.body && typeof ctx.body === 'object' && !Array.isArray(ctx.body) ? (ctx.body as Row) : {});
+
+/** One table's change in a deploy request's diff. */
+type Operation = {
+  table: string;
+  kind: 'create' | 'drop' | 'alter';
+  /** columns the branch added, with their definitions as SHOW CREATE TABLE prints them and the column before each */
+  added: Array<{ name: string; definition: string; after: string | null }>;
+  dropped: string[];
+  ddl: string;
+  /** the statements that apply it: the engine takes an ALTER of drops only or of adds only */
+  apply: string[];
+  can_drop_data: boolean;
+};
+
+/** 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: SemanticsContext, scope: string | undefined, table: string): Promise<string> {
+  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] as unknown[] | undefined)?.[1] ?? '');
+}
+const columnLine = (create: string, column: string): string => {
+  const line = create.split('\n').find((l) => l.trim().startsWith(`\`${column}\` `));
+  return (line ?? '').trim().replace(/^`[^`]+`\s+/, '').replace(/,$/, '');
+};
+const q = (name: string): string => `\`${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: SemanticsContext, database: string, branch: Row): Promise<{ operations: Operation[]; lint: Row[] }> {
+  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 ?? []) as TableDef[]).map((t) => [tableKey(t.name), t]));
+  const operations: Operation[] = [];
+  const lint: Row[] = [];
+  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: Operation[]): boolean => 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: string): Row {
+  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: Row): Row {
+  const ops = (dr._operations ?? []) as Operation[];
+  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 as Row[] | undefined)?.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 ?? []) as Row[], 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: SemanticsContext, database: string): Row[] => 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: SemanticsContext, dr: Row): Row => {
+  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: SemanticsContext): { refused?: Response; db?: Row } {
+  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: SemanticsContext): { refused?: Response; db?: Row; dr?: Row } {
+  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: SemanticsContext, db: Row, dr: Row, action: string, actor: AuditActor): Promise<void> {
+  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: SemanticsContext): string => /^([^:\s]+):/.exec(ctx.call.request.headers.get('authorization') ?? '')?.[1] ?? 'world';
+
+async function createDeployRequest(ctx: SemanticsContext): Promise<Response> {
+  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: SemanticsContext): Promise<Response> {
+  const { refused, dr } = requestOf(ctx);
+  return refused ?? ctx.reply(view(ctx, dr!));
+}
+
+async function getDeployment(ctx: SemanticsContext): Promise<Response> {
+  const { refused, dr } = requestOf(ctx);
+  return refused ?? ctx.reply(deploymentOf(dr!));
+}
+
+async function listDeployOperations(ctx: SemanticsContext): Promise<Response> {
+  const { refused, dr } = requestOf(ctx);
+  return refused ?? page(ctx, (deploymentOf(dr!).deploy_operations as Row[]));
+}
+
+/** list_deploy_requests, newest first (the twin's order), filtered by `state`, `branch` and `into_branch`. */
+async function listDeployRequests(ctx: SemanticsContext): Promise<Response> {
+  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: SemanticsContext, dr: Row): Row[] =>
+  ctx.tree().filter((r) => r.type === '_deploy_review').map((r): Row => ({ ...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: SemanticsContext, db: Row, dr: Row, reviewer: string, actor: Row, state: 'approved' | 'commented', text: string, auditActor: AuditActor): Promise<Row | Response> {
+  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: SemanticsContext): Promise<Response> {
+  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: SemanticsContext): Promise<Response> {
+  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: SemanticsContext): Promise<Response> {
+  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 ?? []) as Operation[])) 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: SemanticsContext): Promise<Response> {
+  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: SemanticsContext, database: string, into: string, at: string, statements: string[]): Promise<void> {
+  const scope = branchScope(database, into);
+  const sctx = { ...storeCtx(ctx, at), ...(scope ? { scope } : {}) };
+  let session: string | null = 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: SemanticsContext, dr: Row, at: string): Promise<Row> {
+  const database = String(dr._database);
+  const into = String(dr.into_branch);
+  const scope = branchScope(database, into);
+  const image = scopeImage(ctx.root, scope);
+  const saved: Row[] = [];
+  const statements: string[] = [];
+  for (const op of (dr._operations ?? []) as Operation[]) {
+    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: SemanticsContext, scope: string | undefined, table: string, name: string, rows: Array<{ cells: Record<string, unknown> }>): Promise<Row> {
+  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: string, saved: Row[]): string[] {
+  const s = saved.find((x) => x.kind === 'drop' && x.table === table);
+  if (!s) return [];
+  return [String(s.create), ...(s.rows as Array<Record<string, string | null>>).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: SemanticsContext, dr: Row): { statements: string[] } | { refused: string } {
+  const database = String(dr._database);
+  const image = scopeImage(ctx.root, branchScope(database, String(dr.into_branch)));
+  const statements: string[] = [];
+  const saved = (dr._saved ?? []) as Row[];
+  for (const op of [...((dr._operations ?? []) as Operation[])].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 ?? []) as string[];
+    const keyOf = (cells: Record<string, unknown>): string => JSON.stringify(pk.map((k) => cells[k] ?? null));
+    const known = new Set(((s?.rows ?? []) as Array<{ key: Row }>).map((r) => keyOf(r.key)));
+    const inserted = current.some((r) => !known.has(keyOf(r.cells)));
+    for (const c of (s?.columns ?? []) as Array<{ name: string; nullable: boolean; hasDefault: boolean }>) {
+      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 ?? []) as Array<{ name: string; definition: string; after: string | null }>).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 ?? []) as Array<{ key: Record<string, string | null>; values: Record<string, string | null> }>) {
+      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: SemanticsContext): Promise<Response> {
+  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: SemanticsContext, id: string): Promise<void> {
+  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: SemanticsContext): Promise<void> {
+  const now = Date.parse(ctx.occurredAt);
+  for (;;) {
+    const events: Array<{ at: string; dr: Row; kind: 'check' | 'start' | 'finish' | 'window' }> = [];
+    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 ?? []) as unknown[]).length === 0 && !((dr._lint ?? []) as unknown[]).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,
+};

package/dist/api/src/semantics/index.d.ts

@@ -0,0 +1,20 @@
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { type AuditActor } from './audit.js';
+type Row = Record<string, unknown>;
+/** The bytes of the branch's stored rows: what a backup of it holds. */
+export declare function branchBytes(ctx: SemanticsContext): number;
+/** A service token as the API answers it, its secret left out ("The plaintext token. Available only after create."). */
+export declare function makeServiceToken(ctx: SemanticsContext, name: string, accesses: Array<{
+    access: string;
+    resource_type: string;
+    resource_name: string;
+}>, createdBy?: string, organization?: string, ttl?: number): Promise<{
+    record: Row;
+    token: string;
+}>;
+/** A service token deleted: its ID and token stop authenticating at once (token-gate.ts refuses a deleted token as any
+ *  token PlanetScale does not hold). "You can delete a service token at any time from the service token detail page"
+ *  (https://planetscale.com/docs/cli/service-tokens); the API's delete_service_token does the same. */
+export declare function removeServiceToken(ctx: SemanticsContext, token: Row, organization: string, actor?: AuditActor): Promise<void>;
+export declare const apiSemantics: Record<string, Semantics>;
+export {};