@volter/twin-planetscale 0.1.0

package/src/planetscale-store.ts

@@ -0,0 +1,869 @@
+// PlanetScale SQL state lives in the kernel tree. One statement or committed transaction
+// appends one action with its final resource projection and ordered row changes for deployment.
+// Session buffers are _session bookkeeping and never enter the deployable set. Row cells remain
+// nested so SQL column names cannot collide with the kernel's subject metadata.
+import { applyTwinWrite, getActiveWorldStore, twinResources, ownFields, readParentTreeMap, treeChangesSince, treeStamp, type ProjectedResource, type TwinResource } from '@volter/world-core';
+import {
+  emptyDatabase,
+  execStatement,
+  parseStatement,
+  SqlError,
+  tableKey,
+  type Cell,
+  unsupported,
+  type ColumnDef,
+  type Database,
+  type IndexDef,
+  type QueryOutcome,
+  type RowRec,
+  type SessionVars,
+  type TableDef,
+  uniqueKeyPart,
+  withColumnCollations,
+  type Write,
+} from './planetscale-sql.ts';
+
+import { keyedRowId, keyedRowIdentity } from './planetscale-row.ts';
+import { prepareSql, combinePlans, type SqlPlan } from './planetscale-deploy.ts';
+
+export const SERVICE = 'planetscale';
+
+export const PLANETSCALE_RESOURCE_TYPES = ['table', 'row', '_session', '_backup', '_branch_table', '_branch_row'] as const;
+
+// BRANCH SCOPES. A password belongs to one branch and acts on it ("Create new credentials to access a branch's data",
+// planetscale.com/docs/cli/password). The production branch `main` is the World's one image: the `table`/`row` subjects
+// above, which the connector pushes to a real branch, unchanged by scopes. Every other branch is a scope
+// `<database>/<branch>` whose tables and rows are `_branch_table`/`_branch_row` subjects: control-plane records the
+// connector never reads, so a development branch's DDL and rows cannot reach the real production branch. Their actions
+// are `branch.sql.apply` and carry no deploy plan.
+// THE TWIN'S LIMIT: every database's `main` shares the one image (psdb never scoped by database; DEFAULT_DATABASE is only
+// the schema name the wire presents). A World whose life makes one database is exact; two databases' `main` branches
+// would see each other's tables.
+export type PlanetscaleResourceType = (typeof PLANETSCALE_RESOURCE_TYPES)[number];
+
+/** The default schema name a twin branch presents. Overridable per server, like the branch. */
+export const DEFAULT_DATABASE = 'twin';
+export const DEFAULT_BRANCH = 'main';
+
+export type SessionState = {
+  id: string;
+  inTransaction: boolean;
+  /** writes buffered by an open transaction, in order. Empty outside a transaction. */
+  pending: Write[];
+  pendingPlans: SqlPlan[];
+  /** row-lock keys a locking read (`FOR UPDATE`/`FOR SHARE`) took in the open transaction. */
+  locks?: string[];
+  /** The open transaction is READ ONLY (`START TRANSACTION READ ONLY`, or SET TRANSACTION's). */
+  readOnly?: boolean;
+  /** `SET SESSION TRANSACTION READ ONLY|READ WRITE`: the access mode of every later transaction. */
+  sessionAccess?: 'READ WRITE' | 'READ ONLY';
+  /** `SET TRANSACTION READ ONLY|READ WRITE`: the access mode of the NEXT transaction only. */
+  nextAccess?: 'READ WRITE' | 'READ ONLY';
+  closed: boolean;
+  /** the branch scope the session was opened on; absent on `main` */
+  scope?: string;
+};
+
+const accessOf = (v: unknown): 'READ WRITE' | 'READ ONLY' | undefined => (v === 'READ WRITE' || v === 'READ ONLY' ? v : undefined);
+
+const sessionOf = (id: string, rec: Record<string, unknown>): SessionState => ({
+  id,
+  inTransaction: rec.in_transaction === true,
+  pending: (rec.pending ?? []) as Write[],
+  pendingPlans: (rec.pending_plans ?? []) as SqlPlan[],
+  ...(Array.isArray(rec.locks) && rec.locks.length ? { locks: rec.locks as string[] } : {}),
+  ...(rec.read_only === true ? { readOnly: true } : {}),
+  ...(accessOf(rec.session_access) !== undefined ? { sessionAccess: accessOf(rec.session_access)! } : {}),
+  ...(accessOf(rec.next_access) !== undefined ? { nextAccess: accessOf(rec.next_access)! } : {}),
+  closed: rec.closed === true,
+  ...(typeof rec.scope === 'string' ? { scope: rec.scope } : {}),
+});
+
+/** A statement's own `_rev` counters over the image's: a flush's bumps land here, reads fall through (a copy of every
+ *  subject's counter per statement grew with the database). Only `get` and `set` are used; it is not a snapshot: a
+ *  later patch of the image raises the counters it reads through to, which only ever grow. */
+class RevBook extends Map<string, number> {
+  private readonly base: ReadonlyMap<string, number>;
+  constructor(base: ReadonlyMap<string, number>) { super(); this.base = base; }
+  override get(key: string): number | undefined { return super.has(key) ? super.get(key) : this.base.get(key); }
+}
+
+type Loaded = {
+  db: Database;
+  /** the sessions of the scope loaded (of `main` when none) */
+  sessions: Map<string, SessionState>;
+  /** every session id of every scope, which a new session's id must not repeat */
+  sessionIds: string[];
+  /** subject id → the highest `_rev` ever written for it, INCLUDING deleted subjects. */
+  revs: Map<string, number>;
+};
+
+const rowId = (table: string, rowid: number, scope?: string): string => `${scope ? `${scope}:` : ''}row:${tableKey(table)}:${rowid}`;
+const tableId = (table: string, scope?: string): string => `${scope ? `${scope}:` : ''}table:${tableKey(table)}`;
+/** A scope that is `main` (or none) is the World's image; any other names a branch's own subjects. */
+export const scopeOf = (database: string, branch: string): string | undefined => (branch === DEFAULT_BRANCH ? undefined : `${database}/${branch}`);
+const sessionId = (id: string): string => `session:${id}`;
+
+// The image is folded once per World state, not once per statement: every statement read the whole tree and rebuilt
+// every row of every table, so a statement's cost grew with the whole database (measured through the MySQL frontend,
+// a select by email: 1.9 ms over 200 rows, 29 ms over 5,000). The memo is keyed by the tree's stamp (what the fold
+// reads; any write moves it), as GitHub's projection is. Each caller gets its own maps, since a transaction overlays its buffer onto the image
+// and a flush bumps `revs`; the row arrays, row records and table definitions are shared, and nothing changes them in place.
+const loadMemos = new WeakMap<object, Map<string, { stamp: string; loaded: Loaded }>>();
+
+/** The action log folded into a `Database` image plus the session book. The maps (tables, rows, sessions) are the
+ *  caller's own; the row arrays, row records, table definitions and `sessionIds` are shared and must not be changed in
+ *  place (replace an array to change it, as `applyWritesToImage` does). */
+export function loadState(root: string | undefined, databaseName: string, scope?: string): Loaded {
+  const store = getActiveWorldStore();
+  const memos = loadMemos.get(store) ?? loadMemos.set(store, new Map()).get(store)!;
+  const key = `${root ?? ''}\u0000${databaseName}\u0000${scope ?? ''}`;
+  // the stamp is read before the fold: a write between them leaves a newer fold under an older stamp, which the next
+  // read refolds; never an older fold under a newer stamp
+  let held = memos.get(key);
+  // a write moves the stamp; the image follows it by the rows and sessions the write touched (a refold per
+  // write made each statement's cost, and its garbage, grow with the whole database: 2.4 GB after 6,000 rows)
+  const delta = held ? treeChangesSince(SERVICE, root, held.stamp) : undefined;
+  if (held && delta && patchState(held.loaded, delta, scope)) held.stamp = delta.stamp;
+  else {
+    const stamp = treeStamp(SERVICE, root);
+    if (!held || held.stamp !== stamp) {
+      held = { stamp, loaded: foldState(root, databaseName, scope) };
+      memos.set(key, held);
+    }
+  }
+  const { db, sessions, sessionIds, revs } = held.loaded;
+  return {
+    // the maps are the caller's own; the row arrays are shared, and every writer replaces an array rather than changing
+    // it (copying each table's rows for every statement made a statement's cost, and its garbage, grow with the database)
+    db: { name: db.name, tables: new Map(db.tables), rows: new Map(db.rows) },
+    sessions: new Map(sessions),
+    sessionIds, // shared: a new session replaces the array (patchState), and a caller only reads it
+    revs: new RevBook(revs),
+  };
+}
+
+/** Bring a folded image forward by the subjects written since it was folded, as `foldState` would fold them.
+ *  False (the caller refolds) when the change is one only a whole fold decides: a table's (the orphan-row
+ *  rule reads the final table set) or a subject gone from the tree (a refold would drop its `_rev`). */
+function patchState(loaded: Loaded, delta: { changed: TwinResource[]; removed: string[] }, scope?: string): boolean {
+  if (delta.removed.length) return false;
+  if (delta.changed.some((r) => r.type === 'table' || r.type === '_branch_table')) return false;
+  const rowType = scope ? '_branch_row' : 'row';
+  const { db, sessions, revs } = loaded;
+  const copied = new Set<string>(); // a table's row array is replaced, never changed: readers may hold the old one
+  for (const r of delta.changed) {
+    const rec = ownFields(r);
+    if (typeof rec._rev === 'number') revs.set(r.id, Math.max(revs.get(r.id) ?? 0, rec._rev));
+    const gone = rec.gone === true || rec.deleted === true;
+    if (r.type === rowType || r.type === 'row' || r.type === '_branch_row') {
+      if (r.type !== rowType || (r.type === '_branch_row' && rec.scope !== scope)) continue;
+      const name = String(rec.table_name ?? '');
+      const rid = typeof rec.rowid === 'number' ? rec.rowid : Number(rec.rowid);
+      if (name === '' || !Number.isFinite(rid)) return false;
+      if (!db.tables.has(tableKey(name))) continue; // an orphan, as the fold drops it
+      const key = tableKey(name);
+      if (!copied.has(key)) { db.rows.set(key, [...(db.rows.get(key) ?? [])]); copied.add(key); }
+      const rows = db.rows.get(key)!;
+      let lo = 0; let hi = rows.length;
+      while (lo < hi) { const mid = (lo + hi) >> 1; if (rows[mid]!.rowid < rid) lo = mid + 1; else hi = mid; }
+      const found = rows[lo]?.rowid === rid;
+      if (gone) { if (found) rows.splice(lo, 1); } else {
+        const row = { rowid: rid, cells: (rec.cells ?? {}) as Record<string, unknown> as Record<string, string | null> };
+        if (found) rows[lo] = row; else rows.splice(lo, 0, row);
+      }
+
+      continue;
+    }
+    if (r.type === '_session') {
+      const id = String(rec.sid ?? '');
+      if (id === '') continue;
+      // a session's id and scope are fixed at creation; only what it holds changes
+      if (gone) return false;
+      if (!sessions.has(id) && !loaded.sessionIds.includes(id)) loaded.sessionIds = [...loaded.sessionIds, id];
+      if ((typeof rec.scope === 'string' ? rec.scope : undefined) !== scope) continue;
+      sessions.set(id, sessionOf(id, rec));
+    }
+  }
+  // an emptied table holds no array, as the fold leaves it
+  for (const key of copied) if (db.rows.get(key)!.length === 0) db.rows.delete(key);
+  return true;
+}
+
+/** Fold the action log into a `Database` image plus the session book. */
+function foldState(root: string | undefined, databaseName: string, scope?: string): Loaded {
+  const db = emptyDatabase(databaseName);
+  const sessions = new Map<string, SessionState>();
+  const sessionIds: string[] = [];
+  const revs = new Map<string, number>();
+  const tableType = scope ? '_branch_table' : 'table';
+  const rowType = scope ? '_branch_row' : 'row';
+  for (const r of twinResources(SERVICE, root)) {
+    const rec = ownFields(r);
+    // Record the ordinal FIRST, for deleted subjects too: a dropped table or a deleted row that is
+    // later recreated must CONTINUE the sequence rather than restart it, or the same content could
+    // collide with its own earlier action all over again.
+    if (typeof rec._rev === 'number') revs.set(r.id, Math.max(revs.get(r.id) ?? 0, rec._rev));
+    if (rec.gone === true || rec.deleted === true) continue;
+    if ((r.type === '_branch_table' || r.type === '_branch_row') && rec.scope !== scope) continue;
+    if (r.type === tableType) {
+      const table: TableDef = {
+        name: String(rec.name ?? ''),
+        columns: (rec.columns ?? []) as ColumnDef[],
+        primaryKey: (rec.primary_key ?? []) as string[],
+        uniques: (rec.uniques ?? []) as Array<{ name: string; columns: string[] }>,
+        autoIncrement: typeof rec.auto_increment === 'number' ? rec.auto_increment : 1,
+        ...(Array.isArray(rec.indexes) && rec.indexes.length ? { indexes: rec.indexes as IndexDef[] } : {}),
+        ...(typeof rec.charset === 'string' ? { charset: rec.charset } : {}),
+        ...(typeof rec.collation === 'string' ? { collation: rec.collation } : {}),
+      };
+      if (table.name === '') continue;
+      db.tables.set(tableKey(table.name), withColumnCollations(table));
+      continue;
+    }
+    if (r.type === rowType) {
+      const name = String(rec.table_name ?? '');
+      const rid = typeof rec.rowid === 'number' ? rec.rowid : Number(rec.rowid);
+      if (name === '' || !Number.isFinite(rid)) continue;
+      const bucket = db.rows.get(tableKey(name)) ?? [];
+      bucket.push({ rowid: rid, cells: (rec.cells ?? {}) as Record<string, unknown> as Record<string, string | null> });
+      db.rows.set(tableKey(name), bucket);
+      continue;
+    }
+    if (r.type === '_session') {
+      const id = String(rec.sid ?? '');
+      if (id === '') continue;
+      sessionIds.push(id);
+      if ((typeof rec.scope === 'string' ? rec.scope : undefined) !== scope) continue;
+      sessions.set(id, sessionOf(id, rec));
+    }
+  }
+  // Rows project in log order, which is insertion order for a table nobody has updated — but an
+  // UPDATE re-appends its subject, so the projection order is "last write wins" order, not row
+  // order. MySQL without an ORDER BY makes no ordering promise either, but a twin that reshuffles
+  // rows on every update is undebuggable, so rows are presented in stable rowid order.
+  for (const bucket of db.rows.values()) bucket.sort((a, b) => a.rowid - b.rowid);
+  // A table with no `table` subject cannot exist; drop orphan rows so a dropped-and-recreated table
+  // can never inherit the previous incarnation's rows.
+  for (const key of [...db.rows.keys()]) if (!db.tables.has(key)) db.rows.delete(key);
+  return { db, sessions, sessionIds, revs };
+}
+
+/** Apply a buffered write list to an in-memory image (the transaction overlay). */
+export function applyWritesToImage(db: Database, writes: Write[]): void {
+  // a table's array is replaced, never changed (the image's arrays are shared with other readers): copied once per
+  // call with a rowid index, and put back in rowid order once at the end (a search and a sort per write made a bulk
+  // write list quadratic)
+  const owned = new Map<string, { rows: RowRec[]; at: Map<number, number> }>();
+  const own = (key: string): { rows: RowRec[]; at: Map<number, number> } => {
+    let held = owned.get(key);
+    if (!held) {
+      const rows = [...(db.rows.get(key) ?? [])];
+      held = { rows, at: new Map(rows.map((r, i) => [r.rowid, i])) };
+      owned.set(key, held); db.rows.set(key, rows);
+    }
+    return held;
+  };
+  for (const w of writes) {
+    if (w.kind === 'table') {
+      db.tables.set(tableKey(w.table.name), w.table);
+      if (!db.rows.has(tableKey(w.table.name))) db.rows.set(tableKey(w.table.name), []);
+      continue;
+    }
+    if (w.kind === 'drop-table') {
+      db.tables.delete(tableKey(w.table));
+      db.rows.delete(tableKey(w.table));
+      owned.delete(tableKey(w.table));
+      continue;
+    }
+    const held = own(tableKey(w.table));
+    if (w.kind === 'row') {
+      const i = held.at.get(w.row.rowid);
+      if (i !== undefined) held.rows[i] = w.row; else { held.at.set(w.row.rowid, held.rows.length); held.rows.push(w.row); }
+      continue;
+    }
+    const i = held.at.get(w.rowid);
+    if (i === undefined) continue;
+    // the last row takes the deleted one's place; the order is restored at the end
+    const last = held.rows.pop()!;
+    held.at.delete(w.rowid);
+    if (i < held.rows.length) { held.rows[i] = last; held.at.set(last.rowid, i); }
+  }
+  for (const { rows } of owned.values()) rows.sort((a: RowRec, b: RowRec) => a.rowid - b.rowid);
+}
+
+type FlushCtx = { root?: string; occurredAt: string; revs: Map<string, number>; scope?: string };
+
+function bumpRev(ctx: FlushCtx, subject: string): number {
+  const next = (ctx.revs.get(subject) ?? 0) + 1;
+  ctx.revs.set(subject, next);
+  return next;
+}
+
+function sessionResource(ctx: FlushCtx, s: SessionState): ProjectedResource {
+  const id = sessionId(s.id);
+  return { type: '_session', id, fields: {
+    sid: s.id, in_transaction: s.inTransaction, pending: s.pending as never,
+    pending_plans: s.pendingPlans as never, locks: (s.locks ?? []) as never, read_only: s.readOnly === true,
+    session_access: s.sessionAccess ?? null, next_access: s.nextAccess ?? null, closed: s.closed, gone: false, _rev: bumpRev(ctx, id),
+    ...(s.scope ? { scope: s.scope } : {}),
+  } };
+}
+
+function assertUpstreamWriteIdentities(root: string | undefined, db: Database, writes: Write[], scope?: string): void {
+  // a branch scope has no upstream: its subjects are never pushed or observed
+  if (scope) return;
+  // A local tombstone cannot release an address still occupied upstream. Check that view
+  // separately before minting rows, including writes buffered inside a transaction.
+  if (writes.some(w => w.kind === 'row')) {
+    const upstream = readParentTreeMap(SERVICE, root);
+    for (const write of writes) {
+      if (write.kind !== 'row') continue;
+      const table = db.tables.get(tableKey(write.table));
+      if (!table?.primaryKey.length) continue;
+      const id = keyedRowId(table, write.row.cells);
+      const prior = upstream.get(`row:${rowId(table.name, id)}`);
+      if (prior && prior.fields.deleted !== true && prior.fields.gone !== true && JSON.stringify(keyedRowIdentity(table, prior.fields.cells as Record<string, Cell>)) !== JSON.stringify(keyedRowIdentity(table, write.row.cells))) {
+        throw unsupported(`row identity hash collision in ${table.name}`);
+      }
+    }
+  }
+}
+
+async function flushWrites(ctx: FlushCtx, writes: Write[], plans: SqlPlan[], session?: SessionState): Promise<void> {
+  // Refresh may have changed upstream while this transaction was buffered. Both COMMIT and
+  // BEGIN's implicit commit pass here and must revalidate before projecting any buffered row.
+  if (writes.some(w => w.kind === 'row')) {
+    const current = loadState(ctx.root, DEFAULT_DATABASE, ctx.scope).db;
+    // A sibling local session can occupy the address without changing upstream. Validate
+    // the held image before replaying the buffer, which would otherwise overwrite that row.
+    for (const write of writes) {
+      if (write.kind !== 'row') continue;
+      const table = current.tables.get(tableKey(write.table));
+      const held = current.rows.get(tableKey(write.table))?.find(r => r.rowid === write.row.rowid);
+      if (table?.primaryKey.length && held && JSON.stringify(keyedRowIdentity(table, held.cells)) !== JSON.stringify(keyedRowIdentity(table, write.row.cells))) {
+        throw unsupported(`row identity hash collision in ${table.name}`);
+      }
+    }
+    applyWritesToImage(current, writes);
+    assertUpstreamWriteIdentities(ctx.root, current, writes, ctx.scope);
+  }
+  // One logical SQL change is one action. Coalescing also preserves delete→reinsert within a
+  // transaction: its last image wins, rather than a projection delete erasing the reinsert.
+  const resources = new Map<string, ProjectedResource>();
+  const scope = ctx.scope;
+  const tableType = scope ? '_branch_table' : 'table';
+  const rowType = scope ? '_branch_row' : 'row';
+  const scoped = scope ? { scope } : {};
+  for (const w of writes) {
+    let resource: ProjectedResource;
+    if (w.kind === 'table') {
+      const id = tableId(w.table.name, scope);
+      resource = { type: tableType, id, fields: { name: w.table.name, columns: w.table.columns as never,
+        primary_key: w.table.primaryKey as never, uniques: w.table.uniques as never,
+        indexes: (w.table.indexes ?? []) as never, charset: w.table.charset ?? null, collation: w.table.collation ?? null,
+        auto_increment: w.table.autoIncrement, gone: false, _rev: bumpRev(ctx, id), ...scoped } };
+    } else if (w.kind === 'drop-table') {
+      const id = tableId(w.table, scope);
+      resource = { type: tableType, id, fields: { name: w.table, columns: [], primary_key: [], uniques: [],
+        auto_increment: 1, gone: true, _rev: bumpRev(ctx, id), ...scoped } };
+    } else {
+      const rid = w.kind === 'row' ? w.row.rowid : w.rowid;
+      const id = rowId(w.table, rid, scope);
+      resource = { type: rowType, id, fields: { table_name: w.table, rowid: rid,
+        cells: w.kind === 'row' ? w.row.cells as never : {}, gone: w.kind === 'delete-row', _rev: bumpRev(ctx, id), ...scoped } };
+    }
+    resources.set(`${resource.type}:${resource.id}`, resource);
+  }
+  if (!resources.size) { if (session) await writeSession(ctx, session); return; }
+  const [subject, ...rest] = [...resources.values()];
+  if (session) rest.push(sessionResource(ctx, session));
+  await applyTwinWrite(SERVICE, {
+    operation: scope ? 'branch.sql.apply' : 'sql.apply', subjectType: subject!.type, subjectId: subject!.id, fields: subject!.fields,
+    ...(scope ? {} : { input: { plan: combinePlans(plans) } }), projection: { updates: rest },
+    occurredAt: ctx.occurredAt, actor: { kind: 'agent' },
+  }, ctx.root);
+}
+
+async function writeSession(ctx: FlushCtx, s: SessionState): Promise<void> {
+  const resource = sessionResource(ctx, s);
+  await applyTwinWrite(SERVICE, { operation: 'session.write', subjectType: resource.type,
+    subjectId: resource.id, fields: resource.fields, occurredAt: ctx.occurredAt, actor: { kind: 'agent' },
+  }, ctx.root);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// SERIALIZATION
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * One in-process promise chain per state root, so every mutating entry point runs to completion
+ * before the next one starts.
+ *
+ * This is NOT belt-and-braces. `executeSql` reads the whole projection (`loadState`, which snapshots
+ * the per-subject `_rev` watermarks and the row ids) and only later writes it back — with `await`
+ * points in between. `Bun.serve` dispatches concurrently, so two overlapping `Execute` requests on
+ * one root would compute the SAME next `_rev` and the SAME `nextRowId` from the same stale snapshot,
+ * and the writes could land on the same subject.
+ *
+ * §9 round one, finding 11: three documents already ASSERTED this ("the twin is single-writer and
+ * serialized") while nothing in the code provided it. The honest options were to drop the claim or
+ * to make it true; this makes it true, which is also the behaviour a caller expects from a database.
+ *
+ * WHAT IT DOES NOT COVER, stated rather than implied (§9 round two, finding 7): the gate wraps the
+ * PSDB ENTRY POINTS — `executeSql`, `createSession`, `closeSession`. The CONNECTOR's write paths
+ * (`syncPlanetscaleFromReal` → `observeResources`, `pushPlanetscaleAction` → `confirmAction`) go straight to
+ * the kernel and take its own file locks instead; they are safe, but they are not on this chain. And
+ * the gate is in-process only, so two SEPARATE processes over one root are ordered solely by that
+ * same kernel locking.
+ */
+const gates = new Map<string, Promise<unknown>>(); // cache: active in-process writer queues, never database state
+
+function serialized<T>(root: string | undefined, run: () => Promise<T>): Promise<T> {
+  const key = root ?? '<default-root>';
+  const prior = gates.get(key) ?? Promise.resolve();
+  // `catch` on the CHAIN (not on `run`): a failed statement must not poison every later one, and
+  // the caller still receives the original rejection from `next`.
+  const next = prior.then(run, run);
+  const settled = next.then(() => undefined, () => undefined);
+  gates.set(key, settled);
+  // Drop the entry once this root goes quiet, so a process that opens many roots (every verify
+  // uses a fresh temp dir) does not retain one closure per root for its lifetime.
+  void settled.then(() => { if (gates.get(key) === settled) gates.delete(key); });
+  return next;
+}
+
+export type ExecuteContext = {
+  root?: string;
+  occurredAt: string;
+  /** the session variables the client's session carries (planetscale-wire.ts, sessionVarsOf) */
+  vars?: SessionVars;
+  readOnly?: boolean;
+  database?: string;
+  branch?: string;
+  /** the branch scope the statement acts on (scopeOf); absent on `main` */
+  scope?: string;
+};
+
+export type ExecuteResult = {
+  outcome: QueryOutcome;
+  /** the session as it stands AFTER the statement — the caller echoes it back on the wire. */
+  session: SessionState;
+};
+
+/** Mint a session id deterministically from the state that already exists — never entropy, never a
+ *  row count. The serve path must be a pure function of (request, stored state), so a session id is
+ *  derived from the ids already present rather than from `crypto.randomUUID()`. */
+export function mintSessionId(existing: Iterable<string>, occurredAt: string): string {
+  let max = 0;
+  for (const id of existing) {
+    const m = /^tws-(\d+)-/.exec(id);
+    if (m !== null) max = Math.max(max, Number(m[1]));
+  }
+  // The instant is part of the id so two sessions minted from different requests differ even when
+  // the projection they were minted from is identical — but the COUNTER is what guarantees
+  // uniqueness, since two requests can share a millisecond.
+  return `tws-${max + 1}-${Date.parse(occurredAt) || 0}`;
+}
+
+/** Open a new session. */
+async function createSessionUnlocked(ctx: ExecuteContext): Promise<SessionState> {
+  const { sessionIds, revs } = loadState(ctx.root, ctx.database ?? DEFAULT_DATABASE, ctx.scope);
+  const state: SessionState = { id: mintSessionId(sessionIds, ctx.occurredAt), inTransaction: false, pending: [], pendingPlans: [], closed: false, ...(ctx.scope ? { scope: ctx.scope } : {}) };
+  await writeSession({ ...(ctx.root !== undefined ? { root: ctx.root } : {}), occurredAt: ctx.occurredAt, revs }, state);
+  return state;
+}
+
+/** Close a session, discarding any uncommitted transaction — exactly what a dropped connection does. */
+async function closeSessionUnlocked(ctx: ExecuteContext, id: string): Promise<boolean> {
+  const { sessions, revs } = loadState(ctx.root, ctx.database ?? DEFAULT_DATABASE, ctx.scope);
+  const existing = sessions.get(id);
+  if (existing === undefined || existing.closed) return false;
+  await writeSession(
+    { ...(ctx.root !== undefined ? { root: ctx.root } : {}), occurredAt: ctx.occurredAt, revs },
+    { ...existing, inTransaction: false, pending: [], pendingPlans: [], locks: [], closed: true },
+  );
+  transactionEnded(ctx.root, id);
+  return true;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// ROW LOCKS
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+//
+// An open transaction holds InnoDB-style exclusive row locks until it ends: on every row it has
+// written (its buffered writes) and on every row a locking read (`FOR UPDATE`/`FOR SHARE`)
+// returned. A statement in ANOTHER session whose writes or locking read touch one of those rows,
+// or would claim a PRIMARY/UNIQUE key value the transaction has claimed, waits for that
+// transaction to end and then runs against what it committed, exactly as a blocked InnoDB
+// statement re-reads the latest version. Plain reads never wait (consistent nonlocking reads).
+// A wait that would close a cycle is MySQL's deadlock (errno 1213, the waiter's transaction rolled
+// back); a wait longer than innodb_lock_wait_timeout (50 s) is errno 1205.
+//
+// FOR SHARE is held exclusively here, which is stricter than InnoDB's shared lock: two readers of
+// one row serialize instead of both proceeding. The rows a locking read locks are the rows it
+// returned; InnoDB's gap and next-key locks on the ranges it scanned are not modeled.
+
+/** The lock keys of one row: its PRIMARY KEY value and every UNIQUE value it holds
+ *  (`table:u:name:[values]`), or, in a table with no primary key, its hidden row id. Keys are VALUES,
+ *  never the engine's hashed row identities, so two rows whose identities collide never share a lock. */
+function rowKeys(db: Database, table: string, rowid: number, cells: Record<string, Cell> | undefined, into: Set<string>): void {
+  const def = db.tables.get(tableKey(table));
+  if (def === undefined || def.primaryKey.length === 0) into.add(`${tableKey(table)}:row:${rowid}`);
+  if (def === undefined || cells === undefined) return;
+  const uniques = [
+    ...(def.primaryKey.length ? [{ name: 'PRIMARY', columns: def.primaryKey }] : []),
+    ...def.uniques,
+    ...def.columns.filter((c) => c.unique).map((c) => ({ name: c.name, columns: [c.name] })),
+  ];
+  for (const u of uniques) {
+    const values = u.columns.map((n) => cells[Object.keys(cells).find((k) => k.toLowerCase() === n.toLowerCase()) ?? n] ?? null);
+    if (values.some((v) => v === null)) continue;
+    // Keyed by the column's collation, as the index is: two sessions claiming 'A@x' and 'a@x' in a
+    // case-insensitive UNIQUE column contend for one key.
+    const parts = values.map((v, i) => uniqueKeyPart(def.columns.find((c) => c.name.toLowerCase() === u.columns[i]!.toLowerCase()), v!));
+    into.add(`${tableKey(table)}:u:${u.name.toLowerCase()}:${JSON.stringify(parts)}`);
+  }
+}
+
+/** The keys a write list (and a locking read's rows) lock. A deleted or locked row's values are read
+ *  from `db`, the image the rows are still in. */
+function rowLockKeys(db: Database, writes: Write[], locked: Array<{ table: string; rowid: number }> = []): Set<string> {
+  const keys = new Set<string>();
+  const held = (table: string, rowid: number): Record<string, Cell> | undefined => db.rows.get(tableKey(table))?.find((r) => r.rowid === rowid)?.cells;
+  for (const w of writes) {
+    if (w.kind === 'row') {
+      rowKeys(db, w.table, w.row.rowid, w.row.cells, keys);
+      // An update also locks the unique values it replaces. The prior image is the same ROW only
+      // when its primary key matches: a row id is a hash of the key, and a colliding id names a
+      // different row (which the write refuses elsewhere) that this statement does not lock.
+      const def = db.tables.get(tableKey(w.table));
+      const before = held(w.table, w.row.rowid);
+      if (before !== undefined && def !== undefined && JSON.stringify(keyedRowIdentity(def, before)) === JSON.stringify(keyedRowIdentity(def, w.row.cells))) rowKeys(db, w.table, w.row.rowid, before, keys);
+    }
+    else if (w.kind === 'delete-row') rowKeys(db, w.table, w.rowid, held(w.table, w.rowid), keys);
+    else keys.add(`${tableKey(w.kind === 'table' ? w.table.name : w.table)}:ddl`);
+  }
+  for (const l of locked) rowKeys(db, l.table, l.rowid, held(l.table, l.rowid), keys);
+  return keys;
+}
+
+/** A statement that must wait for `holder`'s transaction to end before it can run. */
+class LockWait { constructor(readonly holder: string) {} }
+
+/**
+ * In-process transaction bookkeeping per state root (cache: live transactions and who waits on
+ * whom, never database state). A transaction is live from its BEGIN in this process to its end;
+ * one left open by a previous process died with it, as a server restart rolls back InnoDB's open
+ * transactions, so its buffer holds no locks.
+ */
+type Live = { ended: Promise<void>; end: () => void };
+const liveTransactions = new Map<string, { live: Map<string, Live>; waitsFor: Map<string, string> }>(); // cache: in-process lock waits
+
+function lockBook(root: string | undefined): { live: Map<string, Live>; waitsFor: Map<string, string> } {
+  const key = root ?? '<default-root>';
+  let book = liveTransactions.get(key);
+  if (book === undefined) { book = { live: new Map(), waitsFor: new Map() }; liveTransactions.set(key, book); }
+  return book;
+}
+
+function transactionStarted(root: string | undefined, id: string): void {
+  const book = lockBook(root);
+  if (book.live.has(id)) return;
+  let end = (): void => {};
+  const ended = new Promise<void>((resolve) => { end = resolve; });
+  book.live.set(id, { ended, end });
+}
+
+function transactionEnded(root: string | undefined, id: string): void {
+  const book = lockBook(root);
+  const entry = book.live.get(id);
+  if (entry === undefined) return;
+  book.live.delete(id);
+  entry.end();
+}
+
+/** Throw `LockWait` when another live transaction holds a key this statement needs. */
+function assertUnlocked(root: string | undefined, db: Database, sessions: Map<string, SessionState>, self: string, keys: Set<string>): void {
+  if (keys.size === 0) return;
+  const book = lockBook(root);
+  for (const other of sessions.values()) {
+    if (other.id === self || !other.inTransaction || !book.live.has(other.id)) continue;
+    const theirs = rowLockKeys(db, other.pending);
+    for (const k of other.locks ?? []) theirs.add(k);
+    for (const k of keys) if (theirs.has(k)) throw new LockWait(other.id);
+  }
+}
+
+// innodb_lock_wait_timeout's default. The wait is measured in elapsed real time, not on the World
+// clock: a blocked statement is a request in flight, and the World clock only advances between
+// requests, so no World-clock reading can end a wait that nothing else ends.
+const LOCK_WAIT_TIMEOUT_MS = 50_000;
+
+/** Wait for `holder`'s transaction to end, or fail with MySQL's deadlock / lock-wait-timeout. */
+async function waitForLock(ctx: ExecuteContext, waiter: string | null, holder: string): Promise<void> {
+  const book = lockBook(ctx.root);
+  const entry = book.live.get(holder);
+  if (entry === undefined) return; // it ended between the check and now
+  if (waiter !== null) {
+    const seen = new Set<string>();
+    for (let t: string | undefined = holder; t !== undefined && !seen.has(t); t = book.waitsFor.get(t)) {
+      seen.add(t);
+      if (t !== waiter) continue;
+      // A cycle: MySQL rolls back the transaction that would close it and reports errno 1213.
+      await serialized(ctx.root, async () => {
+        const { sessions, revs } = loadState(ctx.root, ctx.database ?? DEFAULT_DATABASE, ctx.scope);
+        const mine = sessions.get(waiter);
+        if (mine !== undefined && mine.inTransaction) {
+          await writeSession({ ...(ctx.root !== undefined ? { root: ctx.root } : {}), occurredAt: ctx.occurredAt, revs },
+            { ...mine, inTransaction: false, pending: [], pendingPlans: [], locks: [] });
+        }
+        transactionEnded(ctx.root, waiter);
+      });
+      throw new SqlError('Deadlock found when trying to get lock; try restarting transaction', 'ABORTED', 1213, '40001');
+    }
+    book.waitsFor.set(waiter, holder);
+  }
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const timedOut = await Promise.race([
+      entry.ended.then(() => false),
+      new Promise<boolean>((resolve) => { timer = setTimeout(() => resolve(true), LOCK_WAIT_TIMEOUT_MS); }),
+    ]);
+    if (timedOut) throw new SqlError('Lock wait timeout exceeded; try restarting transaction', 'DEADLINE_EXCEEDED', 1205, 'HY000');
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+    if (waiter !== null && book.waitsFor.get(waiter) === holder) book.waitsFor.delete(waiter);
+  }
+}
+
+/**
+ * Execute ONE statement in the named session (creating the session when the client sent none —
+ * which is exactly what a first `conn.execute()` does: the client's `session` starts null).
+ */
+async function executeSqlUnlocked(ctx: ExecuteContext, sql: string, incomingSessionId: string | null): Promise<ExecuteResult> {
+  const databaseName = ctx.database ?? DEFAULT_DATABASE;
+  const { db, sessions, sessionIds, revs } = loadState(ctx.root, databaseName, ctx.scope);
+  const flushCtx: FlushCtx = { ...(ctx.root !== undefined ? { root: ctx.root } : {}), occurredAt: ctx.occurredAt, revs, ...(ctx.scope ? { scope: ctx.scope } : {}) };
+
+  let session = incomingSessionId === null ? undefined : sessions.get(incomingSessionId);
+  if (session !== undefined && session.closed) session = undefined;
+  let sessionIsNew = false;
+  if (session === undefined) {
+    session = { id: mintSessionId(sessionIds, ctx.occurredAt), inTransaction: false, pending: [], pendingPlans: [], closed: false, ...(ctx.scope ? { scope: ctx.scope } : {}) };
+    sessionIsNew = true;
+  }
+  const stmt = parseStatement(sql, ctx.vars?.sqlMode);
+
+  // A transaction this process did not open was opened by one that is gone (the server restarted
+  // under it). Its row locks died with that process, so other sessions may already have written
+  // the rows it buffered: committing the buffer now would overwrite them. MySQL rolls back the
+  // transaction of a connection that dies; so does this, and the session learns it on its next
+  // statement (a ROLLBACK simply succeeds).
+  if (session.inTransaction && !lockBook(ctx.root).live.has(session.id)) {
+    session = { ...session, inTransaction: false, pending: [], pendingPlans: [], locks: [], readOnly: false };
+    await writeSession(flushCtx, session);
+    if (stmt.kind === 'rollback') return { outcome: { fields: [], rows: [], rowsAffected: 0, insertId: 0, writes: [], transaction: 'rollback' }, session };
+    throw new SqlError('Lost connection to MySQL server during query: the twin restarted while this transaction was open, so it was rolled back', 'ABORTED', 2013, 'HY000');
+  }
+
+  // SET TRANSACTION holds the access mode for the next transaction (or, with SESSION, for every
+  // later one); the next-transaction form is refused inside an open transaction (errno 1568).
+  if (stmt.kind === 'set-transaction') {
+    if (stmt.scope === 'next' && session.inTransaction) {
+      throw new SqlError("Transaction characteristics can't be changed while a transaction is in progress", 'FAILED_PRECONDITION', 1568, '25001');
+    }
+    if (stmt.access !== undefined) {
+      session = stmt.scope === 'next' ? { ...session, nextAccess: stmt.access } : { ...session, sessionAccess: stmt.access };
+      await writeSession(flushCtx, session);
+    } else if (sessionIsNew) await writeSession(flushCtx, session);
+    return { outcome: { fields: [], rows: [], rowsAffected: 0, insertId: 0, writes: [] }, session };
+  }
+  // The access mode this statement runs under: the open transaction's, else (an autocommit
+  // statement is a transaction of its own, and so is the one BEGIN opens) the one SET TRANSACTION
+  // named for the next transaction, else the session's.
+  const startsTransaction = !session.inTransaction || stmt.kind === 'begin';
+  const nextAccess = startsTransaction ? (stmt.kind === 'begin' ? stmt.access : undefined) ?? session.nextAccess ?? session.sessionAccess : undefined;
+  const readOnlyTransaction = startsTransaction ? nextAccess === 'READ ONLY' : session.readOnly === true;
+  const consumedNext = startsTransaction && session.nextAccess !== undefined;
+  if (consumedNext) { const { nextAccess: _consumed, ...rest } = session; session = rest; }
+
+  // Other transactions' locks are judged against committed state, before this session's own
+  // buffer is overlaid (their buffered deletes name rows by their committed images).
+  const committed: Database = session.inTransaction && session.pending.length > 0
+    ? { name: db.name, tables: new Map(db.tables), rows: new Map(db.rows) } // the arrays are shared: the overlay replaces them
+    : db;
+
+  // Inside an open transaction the statement runs against committed state PLUS the buffer, so it
+  // reads its own uncommitted writes.
+  if (session.inTransaction && session.pending.length > 0) applyWritesToImage(db, session.pending);
+
+  let outcome: QueryOutcome;
+  try {
+    outcome = execStatement(db, stmt, {
+      now: ctx.occurredAt, ...(ctx.readOnly === true ? { readOnly: true } : {}), ...(ctx.vars !== undefined ? { vars: ctx.vars } : {}),
+      ...(readOnlyTransaction && stmt.kind !== 'begin' ? { transactionReadOnly: true } : {}),
+    });
+  } catch (error) {
+    // The failed statement was the transaction SET TRANSACTION named: its characteristics are spent.
+    if (consumedNext) await writeSession(flushCtx, session);
+    throw error;
+  }
+
+  if (outcome.transaction === 'begin') {
+    const next = { ...session, inTransaction: true, pending: [], pendingPlans: [], locks: [], readOnly: readOnlyTransaction };
+    await flushWrites(flushCtx, session.inTransaction ? session.pending : [], session.pendingPlans, next);
+    transactionEnded(ctx.root, session.id);
+    transactionStarted(ctx.root, session.id);
+    return { outcome, session: next };
+  }
+  if (outcome.transaction === 'commit') {
+    const next = { ...session, inTransaction: false, pending: [], pendingPlans: [], locks: [], readOnly: false };
+    await flushWrites(flushCtx, session.inTransaction ? session.pending : [], session.pendingPlans, next);
+    transactionEnded(ctx.root, session.id);
+    return { outcome, session: next };
+  }
+  if (outcome.transaction === 'rollback') {
+    session = { ...session, inTransaction: false, pending: [], pendingPlans: [], locks: [], readOnly: false };
+    await writeSession(flushCtx, session);
+    transactionEnded(ctx.root, session.id);
+    return { outcome, session };
+  }
+
+  assertUpstreamWriteIdentities(ctx.root, db, outcome.writes, ctx.scope);
+  const prepared = prepareSql(db, outcome.writes, stmt.kind, sql);
+  const lockedRows = outcome.locked ?? [];
+  assertUnlocked(ctx.root, committed, sessions, session.id, rowLockKeys(db, prepared.writes, lockedRows));
+  if (session.inTransaction) {
+    const locks = lockedRows.length ? [...new Set([...(session.locks ?? []), ...rowLockKeys(db, [], lockedRows)])] : session.locks;
+    const changed = prepared.writes.length > 0 || locks !== session.locks || consumedNext;
+    session = { ...session, pending: [...session.pending, ...prepared.writes],
+      pendingPlans: [...session.pendingPlans, ...(prepared.writes.length ? [prepared.plan] : [])], ...(locks !== undefined ? { locks } : {}) };
+    // A read inside a transaction changes nothing the session records, so it writes nothing.
+    if (changed || sessionIsNew) await writeSession(flushCtx, session);
+    return { outcome, session };
+  }
+
+  const sessionChanged = sessionIsNew || consumedNext;
+  if (prepared.writes.length > 0) await flushWrites(flushCtx, prepared.writes, [prepared.plan], sessionChanged ? session : undefined);
+  else if (sessionChanged) await writeSession(flushCtx, session);
+  return { outcome, session };
+}
+
+// The PUBLIC entry points: every one runs inside its root's serialization gate (see `serialized`).
+
+/** Open a new session. */
+export const createSession = (ctx: ExecuteContext): Promise<SessionState> =>
+  serialized(ctx.root, () => createSessionUnlocked(ctx));
+
+/** Close a session, discarding any uncommitted transaction. */
+export const closeSession = (ctx: ExecuteContext, id: string): Promise<boolean> =>
+  serialized(ctx.root, () => closeSessionUnlocked(ctx, id));
+
+/** Execute ONE statement in the named session. A statement blocked by another transaction's row
+ *  locks waits OUTSIDE the serialization gate, so the holder's COMMIT can run, then re-executes. */
+export async function executeSql(ctx: ExecuteContext, sql: string, incomingSessionId: string | null): Promise<ExecuteResult> {
+  for (;;) {
+    try {
+      return await serialized(ctx.root, () => executeSqlUnlocked(ctx, sql, incomingSessionId));
+    } catch (error) {
+      if (!(error instanceof LockWait)) throw error;
+      await waitForLock(ctx, incomingSessionId, error.holder);
+    }
+  }
+}
+
+/**
+ * The CURRENT state of one session, or undefined. Read by the request handler's error path: a
+ * statement that FAILS inside an open transaction must still echo `inTransaction: true`, because
+ * MySQL does not end a transaction on a failed statement (§9 round one, finding 10 — the handler
+ * used to answer a flat `false` and tell the caller the transaction had ended when it had not).
+ */
+export function sessionState(root: string | undefined, id: string, databaseName = DEFAULT_DATABASE, scope?: string): SessionState | undefined {
+  return loadState(root, databaseName, scope).sessions.get(id);
+}
+
+/** Read-only projection helper — used by the connector's push-free inspection and by tests. */
+export function readDatabase(root: string | undefined, databaseName = DEFAULT_DATABASE, scope?: string): Database {
+  return loadState(root, databaseName, scope).db;
+}
+
+/** The named projections this pack serves through the store door (planetscale-server.ts). */
+export const STORE_NAMES = ['tables', 'rows'] as const;
+export type StoreName = (typeof STORE_NAMES)[number];
+
+/**
+ * THE STORE DOOR projection (`GET /twin/store/<tables|rows>`, the twin programming model's named
+ * read-only read over stored state).
+ *
+ * The psdb wire is Connect-JSON: EVERY call, `Execute` included, is a POST, and the handler
+ * refuses a GET on the RPC path before it authenticates (Connect unary is POST-only, which is
+ * vendor-faithful). So a `SELECT` — the vendor's own read — cannot be a GET, and nothing in the
+ * vendor surface observes stored state with one. This is that observation: a pure, ordered fold
+ * of the same image `Execute` runs against, with the engine's internal `rowid` included because
+ * it is the row identity the projection is keyed on.
+ *
+ * `Map` iteration order is insertion order, which is a function of the log rather than of the
+ * state, so both projections are SORTED — by table key, and within a table by rowid.
+ */
+export function planetscaleStore(name: StoreName, root: string | undefined, databaseName = DEFAULT_DATABASE): unknown {
+  const db = readDatabase(root, databaseName);
+  const keys = [...db.tables.keys()].sort();
+  if (name === 'tables') return { database: db.name, tables: keys.map((k) => db.tables.get(k)!) };
+  return {
+    database: db.name,
+    rows: keys.map((k) => ({ table: k, rows: [...(db.rows.get(k) ?? [])].sort((a, b) => a.rowid - b.rowid) })),
+  };
+}
+
+export { SqlError };
+
+/** Drop every table of the branch, each in a session of its own that is closed after it: what deleting the database
+ *  does to its data (the management lane's delete_database; "Remove all data and backups permanently"). */
+export async function dropAllTables(ctx: ExecuteContext): Promise<void> {
+  for (const table of [...readDatabase(ctx.root, ctx.database ?? DEFAULT_DATABASE, ctx.scope).tables.values()]) {
+    const { session } = await executeSql(ctx, `DROP TABLE \`${table.name.replace(/`/g, '``')}\``, null);
+    await closeSession(ctx, session.id);
+  }
+}
+
+/** A branch's image as a backup or a new branch carries it: its tables, and its rows by table. */
+export type ScopeImage = { tables: TableDef[]; rows: Array<{ table: string; rows: RowRec[] }> };
+
+/** The image of a scope (`main` when none), sorted as the store door sorts it. */
+export function scopeImage(root: string | undefined, scope?: string): ScopeImage {
+  const db = readDatabase(root, DEFAULT_DATABASE, scope);
+  const keys = [...db.tables.keys()].sort();
+  return { tables: keys.map((k) => db.tables.get(k)!), rows: keys.map((k) => ({ table: db.tables.get(k)!.name, rows: [...(db.rows.get(k) ?? [])] })) };
+}
+
+/**
+ * Make a branch scope hold `image` (its tables, and its rows when a backup is restored): what creating a branch does
+ * ("the schema of the source branch is copied to the new branch", planetscale.com/docs/vitess/schema-changes/branching)
+ * and what restoring a backup into a new branch does (the spec's `create_branch.backup_id`: "restores the backup's schema
+ * and data"). One `branch.seed` action; nothing of `main` is touched.
+ */
+export async function seedScope(ctx: { root?: string; occurredAt: string }, scope: string, image: ScopeImage): Promise<void> {
+  await serialized(ctx.root, async () => {
+    const { revs } = loadState(ctx.root, DEFAULT_DATABASE, scope);
+    const flush: FlushCtx = { ...(ctx.root !== undefined ? { root: ctx.root } : {}), occurredAt: ctx.occurredAt, revs, scope };
+    const writes: Write[] = [
+      ...image.tables.map((table): Write => ({ kind: 'table', table })),
+      ...image.rows.flatMap(({ table, rows }) => rows.map((row): Write => ({ kind: 'row', table, row }))),
+    ];
+    if (writes.length) await flushWrites(flush, writes, []);
+  });
+}
+
+/** Drop every table of a branch scope with its rows, in one action: what deleting the branch does to its data. */
+export async function dropScope(ctx: { root?: string; occurredAt: string }, scope: string): Promise<void> {
+  await serialized(ctx.root, async () => {
+    const { db, revs } = loadState(ctx.root, DEFAULT_DATABASE, scope);
+    const flush: FlushCtx = { ...(ctx.root !== undefined ? { root: ctx.root } : {}), occurredAt: ctx.occurredAt, revs, scope };
+    const writes: Write[] = [
+      ...[...db.rows].flatMap(([key, rows]) => rows.map((r): Write => ({ kind: 'delete-row', table: db.tables.get(key)?.name ?? key, rowid: r.rowid }))),
+      ...[...db.tables.values()].map((t): Write => ({ kind: 'drop-table', table: t.name })),
+    ];
+    if (writes.length) await flushWrites(flush, writes, []);
+  });
+}