@volter/twin-planetscale 0.1.0

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

@@ -0,0 +1,53 @@
+import type { SemanticsContext } from '@volter/world-core';
+import { type ScopeImage } from '../../../src/planetscale-store.js';
+import { type AuditActor } from './audit.js';
+type Row = Record<string, unknown>;
+/** The live branches of a database (by name). */
+export declare const branchesOf: (ctx: SemanticsContext, database: string) => Row[];
+/** The store scope a branch's statements act on (`main` is the World's image: undefined). */
+export declare const branchScope: (database: string, branch: string) => string | undefined;
+/** The context the root store is written with. */
+export declare const storeCtx: (ctx: SemanticsContext, at?: string) => {
+    root?: string;
+    occurredAt: string;
+};
+/** A branch as the spec's DatabaseBranch answers it, the bookkeeping kept beside it. */
+export declare function makeBranch(ctx: SemanticsContext, db: Row, o: {
+    name: string;
+    parent: string | null;
+    production: boolean;
+    parentSchema: ScopeImage['tables'];
+    restoredFrom?: Row;
+}): Promise<Row>;
+/**
+ * create_branch: from `parent_branch` (default: the database's default branch) with its schema and no rows, or from
+ * `backup_id` with the backup's schema and rows ("If provided, restores the backup's schema and data to the new branch.
+ * Must have `restore_production_branch_backup(s)` or `restore_backup(s)` access to do this", the spec). A name the
+ * database already has, or one outside PlanetScale's branch-name rule, answers 422 (the twin's wording). The branch is
+ * `pending` and not ready until the World clock makes it ready (semantics/time.ts).
+ */
+declare function createBranch(ctx: SemanticsContext): Promise<Response>;
+/** The image a backup holds (src/planetscale-store.ts, `_snapshot`), or an empty one for a backup that holds none. */
+export declare function backupImage(ctx: SemanticsContext, backup: Row): ScopeImage;
+declare function getBranch(ctx: SemanticsContext): Promise<Response>;
+/** list_branches, oldest first (the twin's order), filtered by `q` (a name contains it), `production` and
+ *  `safe_migrations`. */
+declare function listBranches(ctx: SemanticsContext): Promise<Response>;
+/**
+ * delete_branch. "You cannot delete a branch that's set as default" and "Only Organization Administrators have
+ * permission to delete production branches" (https://planetscale.com/docs/vitess/schema-changes/branching); a token needs
+ * `delete_production_branch` for a production branch ("Delete a production database branch",
+ * https://planetscale.com/docs/api/reference/service-tokens). The branch's tables, rows and passwords go with it.
+ */
+declare function deleteBranch(ctx: SemanticsContext): Promise<Response>;
+/** A branch gone: its passwords stop authenticating and its tables and rows are dropped. */
+export declare function removeBranch(ctx: SemanticsContext, database: string, b: Row, actor?: AuditActor): Promise<void>;
+export declare const branchSemantics: {
+    enable_safe_migrations: (ctx: SemanticsContext) => Promise<Response>;
+    disable_safe_migrations: (ctx: SemanticsContext) => Promise<Response>;
+    create_branch: typeof createBranch;
+    get_branch: typeof getBranch;
+    list_branches: typeof listBranches;
+    delete_branch: typeof deleteBranch;
+};
+export {};

package/dist/api/src/semantics/branches.js

