@volter/twin-planetscale 0.1.0

package/api/src/semantics/backups.ts

@@ -0,0 +1,258 @@
+// Backup policies, the backups the World clock makes, and what a completed backup holds.
+// "Our Base plan includes automated backups every 12 hours"; "You can add additional scheduled backups for your
+// branches"; "To restore a backup to a new branch" (https://planetscale.com/docs/vitess/backups). The spec's
+// create_backup_policy takes a name, a `target` (production or development branches), a retention and a frequency, a
+// `schedule_time` ("HH:MM"), a `schedule_day` ("0 is Sunday, 6 is Saturday") and a `schedule_week` ("0 is the first week,
+// 3 is the fourth week"); its BackupPolicy's `required` is "Whether the policy is a required system backup".
+//
+// Where the pages stop and the twin decides: the Base plan's backups are a required system policy each database is made
+// with ("Default schedule": production branches, every 12 hours at 00:00 and 12:00 UTC, kept 7 days: the pages give the
+// frequency and neither the hours nor the retention). A policy's backup falls at its schedule_time on the days its
+// frequency names (every N hours from schedule_time, every N days, on schedule_day every N weeks, or on schedule_day of
+// week schedule_week every N months, the week being days 1–7, 8–14, 15–21 or 22–28 of the month), for every ready branch
+// of its target, and runs as an asked-for backup does (semantics/time.ts). A completed backup holds its branch's schema
+// and rows (a `_snapshot`, one per distinct image), which a restore copies into a new branch; a backup whose retention
+// has passed is deleted on the World clock.
+import { createHash } from 'node:crypto';
+import { applyTwinWrite, type ProjectedResource, type SemanticsContext } from '@volter/world-core';
+import { scopeImage, type ScopeImage } from '../../../src/planetscale-store.ts';
+import { branchScope, branchesOf } from './branches.ts';
+import { mintId, page } from './shared.ts';
+import { audit, orgOf } from './audit.ts';
+
+type Row = Record<string, unknown>;
+
+export const UNITS: Record<string, number> = { hour: 3_600_000, day: 86_400_000, week: 604_800_000, month: 2_592_000_000, year: 31_536_000_000 };
+const DAY = 86_400_000;
+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) : {});
+
+/** The actor PlanetScale's own scheduled backups carry (the twin's). */
+export const SCHEDULER = { id: 'planetscale', display_name: 'PlanetScale', avatar_url: 'https://app.planetscale.com/gravatar-fallback.png' };
+
+/** The first time after `after` (ms) a policy runs. */
+export function nextRun(policy: Row, after: number): number {
+  return firstRun(policy, after) ?? noRunWithin();
+}
+
+function firstRun(policy: Row, after: number): number | undefined {
+  const start = Math.floor(after / DAY);
+  let hit: number | undefined;
+  Array.from({ length: 800 }, (_, k) => start + k).some((day) => (hit = runOn(policy, day, after)) !== undefined);
+  return hit;
+}
+
+/** The first time on `day` (days since 1970, UTC) after `after` that a policy runs, if it runs that day. */
+function runOn(policy: Row, day: number, after: number): number | undefined {
+  const [hh, mm] = String(policy.schedule_time ?? '00:00').split(':').map(Number) as [number, number];
+  const offset = (hh * 60 + mm) * 60_000;
+  const n = Math.max(1, Number(policy.frequency_value ?? 1));
+  const unit = String(policy.frequency_unit);
+  const created = Date.parse(String(policy.created_at));
+  const createdDay = Math.floor(created / DAY);
+  const d = new Date(day * DAY);
+  const times: number[] = [];
+  if (unit === 'hour') {
+    for (let t = offset % (n * 3_600_000); t < DAY; t += n * 3_600_000) times.push(day * DAY + t);
+  } else {
+    const ok = unit === 'day' ? (day - createdDay) % n === 0
+      : unit === 'week' ? d.getUTCDay() === Number(policy.schedule_day ?? 0) && Math.floor((day - createdDay) / 7) % n === 0
+      : unit === 'month' ? d.getUTCDay() === Number(policy.schedule_day ?? 0) && Math.floor((d.getUTCDate() - 1) / 7) === Number(policy.schedule_week ?? 0)
+        && ((d.getUTCFullYear() - new Date(created).getUTCFullYear()) * 12 + d.getUTCMonth() - new Date(created).getUTCMonth()) % n === 0
+      : false;
+    if (ok) times.push(day * DAY + offset);
+  }
+  return times.find((t) => t > after && t >= created);
+}
+
+/** A policy none of whose runs falls within the next 800 days: it never runs in a World's span. */
+function noRunWithin(): number {
+  return Number.POSITIVE_INFINITY;
+}
+
+/** A policy as the spec's BackupPolicy answers it. */
+async function makePolicy(ctx: SemanticsContext, database: string, p: { name: string; target: string; retention_value: number; retention_unit: string; frequency_value: number; frequency_unit: string; schedule_time: string; schedule_day: number; schedule_week: number; required: boolean }): Promise<Row> {
+  const id = mintId(ctx, 'BackupPolicy', 'bp', `${database}/${p.name}`);
+  const at = ctx.occurredAt;
+  const draft = { ...p, created_at: at };
+  const next = nextRun(draft, Date.parse(at));
+  return ctx.write('BackupPolicy', id, {
+    id, display_name: p.name, ...p, created_at: at, updated_at: at, last_ran_at: null,
+    next_run_at: Number.isFinite(next) ? new Date(next).toISOString() : null, _database: database,
+  }, 'backup_policy.create');
+}
+
+/** The Base plan's required system policy, made with each database. */
+export const makeDefaultPolicy = (ctx: SemanticsContext, database: string): Promise<Row> => makePolicy(ctx, database, {
+  name: 'Default schedule', target: 'production', retention_value: 7, retention_unit: 'day', frequency_value: 12, frequency_unit: 'hour',
+  schedule_time: '00:00', schedule_day: 0, schedule_week: 0, required: true,
+});
+
+const policiesOf = (ctx: SemanticsContext, database: string): Row[] => ctx.rowsRaw('BackupPolicy').filter((p) => p._database === database && !p._deleted_at);
+const policyView = (ctx: SemanticsContext, p: Row): Row => ctx.get('BackupPolicy', String(p.id))!;
+
+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') };
+}
+
+async function createBackupPolicy(ctx: SemanticsContext): Promise<Response> {
+  const { refused, db } = createdDatabase(ctx);
+  if (refused) return refused;
+  const b = body(ctx);
+  const name = typeof b.name === 'string' && b.name ? b.name : '';
+  if (!name) return unprocessable(ctx, 'name is required');
+  const target = String(b.target ?? 'production');
+  if (target !== 'production' && target !== 'development') return unprocessable(ctx, 'target must be production or development');
+  const retentionUnit = String(b.retention_unit ?? '');
+  const frequencyUnit = String(b.frequency_unit ?? '');
+  if (!(retentionUnit in UNITS)) return unprocessable(ctx, 'retention_unit must be one of hour, day, week, month, year');
+  if (!['hour', 'day', 'week', 'month'].includes(frequencyUnit)) return unprocessable(ctx, 'frequency_unit must be one of hour, day, week, month');
+  const int = (v: unknown): number | undefined => (Number.isInteger(v) ? Number(v) : undefined);
+  const retentionValue = int(b.retention_value);
+  const frequencyValue = int(b.frequency_value);
+  if (!retentionValue || retentionValue < 1 || !frequencyValue || frequencyValue < 1) return unprocessable(ctx, 'retention_value and frequency_value must be whole numbers of at least 1');
+  const time = typeof b.schedule_time === 'string' ? b.schedule_time : '00:00';
+  if (!/^([01]\d|2[0-3]):[0-5]\d$/.test(time)) return unprocessable(ctx, 'schedule_time must be HH:MM');
+  const day = b.schedule_day === undefined ? null : int(b.schedule_day);
+  const week = b.schedule_week === undefined ? null : int(b.schedule_week);
+  if (day === undefined || (day !== null && (day < 0 || day > 6))) return unprocessable(ctx, 'schedule_day must be 0 (Sunday) to 6 (Saturday)');
+  if (week === undefined || (week !== null && (week < 0 || week > 3))) return unprocessable(ctx, 'schedule_week must be 0 to 3');
+  if ((frequencyUnit === 'week' || frequencyUnit === 'month') && day === null) return unprocessable(ctx, 'schedule_day is required for a weekly or monthly policy');
+  if (frequencyUnit === 'month' && week === null) return unprocessable(ctx, 'schedule_week is required for a monthly policy');
+  const record = await makePolicy(ctx, String(db!.name), {
+    name, target, retention_value: retentionValue, retention_unit: retentionUnit, frequency_value: frequencyValue, frequency_unit: frequencyUnit,
+    schedule_time: time, schedule_day: day ?? 0, schedule_week: week ?? 0, required: false,
+  });
+  await audit(ctx, orgOf(ctx), 'backup_policy', 'created', { type: 'BackupPolicy', id: String(record.id), name }, { auditable: { type: 'Database', id: String(db!.id), name: String(db!.name) } });
+  return ctx.reply(policyView(ctx, record), 201);
+}
+
+async function listBackupPolicies(ctx: SemanticsContext): Promise<Response> {
+  const { refused, db } = createdDatabase(ctx);
+  if (refused) return refused;
+  return page(ctx, policiesOf(ctx, String(db!.name)).map((p) => policyView(ctx, p)));
+}
+
+async function getBackupPolicy(ctx: SemanticsContext): Promise<Response> {
+  const { refused, db } = createdDatabase(ctx);
+  if (refused) return refused;
+  const p = policiesOf(ctx, String(db!.name)).find((x) => x.id === ctx.call.params.id);
+  return p ? ctx.reply(policyView(ctx, p)) : ctx.notFound('BackupPolicy', String(ctx.call.params.id), 'id');
+}
+
+/** Each policy's backups that have fallen due, in the order they fell due across every policy, each made at the instant
+ *  it fell due. Nothing but a request writes a branch, so every backup this catch-up settles holds the branch as it
+ *  stands now: its image and size are read once per branch. Where that stops: a deploy the same catch-up carries into the
+ *  branch (semantics/deploy-requests.ts runs first) is held by a backup that fell due before it (the twin's limit). */
+export async function catchUpPolicies(ctx: SemanticsContext): Promise<void> {
+  const now = Date.parse(ctx.occurredAt);
+  const databases = new Set(ctx.rowsRaw('Database').filter((d) => !d._deleted_at).map((d) => String(d.name)));
+  const policies = ctx.rowsRaw('BackupPolicy').filter((p) => !p._deleted_at && databases.has(String(p._database)));
+  if (!policies.some((p) => typeof p.next_run_at === 'string' && Date.parse(p.next_run_at) <= now)) return;
+  const held = new Map<string, { id: string; size: number }>();
+  const holding = async (at: SemanticsContext, database: string, branch: Row): Promise<{ id: string; size: number }> => {
+    const key = `${database}/${String(branch.name)}`;
+    if (!held.has(key)) {
+      const snap = await snapshotBranch(at, { _database: database, database_branch: { name: branch.name } });
+      held.set(key, branch.name === 'main' ? { id: snap.id, size: mainBytes(at) } : snap);
+    }
+    return held.get(key)!;
+  };
+  let n = ctx.rowsRaw('Backup', { withDeleted: true }).length;
+  // every backup and policy run this catch-up makes, written as one action (the pack's store writes a transaction's rows
+  // the same way): each keeps the instants it fell due, started, completed and expired in its own fields
+  const made: ProjectedResource[] = [];
+  let last = '';
+  const branches = new Map([...databases].map((d) => [d, branchesOf(ctx, d)]));
+  // each policy's last run is written once, at the instant of its last run
+  const ran = new Map<string, { at: SemanticsContext; when: string }>();
+  for (;;) {
+    const due = policies.filter((p) => typeof p.next_run_at === 'string' && Date.parse(p.next_run_at) <= now)
+      .sort((a, b) => String(a.next_run_at).localeCompare(String(b.next_run_at)))[0];
+    if (!due) break;
+    const when = String(due.next_run_at);
+    const at = await ctx.at(when);
+    const production = due.target === 'production';
+    for (const branch of branches.get(String(due._database)) ?? []) {
+      if (branch.production !== production || String(branch.created_at) > when) continue;
+      // a branch is ready a minute after it is made (semantics/time.ts); one not ready yet at `when` is skipped
+      if (Date.parse(String(branch.created_at)) + 60_000 > Date.parse(when)) continue;
+      n += 1;
+      const backup = scheduledBackup(at, String(due._database), branch, due, n, now, await holding(at, String(due._database), branch));
+      if (backup) made.push(backup);
+    }
+    const next = nextRun(due, Date.parse(when));
+    Object.assign(due, { last_ran_at: when, next_run_at: Number.isFinite(next) ? new Date(next).toISOString() : null, updated_at: when });
+    ran.set(String(due.id), { at, when });
+    last = when;
+  }
+  for (const p of policies) if (ran.has(String(p.id))) made.push({ type: '_backup_policy', id: String(p.id), fields: ctx.own(p) as ProjectedResource['fields'] });
+  if (!made.length) return;
+  const [subject, ...rest] = made;
+  await applyTwinWrite('planetscale', {
+    operation: 'backup_policy.run', subjectType: subject!.type, subjectId: subject!.id, fields: subject!.fields,
+    projection: { updates: rest }, occurredAt: last, actor: { kind: 'system' },
+  }, ctx.root);
+}
+
+/**
+ * A backup a policy made at `ctx`'s instant. One the World clock has already carried past its run is caught up in the
+ * same write: it started and completed at the instants the lane's timers give (semantics/time.ts), each move asked of
+ * the machine, and, when its retention has also passed, it is deleted. One still running is left to semantics/time.ts.
+ */
+function scheduledBackup(ctx: SemanticsContext, database: string, branch: Row, policy: Row, n: number, now: number, holds: { id: string; size: number }): ProjectedResource | undefined {
+  const at = ctx.occurredAt;
+  const id = `bk${createHash('sha256').update(`${at}:${database}/${String(branch.name)}:${String(policy.id)}:${n}`).digest('hex').slice(0, 12)}`;
+  const retention = Number(policy.retention_value) * UNITS[String(policy.retention_unit)]!;
+  const ref = { id: String(branch.id), name: String(branch.name), production: branch.production === true, created_at: String(branch.created_at), updated_at: String(branch.updated_at), deleted_at: null };
+  const { _database: _d, ...policyView } = ctx.own(policy);
+  const base: Row = {
+    id, name: `backup-${n}`, state: 'pending', size: 0, estimated_storage_cost: 0,
+    created_at: at, updated_at: at, started_at: null, completed_at: null, expires_at: null, deleted_at: null,
+    pvc_size: 0, uncompressed_size: 0, protected: false, required: policy.required === true, restored_branches: [],
+    actor: SCHEDULER, backup_policy: policyView, schema_snapshot: null, database_branch: ref,
+    _database: database, _retention_ms: retention,
+  };
+  const completed = new Date(Date.parse(at) + COMPLETE_AFTER).toISOString();
+  if (Date.parse(completed) > now) return { type: '_backup', id, fields: base as ProjectedResource['fields'] };
+  if (ctx.legal('Backup', 'state', 'start', 'pending', 'running', id, 'time')) return undefined;
+  if (ctx.legal('Backup', 'state', 'complete', 'running', 'success', id, 'time')) return undefined;
+  const expires = new Date(Date.parse(completed) + retention).toISOString();
+  const gone = Date.parse(expires) <= now;
+  return { type: '_backup', id, fields: {
+    ...base, state: 'success', size: holds.size, pvc_size: holds.size, uncompressed_size: holds.size,
+    started_at: new Date(Date.parse(at) + START_AFTER).toISOString(), completed_at: completed, updated_at: gone ? expires : completed,
+    expires_at: expires, _snapshot: holds.id, ...(gone ? { deleted_at: expires } : {}),
+  } as ProjectedResource['fields'] };
+}
+
+/** The bytes of `main`'s stored rows (the World's image), what a backup of `main` holds. */
+export function mainBytes(ctx: SemanticsContext): number {
+  return ctx.tree().filter((r) => r.type === 'row' && r.deleted !== true).map((r) => ctx.own(r))
+    .filter((f) => f.gone !== true && f.deleted !== true).reduce((n, f) => n + Buffer.byteLength(JSON.stringify(f.cells ?? {})), 0);
+}
+
+/** How long after it is asked for a backup starts and completes (the twin's timing; semantics/time.ts runs it). */
+export const START_AFTER = 30_000;
+export const COMPLETE_AFTER = 120_000;
+
+/** What a completed backup holds: its branch's image, stored once per distinct image as a `_snapshot`. */
+export async function snapshotBranch(ctx: SemanticsContext, backup: Row): Promise<{ id: string; size: number }> {
+  const database = String(backup._database ?? '');
+  const branch = String((backup.database_branch as Row | undefined)?.name ?? 'main');
+  const image: ScopeImage = scopeImage(ctx.root, database ? branchScope(database, branch) : undefined);
+  const text = JSON.stringify(image);
+  const id = `snapshot:${createHash('sha256').update(text).digest('hex').slice(0, 24)}`;
+  if (!ctx.tree().some((r) => r.type === '_snapshot' && r.id === id)) await ctx.record('_snapshot', { image }, id);
+  const size = image.rows.reduce((n, t) => n + t.rows.reduce((m, r) => m + Buffer.byteLength(JSON.stringify(r.cells)), 0), 0);
+  return { id, size };
+}
+
+export const backupPolicySemantics = {
+  create_backup_policy: createBackupPolicy,
+  list_backup_policies: listBackupPolicies,
+  get_backup_policy: getBackupPolicy,
+};
+

package/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,
+};