@volter/twin-planetscale 0.1.0

package/dist/src/planetscale-store.js

@@ -0,0 +1,827 @@
+// 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 } from '@volter/world-core';
+import { emptyDatabase, execStatement, parseStatement, SqlError, tableKey, unsupported, uniqueKeyPart, withColumnCollations, } from "./planetscale-sql.js";
+import { keyedRowId, keyedRowIdentity } from "./planetscale-row.js";
+import { prepareSql, combinePlans } from "./planetscale-deploy.js";
+export const SERVICE = 'planetscale';
+export const PLANETSCALE_RESOURCE_TYPES = ['table', 'row', '_session', '_backup', '_branch_table', '_branch_row'];
+/** The default schema name a twin branch presents. Overridable per server, like the branch. */
+export const DEFAULT_DATABASE = 'twin';
+export const DEFAULT_BRANCH = 'main';
+const accessOf = (v) => (v === 'READ WRITE' || v === 'READ ONLY' ? v : undefined);
+const sessionOf = (id, rec) => ({
+    id,
+    inTransaction: rec.in_transaction === true,
+    pending: (rec.pending ?? []),
+    pendingPlans: (rec.pending_plans ?? []),
+    ...(Array.isArray(rec.locks) && rec.locks.length ? { locks: rec.locks } : {}),
+    ...(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 {
+    base;
+    constructor(base) { super(); this.base = base; }
+    get(key) { return super.has(key) ? super.get(key) : this.base.get(key); }
+}
+const rowId = (table, rowid, scope) => `${scope ? `${scope}:` : ''}row:${tableKey(table)}:${rowid}`;
+const tableId = (table, scope) => `${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, branch) => (branch === DEFAULT_BRANCH ? undefined : `${database}/${branch}`);
+const sessionId = (id) => `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();
+/** 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, databaseName, scope) {
+    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, delta, scope) {
+    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(); // 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 ?? {}) };
+                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, databaseName, scope) {
+    const db = emptyDatabase(databaseName);
+    const sessions = new Map();
+    const sessionIds = [];
+    const revs = new Map();
+    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 = {
+                name: String(rec.name ?? ''),
+                columns: (rec.columns ?? []),
+                primaryKey: (rec.primary_key ?? []),
+                uniques: (rec.uniques ?? []),
+                autoIncrement: typeof rec.auto_increment === 'number' ? rec.auto_increment : 1,
+                ...(Array.isArray(rec.indexes) && rec.indexes.length ? { indexes: rec.indexes } : {}),
+                ...(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 ?? {}) });
+            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, writes) {
+    // 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();
+    const own = (key) => {
+        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, b) => a.rowid - b.rowid);
+}
+function bumpRev(ctx, subject) {
+    const next = (ctx.revs.get(subject) ?? 0) + 1;
+    ctx.revs.set(subject, next);
+    return next;
+}
+function sessionResource(ctx, s) {
+    const id = sessionId(s.id);
+    return { type: '_session', id, fields: {
+            sid: s.id, in_transaction: s.inTransaction, pending: s.pending,
+            pending_plans: s.pendingPlans, locks: (s.locks ?? []), 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, db, writes, scope) {
+    // 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)) !== JSON.stringify(keyedRowIdentity(table, write.row.cells))) {
+                throw unsupported(`row identity hash collision in ${table.name}`);
+            }
+        }
+    }
+}
+async function flushWrites(ctx, writes, plans, session) {
+    // 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();
+    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;
+        if (w.kind === 'table') {
+            const id = tableId(w.table.name, scope);
+            resource = { type: tableType, id, fields: { name: w.table.name, columns: w.table.columns,
+                    primary_key: w.table.primaryKey, uniques: w.table.uniques,
+                    indexes: (w.table.indexes ?? []), 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 : {}, 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, s) {
+    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(); // cache: active in-process writer queues, never database state
+function serialized(root, run) {
+    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;
+}
+/** 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, occurredAt) {
+    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) {
+    const { sessionIds, revs } = loadState(ctx.root, ctx.database ?? DEFAULT_DATABASE, ctx.scope);
+    const state = { 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, id) {
+    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, table, rowid, cells, into) {
+    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, writes, locked = []) {
+    const keys = new Set();
+    const held = (table, rowid) => 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 {
+    holder;
+    constructor(holder) {
+        this.holder = holder;
+    }
+}
+const liveTransactions = new Map(); // cache: in-process lock waits
+function lockBook(root) {
+    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, id) {
+    const book = lockBook(root);
+    if (book.live.has(id))
+        return;
+    let end = () => { };
+    const ended = new Promise((resolve) => { end = resolve; });
+    book.live.set(id, { ended, end });
+}
+function transactionEnded(root, id) {
+    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, db, sessions, self, keys) {
+    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, waiter, holder) {
+    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();
+        for (let t = 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;
+    try {
+        const timedOut = await Promise.race([
+            entry.ended.then(() => false),
+            new Promise((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, sql, incomingSessionId) {
+    const databaseName = ctx.database ?? DEFAULT_DATABASE;
+    const { db, sessions, sessionIds, revs } = loadState(ctx.root, databaseName, ctx.scope);
+    const 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 = 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;
+    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) => serialized(ctx.root, () => createSessionUnlocked(ctx));
+/** Close a session, discarding any uncommitted transaction. */
+export const closeSession = (ctx, id) => 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, sql, incomingSessionId) {
+    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, id, databaseName = DEFAULT_DATABASE, scope) {
+    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, databaseName = DEFAULT_DATABASE, scope) {
+    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'];
+/**
+ * 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, root, databaseName = DEFAULT_DATABASE) {
+    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) {
+    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);
+    }
+}
+/** The image of a scope (`main` when none), sorted as the store door sorts it. */
+export function scopeImage(root, scope) {
+    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, scope, image) {
+    await serialized(ctx.root, async () => {
+        const { revs } = loadState(ctx.root, DEFAULT_DATABASE, scope);
+        const flush = { ...(ctx.root !== undefined ? { root: ctx.root } : {}), occurredAt: ctx.occurredAt, revs, scope };
+        const writes = [
+            ...image.tables.map((table) => ({ kind: 'table', table })),
+            ...image.rows.flatMap(({ table, rows }) => rows.map((row) => ({ 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, scope) {
+    await serialized(ctx.root, async () => {
+        const { db, revs } = loadState(ctx.root, DEFAULT_DATABASE, scope);
+        const flush = { ...(ctx.root !== undefined ? { root: ctx.root } : {}), occurredAt: ctx.occurredAt, revs, scope };
+        const writes = [
+            ...[...db.rows].flatMap(([key, rows]) => rows.map((r) => ({ kind: 'delete-row', table: db.tables.get(key)?.name ?? key, rowid: r.rowid }))),
+            ...[...db.tables.values()].map((t) => ({ kind: 'drop-table', table: t.name })),
+        ];
+        if (writes.length)
+            await flushWrites(flush, writes, []);
+    });
+}