@@ -0,0 +1,197 @@
+import { dropScope, scopeImage, scopeOf, seedScope } from "../../../src/planetscale-store.js";
+import { lacks } from "../token-gate.js";
+import { actorOf, AVATAR, mintId, page, REGION } from "./shared.js";
+import { audit, orgOf } from "./audit.js";
+/** The live branches of a database (by name). */
+export const branchesOf = (ctx, database) => ctx.rowsRaw('DatabaseBranch').filter((b) => b._database === database && b.deleted_at === null);
+/** The store scope a branch's statements act on (`main` is the World's image: undefined). */
+export const branchScope = (database, branch) => scopeOf(database, branch);
+/** The context the root store is written with. */
+export const storeCtx = (ctx, at = ctx.occurredAt) => ({ ...(ctx.root !== undefined ? { root: ctx.root } : {}), occurredAt: at });
+/** A branch as the spec's DatabaseBranch answers it, the bookkeeping kept beside it. */
+export async function makeBranch(ctx, db, o) {
+    const database = String(db.name);
+    const org = String(ctx.call.params.organization);
+    const id = mintId(ctx, 'DatabaseBranch', 'br', `${database}/${o.name}`);
+    const at = ctx.occurredAt;
+    return ctx.write('DatabaseBranch', id, {
+        id, name: o.name, created_at: at, updated_at: at, deleted_at: null, restore_checklist_completed_at: null,
+        schema_last_updated_at: at, kind: 'mysql', mysql_address: 'aws.connect.psdb.cloud', mysql_edge_address: 'aws.connect.psdb.cloud',
+        state: 'pending', ready: false, schema_ready: false, metal: false, production: o.production, safe_migrations: false,
+        deletion_protected: false, sharded: false, shard_count: 1, keyspace_count: 1, stale_schema: false,
+        cluster_name: String(db._cluster_size ?? 'PS_10'), cluster_iops: 0, direct_vtgate: false,
+        actor: actorOf(ctx),
+        restored_from_branch: o.restoredFrom ? { id: String(o.restoredFrom.id), name: String(o.restoredFrom.name), created_at: String(o.restoredFrom.created_at), updated_at: String(o.restoredFrom.updated_at), deleted_at: null } : null,
+        private_edge_connectivity: false, has_replicas: o.production, has_read_only_replicas: false,
+        html_url: `https://app.planetscale.com/${org}/${database}/${o.name}`,
+        url: `https://api.planetscale.com/v1/organizations/${org}/databases/${database}/branches/${o.name}`,
+        region: REGION(),
+        parent_branch: o.parent,
+        _database: database, _parent_schema: o.parentSchema,
+    }, 'branch.create');
+}
+/** "PlanetScale branch names must be lowercase, alphanumeric characters and hyphens are allowed"
+ *  (https://planetscale.com/docs/vitess/integrations/github-actions). */
+const BRANCH_NAME = /^[a-z0-9][a-z0-9-]*$/;
+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 : {});
+const view = (ctx, b) => ctx.get('DatabaseBranch', String(b.id));
+/** The created database a path names, live, or its 404. Branches exist only on a database this lane created. */
+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') };
+}
+/**
+ * create_branch: from `parent_branch` (default: the database's default branch) with its schema and no rows, or from
+ * `backup_id` with the backup's schema and rows ("If provided, restores the backup's schema and data to the new branch.
+ * Must have `restore_production_branch_backup(s)` or `restore_backup(s)` access to do this", the spec). A name the
+ * database already has, or one outside PlanetScale's branch-name rule, answers 422 (the twin's wording). The branch is
+ * `pending` and not ready until the World clock makes it ready (semantics/time.ts).
+ */
+async function createBranch(ctx) {
+    const { refused, db } = createdDatabase(ctx);
+    if (refused)
+        return refused;
+    const database = String(db.name);
+    const b = body(ctx);
+    const name = typeof b.name === 'string' ? b.name : '';
+    if (!name)
+        return unprocessable(ctx, 'name is required');
+    if (!BRANCH_NAME.test(name))
+        return unprocessable(ctx, 'Name must be lowercase, alphanumeric characters and hyphens');
+    if (branchesOf(ctx, database).some((x) => x.name === name))
+        return unprocessable(ctx, 'Name has already been taken');
+    if (typeof b.backup_id === 'string' && b.backup_id) {
+        const backup = ctx.rowsRaw('Backup').find((k) => k.id === b.backup_id && k._database === database && k.deleted_at === null);
+        if (!backup)
+            return ctx.notFound('Backup', b.backup_id, 'backup_id');
+        if (backup.state !== 'success')
+            return unprocessable(ctx, 'The backup has not completed');
+        const source = branchesOf(ctx, database).find((x) => x.name === backup.database_branch?.name);
+        const denied = lacks(ctx, database, source?.production === true ? ['restore_production_branch_backup'] : ['restore_backup', 'restore_production_branch_backup']);
+        if (denied)
+            return denied;
+        const snapshot = backupImage(ctx, backup);
+        const record = await makeBranch(ctx, db, { name, parent: String(backup.database_branch.name), production: false, parentSchema: snapshot.tables, restoredFrom: source });
+        const scope = branchScope(database, name);
+        await seedScope(storeCtx(ctx), scope, snapshot);
+        await ctx.write('Backup', String(backup.id), { ...ctx.own(backup), restored_branches: [...(backup.restored_branches ?? []), String(record.id)] }, 'backup.restore');
+        await audit(ctx, orgOf(ctx), 'database_branch', 'created', { type: 'DatabaseBranch', id: String(record.id), name }, { auditable: { type: 'Database', id: String(db.id), name: database } });
+        return ctx.reply(view(ctx, record), 201);
+    }
+    const denied = lacks(ctx, database, ['create_branch']);
+    if (denied)
+        return denied;
+    const parentName = typeof b.parent_branch === 'string' && b.parent_branch ? b.parent_branch : String(db.default_branch);
+    const parent = branchesOf(ctx, database).find((x) => x.name === parentName);
+    if (!parent)
+        return ctx.notFound('DatabaseBranch', parentName, 'parent_branch');
+    const schema = scopeImage(ctx.root, branchScope(database, parentName)).tables;
+    const record = await makeBranch(ctx, db, { name, parent: parentName, production: false, parentSchema: schema });
+    await seedScope(storeCtx(ctx), branchScope(database, name), { tables: schema, rows: [] });
+    await audit(ctx, orgOf(ctx), 'database_branch', 'created', { type: 'DatabaseBranch', id: String(record.id), name }, { auditable: { type: 'Database', id: String(db.id), name: database } });
+    return ctx.reply(view(ctx, record), 201);
+}
+/** The image a backup holds (src/planetscale-store.ts, `_snapshot`), or an empty one for a backup that holds none. */
+export function backupImage(ctx, backup) {
+    const snap = backup._snapshot === undefined ? undefined : ctx.tree().find((r) => r.type === '_snapshot' && r.id === backup._snapshot);
+    const image = snap ? ctx.own(snap).image : undefined;
+    return image ?? { tables: [], rows: [] };
+}
+async function getBranch(ctx) {
+    const { refused, db } = createdDatabase(ctx);
+    if (refused)
+        return refused;
+    const b = branchesOf(ctx, String(db.name)).find((x) => x.name === ctx.call.params.branch);
+    return b ? ctx.reply(view(ctx, b)) : ctx.notFound('DatabaseBranch', String(ctx.call.params.branch), 'branch');
+}
+/** list_branches, oldest first (the twin's order), filtered by `q` (a name contains it), `production` and
+ *  `safe_migrations`. */
+async function listBranches(ctx) {
+    const { refused, db } = createdDatabase(ctx);
+    if (refused)
+        return refused;
+    const q = new URL(ctx.call.request.url).searchParams;
+    const flag = (k) => (q.has(k) ? q.get(k) === 'true' : undefined);
+    const production = flag('production');
+    const safe = flag('safe_migrations');
+    const rows = branchesOf(ctx, String(db.name)).filter((b) => (!q.get('q') || String(b.name).includes(q.get('q')))
+        && (production === undefined || b.production === production) && (safe === undefined || b.safe_migrations === safe));
+    return page(ctx, rows.map((b) => view(ctx, b)));
+}
+/**
+ * delete_branch. "You cannot delete a branch that's set as default" and "Only Organization Administrators have
+ * permission to delete production branches" (https://planetscale.com/docs/vitess/schema-changes/branching); a token needs
+ * `delete_production_branch` for a production branch ("Delete a production database branch",
+ * https://planetscale.com/docs/api/reference/service-tokens). The branch's tables, rows and passwords go with it.
+ */
+async function deleteBranch(ctx) {
+    const { refused, db } = createdDatabase(ctx);
+    if (refused)
+        return refused;
+    const database = String(db.name);
+    const b = branchesOf(ctx, database).find((x) => x.name === ctx.call.params.branch);
+    if (!b)
+        return ctx.notFound('DatabaseBranch', String(ctx.call.params.branch), 'branch');
+    if (b.name === db.default_branch)
+        return unprocessable(ctx, 'You cannot delete the default branch');
+    if (b.production === true) {
+        const denied = lacks(ctx, database, ['delete_production_branch']);
+        if (denied)
+            return denied;
+    }
+    await removeBranch(ctx, database, b);
+    return new Response(null, { status: 204 });
+}
+/** A branch gone: its passwords stop authenticating and its tables and rows are dropped. */
+export async function removeBranch(ctx, database, b, actor) {
+    const at = ctx.occurredAt;
+    for (const p of ctx.rowsRaw('DatabaseBranchPassword')) {
+        if (p._database === database && p.database_branch?.name === b.name && p.deleted_at === null) {
+            await ctx.write('DatabaseBranchPassword', String(p.id), { ...ctx.own(p), deleted_at: at }, 'password.delete');
+        }
+    }
+    // a deploy request outlives its branch, marked `branch_deleted` (the spec's DatabaseDeployRequest)
+    for (const dr of ctx.rowsRaw('DatabaseDeployRequest')) {
+        if (dr._database === database && dr.branch === b.name && dr.branch_deleted !== true) {
+            await ctx.write('DatabaseDeployRequest', String(dr.id), { ...ctx.own(dr), branch_deleted: true, branch_deleted_at: at, branch_deleted_by: actor ? { id: actor.id, display_name: actor.name, avatar_url: AVATAR } : actorOf(ctx), updated_at: at }, 'deploy_request.branch_deleted');
+        }
+    }
+    const scope = branchScope(database, String(b.name));
+    if (scope)
+        await dropScope(storeCtx(ctx), scope);
+    await ctx.write('DatabaseBranch', String(b.id), { ...ctx.own(b), deleted_at: at, updated_at: at }, 'branch.delete');
+    const db = ctx.rowsRaw('Database').find((d) => d.name === database);
+    await audit(ctx, String(db?._organization ?? orgOf(ctx)), 'database_branch', 'deleted', { type: 'DatabaseBranch', id: String(b.id), name: String(b.name) }, { auditable: { type: 'Database', id: String(db?.id ?? database), name: database }, ...(actor ? { actor } : {}) });
+}
+/**
+ * enable_safe_migrations / disable_safe_migrations. "With safe migrations enabled, Data Definition Language (DDL)
+ * statements issued to branches with safe migrations enabled will automatically be rejected by PlanetScale"
+ * (https://planetscale.com/docs/vitess/schema-changes/safe-migrations): psdb refuses DDL on the branch while the flag is
+ * set (the pack root's planetscale-twin.ts). The answer is the branch. The spec names no access for either operation;
+ * the twin's gate asks `write_database` (token-gate.ts).
+ */
+function safeMigrations(on) {
+    return async (ctx) => {
+        const { refused, db } = createdDatabase(ctx);
+        if (refused)
+            return refused;
+        const b = branchesOf(ctx, String(db.name)).find((x) => x.name === ctx.call.params.branch);
+        if (!b)
+            return ctx.notFound('DatabaseBranch', String(ctx.call.params.branch), 'branch');
+        if (b.safe_migrations !== on) {
+            await ctx.write('DatabaseBranch', String(b.id), { ...ctx.own(b), safe_migrations: on, updated_at: ctx.occurredAt }, on ? 'branch.enable_safe_migrations' : 'branch.disable_safe_migrations');
+            await audit(ctx, orgOf(ctx), 'database_branch', on ? 'enabled_safe_migrations' : 'disabled_safe_migrations', { type: 'DatabaseBranch', id: String(b.id), name: String(b.name) }, { auditable: { type: 'Database', id: String(db.id), name: String(db.name) } });
+        }
+        return ctx.reply(view(ctx, branchesOf(ctx, String(db.name)).find((x) => x.id === b.id)));
+    };
+}
+export const branchSemantics = {
+    enable_safe_migrations: safeMigrations(true),
+    disable_safe_migrations: safeMigrations(false),
+    create_branch: createBranch,
+    get_branch: getBranch,
+    list_branches: listBranches,
+    delete_branch: deleteBranch,
+};

package/dist/api/src/semantics/branches.ts

@@ -0,0 +1,201 @@
+// A database's branches. "When your database is first initialized, a single production branch is created called `main`
+// and acts as the default branch. When you create additional branches, the schema of the source branch is copied to the
+// new branch"; "Development branches **will not** copy over data, just the schema"
+// (https://planetscale.com/docs/vitess/schema-changes/branching). A branch's tables and rows live in the pack root's
+// store: `main` is the World's one image, any other branch a scope of its own (src/planetscale-store.ts, "BRANCH
+// SCOPES"). Where the reference stops and the twin decides, the comment beside the rule says so.
+import type { SemanticsContext } from '@volter/world-core';
+import { dropScope, scopeImage, scopeOf, seedScope, type ScopeImage } from '../../../src/planetscale-store.ts';
+import { lacks } from '../token-gate.ts';
+import { actorOf, AVATAR, mintId, page, REGION } from './shared.ts';
+import { audit, orgOf, type AuditActor } from './audit.ts';
+
+type Row = Record<string, unknown>;
+
+/** The live branches of a database (by name). */
+export const branchesOf = (ctx: SemanticsContext, database: string): Row[] =>
+  ctx.rowsRaw('DatabaseBranch').filter((b) => b._database === database && b.deleted_at === null);
+
+/** The store scope a branch's statements act on (`main` is the World's image: undefined). */
+export const branchScope = (database: string, branch: string): string | undefined => scopeOf(database, branch);
+
+/** The context the root store is written with. */
+export const storeCtx = (ctx: SemanticsContext, at = ctx.occurredAt): { root?: string; occurredAt: string } => ({ ...(ctx.root !== undefined ? { root: ctx.root } : {}), occurredAt: at });
+
+/** A branch as the spec's DatabaseBranch answers it, the bookkeeping kept beside it. */
+export async function makeBranch(ctx: SemanticsContext, db: Row, o: { name: string; parent: string | null; production: boolean; parentSchema: ScopeImage['tables']; restoredFrom?: Row }): Promise<Row> {
+  const database = String(db.name);
+  const org = String(ctx.call.params.organization);
+  const id = mintId(ctx, 'DatabaseBranch', 'br', `${database}/${o.name}`);
+  const at = ctx.occurredAt;
+  return ctx.write('DatabaseBranch', id, {
+    id, name: o.name, created_at: at, updated_at: at, deleted_at: null, restore_checklist_completed_at: null,
+    schema_last_updated_at: at, kind: 'mysql', mysql_address: 'aws.connect.psdb.cloud', mysql_edge_address: 'aws.connect.psdb.cloud',
+    state: 'pending', ready: false, schema_ready: false, metal: false, production: o.production, safe_migrations: false,
+    deletion_protected: false, sharded: false, shard_count: 1, keyspace_count: 1, stale_schema: false,
+    cluster_name: String(db._cluster_size ?? 'PS_10'), cluster_iops: 0, direct_vtgate: false,
+    actor: actorOf(ctx),
+    restored_from_branch: o.restoredFrom ? { id: String(o.restoredFrom.id), name: String(o.restoredFrom.name), created_at: String(o.restoredFrom.created_at), updated_at: String(o.restoredFrom.updated_at), deleted_at: null } : null,
+    private_edge_connectivity: false, has_replicas: o.production, has_read_only_replicas: false,
+    html_url: `https://app.planetscale.com/${org}/${database}/${o.name}`,
+    url: `https://api.planetscale.com/v1/organizations/${org}/databases/${database}/branches/${o.name}`,
+    region: REGION(),
+    parent_branch: o.parent,
+    _database: database, _parent_schema: o.parentSchema,
+  }, 'branch.create');
+}
+
+/** "PlanetScale branch names must be lowercase, alphanumeric characters and hyphens are allowed"
+ *  (https://planetscale.com/docs/vitess/integrations/github-actions). */
+const BRANCH_NAME = /^[a-z0-9][a-z0-9-]*$/;
+
+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) : {});
+const view = (ctx: SemanticsContext, b: Row): Row => ctx.get('DatabaseBranch', String(b.id))!;
+
+/** The created database a path names, live, or its 404. Branches exist only on a database this lane created. */
+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') };
+}
+
+/**
+ * create_branch: from `parent_branch` (default: the database's default branch) with its schema and no rows, or from
+ * `backup_id` with the backup's schema and rows ("If provided, restores the backup's schema and data to the new branch.
+ * Must have `restore_production_branch_backup(s)` or `restore_backup(s)` access to do this", the spec). A name the
+ * database already has, or one outside PlanetScale's branch-name rule, answers 422 (the twin's wording). The branch is
+ * `pending` and not ready until the World clock makes it ready (semantics/time.ts).
+ */
+async function createBranch(ctx: SemanticsContext): Promise<Response> {
+  const { refused, db } = createdDatabase(ctx);
+  if (refused) return refused;
+  const database = String(db!.name);
+  const b = body(ctx);
+  const name = typeof b.name === 'string' ? b.name : '';
+  if (!name) return unprocessable(ctx, 'name is required');
+  if (!BRANCH_NAME.test(name)) return unprocessable(ctx, 'Name must be lowercase, alphanumeric characters and hyphens');
+  if (branchesOf(ctx, database).some((x) => x.name === name)) return unprocessable(ctx, 'Name has already been taken');
+  if (typeof b.backup_id === 'string' && b.backup_id) {
+    const backup = ctx.rowsRaw('Backup').find((k) => k.id === b.backup_id && k._database === database && k.deleted_at === null);
+    if (!backup) return ctx.notFound('Backup', b.backup_id, 'backup_id');
+    if (backup.state !== 'success') return unprocessable(ctx, 'The backup has not completed');
+    const source = branchesOf(ctx, database).find((x) => x.name === (backup.database_branch as Row | undefined)?.name);
+    const denied = lacks(ctx, database, source?.production === true ? ['restore_production_branch_backup'] : ['restore_backup', 'restore_production_branch_backup']);
+    if (denied) return denied;
+    const snapshot = backupImage(ctx, backup);
+    const record = await makeBranch(ctx, db!, { name, parent: String((backup.database_branch as Row).name), production: false, parentSchema: snapshot.tables, restoredFrom: source });
+    const scope = branchScope(database, name)!;
+    await seedScope(storeCtx(ctx), scope, snapshot);
+    await ctx.write('Backup', String(backup.id), { ...ctx.own(backup), restored_branches: [...((backup.restored_branches ?? []) as string[]), String(record.id)] }, 'backup.restore');
+    await audit(ctx, orgOf(ctx), 'database_branch', 'created', { type: 'DatabaseBranch', id: String(record.id), name }, { auditable: { type: 'Database', id: String(db!.id), name: database } });
+    return ctx.reply(view(ctx, record), 201);
+  }
+  const denied = lacks(ctx, database, ['create_branch']);
+  if (denied) return denied;
+  const parentName = typeof b.parent_branch === 'string' && b.parent_branch ? b.parent_branch : String(db!.default_branch);
+  const parent = branchesOf(ctx, database).find((x) => x.name === parentName);
+  if (!parent) return ctx.notFound('DatabaseBranch', parentName, 'parent_branch');
+  const schema = scopeImage(ctx.root, branchScope(database, parentName)).tables;
+  const record = await makeBranch(ctx, db!, { name, parent: parentName, production: false, parentSchema: schema });
+  await seedScope(storeCtx(ctx), branchScope(database, name)!, { tables: schema, rows: [] });
+  await audit(ctx, orgOf(ctx), 'database_branch', 'created', { type: 'DatabaseBranch', id: String(record.id), name }, { auditable: { type: 'Database', id: String(db!.id), name: database } });
+  return ctx.reply(view(ctx, record), 201);
+}
+
+/** The image a backup holds (src/planetscale-store.ts, `_snapshot`), or an empty one for a backup that holds none. */
+export function backupImage(ctx: SemanticsContext, backup: Row): ScopeImage {
+  const snap = backup._snapshot === undefined ? undefined : ctx.tree().find((r) => r.type === '_snapshot' && r.id === backup._snapshot);
+  const image = snap ? (ctx.own(snap).image as ScopeImage | undefined) : undefined;
+  return image ?? { tables: [], rows: [] };
+}
+
+async function getBranch(ctx: SemanticsContext): Promise<Response> {
+  const { refused, db } = createdDatabase(ctx);
+  if (refused) return refused;
+  const b = branchesOf(ctx, String(db!.name)).find((x) => x.name === ctx.call.params.branch);
+  return b ? ctx.reply(view(ctx, b)) : ctx.notFound('DatabaseBranch', String(ctx.call.params.branch), 'branch');
+}
+
+/** list_branches, oldest first (the twin's order), filtered by `q` (a name contains it), `production` and
+ *  `safe_migrations`. */
+async function listBranches(ctx: SemanticsContext): Promise<Response> {
+  const { refused, db } = createdDatabase(ctx);
+  if (refused) return refused;
+  const q = new URL(ctx.call.request.url).searchParams;
+  const flag = (k: string): boolean | undefined => (q.has(k) ? q.get(k) === 'true' : undefined);
+  const production = flag('production');
+  const safe = flag('safe_migrations');
+  const rows = branchesOf(ctx, String(db!.name)).filter((b) => (!q.get('q') || String(b.name).includes(q.get('q')!))
+    && (production === undefined || b.production === production) && (safe === undefined || b.safe_migrations === safe));
+  return page(ctx, rows.map((b) => view(ctx, b)));
+}
+
+/**
+ * delete_branch. "You cannot delete a branch that's set as default" and "Only Organization Administrators have
+ * permission to delete production branches" (https://planetscale.com/docs/vitess/schema-changes/branching); a token needs
+ * `delete_production_branch` for a production branch ("Delete a production database branch",
+ * https://planetscale.com/docs/api/reference/service-tokens). The branch's tables, rows and passwords go with it.
+ */
+async function deleteBranch(ctx: SemanticsContext): Promise<Response> {
+  const { refused, db } = createdDatabase(ctx);
+  if (refused) return refused;
+  const database = String(db!.name);
+  const b = branchesOf(ctx, database).find((x) => x.name === ctx.call.params.branch);
+  if (!b) return ctx.notFound('DatabaseBranch', String(ctx.call.params.branch), 'branch');
+  if (b.name === db!.default_branch) return unprocessable(ctx, 'You cannot delete the default branch');
+  if (b.production === true) { const denied = lacks(ctx, database, ['delete_production_branch']); if (denied) return denied; }
+  await removeBranch(ctx, database, b);
+  return new Response(null, { status: 204 });
+}
+
+/** A branch gone: its passwords stop authenticating and its tables and rows are dropped. */
+export async function removeBranch(ctx: SemanticsContext, database: string, b: Row, actor?: AuditActor): Promise<void> {
+  const at = ctx.occurredAt;
+  for (const p of ctx.rowsRaw('DatabaseBranchPassword')) {
+    if (p._database === database && (p.database_branch as Row | undefined)?.name === b.name && p.deleted_at === null) {
+      await ctx.write('DatabaseBranchPassword', String(p.id), { ...ctx.own(p), deleted_at: at }, 'password.delete');
+    }
+  }
+  // a deploy request outlives its branch, marked `branch_deleted` (the spec's DatabaseDeployRequest)
+  for (const dr of ctx.rowsRaw('DatabaseDeployRequest')) {
+    if (dr._database === database && dr.branch === b.name && dr.branch_deleted !== true) {
+      await ctx.write('DatabaseDeployRequest', String(dr.id), { ...ctx.own(dr), branch_deleted: true, branch_deleted_at: at, branch_deleted_by: actor ? { id: actor.id, display_name: actor.name, avatar_url: AVATAR } : actorOf(ctx), updated_at: at }, 'deploy_request.branch_deleted');
+    }
+  }
+  const scope = branchScope(database, String(b.name));
+  if (scope) await dropScope(storeCtx(ctx), scope);
+  await ctx.write('DatabaseBranch', String(b.id), { ...ctx.own(b), deleted_at: at, updated_at: at }, 'branch.delete');
+  const db = ctx.rowsRaw('Database').find((d) => d.name === database);
+  await audit(ctx, String(db?._organization ?? orgOf(ctx)), 'database_branch', 'deleted', { type: 'DatabaseBranch', id: String(b.id), name: String(b.name) }, { auditable: { type: 'Database', id: String(db?.id ?? database), name: database }, ...(actor ? { actor } : {}) });
+}
+
+/**
+ * enable_safe_migrations / disable_safe_migrations. "With safe migrations enabled, Data Definition Language (DDL)
+ * statements issued to branches with safe migrations enabled will automatically be rejected by PlanetScale"
+ * (https://planetscale.com/docs/vitess/schema-changes/safe-migrations): psdb refuses DDL on the branch while the flag is
+ * set (the pack root's planetscale-twin.ts). The answer is the branch. The spec names no access for either operation;
+ * the twin's gate asks `write_database` (token-gate.ts).
+ */
+function safeMigrations(on: boolean) {
+  return async (ctx: SemanticsContext): Promise<Response> => {
+    const { refused, db } = createdDatabase(ctx);
+    if (refused) return refused;
+    const b = branchesOf(ctx, String(db!.name)).find((x) => x.name === ctx.call.params.branch);
+    if (!b) return ctx.notFound('DatabaseBranch', String(ctx.call.params.branch), 'branch');
+    if (b.safe_migrations !== on) {
+      await ctx.write('DatabaseBranch', String(b.id), { ...ctx.own(b), safe_migrations: on, updated_at: ctx.occurredAt }, on ? 'branch.enable_safe_migrations' : 'branch.disable_safe_migrations');
+      await audit(ctx, orgOf(ctx), 'database_branch', on ? 'enabled_safe_migrations' : 'disabled_safe_migrations', { type: 'DatabaseBranch', id: String(b.id), name: String(b.name) }, { auditable: { type: 'Database', id: String(db!.id), name: String(db!.name) } });
+    }
+    return ctx.reply(view(ctx, branchesOf(ctx, String(db!.name)).find((x) => x.id === b.id)!));
+  };
+}
+
+export const branchSemantics = {
+  enable_safe_migrations: safeMigrations(true),
+  disable_safe_migrations: safeMigrations(false),
+  create_branch: createBranch,
+  get_branch: getBranch,
+  list_branches: listBranches,
+  delete_branch: deleteBranch,
+};

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

@@ -0,0 +1,47 @@
+import type { SemanticsContext } from '@volter/world-core';
+import { type AuditActor } from './audit.js';
+type Row = Record<string, unknown>;
+export declare const CHECK_AFTER = 30000;
+export declare const RUN_FOR = 120000;
+export declare const REVERT_WINDOW: number;
+/** The spec's Deployment for a deploy request as it stands. */
+export declare function deploymentOf(dr: Row): Row;
+/** Who is acting: the calling token's id, or the person a page names (screens pass it). */
+export declare const actingAs: (ctx: SemanticsContext) => string;
+declare function createDeployRequest(ctx: SemanticsContext): Promise<Response>;
+declare function getDeployRequest(ctx: SemanticsContext): Promise<Response>;
+declare function getDeployment(ctx: SemanticsContext): Promise<Response>;
+declare function listDeployOperations(ctx: SemanticsContext): Promise<Response>;
+/** list_deploy_requests, newest first (the twin's order), filtered by `state`, `branch` and `into_branch`. */
+declare function listDeployRequests(ctx: SemanticsContext): Promise<Response>;
+/** The reviews of a deploy request (bookkeeping `_deploy_review` records), oldest first. */
+export declare const reviewsOf: (ctx: SemanticsContext, dr: Row) => Row[];
+/**
+ * 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 declare function recordReview(ctx: SemanticsContext, db: Row, dr: Row, reviewer: string, actor: Row, state: 'approved' | 'commented', text: string, auditActor: AuditActor): Promise<Row | Response>;
+declare function reviewDeployRequest(ctx: SemanticsContext): Promise<Response>;
+declare function listReviews(ctx: SemanticsContext): Promise<Response>;
+/** queue_deploy_request: a deployable request, approved where the database requires it, joins the serial queue. */
+declare function queueDeployRequest(ctx: SemanticsContext): Promise<Response>;
+declare function closeDeployRequest(ctx: SemanticsContext): Promise<Response>;
+/** 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 declare function applyDeploy(ctx: SemanticsContext, dr: Row, at: string): Promise<Row>;
+declare function completeRevert(ctx: SemanticsContext): Promise<Response>;
+export declare function catchUpDeployRequests(ctx: SemanticsContext): Promise<void>;
+export declare const deployRequestSemantics: {
+    create_deploy_request: typeof createDeployRequest;
+    get_deploy_request: typeof getDeployRequest;
+    list_deploy_requests: typeof listDeployRequests;
+    get_deployment: typeof getDeployment;
+    list_deploy_operations: typeof listDeployOperations;
+    review_deploy_request: typeof reviewDeployRequest;
+    list_deploy_request_reviews: typeof listReviews;
+    queue_deploy_request: typeof queueDeployRequest;
+    close_deploy_request: typeof closeDeployRequest;
+    complete_revert: typeof completeRevert;
+};
+export {};