@volter/twin-planetscale 0.1.0

package/dist/src/planetscale-capabilities.js

@@ -0,0 +1,3977 @@
+// planetscale capability manifest — the EXPECTED REAL-PRODUCT SURFACE (the target), authored
+// top-down from what PlanetScale actually does, NOT from what this twin has built.
+//
+// GROUNDED (2026-08-31), all read-only — see spec-sources.json:
+//   (a) the ACTUALLY-INSTALLED `@planetscale/database@1.20.1` package source (npm pack) — the
+//       authoritative wire contract: dist/index.js (URL construction, the Basic header, the two
+//       error channels, `decodeRow`'s base64+lengths packing, the omitted-zero-field defaults),
+//       dist/cast.js (the field-type → JavaScript-type table), dist/sanitization.js (the client's
+//       own `?`/`:name` interpolation, which is why this wire carries no bind parameters), plus its
+//       own test fixtures for the 401 and query-error envelopes;
+//   (b) `github.com/mattrobenolt/ps-http-sim` and the `psdb.v1alpha1.Database` Connect service it
+//       implements — CreateSession / Execute / StreamExecute / CloseSession / Prepare, with Prepare
+//       answering Unimplemented;
+//   (c) planetscale.com/docs/reference/planetscale-system-limits — the published scalar limits.
+//
+// THE DENOMINATOR is enumerated from MySQL's own statement families (DDL, INSERT, SELECT, UPDATE,
+// DELETE, transactions, functions, error codes) crossed with the psdb protocol's own surface AND
+// with PlanetScale's MANAGEMENT API (api.planetscale.com: organizations, databases, branches,
+// deploy requests, backups, passwords, insights) — of which this pack models the slice its `api` lane
+// serves (api/src/: databases, branches, passwords, deploy requests, backups and policies, the audit log,
+// service tokens). The rest appear as `todo`s rather than being quietly left out, because a
+// reader deciding whether this twin covers their PlanetScale integration needs to see that the control
+// plane is missing, not infer it.
+//
+// `verify()` (required to count as done) is ground truth: every API verify drives the REAL
+// `handlePlanetscaleTwinRequest` over a FRESH temp root with a PINNED clock, and asserts VALUES —
+// never a bare status code. Nothing here is a mock.
+//
+// ── THE HONEST CARVE-OUTS ─────────────────────────────────────────────────────────────────────
+// A local twin cannot make a wall clock pass and cannot run a storage engine. `NOW()` and the
+// other clock functions read the World clock's instant for the statement, never the wall clock;
+// `RAND()` and `UUID()` are REFUSED rather than frozen (a served response must
+// be a pure function of (request, stored state)); elapsed query `timing` is never emitted; and real
+// Vitess sharding, real storage-engine physics and real replication lag are out of reach. Those are
+//
+// (PlanetScale is an API-first vendor — docs/contributing/architecture.md C1b: an integrator TALKS TO A DATABASE from
+// code, and PlanetScale's console is a provisioning/insights dashboard, not where the work happens.
+// So this pack ships NO mirror and there are no UI capabilities. README ## Coverage § No UI mirror.)
+import assert from 'node:assert/strict';
+import { deployableEntries, parentEntries } from '@volter/world-core';
+import { cpSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { checkCapabilities, verifyBoundary } from '@volter/world-tooling';
+import { handlePlanetscaleTwinRequest, PSDB_SERVICE } from "./planetscale-twin.js";
+import { createPlanetscaleTwinFetch } from "./planetscale-server.js";
+import { packRow, unpackRow } from "./planetscale-wire.js";
+import { checkPlanetscaleConformance } from "./planetscale-conformance.js";
+import { applyPlanetscaleRows, planetscaleClientOver, mapDescribeRow, pullPlanetscaleDatabase, pullPlanetscaleSnapshot, pullPlanetscaleTables, pushPlanetscaleAction, syncPlanetscaleFromReal, } from "./planetscale-connector.js";
+import { guardPlanetscaleClient, PlanetscaleBudget, PLANETSCALE_BUDGET_CEILING, PLANETSCALE_CALL_WEIGHTS } from "./planetscale-budget.js";
+import { applyWritesToImage, executeSql, readDatabase } from "./planetscale-store.js";
+import { keyedRowId } from "./planetscale-row.js";
+import { emptyDatabase, runSql, SqlError, PLANETSCALE_LIMITS } from "./planetscale-sql.js";
+/** The pinned clock every verify runs against, so session ids and action ordinals are deterministic. */
+const AT = '2026-01-01T00:00:00.000Z';
+const AT_MS = Date.parse(AT);
+/** A later instant, for verifies that need the clock to ADVANCE (a second request, a second pull). */
+const laterAt = (ms) => new Date(AT_MS + ms).toISOString();
+const AUTH = { authorization: `Basic ${btoa('twinuser:twinpass')}` };
+const EXECUTE = `/${PSDB_SERVICE}/Execute`;
+const CREATE_SESSION = `/${PSDB_SERVICE}/CreateSession`;
+const CLOSE_SESSION = `/${PSDB_SERVICE}/CloseSession`;
+function decode(res) {
+    const body = (res.body ?? {});
+    const result = body.result;
+    return {
+        status: res.status,
+        fields: result?.fields ?? [],
+        rows: (result?.rows ?? []).map(unpackRow),
+        rowsAffected: result?.rowsAffected === undefined ? 0 : Number(result.rowsAffected),
+        insertId: result?.insertId ?? '0',
+        ...(body.error !== undefined ? { error: body.error } : {}),
+        session: body.session,
+        raw: res,
+    };
+}
+async function withRoot(steps) {
+    const root = mkdtempSync(join(tmpdir(), 'planetscale-cap-'));
+    let carried = null;
+    const raw = (req) => handlePlanetscaleTwinRequest({
+        method: req.method ?? 'POST',
+        path: req.path ?? EXECUTE,
+        root,
+        occurredAt: req.at ?? AT,
+        headers: req.headers === undefined ? AUTH : req.headers,
+        ...(req.body !== undefined ? { body: req.body } : {}),
+        ...(req.readOnly !== undefined ? { readOnly: req.readOnly } : {}),
+        ...(req.username !== undefined ? { username: req.username } : {}),
+        ...(req.password !== undefined ? { password: req.password } : {}),
+        ...(req.database !== undefined ? { database: req.database } : {}),
+    });
+    const run = (async (sql, opts = {}) => {
+        const session = opts.session !== undefined ? opts.session : carried;
+        const res = await raw({
+            body: JSON.stringify({ query: sql, session }),
+            ...(opts.at !== undefined ? { at: opts.at } : {}),
+            ...(opts.readOnly !== undefined ? { readOnly: opts.readOnly } : {}),
+        });
+        const q = decode(res);
+        if (q.session !== undefined && opts.session === undefined)
+            carried = q.session;
+        return q;
+    });
+    run.raw = raw;
+    run.newSession = () => { carried = null; };
+    run.root = root;
+    try {
+        return await verifyBoundary('planetscale.withRoot', () => steps(run, root));
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+}
+/** The schema every DML verify seeds — deliberately dub-shaped, since dub is the demand source. */
+const LINK_DDL = 'CREATE TABLE Link (id BIGINT NOT NULL AUTO_INCREMENT, `key` VARCHAR(255) NOT NULL, url TEXT NOT NULL, '
+    + 'clicks INT NOT NULL DEFAULT 0, archived BOOLEAN NULL, PRIMARY KEY (id), UNIQUE KEY key_unique (`key`))';
+const ok = (q) => q.status === 200 && q.error === undefined;
+const failed = (q, code, fragment) => q.status === 200 && q.error?.code === code && q.error.message.includes(fragment);
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// CONNECTOR FAKES — an injected client, never a real one. Offline by construction.
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+/**
+ * A fake PlanetScale client shaped EXACTLY like what the real one emits: `execute` returns an
+ * `ExecutedQuery` whose `rows` are OBJECTS already cast by the client (`cast.js` has run), which is
+ * what the connector consumes. A fixture returning packed wire rows here would be green over an
+ * input the real SDK never produces.
+ */
+function fakeClient(script, opts = {}) {
+    const calls = [];
+    const client = {
+        transaction: async (fn) => fn(client),
+        async execute(query) {
+            calls.push(query);
+            if (opts.fail?.has(query))
+                throw new Error(`vendor refused: ${query}`);
+            const hit = script[query];
+            if (hit === undefined)
+                throw new Error(`unscripted query: ${query}`);
+            return hit;
+        },
+    };
+    return { client, calls };
+}
+const describeRows = (rows) => ({
+    rows: rows.map(([Field, Type, Null, Key, Default, Extra]) => ({ Field, Type, Null, Key, Default, Extra })),
+});
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// THE MANIFEST
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+/**
+ * The AREA CENSUS — enumerated TOP-DOWN from MySQL's own statement families and PlanetScale's own
+ * product surface (the psdb protocol, the branch credential model, the management API), NOT derived
+ * from the manifest below. Deriving it from the manifest would make `assertAreaCensus` a tautology;
+ * enumerating it independently is what gives the check teeth.
+ */
+export const PLANETSCALE_AREAS = [
+    'auth',
+    'collation',
+    'conformance',
+    'connector',
+    'ddl',
+    'delete',
+    'errors',
+    'functions',
+    'insert',
+    'limits',
+    'management',
+    'native',
+    'protocol',
+    'readonly',
+    'select',
+    'session',
+    'transactions',
+    'update',
+    'wire',
+];
+const todo = (id, area, title, tier) => ({ id, area, title, dimension: 'api', tier, expected: 'todo' });
+/** A minimal MySQL text-protocol client over node:net for the manifest's native verify: the
+ *  handshake response (protocol 41, secure auth, no password: the frontend takes any non-empty
+ *  auth bytes when started without --password) and COM_QUERY with text result-set decoding. */
+async function rawMysqlClient(port) {
+    const { connect } = await import('node:net');
+    const socket = connect({ host: '127.0.0.1', port });
+    let buffer = Buffer.alloc(0);
+    const packets = [];
+    const waiters = [];
+    const pump = () => {
+        while (buffer.length >= 4) {
+            const size = buffer.readUIntLE(0, 3);
+            if (buffer.length < size + 4)
+                break;
+            packets.push(Buffer.from(buffer.subarray(4, size + 4)));
+            buffer = buffer.subarray(size + 4);
+        }
+        while (packets.length > 0 && waiters.length > 0)
+            waiters.shift().resolve(packets.shift());
+    };
+    socket.on('data', (chunk) => { buffer = Buffer.concat([buffer, chunk]); pump(); });
+    socket.on('close', () => { for (const w of waiters.splice(0))
+        w.reject(new Error('native frontend closed the connection')); });
+    const next = () => new Promise((resolve, reject) => { waiters.push({ resolve, reject }); pump(); });
+    const send = (payload, seq) => { const head = Buffer.alloc(4); head.writeUIntLE(payload.length, 0, 3); head[3] = seq; socket.write(Buffer.concat([head, payload])); };
+    const lenenc = (b, at) => {
+        const first = b[at.i++];
+        if (first < 251)
+            return first;
+        if (first === 251)
+            return null;
+        if (first === 252) {
+            const v = b.readUIntLE(at.i, 2);
+            at.i += 2;
+            return v;
+        }
+        if (first === 253) {
+            const v = b.readUIntLE(at.i, 3);
+            at.i += 3;
+            return v;
+        }
+        const v = Number(b.readBigUInt64LE(at.i));
+        at.i += 8;
+        return v;
+    };
+    await new Promise((resolve, reject) => { socket.once('connect', resolve); socket.once('error', reject); });
+    await next(); // the server handshake
+    const capabilities = 512 | 8 | 32768; // PROTOCOL_41 | CONNECT_WITH_DB | SECURE_CONNECTION
+    const head = Buffer.alloc(32);
+    head.writeUInt32LE(capabilities, 0);
+    head.writeUInt32LE(16777215, 4);
+    head[8] = 45;
+    send(Buffer.concat([head, Buffer.from('twin\0'), Buffer.from([20]), Buffer.alloc(20, 1), Buffer.from('twin\0')]), 1);
+    const ok = await next();
+    if (ok[0] !== 0)
+        throw new Error(`handshake refused: ${ok.subarray(1).toString()}`);
+    const isEof = (p) => p[0] === 0xfe && p.length < 9;
+    const query = async (sql) => {
+        send(Buffer.concat([Buffer.from([3]), Buffer.from(sql)]), 0);
+        const first = await next();
+        if (first[0] === 0xff)
+            throw new Error(`query failed: ${first.subarray(3).toString()}`);
+        if (first[0] === 0)
+            return [];
+        const columns = lenenc(first, { i: 0 }) ?? 0;
+        for (let i = 0; i < columns; i++)
+            await next();
+        if (!isEof(await next()))
+            throw new Error('expected EOF after columns');
+        const rows = [];
+        for (;;) {
+            const p = await next();
+            if (isEof(p))
+                return rows;
+            const at = { i: 0 };
+            const row = [];
+            for (let i = 0; i < columns; i++) {
+                const n = lenenc(p, at);
+                if (n === null)
+                    row.push(null);
+                else {
+                    row.push(p.subarray(at.i, at.i + n).toString());
+                    at.i += n;
+                }
+            }
+            rows.push(row);
+        }
+    };
+    return { query, end: () => { send(Buffer.from([1]), 0); socket.end(); } };
+}
+export const PLANETSCALE_CAPABILITIES = [
+    // ── protocol ────────────────────────────────────────────────────────────────────────────────
+    {
+        id: 'planetscale.protocol.create_session',
+        area: 'protocol', title: 'POST /psdb.v1alpha1.Database/CreateSession mints a session, branch and user',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            const res = await q.raw({ path: CREATE_SESSION, body: '{}' });
+            const body = res.body;
+            // The user echoed back is the AUTHENTICATED one, not a constant — a handler returning a fixed
+            // envelope would pass a shape check and fail this.
+            const other = await q.raw({ path: CREATE_SESSION, body: '{}', headers: { authorization: `Basic ${btoa('someone-else:pw')}` } });
+            const otherBody = other.body;
+            return res.status === 200
+                && body.branch === 'main'
+                && body.user?.username === 'twinuser'
+                && body.session?.vitessSession?.autocommit === true
+                && body.session.vitessSession.targetString === 'main@primary'
+                && typeof body.session.vitessSession.sessionUUID === 'string' && body.session.vitessSession.sessionUUID.startsWith('tws-')
+                && typeof body.session.signature === 'string' && body.session.signature.length > 0
+                && otherBody.user?.username === 'someone-else'
+                // …and two CreateSession calls mint DIFFERENT sessions, so the id is minted from state.
+                && otherBody.session?.vitessSession?.sessionUUID !== body.session.vitessSession.sessionUUID;
+        }),
+    },
+    {
+        id: 'planetscale.protocol.execute',
+        area: 'protocol', title: 'POST /psdb.v1alpha1.Database/Execute runs a statement and returns a QueryResult',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            const res = await q('SELECT 7 AS answer FROM dual');
+            return ok(res) && res.fields.length === 1 && res.fields[0].name === 'answer' && res.rows.length === 1 && res.rows[0][0] === '7';
+        }),
+    },
+    {
+        id: 'planetscale.protocol.session_round_trip',
+        area: 'session', title: 'the client-echoed session is honoured — the same session id comes back',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            const first = await q('SELECT 1 FROM dual');
+            const id = first.session.vitessSession?.sessionUUID;
+            const second = await q('SELECT 2 FROM dual');
+            const secondId = second.session.vitessSession?.sessionUUID;
+            // A DIFFERENT session, explicitly echoed, must come back as itself rather than being reissued.
+            q.newSession();
+            const third = await q('SELECT 3 FROM dual');
+            const thirdId = third.session.vitessSession?.sessionUUID;
+            return typeof id === 'string' && id !== '' && secondId === id && typeof thirdId === 'string' && thirdId !== id;
+        }),
+    },
+    {
+        id: 'planetscale.protocol.close_session',
+        area: 'session', title: 'POST /CloseSession closes the session and discards its open transaction',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q('BEGIN');
+            await q("INSERT INTO Link (`key`, url) VALUES ('gone', 'https://g.test')");
+            const session = (await q('SELECT COUNT(*) FROM Link')).session;
+            const inside = (await q('SELECT COUNT(*) FROM Link')).rows[0][0];
+            const closed = await q.raw({ path: CLOSE_SESSION, body: JSON.stringify({ session }) });
+            const closedBody = closed.body;
+            // The buffered INSERT must be GONE — a close that flushed it would be data the caller never
+            // committed, and a close that left the session open would let the next request commit it.
+            q.newSession();
+            const after = await q('SELECT COUNT(*) FROM Link');
+            const reuse = await q('SELECT COUNT(*) FROM Link', { session });
+            const reusedId = reuse.session.vitessSession?.sessionUUID;
+            const oldId = session.vitessSession?.sessionUUID;
+            return inside === '1' && closed.status === 200
+                && closedBody.session?.vitessSession?.sessionUUID === oldId
+                && after.rows[0][0] === '0'
+                && reusedId !== oldId; // a closed session is not resurrected
+        }),
+    },
+    {
+        id: 'planetscale.protocol.prepare_unimplemented',
+        area: 'protocol', title: 'Prepare answers Connect `unimplemented` — the vendor\'s own behaviour, reproduced',
+        dimension: 'api', tier: 'niche', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            const res = await q.raw({ path: `/${PSDB_SERVICE}/Prepare`, body: '{}' });
+            const body = res.body;
+            // NOT dressed up in the `{error}` query envelope: a transport-level refusal must reach the
+            // client as `UnknownError`, not as a database error.
+            return res.status === 501 && body.code === 'unimplemented' && body.error === undefined
+                && String(body.message).includes('Prepare');
+        }),
+    },
+    {
+        id: 'planetscale.protocol.unknown_method',
+        area: 'protocol', title: 'an unknown service method answers Connect `unimplemented`, never a fabricated result',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            const unknown = await q.raw({ path: `/${PSDB_SERVICE}/DropEverything`, body: '{}' });
+            const other = await q.raw({ path: '/v1/query', body: '{}' });
+            return unknown.status === 404 && unknown.body.code === 'unimplemented'
+                && other.status === 404 && other.body.code === 'not_found';
+        }),
+    },
+    {
+        id: 'planetscale.protocol.post_only',
+        area: 'protocol', title: 'a non-POST verb is refused — Connect unary RPCs are POST-only',
+        dimension: 'api', tier: 'niche', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            const res = await q.raw({ method: 'GET', path: EXECUTE });
+            // Refused BEFORE authentication: a GET with a perfect credential is still refused.
+            const authed = await q.raw({ method: 'GET', path: EXECUTE, headers: AUTH });
+            return res.status === 405 && res.body.code === 'unimplemented' && authed.status === 405;
+        }),
+    },
+    {
+        id: 'planetscale.protocol.malformed_body',
+        area: 'protocol', title: 'a malformed JSON body and a non-string query are both refused',
+        dimension: 'api', tier: 'niche', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            const bad = await q.raw({ body: '{not json' });
+            const array = await q.raw({ body: '[1,2,3]' });
+            const noQuery = await q.raw({ body: JSON.stringify({ query: 42 }) });
+            return bad.status === 400 && bad.body.code === 'invalid_argument'
+                && array.status === 400
+                && noQuery.status === 400 && String(noQuery.body.message).includes('query must be a string');
+        }),
+    },
+    todo('planetscale.protocol.stream_execute', 'protocol', 'StreamExecute (Connect server-streaming envelope framing)', 'niche'),
+    todo('planetscale.protocol.connect_binary_codecs', 'protocol', 'the Connect/gRPC binary protobuf codecs (this twin serves the JSON codec only)', 'niche'),
+    todo('planetscale.protocol.connect_status_mapping', 'protocol', "the exact HTTP status connect-go gives an unknown method on a registered service (this twin answers 404 {code:'unimplemented'}; connect-go maps the `unimplemented` code to 501, and an unregistered mux path to a bodiless 404) — UNVERIFIED, because this build read ps-http-sim's behaviour through documentation rather than its compiled source", 'niche'),
+    todo('planetscale.protocol.allow_header', 'protocol', 'the `Allow: POST` header a 405 should carry', 'niche'),
+    todo('planetscale.protocol.compression', 'protocol', 'Connect content-encoding negotiation (gzip/br request and response compression)', 'niche'),
+    {
+        id: 'planetscale.protocol.timing',
+        area: 'protocol', title: 'ExecuteResponse.timing: emit the field as a deterministic value (today it is omitted)',
+        dimension: 'api', tier: 'niche', expected: 'todo',
+    },
+    // ── auth ────────────────────────────────────────────────────────────────────────────────────
+    {
+        id: 'planetscale.auth.basic_accepted',
+        area: 'auth', title: 'HTTP Basic credentials are accepted and the username is echoed back',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            // A password containing a colon must survive: PlanetScale connection-URL passwords are
+            // arbitrary, and splitting on the LAST colon (or on every colon) truncates them.
+            const res = await q.raw({ path: CREATE_SESSION, body: '{}', headers: { authorization: `Basic ${btoa('user:pa:ss:word')}` }, username: 'user', password: 'pa:ss:word' });
+            return res.status === 200 && res.body.user?.username === 'user';
+        }),
+    },
+    {
+        id: 'planetscale.auth.missing_credential_401',
+        area: 'auth', title: 'a missing credential answers 401 in the {error:{code,message}} envelope',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            const res = await q.raw({ body: JSON.stringify({ query: 'SELECT 1' }), headers: {} });
+            const body = res.body;
+            // The envelope matters as much as the status: the client only propagates the REAL 401 when
+            // the body carries `error`. A bare Connect body would surface as UnknownError instead.
+            return res.status === 401 && body.error?.code === 'unauthenticated' && body.error.message === 'invalid auth credentials';
+        }),
+    },
+    {
+        id: 'planetscale.auth.wrong_credential_401',
+        area: 'auth', title: 'a wrong username or password answers the SAME 401 — the vendor draws no distinction',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            const wrongPw = await q.raw({ body: JSON.stringify({ query: 'SELECT 1' }), headers: { authorization: `Basic ${btoa('right:WRONG')}` }, username: 'right', password: 'secret' });
+            const wrongUser = await q.raw({ body: JSON.stringify({ query: 'SELECT 1' }), headers: { authorization: `Basic ${btoa('WRONG:secret')}` }, username: 'right', password: 'secret' });
+            const right = await q.raw({ body: JSON.stringify({ query: 'SELECT 9 AS n FROM dual' }), headers: { authorization: `Basic ${btoa('right:secret')}` }, username: 'right', password: 'secret' });
+            const good = decode(right);
+            return wrongPw.status === 401 && wrongUser.status === 401
+                && wrongPw.body.error?.code === 'unauthenticated'
+                && wrongUser.body.error?.code === 'unauthenticated'
+                && ok(good) && good.rows[0][0] === '9';
+        }),
+    },
+    {
+        id: 'planetscale.auth.malformed_header_401',
+        area: 'auth', title: 'a malformed Authorization header never falls through as a bare credential',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            const body = JSON.stringify({ query: 'SELECT 1' });
+            const cases = [
+                { authorization: 'Bearer sometoken' }, // wrong scheme
+                { authorization: 'Basic' }, // scheme with no payload
+                { authorization: `Basic ${btoa('nocolon')}` }, // no colon in the decoded pair
+                { authorization: `Basic ${btoa(':pw')}` }, // empty username
+                { authorization: `Basic ${btoa('user:')}` }, // empty password
+                { authorization: 'Basic !!!not-base64!!!' },
+            ];
+            for (const headers of cases) {
+                const res = await q.raw({ body, headers });
+                if (res.status !== 401 || res.body.error?.code !== 'unauthenticated')
+                    return false;
+            }
+            return true;
+        }),
+    },
+    todo('planetscale.session.vitess_session_fields', 'session', "the inner psdb Session shape beyond the identity + transaction state this protocol needs \u2014 the real Vitess Session proto carries shard sessions, options, warnings and a DDL strategy; the client reads NONE of them (it echoes the session verbatim), so they are not fabricated", 'niche'),
+    todo('planetscale.session.concurrent_use_refusal', 'session', "ps-http-sim's PermissionDenied when a session is already in use by another IN-FLIGHT request. This twin serializes per state root instead of refusing (planetscale-store.ts's `serialized` gate), so the condition never arises in-process — but two SEPARATE processes over one root are ordered only by the kernel's own file locking, and neither refuses", 'niche'),
+    todo('planetscale.auth.password_expiry', 'auth', 'expiring branch passwords and the refusal a lapsed one gets', 'niche'),
+    // ── wire encoding ───────────────────────────────────────────────────────────────────────────
+    {
+        id: 'planetscale.wire.row_packing',
+        area: 'wire', title: 'rows are packed as concatenated bytes with per-column decimal byte lengths',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url) VALUES ('ab', 'https://x.test')");
+            const res = await q('SELECT `key`, url FROM Link');
+            const raw = (res.raw.body.result?.rows ?? [])[0];
+            if (raw === undefined)
+                return false;
+            // Assert the LITERAL packing, not just the decode: lengths are decimal STRINGS, values are ONE
+            // base64 blob with no separators, and the decoded slices are the seeded values.
+            return raw.lengths.length === 2 && raw.lengths[0] === '2' && raw.lengths[1] === '14'
+                && raw.values === btoa('abhttps://x.test')
+                && res.rows[0][0] === 'ab' && res.rows[0][1] === 'https://x.test';
+        }),
+    },
+    {
+        id: 'planetscale.wire.null_lengths',
+        area: 'wire', title: 'a NULL column is length -1 and contributes no bytes; an all-NULL row omits `values`',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url) VALUES ('n', 'https://n.test')");
+            const res = await q('SELECT archived, `key`, archived FROM Link');
+            const raw = (res.raw.body.result?.rows ?? [])[0];
+            const allNull = await q('SELECT archived FROM Link');
+            const allNullRaw = (allNull.raw.body.result?.rows ?? [])[0];
+            return raw !== undefined && raw.lengths[0] === '-1' && raw.lengths[1] === '1' && raw.lengths[2] === '-1'
+                && raw.values === btoa('n')
+                && res.rows[0][0] === null && res.rows[0][1] === 'n' && res.rows[0][2] === null
+                && allNullRaw !== undefined && allNullRaw.lengths[0] === '-1' && allNullRaw.values === undefined;
+        }),
+    },
+    {
+        id: 'planetscale.wire.multibyte_lengths',
+        area: 'wire', title: 'a length is the BYTE count, not the character count',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            // '鍵' is 3 UTF-8 bytes, '🔑' is 4 — a character count here would be 2, and every LATER column
+            // in the row would be sliced from the wrong offset.
+            await q("INSERT INTO Link (`key`, url) VALUES ('鍵🔑', 'https://after.test')");
+            const res = await q('SELECT `key`, url FROM Link');
+            const raw = (res.raw.body.result?.rows ?? [])[0];
+            if (raw === undefined || res.rows[0] === undefined)
+                return false;
+            const packedKey = res.rows[0][0];
+            if (packedKey === null)
+                return false;
+            // `unpackRow` returns the RAW BYTES as latin-1 chars (exactly what the client's `atob` gives
+            // it), so the assertion decodes them the way the client's own `decodeUtf8` does.
+            const decoded = new TextDecoder().decode(Uint8Array.from(packedKey, (c) => c.charCodeAt(0)));
+            return raw.lengths[0] === '7' && decoded === '鍵🔑' && res.rows[0][1] === 'https://after.test';
+        }),
+    },
+    {
+        id: 'planetscale.wire.omitted_zero_fields',
+        area: 'wire', title: 'protojson zero values are OMITTED — a DDL result is the empty object',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            const ddl = await q(LINK_DDL);
+            const ddlResult = ddl.raw.body.result;
+            const insert = await q("INSERT INTO Link (`key`, url) VALUES ('z', 'https://z.test')");
+            const insertResult = insert.raw.body.result;
+            const update = await q("UPDATE Link SET clicks = 3 WHERE `key` = 'z'");
+            const updateResult = update.raw.body.result;
+            // The client's own defaults (`result?.rowsAffected ? … : 0`, `insertId ?? '0'`) depend on this
+            // exactly — emitting `"rowsAffected":"0"` would be a different wire.
+            return ddlResult !== undefined && Object.keys(ddlResult).length === 0
+                && insertResult?.rowsAffected === '1' && insertResult.insertId === '1'
+                && insertResult.fields === undefined && insertResult.rows === undefined
+                && updateResult?.rowsAffected === '1' && updateResult.insertId === undefined;
+        }),
+    },
+    {
+        id: 'planetscale.wire.field_metadata',
+        area: 'wire', title: 'Field carries name/type/table/orgName/charset/flags/columnType, and NULL_TYPE is omitted',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            const res = await q('SELECT id, `key`, clicks FROM Link');
+            const [id, key, clicks] = res.fields;
+            const nullField = (await q('SELECT NULL AS nothing FROM dual')).fields[0];
+            return id?.type === 'INT64' && id.table === 'Link' && id.orgName === 'id' && id.database === 'twin'
+                // NOT_NULL | PRI_KEY | AUTO_INCREMENT — the literal mysql_com.h flag bits, asserted as
+                // numbers rather than against the pack's own constants (which would be a tautology).
+                && ((id.flags ?? 0) & 1) !== 0 && ((id.flags ?? 0) & 2) !== 0 && ((id.flags ?? 0) & 512) !== 0
+                && id.columnType === 'bigint'
+                && key?.type === 'VARCHAR' && key.charset === 45 && key.columnLength === 255
+                && clicks?.type === 'INT32' && clicks.columnType === 'int'
+                // NULL_TYPE is enum 0 and protojson omits it — the client re-adds it with `field.type ||= 'NULL'`.
+                && nullField !== undefined && nullField.name === 'nothing' && nullField.type === undefined;
+        }),
+    },
+    {
+        id: 'planetscale.wire.binary_charset',
+        area: 'wire', title: 'a BINARY/BLOB column reports charset 63 and packs one byte per character',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q('CREATE TABLE Blobs (id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, payload VARBINARY(64) NULL)');
+            // `x'…'` is what the client's own `format()` emits for a Uint8Array argument
+            // (dist/text.js `uint8ArrayToHex`), so this is the literal shape a real caller sends.
+            await q("INSERT INTO Blobs (payload) VALUES (x'00ff41')");
+            const res = await q('SELECT payload FROM Blobs');
+            const raw = (res.raw.body.result?.rows ?? [])[0];
+            const field = res.fields[0];
+            // 3 BYTES, not the 5 a UTF-8 encoding of U+00FF would produce — charset 63 means latin-1
+            // layout, which is what makes the client's `Uint8Array.from` give back the original bytes.
+            return field?.charset === 63 && field.type === 'VARBINARY'
+                && raw?.lengths[0] === '3' && raw.values === btoa('\x00\xff\x41');
+        }),
+    },
+    {
+        id: 'planetscale.wire.json_column',
+        area: 'wire', title: 'a JSON column is typed JSON so the client parses it back into an object',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q('CREATE TABLE Docs (id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, body JSON NULL)');
+            await q(`INSERT INTO Docs (body) VALUES ('{"a":[1,2],"b":"x"}')`);
+            const res = await q('SELECT body FROM Docs');
+            return res.fields[0]?.type === 'JSON' && res.fields[0].columnLength === 4294967295
+                && JSON.parse(res.rows[0][0]).a[1] === 2;
+        }),
+    },
+    {
+        id: 'planetscale.wire.decimal_and_bigint_stay_strings',
+        area: 'wire', title: 'DECIMAL and INT64 are typed so the client leaves them as strings (precision-safe)',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q('CREATE TABLE Money (id BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY, amount DECIMAL(20,4) NOT NULL, big BIGINT UNSIGNED NOT NULL)');
+            await q("INSERT INTO Money (amount, big) VALUES ('12345678901234.5678', '18446744073709551615')");
+            const res = await q('SELECT amount, big FROM Money');
+            // Both survive EXACTLY: a twin typing these FLOAT64 would hand the client a number and the
+            // last digits would silently vanish.
+            return res.fields[0]?.type === 'DECIMAL' && res.fields[1]?.type === 'UINT64'
+                && res.rows[0][0] === '12345678901234.5678' && res.rows[0][1] === '18446744073709551615';
+        }),
+    },
+    // ── ddl ─────────────────────────────────────────────────────────────────────────────────────
+    {
+        id: 'planetscale.ddl.create_table',
+        area: 'ddl', title: 'CREATE TABLE creates a real schema the later DML sees',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            const before = await q('SELECT * FROM Link');
+            const created = await q(LINK_DDL);
+            const after = await q('SELECT * FROM Link');
+            return failed(before, 'NOT_FOUND', "Table 'twin.Link' doesn't exist")
+                && ok(created) && ok(after) && after.fields.map((f) => f.name).join(',') === 'id,key,url,clicks,archived';
+        }),
+    },
+    {
+        id: 'planetscale.ddl.create_table_already_exists',
+        area: 'ddl', title: 'a second CREATE TABLE raises errno 1050, and IF NOT EXISTS makes it a no-op',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            const again = await q(LINK_DDL);
+            const guarded = await q('CREATE TABLE IF NOT EXISTS Link (id INT PRIMARY KEY)');
+            // The IF NOT EXISTS form must NOT have replaced the schema.
+            const shape = await q('SELECT * FROM Link');
+            return failed(again, 'ALREADY_EXISTS', "Table 'Link' already exists")
+                && again.error.message.includes('(errno 1050) (sqlstate 42S01)')
+                && ok(guarded) && shape.fields.length === 5;
+        }),
+    },
+    {
+        id: 'planetscale.ddl.drop_table',
+        area: 'ddl', title: 'DROP TABLE removes the schema AND its rows; IF EXISTS is a no-op',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url) VALUES ('a', 'https://a.test')");
+            const dropped = await q('DROP TABLE Link');
+            const gone = await q('SELECT * FROM Link');
+            const missing = await q('DROP TABLE Nope');
+            const guarded = await q('DROP TABLE IF EXISTS Nope');
+            // Recreate it: the previous incarnation's row must NOT come back — the classic
+            // dropped-and-recreated-table dirty-state bug.
+            await q(LINK_DDL);
+            const fresh = await q('SELECT COUNT(*) FROM Link');
+            return ok(dropped) && failed(gone, 'NOT_FOUND', "doesn't exist")
+                && failed(missing, 'NOT_FOUND', "Unknown table 'twin.Nope'") && ok(guarded)
+                && fresh.rows[0][0] === '0';
+        }),
+    },
+    {
+        id: 'planetscale.ddl.truncate_resets_auto_increment',
+        area: 'ddl', title: 'TRUNCATE empties the table AND resets AUTO_INCREMENT (unlike DELETE)',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url) VALUES ('a', 'https://a.test'), ('b', 'https://b.test')");
+            const truncated = await q('TRUNCATE TABLE Link');
+            const empty = await q('SELECT COUNT(*) FROM Link');
+            const reinserted = await q("INSERT INTO Link (`key`, url) VALUES ('c', 'https://c.test')");
+            return ok(truncated) && empty.rows[0][0] === '0' && reinserted.insertId === '1';
+        }),
+    },
+    {
+        id: 'planetscale.ddl.show_tables',
+        area: 'ddl', title: 'SHOW TABLES lists the real tables under the Tables_in_<db> column',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            const before = await q('SHOW TABLES');
+            await q(LINK_DDL);
+            await q('CREATE TABLE Domain (id INT NOT NULL PRIMARY KEY, slug VARCHAR(64) NOT NULL)');
+            const after = await q('SHOW TABLES');
+            await q('DROP TABLE Domain');
+            const dropped = await q('SHOW TABLES');
+            return before.rows.length === 0 && after.fields[0]?.name === 'Tables_in_twin'
+                && after.rows.map((r) => r[0]).join(',') === 'Domain,Link'
+                && dropped.rows.map((r) => r[0]).join(',') === 'Link';
+        }),
+    },
+    {
+        id: 'planetscale.ddl.describe',
+        area: 'ddl', title: 'DESCRIBE / SHOW COLUMNS report Field/Type/Null/Key/Default/Extra',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            const described = await q('DESCRIBE Link');
+            const columns = await q('SHOW COLUMNS FROM Link');
+            const byName = new Map(described.rows.map((r) => [r[0], r]));
+            const missing = await q('DESCRIBE Nope');
+            return described.fields.map((f) => f.name).join(',') === 'Field,Type,Null,Key,Default,Extra'
+                && byName.get('id')?.slice(1).join('|') === 'bigint|NO|PRI||auto_increment'
+                && byName.get('key')?.slice(1).join('|') === 'varchar(255)|NO|UNI||'
+                && byName.get('clicks')?.slice(1).join('|') === 'int|NO||0|'
+                // `archived` is nullable with no explicit DEFAULT, which MySQL reports as DEFAULT NULL.
+                && byName.get('archived')?.[4] === null
+                && JSON.stringify(columns.rows) === JSON.stringify(described.rows)
+                && failed(missing, 'NOT_FOUND', "Table 'twin.Nope' doesn't exist");
+        }),
+    },
+    {
+        id: 'planetscale.ddl.column_definition_errors',
+        area: 'ddl', title: 'a duplicate column, a keyless AUTO_INCREMENT and a phantom key column are all refused',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            const dup = await q('CREATE TABLE A (id INT PRIMARY KEY, id INT)');
+            const keyless = await q('CREATE TABLE B (id INT AUTO_INCREMENT, name VARCHAR(8))');
+            const phantom = await q('CREATE TABLE C (id INT, PRIMARY KEY (nope))');
+            const twoAuto = await q('CREATE TABLE D (a INT AUTO_INCREMENT PRIMARY KEY, b INT AUTO_INCREMENT UNIQUE)');
+            // …and none of them left a half-built table behind.
+            const listed = await q('SHOW TABLES');
+            return failed(dup, 'INVALID_ARGUMENT', "Duplicate column name 'id'")
+                && failed(keyless, 'INVALID_ARGUMENT', 'there can be only one auto column')
+                && failed(phantom, 'INVALID_ARGUMENT', "Key column 'nope' doesn't exist in table")
+                && failed(twoAuto, 'INVALID_ARGUMENT', 'there can be only one auto column')
+                && listed.rows.length === 0;
+        }),
+    },
+    {
+        id: 'planetscale.ddl.secondary_index_accepted',
+        area: 'ddl', title: 'a non-unique KEY/INDEX declaration is accepted (it changes access paths, not results)',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            const created = await q('CREATE TABLE Click (id BIGINT NOT NULL AUTO_INCREMENT, link_id BIGINT NOT NULL, country CHAR(2) NULL, '
+                + 'PRIMARY KEY (id), KEY link_idx (link_id), KEY country_idx (country(2)))');
+            await q('INSERT INTO Click (link_id, country) VALUES (7, \'GB\'), (7, \'US\'), (8, \'GB\')');
+            const filtered = await q('SELECT COUNT(*) FROM Click WHERE link_id = 7');
+            // The index does NOT become a uniqueness constraint — two rows with link_id 7 coexist.
+            return ok(created) && filtered.rows[0][0] === '2';
+        }),
+    },
+    {
+        id: 'planetscale.ddl.default_current_timestamp',
+        area: 'ddl', title: 'DEFAULT CURRENT_TIMESTAMP(fsp) is accepted, reported by INFORMATION_SCHEMA and evaluated from the World clock at insert',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            // Prisma's rendering of `@default(now())` on a `DateTime` (@db.DateTime(3)), verbatim in shape.
+            const created = await q('CREATE TABLE Ev (id INT NOT NULL, at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), PRIMARY KEY (id))');
+            const mismatched = await q('CREATE TABLE Bad (id INT PRIMARY KEY, at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP)');
+            await q('INSERT INTO Ev (id) VALUES (1)', { at: '2026-03-04T05:06:07.890Z' });
+            const read = await q('SELECT at FROM Ev');
+            const column = await q("SELECT COLUMN_DEFAULT, EXTRA FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_NAME = 'Ev' AND COLUMN_NAME = 'at'");
+            // The instant is the request's World-clock instant, never the wall clock.
+            return ok(created) && read.rows[0][0] === '2026-03-04 05:06:07.890'
+                && column.rows[0][0] === 'CURRENT_TIMESTAMP(3)' && column.rows[0][1] === 'DEFAULT_GENERATED'
+                && failed(mismatched, 'INVALID_ARGUMENT', "Invalid default value for 'at'") && mismatched.error.message.includes('(errno 1067)');
+        }),
+    },
+    todo('planetscale.ddl.on_update_current_timestamp', 'ddl', 'ON UPDATE CURRENT_TIMESTAMP evaluated from the World clock at write time', 'common'),
+    {
+        id: 'planetscale.ddl.composite_unique',
+        area: 'ddl', title: 'a composite UNIQUE (a, b) constrains the tuple, not each column on its own',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q('CREATE TABLE Member (id INT NOT NULL, email VARCHAR(191) NOT NULL, projectId VARCHAR(191) NOT NULL, '
+                + 'UNIQUE INDEX Member_email_projectId_key(email, projectId), PRIMARY KEY (id))');
+            const first = await q("INSERT INTO Member (id, email, projectId) VALUES (1, 'a@x.test', 'p1')");
+            const sameEmail = await q("INSERT INTO Member (id, email, projectId) VALUES (2, 'a@x.test', 'p2')");
+            const dup = await q("INSERT INTO Member (id, email, projectId) VALUES (3, 'a@x.test', 'p1')");
+            return ok(first) && ok(sameEmail)
+                && failed(dup, 'ALREADY_EXISTS', "Duplicate entry 'a@x.test-p1' for key 'Member.Member_email_projectId_key'");
+        }),
+    },
+    todo('planetscale.ddl.alter_table', 'ddl', 'ALTER TABLE beyond ADD and DROP COLUMN (modify/rename column, add/drop index, a column added as a key)', 'core'),
+    {
+        id: 'planetscale.ddl.alter_table_add_column',
+        area: 'ddl', title: 'ALTER TABLE … ADD COLUMN places the column last, FIRST or AFTER a column, fills existing rows with its default, and refuses a duplicate name (errno 1060)',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q('CREATE TABLE Link (id BIGINT PRIMARY KEY AUTO_INCREMENT, domain VARCHAR(190) NOT NULL)');
+            await q("INSERT INTO Link (domain) VALUES ('go.t.io')");
+            const add = await q('ALTER TABLE Link ADD COLUMN archived TINYINT(1) NOT NULL DEFAULT 0, ADD COLUMN note VARCHAR(20) AFTER id, ADD COLUMN rank INT NOT NULL FIRST');
+            const dup = await q('ALTER TABLE Link ADD COLUMN archived INT');
+            const rows = await q('SELECT * FROM Link');
+            return ok(add) && failed(dup, 'INVALID_ARGUMENT', "Duplicate column name 'archived'") && dup.error.message.includes('1060')
+                && JSON.stringify(rows.rows.map((r) => r.map((v) => (v === null ? null : String(v))))) === JSON.stringify([['0', '1', null, 'go.t.io', '0']]);
+        }),
+    },
+    todo('planetscale.ddl.foreign_keys', 'ddl', 'FOREIGN KEY constraints and their referential actions', 'common'),
+    todo('planetscale.ddl.check_constraints', 'ddl', 'CHECK constraints', 'niche'),
+    todo('planetscale.ddl.generated_columns', 'ddl', 'GENERATED ALWAYS AS (…) VIRTUAL/STORED columns', 'niche'),
+    todo('planetscale.ddl.create_view', 'ddl', 'CREATE VIEW / DROP VIEW and querying a view', 'niche'),
+    {
+        id: 'planetscale.ddl.enum_set_validation',
+        area: 'ddl', title: 'ENUM/SET values are checked against their members (errno 1265) and stored in the declared spelling and order',
+        dimension: 'api', tier: 'niche', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q("CREATE TABLE Pet (id INT PRIMARY KEY, kind ENUM('cat','dog') NOT NULL, tags SET('a','b','c'))");
+            const good = await q("INSERT INTO Pet VALUES (1, 'DOG', 'c,a'), (2, 1, NULL)");
+            const bad = await q("INSERT INTO Pet VALUES (3, 'fish', NULL)");
+            const badSet = await q("INSERT INTO Pet VALUES (4, 'cat', 'a,z')");
+            const rows = await q('SELECT kind, tags FROM Pet ORDER BY id');
+            return ok(good) && failed(bad, 'INVALID_ARGUMENT', "Data truncated for column 'kind' at row 1") && bad.error.message.includes('1265')
+                && failed(badSet, 'INVALID_ARGUMENT', "Data truncated for column 'tags'")
+                && JSON.stringify(rows.rows) === JSON.stringify([['dog', 'a,c'], ['cat', null]]);
+        }),
+    },
+    {
+        id: 'planetscale.ddl.column_length_enforcement',
+        area: 'ddl', title: 'CHAR/VARCHAR(n) count characters and VARBINARY(n)/TEXT count bytes: a longer value is errno 1406; excess trailing spaces are dropped',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q('CREATE TABLE Note (id INT PRIMARY KEY, title VARCHAR(5), code CHAR(3), raw VARBINARY(2), body TINYTEXT)');
+            const fits = await q("INSERT INTO Note (id, title, code) VALUES (1, 'héllo', 'ab     ')");
+            const long = await q("INSERT INTO Note (id, title) VALUES (2, 'héllo!')");
+            const bytes = await q("INSERT INTO Note (id, raw) VALUES (3, 'abc')");
+            const text = await q(`INSERT INTO Note (id, body) VALUES (4, '${'é'.repeat(128)}')`);
+            const read = await q('SELECT title, code FROM Note WHERE id = 1');
+            return ok(fits) && failed(long, 'INVALID_ARGUMENT', "Data too long for column 'title' at row 1") && long.error.message.includes('1406')
+                && failed(bytes, 'INVALID_ARGUMENT', "Data too long for column 'raw'") && failed(text, 'INVALID_ARGUMENT', "Data too long for column 'body'")
+                // The wire carries UTF-8 bytes (`unpackRow` hands them back as latin-1 chars, as the client's
+                // `atob` does), so decode them as the client's `decodeUtf8` does before comparing text.
+                && JSON.stringify(read.rows.map((row) => row.map((v) => v === null ? null : new TextDecoder().decode(Uint8Array.from(v, (c) => c.charCodeAt(0))))))
+                    === JSON.stringify([['héllo', 'ab']]);
+        }),
+    },
+    {
+        id: 'planetscale.ddl.numeric_range_enforcement',
+        area: 'ddl', title: 'integers and DECIMAL(p,s) are range-checked on write (errno 1264); DECIMAL is rounded to its scale; INSERT IGNORE clips instead',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q('CREATE TABLE Acct (id INT PRIMARY KEY, n TINYINT UNSIGNED, bal DECIMAL(5,2))');
+            const tiny = await q('INSERT INTO Acct (id, n) VALUES (1, 256)');
+            const neg = await q('INSERT INTO Acct (id, n) VALUES (2, -1)');
+            const wide = await q('INSERT INTO Acct (id, bal) VALUES (3, 1000)');
+            const rounds = await q("INSERT INTO Acct (id, n, bal) VALUES (4, '7.5', 2.345)");
+            const clipped = await q('INSERT IGNORE INTO Acct (id, n, bal) VALUES (5, 999, 99999)');
+            const rows = await q('SELECT n, bal FROM Acct ORDER BY id');
+            return failed(tiny, 'INVALID_ARGUMENT', "Out of range value for column 'n' at row 1") && tiny.error.message.includes('1264')
+                && failed(neg, 'INVALID_ARGUMENT', 'Out of range') && failed(wide, 'INVALID_ARGUMENT', "Out of range value for column 'bal'")
+                && ok(rounds) && ok(clipped) && JSON.stringify(rows.rows) === JSON.stringify([['8', '2.35'], ['255', '999.99']]);
+        }),
+    },
+    // ── limits ──────────────────────────────────────────────────────────────────────────────────
+    {
+        id: 'planetscale.limits.tables_per_schema',
+        area: 'limits', title: 'the published 2048-table-per-schema limit is genuinely enforced (errno 1116)',
+        dimension: 'api', tier: 'niche', expected: 'done',
+        verify: () => withRoot(async () => {
+            // §9 ROUND ONE, FINDING 2: this used to be titled "the 2048-TABLE limit is enforced" while
+            // exercising only the COLUMN limit — delete the `db.tables.size >= …` branch and it stayed
+            // green. It now actually creates 2048 tables and refuses the 2049th. That is affordable at
+            // the ENGINE level (measured: ~8 ms), which is why this verify does not go through HTTP.
+            if (PLANETSCALE_LIMITS.maxTablesPerSchema !== 2048)
+                return false; // the LITERAL published figure
+            const image = emptyDatabase('twin');
+            for (let i = 0; i < 2048; i++)
+                applyWritesToImage(image, runSql(image, `CREATE TABLE t${i} (id INT PRIMARY KEY)`).writes);
+            if (image.tables.size !== 2048)
+                return false;
+            let refused = null;
+            try {
+                runSql(image, 'CREATE TABLE overflow (id INT PRIMARY KEY)');
+            }
+            catch (e) {
+                refused = e instanceof SqlError ? e : null;
+            }
+            // …and the 2048th was ACCEPTED, so the cap is off-by-none rather than merely present.
+            return refused !== null && refused.errno === 1116 && refused.code === 'RESOURCE_EXHAUSTED'
+                && refused.message.includes('limited to 2048 tables')
+                && image.tables.has('t2047');
+        }),
+    },
+    {
+        id: 'planetscale.limits.columns_per_table',
+        area: 'limits', title: 'the published 1017-column-per-table limit is enforced (errno 1117)',
+        dimension: 'api', tier: 'niche', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            // Split out of the entry above by §9 round one: this is what that verify actually proved, so
+            // it now has its own id and a title that matches it. Routed through the real handler.
+            if (PLANETSCALE_LIMITS.maxColumnsPerTable !== 1017)
+                return false; // the LITERAL published figure
+            const refused = await q(`CREATE TABLE Wide (${Array.from({ length: 1018 }, (_, i) => `c${i} INT`).join(', ')})`);
+            const fits = await q(`CREATE TABLE Fits (${Array.from({ length: 1017 }, (_, i) => `c${i} INT`).join(', ')})`);
+            const listed = await q('SHOW TABLES');
+            return failed(refused, 'RESOURCE_EXHAUSTED', 'limited to 1017 columns')
+                && refused.error.message.includes('(errno 1117)')
+                && ok(fits)
+                // The refused table left NOTHING behind — the check precedes the write.
+                && listed.rows.map((r) => r[0]).join(',') === 'Fits';
+        }),
+    },
+    {
+        id: 'planetscale.limits.rows_per_query',
+        area: 'limits', title: 'a result set beyond the published 100000-row cap is refused (errno 1153)',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async () => {
+            // §9 ROUND ONE, FINDING 1: this used to assert the constant and then read back 40 rows —
+            // delete every `rowLimitExceeded` throw and it stayed green. It now builds a 100_001-row
+            // image and asserts the refusal for SELECT, UPDATE and DELETE, plus that 100_000 is ACCEPTED
+            // (an off-by-one cap would refuse a legal query). Measured at ~6 ms; the seeding is done at
+            // the ENGINE level because seeding 100k rows through HTTP is not affordable in a verify.
+            if (PLANETSCALE_LIMITS.maxRowsPerQuery !== 100_000)
+                return false; // the LITERAL published figure
+            const image = emptyDatabase('twin');
+            applyWritesToImage(image, runSql(image, 'CREATE TABLE Big (id INT NOT NULL PRIMARY KEY, n INT NULL)').writes);
+            const rows = [];
+            for (let i = 1; i <= 100_001; i++)
+                rows.push({ rowid: i, cells: { id: String(i), n: null } });
+            image.rows.set('big', rows);
+            const refusal = (sql) => {
+                try {
+                    runSql(image, sql);
+                    return null;
+                }
+                catch (e) {
+                    return e instanceof SqlError ? e : null;
+                }
+            };
+            const read = refusal('SELECT id FROM Big');
+            const updated = refusal('UPDATE Big SET n = 1');
+            const deleted = refusal('DELETE FROM Big');
+            // Exactly at the cap: allowed. One over: refused. That is what makes this a CAP, not a mood.
+            const atCap = runSql(image, 'SELECT id FROM Big LIMIT 100000');
+            return read !== null && read.errno === 1153 && read.code === 'RESOURCE_EXHAUSTED'
+                && read.message.includes('got 100001')
+                && updated !== null && updated.errno === 1153
+                && deleted !== null && deleted.errno === 1153
+                && atCap.rows.length === 100_000;
+        }),
+    },
+    todo('planetscale.limits.result_set_bytes', 'limits', 'the published 64 MiB per-query result-set size limit', 'niche'),
+    todo('planetscale.limits.query_timeout', 'limits', 'the published 900s autocommit / 20s transaction timeouts', 'niche'),
+    // ── insert ──────────────────────────────────────────────────────────────────────────────────
+    {
+        id: 'planetscale.insert.single_and_multi_row',
+        area: 'insert', title: 'INSERT writes one or many rows and reports rowsAffected + insertId',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            const one = await q("INSERT INTO Link (`key`, url) VALUES ('a', 'https://a.test')");
+            const many = await q("INSERT INTO Link (`key`, url) VALUES ('b', 'https://b.test'), ('c', 'https://c.test')");
+            const read = await q('SELECT id, `key` FROM Link ORDER BY id');
+            // insertId is the FIRST id of the batch, exactly as MySQL reports it.
+            return one.rowsAffected === 1 && one.insertId === '1'
+                && many.rowsAffected === 2 && many.insertId === '2'
+                && read.rows.map((r) => r.join(':')).join(',') === '1:a,2:b,3:c';
+        }),
+    },
+    {
+        id: 'planetscale.insert.defaults_and_omitted_columns',
+        area: 'insert', title: 'an omitted column takes its DEFAULT, or NULL, or raises errno 1364',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url) VALUES ('a', 'https://a.test')");
+            const read = await q("SELECT clicks, archived FROM Link WHERE `key` = 'a'");
+            const noDefault = await q("INSERT INTO Link (`key`) VALUES ('b')"); // url is NOT NULL, no default
+            const explicitNull = await q("INSERT INTO Link (`key`, url) VALUES ('c', NULL)");
+            return read.rows[0][0] === '0' && read.rows[0][1] === null
+                && failed(noDefault, 'INVALID_ARGUMENT', "Field 'url' doesn't have a default value")
+                && noDefault.error.message.includes('(errno 1364)')
+                && failed(explicitNull, 'INVALID_ARGUMENT', "Column 'url' cannot be null")
+                && explicitNull.error.message.includes('(errno 1048) (sqlstate 23000)');
+        }),
+    },
+    {
+        id: 'planetscale.insert.auto_increment',
+        area: 'insert', title: 'AUTO_INCREMENT mints the next id and an EXPLICIT id pushes the watermark past it',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url) VALUES ('a', 'https://a.test')");
+            // An explicit id ABOVE the watermark — the shape a connector-pulled row has. The next minted
+            // id must jump past it; a naive counter would mint 2 and clobber this row.
+            await q("INSERT INTO Link (id, `key`, url) VALUES (500, 'b', 'https://b.test')");
+            const next = await q("INSERT INTO Link (`key`, url) VALUES ('c', 'https://c.test')");
+            const read = await q('SELECT id, `key` FROM Link ORDER BY id');
+            return next.insertId === '501'
+                && read.rows.map((r) => r.join(':')).join(',') === '1:a,500:b,501:c';
+        }),
+    },
+    {
+        id: 'planetscale.insert.auto_increment_survives_delete',
+        area: 'insert', title: 'a deleted id is NEVER reissued — the watermark survives DELETE (dirty state)',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url) VALUES ('a', 'https://a.test'), ('b', 'https://b.test'), ('c', 'https://c.test')");
+            await q("DELETE FROM Link WHERE `key` IN ('b', 'c')");
+            const next = await q("INSERT INTO Link (`key`, url) VALUES ('d', 'https://d.test')");
+            const again = await q("INSERT INTO Link (`key`, url) VALUES ('e', 'https://e.test')");
+            const read = await q('SELECT id, `key` FROM Link ORDER BY id');
+            // 4 and 5, NOT 2 and 3: a watermark derived from the surviving row COUNT (or from MAX(id) of
+            // what is left) would reissue the retired ids, silently rebinding old references to new rows.
+            return next.insertId === '4' && again.insertId === '5'
+                && read.rows.map((r) => r.join(':')).join(',') === '1:a,4:d,5:e';
+        }),
+    },
+    {
+        id: 'planetscale.insert.duplicate_key',
+        area: 'insert', title: 'a PRIMARY/UNIQUE collision raises errno 1062 and writes NOTHING',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url) VALUES ('a', 'https://a.test')");
+            const dupUnique = await q("INSERT INTO Link (`key`, url) VALUES ('a', 'https://other.test')");
+            const dupPk = await q("INSERT INTO Link (id, `key`, url) VALUES (1, 'z', 'https://z.test')");
+            const read = await q('SELECT `key`, url FROM Link');
+            return failed(dupUnique, 'ALREADY_EXISTS', "Duplicate entry 'a' for key 'Link.key_unique'")
+                && dupUnique.error.message.includes('(errno 1062) (sqlstate 23000)')
+                && failed(dupPk, 'ALREADY_EXISTS', "Duplicate entry '1' for key 'Link.PRIMARY'")
+                && read.rows.length === 1 && read.rows[0][1] === 'https://a.test';
+        }),
+    },
+    {
+        id: 'planetscale.insert.ignore',
+        area: 'insert', title: 'INSERT IGNORE skips the colliding row and still writes the others',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url) VALUES ('a', 'https://a.test')");
+            const res = await q("INSERT IGNORE INTO Link (`key`, url) VALUES ('a', 'https://dup.test'), ('b', 'https://b.test')");
+            const read = await q('SELECT `key`, url FROM Link ORDER BY id');
+            return ok(res) && res.rowsAffected === 1
+                && read.rows.map((r) => r.join('=')).join(',') === 'a=https://a.test,b=https://b.test';
+        }),
+    },
+    {
+        id: 'planetscale.insert.on_duplicate_key_update',
+        area: 'insert', title: 'ON DUPLICATE KEY UPDATE updates in place with MySQL\'s 1/2/0 rowsAffected',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            const inserted = await q("INSERT INTO Link (`key`, url) VALUES ('a', 'https://a.test') ON DUPLICATE KEY UPDATE clicks = clicks + 1");
+            const bumped = await q("INSERT INTO Link (`key`, url) VALUES ('a', 'https://a.test') ON DUPLICATE KEY UPDATE clicks = clicks + 1");
+            const bumpedAgain = await q("INSERT INTO Link (`key`, url) VALUES ('a', 'https://a.test') ON DUPLICATE KEY UPDATE clicks = clicks + 1");
+            const noop = await q("INSERT INTO Link (`key`, url) VALUES ('a', 'https://a.test') ON DUPLICATE KEY UPDATE clicks = clicks");
+            const read = await q('SELECT clicks FROM Link');
+            const count = await q('SELECT COUNT(*) FROM Link');
+            // 1 for the insert, 2 for a real update, 0 for an update that changed nothing — MySQL's own
+            // documented counting, and the reason `clicks` is 2 rather than 3 rows existing.
+            return inserted.rowsAffected === 1 && bumped.rowsAffected === 2 && bumpedAgain.rowsAffected === 2
+                && noop.rowsAffected === 0 && read.rows[0][0] === '2' && count.rows[0][0] === '1';
+        }),
+    },
+    {
+        id: 'planetscale.insert.shape_errors',
+        area: 'insert', title: 'a column-count mismatch and an unknown column are refused (errno 1136 / 1054)',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            const mismatch = await q("INSERT INTO Link (`key`, url) VALUES ('a')");
+            const secondRow = await q("INSERT INTO Link (`key`, url) VALUES ('a', 'https://a.test'), ('b')");
+            const unknown = await q("INSERT INTO Link (`key`, nope) VALUES ('a', 'x')");
+            const count = await q('SELECT COUNT(*) FROM Link');
+            // The batch is refused WHOLE — the good first row of `secondRow` must not have landed.
+            return failed(mismatch, 'INVALID_ARGUMENT', "Column count doesn't match value count at row 1")
+                && failed(secondRow, 'INVALID_ARGUMENT', "Column count doesn't match value count at row 2")
+                && failed(unknown, 'INVALID_ARGUMENT', "Unknown column 'nope' in 'field list'")
+                && count.rows[0][0] === '0';
+        }),
+    },
+    todo('planetscale.insert.select', 'insert', 'INSERT … SELECT', 'common'),
+    todo('planetscale.insert.replace_into', 'insert', 'REPLACE INTO (delete-then-insert semantics)', 'niche'),
+    todo('planetscale.insert.set_syntax', 'insert', 'INSERT … SET col = value (MySQL\'s alternative form)', 'niche'),
+    {
+        id: 'planetscale.insert.values_function',
+        area: 'insert', title: 'ON DUPLICATE KEY UPDATE reads the proposed row through VALUES(col) and the 8.0.19 row alias (`AS new`, `AS new (m, n)`)',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q('CREATE TABLE Counter (name VARCHAR(20) PRIMARY KEY, hits INT NOT NULL, seen INT NOT NULL DEFAULT 0)');
+            await q("INSERT INTO Counter (name, hits) VALUES ('x', 1)");
+            const viaValues = await q("INSERT INTO Counter (name, hits) VALUES ('x', 5) ON DUPLICATE KEY UPDATE hits = hits + VALUES(hits)");
+            const viaAlias = await q("INSERT INTO Counter (name, hits) VALUES ('x', 10) AS new ON DUPLICATE KEY UPDATE hits = new.hits, seen = seen + 1");
+            const viaColumns = await q("INSERT INTO Counter (name, hits) VALUES ('x', 3) AS n (a, b) ON DUPLICATE KEY UPDATE hits = hits * b");
+            const row = await q("SELECT hits, seen FROM Counter WHERE name = 'x'");
+            return viaValues.rowsAffected === 2 && viaAlias.rowsAffected === 2 && ok(viaColumns)
+                && JSON.stringify(row.rows) === JSON.stringify([['30', '1']]);
+        }),
+    },
+    // ── select ──────────────────────────────────────────────────────────────────────────────────
+    {
+        id: 'planetscale.select.star_and_projection',
+        area: 'select', title: 'SELECT * expands the schema; a projection returns exactly its columns, aliased',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url) VALUES ('a', 'https://a.test')");
+            const star = await q('SELECT * FROM Link');
+            const qualified = await q('SELECT Link.* FROM Link');
+            const projected = await q('SELECT `key` AS slug, clicks FROM Link');
+            // a string-quoted alias, as the manual's `SELECT 1 AS `one`, 2 AS 'two'` (11.2 Schema Object Names)
+            const stringAliased = await q(`SELECT \`key\` AS "click", clicks AS 'two' FROM Link`);
+            const unknown = await q('SELECT nope FROM Link');
+            return star.fields.map((f) => f.name).join(',') === 'id,key,url,clicks,archived'
+                && qualified.fields.length === 5
+                && projected.fields.map((f) => f.name).join(',') === 'slug,clicks'
+                && projected.fields[0].orgName === 'key'
+                && projected.rows[0].join(':') === 'a:0'
+                && stringAliased.fields.map((f) => f.name).join(',') === 'click,two' && stringAliased.rows[0].join(':') === 'a:0'
+                && failed(unknown, 'INVALID_ARGUMENT', "Unknown column 'nope' in 'field list'");
+        }),
+    },
+    {
+        id: 'planetscale.select.where_operators',
+        area: 'select', title: 'WHERE handles =, !=, <, <=, >, >=, AND, OR and parentheses',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url, clicks) VALUES ('a', 'https://a.test', 1), ('b', 'https://b.test', 5), ('c', 'https://c.test', 9)");
+            const keys = async (where) => (await q(`SELECT \`key\` FROM Link WHERE ${where} ORDER BY \`key\``)).rows.map((r) => r[0]).join('');
+            // Numeric columns compare NUMERICALLY, not lexically: '9' < '10' as strings.
+            await q("INSERT INTO Link (`key`, url, clicks) VALUES ('d', 'https://d.test', 10)");
+            return await keys("`key` = 'b'") === 'b'
+                && await keys("`key` != 'b'") === 'acd'
+                && await keys('clicks > 5') === 'cd'
+                && await keys('clicks >= 5') === 'bcd'
+                && await keys('clicks < 5') === 'a'
+                && await keys('clicks <= 5') === 'ab'
+                && await keys("clicks > 4 AND `key` != 'c'") === 'bd'
+                && await keys("`key` = 'a' OR clicks = 9") === 'ac'
+                && await keys("(`key` = 'a' OR clicks = 9) AND clicks < 5") === 'a';
+        }),
+    },
+    // ── COLLATION (MySQL 8 manual ch. 10) — src/planetscale-collation.ts ──────────────────────
+    {
+        id: 'planetscale.collation.connection_literals',
+        area: 'collation', title: 'string literals compare under the connection collation utf8mb4_0900_ai_ci: case- and accent-insensitive, NO PAD, LIKE per character',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            const r = await q("SELECT 'A' = 'a', 'é' = 'e', 'ß' = 'ss', 'a ' = 'a', 'abc' LIKE 'ABC', 'é' LIKE 'e', 'ß' LIKE 'ss' FROM dual");
+            return ok(r) && r.rows[0].join(',') === '1,1,1,0,1,1,0';
+        }),
+    },
+    {
+        id: 'planetscale.collation.column_resolution',
+        area: 'collation', title: "a column compares under its resolved collation (its COLLATE, else the table's, else utf8mb4_0900_ai_ci), which INFORMATION_SCHEMA reports",
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q('CREATE TABLE p (id INT PRIMARY KEY, s VARCHAR(20) COLLATE utf8mb4_bin, t VARCHAR(20)) DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci');
+            await q("INSERT INTO p VALUES (1, 'Bob', 'alice'), (2, 'bob', 'Bob')");
+            const bin = await q("SELECT id FROM p WHERE s = 'bob'");
+            const ci = await q("SELECT id FROM p WHERE t = 'BOB'");
+            const info = await q("SELECT COLUMN_NAME, COLLATION_NAME FROM information_schema.COLUMNS WHERE TABLE_NAME = 'p' ORDER BY ORDINAL_POSITION");
+            const table = await q("SELECT TABLE_COLLATION FROM information_schema.TABLES WHERE TABLE_NAME = 'p'");
+            return bin.rows.map((x) => x[0]).join() === '2' && ci.rows.map((x) => x[0]).join() === '2'
+                && JSON.stringify(info.rows) === JSON.stringify([['id', null], ['s', 'utf8mb4_bin'], ['t', 'utf8mb4_unicode_ci']])
+                && table.rows[0][0] === 'utf8mb4_unicode_ci';
+        }),
+    },
+    {
+        id: 'planetscale.collation.unique_keys',
+        area: 'collation', title: 'PRIMARY/UNIQUE keys collide under the column collation: a case variant in a _ci column is errno 1062, in a _bin column a distinct key',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q('CREATE TABLE u (id INT PRIMARY KEY, email VARCHAR(191), s VARCHAR(20) COLLATE utf8mb4_bin, UNIQUE KEY u_email (email), UNIQUE KEY u_s (s)) COLLATE utf8mb4_unicode_ci');
+            await q("INSERT INTO u VALUES (1, 'abcxyz12@x.test', 'bob')");
+            const variant = await q("INSERT INTO u VALUES (2, 'aBcXyZ12@x.test', 'other')");
+            const binVariant = await q("INSERT INTO u VALUES (3, 'z@x.test', 'BOB')");
+            const binSame = await q("INSERT INTO u VALUES (4, 'y@x.test', 'bob')");
+            const lookup = await q("SELECT id FROM u WHERE email = 'ABCXYZ12@X.TEST'");
+            return failed(variant, 'ALREADY_EXISTS', "Duplicate entry 'aBcXyZ12@x.test' for key 'u.u_email'")
+                && ok(binVariant) && failed(binSame, 'ALREADY_EXISTS', "for key 'u.u_s'")
+                && lookup.rows.map((x) => x[0]).join() === '1';
+        }),
+    },
+    {
+        id: 'planetscale.collation.order_group_distinct',
+        area: 'collation', title: 'ORDER BY, GROUP BY, DISTINCT, COUNT(DISTINCT) and MAX order and fold strings under their collation',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q('CREATE TABLE g (id INT PRIMARY KEY, s VARCHAR(20) COLLATE utf8mb4_bin, t VARCHAR(20)) COLLATE utf8mb4_unicode_ci');
+            await q("INSERT INTO g VALUES (1, 'Bob', 'alice'), (2, 'bob', 'Bob'), (3, 'carol', 'carol'), (4, 'Dup', 'dup'), (5, 'dup2', 'DUP')");
+            const col = async (sql) => (await q(sql)).rows.map((x) => x.join('|')).join(',');
+            return await col('SELECT t FROM g ORDER BY t, id') === 'alice,Bob,carol,dup,DUP'
+                && await col('SELECT s FROM g ORDER BY s') === 'Bob,Dup,bob,carol,dup2'
+                && await col('SELECT MIN(t), COUNT(*) FROM g GROUP BY t ORDER BY MIN(t)') === 'alice|1,Bob|1,carol|1,dup|2'
+                && await col('SELECT DISTINCT t FROM g ORDER BY t') === 'alice,Bob,carol,dup'
+                && await col('SELECT COUNT(DISTINCT t), COUNT(DISTINCT s), MAX(t) FROM g') === '4|5|dup';
+        }),
+    },
+    {
+        id: 'planetscale.collation.predicates',
+        area: 'collation', title: 'IN, BETWEEN, row constructors, simple CASE, NULLIF and join conditions compare under the operands\' collation',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q('CREATE TABLE a (id INT PRIMARY KEY, t VARCHAR(20)) COLLATE utf8mb4_unicode_ci');
+            await q("INSERT INTO a VALUES (1, 'alice'), (2, 'Bob'), (3, 'carol')");
+            await q('CREATE TABLE b (k VARCHAR(20) PRIMARY KEY, n INT) COLLATE utf8mb4_0900_as_cs');
+            await q("INSERT INTO b VALUES ('ALICE', 1), ('carol', 2)");
+            const col = async (sql) => (await q(sql)).rows.map((x) => x.join('|')).join(',');
+            return await col("SELECT id FROM a WHERE t IN ('ALICE', 'CAROL') ORDER BY id") === '1,3'
+                && await col("SELECT id FROM a WHERE t BETWEEN 'B' AND 'CAROL' ORDER BY id") === '2,3'
+                && await col("SELECT id FROM a WHERE (t, id) IN (('BOB', 2), ('Alice', 9))") === '2'
+                && await col("SELECT CASE t WHEN 'ALICE' THEN 'hit' ELSE 'miss' END, NULLIF(t, 'ALICE') IS NULL FROM a WHERE id = 1") === 'hit|1'
+                && await col('SELECT a.id, b.n FROM a JOIN b ON a.t = b.k COLLATE utf8mb4_unicode_ci ORDER BY a.id') === '1|1,3|2'
+                && await col("SELECT k FROM b WHERE k = 'alice'") === '';
+        }),
+    },
+    {
+        id: 'planetscale.collation.coercibility',
+        area: 'collation', title: "COLLATE, BINARY and introducers choose the comparison by MySQL's coercibility rules; an illegal mix is errno 1267, an unknown collation 1273",
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q('CREATE TABLE a (t VARCHAR(20)) COLLATE utf8mb4_unicode_ci');
+            await q('CREATE TABLE b (k VARCHAR(20)) COLLATE utf8mb4_0900_as_cs');
+            await q("INSERT INTO a VALUES ('x')");
+            await q("INSERT INTO b VALUES ('x')");
+            const r = await q("SELECT BINARY 'A' = 'a', 'A' = 'a' COLLATE utf8mb4_bin, 'é' = 'e' COLLATE utf8mb4_0900_as_ci, 'a ' = 'a' COLLATE utf8mb4_bin, _utf8mb4'A' = 'a', _binary'A' = 'a' FROM dual");
+            const mix = await q('SELECT a.t FROM a JOIN b ON a.t = b.k');
+            const unknown = await q("SELECT 'a' COLLATE no_such_collation FROM dual");
+            return ok(r) && r.rows[0].join(',') === '0,0,0,1,1,0'
+                && failed(mix, 'INVALID_ARGUMENT', "Illegal mix of collations (utf8mb4_unicode_ci,IMPLICIT) and (utf8mb4_0900_as_cs,IMPLICIT) for operation '='")
+                && failed(unknown, 'INVALID_ARGUMENT', "Unknown collation: 'no_such_collation'");
+        }),
+    },
+    {
+        id: 'planetscale.collation.named_collations',
+        area: 'collation', title: 'utf8mb4_0900_ai_ci/_as_ci/_as_cs/_bin, utf8mb4_unicode_ci (UCA 4.0.0), utf8mb4_general_ci and utf8mb4_bin weigh characters by their own tables',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            const r = await q("SELECT 'ß' = 's' COLLATE utf8mb4_general_ci, 'ß' = 'ss' COLLATE utf8mb4_unicode_ci, 'Ø' = 'O' COLLATE utf8mb4_unicode_ci, 'Ø' = 'O', 'a' = 'A' COLLATE utf8mb4_0900_as_cs FROM dual");
+            return ok(r) && r.rows[0].join(',') === '1,1,0,1,0';
+        }),
+    },
+    todo('planetscale.collation.uca_full_weight_table', 'collation', 'the DUCET weights outside U+0000..U+052F, U+1E00..U+206F, U+20A0..U+20CF, U+2100..U+218F, U+FB00..U+FB06 and U+FF01..U+FF5E (Armenian, Hebrew, Arabic, Indic, kana, Hangul, CJK order, emoji, …): those characters take the UCA implicit weight, so they equal only themselves and sort after the modelled ranges', 'niche'),
+    todo('planetscale.collation.other_collations', 'collation', 'character sets and collations beyond utf8mb4/utf8mb3/binary and the eleven modelled collations (latin1, ascii, utf16, the language-tailored utf8mb4_*_0900_* and utf8mb4_unicode_520_ci families, …): refused as unsupported', 'niche'),
+    todo('planetscale.connector.column_collations', 'connector', "a pulled table's column collations: refresh reads DESCRIBE, which carries none, so pulled character columns compare under utf8mb4_0900_ai_ci whatever the upstream column declares", 'niche'),
+    {
+        id: 'planetscale.select.where_in_like_between',
+        area: 'select', title: 'IN, NOT IN, LIKE, NOT LIKE and BETWEEN all filter correctly',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url, clicks) VALUES ('alpha', 'https://a.test', 1), ('beta', 'https://b.test', 5), ('gamma', 'https://c.test', 9)");
+            const keys = async (where) => (await q(`SELECT \`key\` FROM Link WHERE ${where} ORDER BY \`key\``)).rows.map((r) => r[0]).join(',');
+            return await keys("`key` IN ('alpha', 'gamma')") === 'alpha,gamma'
+                && await keys("`key` NOT IN ('alpha', 'gamma')") === 'beta'
+                && await keys("`key` LIKE 'a%'") === 'alpha'
+                && await keys("`key` LIKE '%m%'") === 'gamma'
+                && await keys("`key` LIKE 'bet_'") === 'beta'
+                && await keys("`key` NOT LIKE 'a%'") === 'beta,gamma'
+                && await keys('clicks BETWEEN 2 AND 9') === 'beta,gamma'
+                && await keys('clicks NOT BETWEEN 2 AND 9') === 'alpha';
+        }),
+    },
+    {
+        id: 'planetscale.select.null_three_valued_logic',
+        area: 'select', title: 'NULL comparisons are UNKNOWN — IS NULL / IS NOT NULL / <=> behave like MySQL',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url, archived) VALUES ('a', 'https://a.test', 1), ('b', 'https://b.test', NULL)");
+            const keys = async (where) => (await q(`SELECT \`key\` FROM Link WHERE ${where} ORDER BY \`key\``)).rows.map((r) => r[0]).join(',');
+            // The bug this pins: `archived != 1` must NOT return the NULL row. A twin comparing `null !=
+            // '1'` in JavaScript returns true and silently leaks it into every "not archived" query.
+            return await keys('archived IS NULL') === 'b'
+                && await keys('archived IS NOT NULL') === 'a'
+                && await keys('archived != 1') === ''
+                && await keys('archived = 1') === 'a'
+                && await keys('archived <=> NULL') === 'b'
+                && await keys('NOT (archived = 1)') === ''
+                && await keys("archived IN (1, NULL)") === 'a';
+        }),
+    },
+    {
+        id: 'planetscale.select.order_by',
+        area: 'select', title: 'ORDER BY sorts ASC/DESC, numerically for numeric columns, NULLs first ascending',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url, clicks, archived) VALUES ('a', 'https://a.test', 9, NULL), "
+                + "('b', 'https://b.test', 10, 1), ('c', 'https://c.test', 2, 0)");
+            const order = async (by) => (await q(`SELECT \`key\` FROM Link ORDER BY ${by}`)).rows.map((r) => r[0]).join(',');
+            return await order('clicks') === 'c,a,b' // numeric: 2 < 9 < 10 (lexically '10' < '2')
+                && await order('clicks DESC') === 'b,a,c'
+                && await order('`key` DESC') === 'c,b,a'
+                && await order('archived') === 'a,c,b' // MySQL sorts NULL first ascending
+                && await order('archived DESC') === 'b,c,a' // …and last descending
+                && await order('archived, `key`') === 'a,c,b';
+        }),
+    },
+    {
+        id: 'planetscale.select.limit_offset',
+        area: 'select', title: 'LIMIT n, LIMIT n OFFSET m and MySQL\'s LIMIT m, n all page correctly',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            const values = Array.from({ length: 6 }, (_, i) => `('k${i}', 'https://x${i}.test')`).join(', ');
+            await q(`INSERT INTO Link (\`key\`, url) VALUES ${values}`);
+            const page = async (clause) => (await q(`SELECT \`key\` FROM Link ORDER BY id ${clause}`)).rows.map((r) => r[0]).join(',');
+            return await page('LIMIT 2') === 'k0,k1'
+                && await page('LIMIT 2 OFFSET 2') === 'k2,k3'
+                && await page('LIMIT 2, 3') === 'k2,k3,k4' // MySQL's offset-first two-argument form
+                && await page('LIMIT 0') === ''
+                && await page('LIMIT 100') === 'k0,k1,k2,k3,k4,k5';
+        }),
+    },
+    {
+        id: 'planetscale.select.count_star',
+        area: 'select', title: 'COUNT(*) and COUNT(col) honour WHERE and NULLs, typed INT64',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url, archived) VALUES ('a', 'https://a.test', 1), ('b', 'https://b.test', NULL), ('c', 'https://c.test', 0)");
+            const all = await q('SELECT COUNT(*) AS total FROM Link');
+            const filtered = await q("SELECT COUNT(*) FROM Link WHERE `key` != 'a'");
+            const nonNull = await q('SELECT COUNT(archived) AS n FROM Link');
+            const none = await q("SELECT COUNT(*) FROM Link WHERE `key` = 'zzz'");
+            return all.rows[0][0] === '3' && all.fields[0].type === 'INT64' && all.fields[0].name === 'total'
+                && filtered.rows[0][0] === '2'
+                && nonNull.rows[0][0] === '2' // COUNT(col) skips NULL
+                && none.rows[0][0] === '0' && none.rows.length === 1; // …and still returns ONE row
+        }),
+    },
+    {
+        id: 'planetscale.select.constant_and_dual',
+        area: 'select', title: 'SELECT <expr> with no FROM (or FROM dual) returns one constant row',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            const bare = await q('SELECT 1');
+            const dual = await q("SELECT 1 AS one, 'x' AS letter, NULL AS nothing FROM dual");
+            const filteredOut = await q('SELECT 1 FROM dual WHERE 1 = 2');
+            const star = await q('SELECT * FROM dual');
+            return bare.rows[0][0] === '1' && bare.fields[0].name === '1'
+                && dual.rows[0][0] === '1' && dual.rows[0][1] === 'x' && dual.rows[0][2] === null
+                && dual.fields.map((f) => f.name).join(',') === 'one,letter,nothing'
+                && filteredOut.rows.length === 0
+                && failed(star, 'INVALID_ARGUMENT', 'No tables used');
+        }),
+    },
+    {
+        id: 'planetscale.select.no_such_table',
+        area: 'select', title: 'SELECT from a missing table raises errno 1146 with the database-qualified name',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            const missing = await q('SELECT * FROM Nope');
+            // The DATABASE NAME in the message is the server's, not a constant: a different schema name
+            // must appear in the error.
+            const other = await q.raw({ body: JSON.stringify({ query: 'SELECT * FROM Nope' }), database: 'shop' });
+            const otherQ = decode(other);
+            return failed(missing, 'NOT_FOUND', "Table 'twin.Nope' doesn't exist")
+                && missing.error.message.includes('(errno 1146) (sqlstate 42S02)')
+                && failed(otherQ, 'NOT_FOUND', "Table 'shop.Nope' doesn't exist");
+        }),
+    },
+    {
+        id: 'planetscale.select.unmodeled_clauses_refused',
+        area: 'select', title: 'UNION, RIGHT/NATURAL joins, JOIN … USING, window functions and WITH ROLLUP fail like Vitess, never as empty results',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url) VALUES ('a', 'https://a.test')");
+            const cases = [
+                ['SELECT id FROM Link UNION SELECT id FROM Link', 'UNION'],
+                ['SELECT * FROM Link RIGHT JOIN Link l2 ON Link.id = l2.id', 'RIGHT JOIN'],
+                ['SELECT * FROM Link NATURAL JOIN Link l2', 'NATURAL JOIN'],
+                ['SELECT * FROM Link JOIN Link l2 USING (id)', 'USING'],
+                ['SELECT ROW_NUMBER() OVER (ORDER BY id) FROM Link', 'window functions'],
+                ['SELECT clicks, COUNT(*) FROM Link GROUP BY clicks WITH ROLLUP', 'WITH ROLLUP'],
+            ];
+            for (const [sql, fragment] of cases) {
+                const res = await q(sql);
+                // An empty result set here would read to the caller as "ran fine, matched nothing" — the
+                // fake success the bar forbids. It must be UNIMPLEMENTED with Vitess's own `unsupported:`.
+                if (!failed(res, 'UNIMPLEMENTED', 'unsupported:'))
+                    return false;
+                if (!res.error.message.includes(fragment))
+                    return false;
+                if (res.rows.length !== 0 || res.status !== 200)
+                    return false;
+            }
+            return true;
+        }),
+    },
+    {
+        id: 'planetscale.select.derived_tables',
+        area: 'select', title: 'A derived table in FROM is read as a table, and one without an alias is errno 1248',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url, archived) VALUES ('a', 'https://a.test', 1), ('b', 'https://b.test', NULL), ('c', 'https://c.test', 0)");
+            // Prisma's count over a filtered set, verbatim in shape.
+            const counted = await q("SELECT COUNT(*) AS `_count$_all` FROM (SELECT Link.id FROM Link WHERE `key` != 'a') AS `sub`");
+            const projected = await q("SELECT sub.url FROM (SELECT url, archived FROM Link) AS sub WHERE sub.archived IS NULL");
+            const unaliased = await q('SELECT COUNT(*) FROM (SELECT id FROM Link)');
+            return counted.rows[0][0] === '2' && counted.fields[0].name === '_count$_all' && counted.fields[0].type === 'INT64'
+                && projected.rows.length === 1 && projected.rows[0][0] === 'https://b.test' && projected.fields[0].table === 'sub'
+                && failed(unaliased, 'INVALID_ARGUMENT', 'Every derived table must have its own alias') && unaliased.error.message.includes('1248');
+        }),
+    },
+    {
+        id: 'planetscale.select.information_schema_prisma_describer',
+        area: 'select', title: "INFORMATION_SCHEMA TABLES / COLUMNS / STATISTICS / VIEWS / ROUTINES / KEY_COLUMN_USAGE ⋈ REFERENTIAL_CONSTRAINTS answer Prisma's MySQL describer, derived from the live catalog",
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            // Prisma's own DDL shape and its describer's own queries (sql-schema-describer/src/mysql.rs), verbatim.
+            await q('CREATE TABLE `Link` ( `id` VARCHAR(191) NOT NULL, `projectId` VARCHAR(191) NULL, `url` LONGTEXT NOT NULL, '
+                + '`archived` BOOLEAN NOT NULL DEFAULT false, `clicks` INTEGER NOT NULL DEFAULT 0, `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), '
+                + "`kind` ENUM('short', 'long') NOT NULL DEFAULT 'short', `fee` DECIMAL(5, 2) NULL, "
+                + 'INDEX `Link_projectId_url_idx`(`projectId`, `url`(500)), INDEX `Link_createdAt_idx`(`createdAt` DESC), UNIQUE INDEX `Link_url_key`(`url`(191)), '
+                + 'FULLTEXT INDEX `Link_url_idx`(`url`), PRIMARY KEY (`id`) ) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci');
+            const tables = await q("SELECT DISTINCT BINARY table_info.table_name AS table_name, table_info.create_options AS create_options, table_info.table_comment AS table_comment "
+                + 'FROM information_schema.tables AS table_info JOIN information_schema.columns AS column_info ON BINARY column_info.table_name = BINARY table_info.table_name '
+                + "WHERE table_info.table_schema = 'twin' AND column_info.table_schema = 'twin' -- Exclude views.\n AND table_info.table_type = 'BASE TABLE' ORDER BY BINARY table_info.table_name");
+            const columns = await q("SELECT column_name column_name, data_type data_type, column_type full_data_type, character_maximum_length character_maximum_length, "
+                + 'numeric_precision numeric_precision, numeric_scale numeric_scale, datetime_precision datetime_precision, column_default column_default, '
+                + "is_nullable is_nullable, extra extra, table_name table_name, IF(column_comment = '', NULL, column_comment) AS column_comment "
+                + "FROM information_schema.columns WHERE table_schema = 'twin' ORDER BY ordinal_position");
+            const indexes = await q('SELECT table_name AS table_name, index_name AS index_name, column_name AS column_name, sub_part AS partial, seq_in_index AS seq_in_index, '
+                + "collation AS column_order, non_unique AS non_unique, index_type AS index_type FROM information_schema.statistics WHERE table_schema = 'twin' "
+                + 'ORDER BY BINARY table_name, BINARY index_name, seq_in_index');
+            const fks = await q('SELECT kcu.constraint_name constraint_name, kcu.column_name column_name, rc.delete_rule delete_rule FROM information_schema.key_column_usage AS kcu '
+                + "INNER JOIN information_schema.referential_constraints AS rc ON BINARY kcu.constraint_name = BINARY rc.constraint_name WHERE BINARY kcu.table_schema = 'twin' "
+                + "AND BINARY rc.constraint_schema = 'twin' AND kcu.referenced_column_name IS NOT NULL");
+            const views = await q("SELECT TABLE_NAME AS view_name, VIEW_DEFINITION AS view_sql FROM INFORMATION_SCHEMA.VIEWS WHERE TABLE_SCHEMA = 'twin';");
+            const routines = await q("SELECT routine_name AS name, routine_definition AS definition FROM information_schema.routines WHERE ROUTINE_SCHEMA = 'twin' AND ROUTINE_TYPE = 'PROCEDURE'");
+            const unknown = await q('SELECT * FROM information_schema.NOPE');
+            const col = (name) => columns.rows.find((r) => r[0] === name).slice(0, 11).join('|');
+            const index = indexes.rows.map((r) => r.slice(1).join('|')).join(';');
+            return tables.rows.length === 1 && tables.rows[0][0] === 'Link' && tables.fields[0].type === 'VARBINARY'
+                && columns.rows.length === 8 && columns.fields[0].name === 'column_name'
+                && col('id') === 'id|varchar|varchar(191)|191|||||NO||Link'
+                && col('archived') === 'archived|tinyint|tinyint(1)||3|0||0|NO||Link'
+                && col('clicks') === 'clicks|int|int||10|0||0|NO||Link'
+                && col('createdAt') === 'createdAt|datetime|datetime(3)||||3|CURRENT_TIMESTAMP(3)|NO|DEFAULT_GENERATED|Link'
+                && col('kind') === "kind|enum|enum('short','long')|5||||short|NO||Link"
+                && col('fee') === 'fee|decimal|decimal(5,2)||5|2|||YES||Link'
+                && col('url') === 'url|longtext|longtext|4294967295|||||NO||Link'
+                && index === 'Link_createdAt_idx|createdAt||1|D|1|BTREE;Link_projectId_url_idx|projectId||1|A|1|BTREE;Link_projectId_url_idx|url|500|2|A|1|BTREE;'
+                    + 'Link_url_idx|url||1||1|FULLTEXT;Link_url_key|url|191|1|A|0|BTREE;PRIMARY|id||1|A|0|BTREE'
+                && ok(fks) && fks.rows.length === 0 && ok(views) && views.rows.length === 0 && ok(routines) && routines.rows.length === 0
+                && failed(unknown, 'NOT_FOUND', "Unknown table 'NOPE' in information_schema") && unknown.error.message.includes('(errno 1109)');
+        }),
+    },
+    todo('planetscale.select.information_schema_other_views', 'select', "INFORMATION_SCHEMA beyond Prisma's describer reads: TABLE_CONSTRAINTS / CHECK_CONSTRAINTS / TRIGGERS / SCHEMATA are derived but unverified, and PARTITIONS, ENGINES, CHARACTER_SETS, COLLATIONS, PROCESSLIST and the other views are absent", 'niche'),
+    {
+        id: 'planetscale.select.joins',
+        area: 'select', title: '[INNER|CROSS] JOIN, LEFT [OUTER] JOIN … ON and comma joins across stored tables, with aliases, `t.*`, NULL-extended LEFT JOIN rows and errno 1052 for an ambiguous column',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q('CREATE TABLE Tag (id INT NOT NULL, linkId BIGINT NULL, name VARCHAR(20) NOT NULL, PRIMARY KEY (id))');
+            await q("INSERT INTO Link (`key`, url) VALUES ('a', 'https://a.test'), ('b', 'https://b.test')");
+            await q("INSERT INTO Tag (id, linkId, name) VALUES (1, 1, 'x'), (2, 1, 'y'), (3, NULL, 'z')");
+            // The shape of Dub's lib/planetscale/get-link-with-partner.ts: base-table `*` plus aliased LEFT JOINs.
+            const left = await q('SELECT Link.`key`, t.name AS tagName FROM Link LEFT JOIN Tag AS t ON t.linkId = Link.id ORDER BY Link.id, t.name');
+            const inner = await q("SELECT l.`key`, t.* FROM Tag t JOIN Link l ON l.id = t.linkId WHERE t.name <> 'y'");
+            const comma = await q('SELECT COUNT(*) FROM Link, Tag');
+            const ambiguous = await q('SELECT id FROM Link JOIN Tag ON Tag.linkId = Link.id');
+            const leftRows = left.rows.map((r) => r.join(':')).join(',');
+            return leftRows === 'a:x,a:y,b:' && left.rows[2][1] === null && left.fields[1].name === 'tagName'
+                && inner.rows.length === 1 && inner.rows[0].join(':') === 'a:1:1:x' && inner.fields.map((f) => f.name).join(',') === 'key,id,linkId,name'
+                && comma.rows[0][0] === '6'
+                && failed(ambiguous, 'INVALID_ARGUMENT', "Column 'id' in field list is ambiguous") && ambiguous.error.message.includes('1052');
+        }),
+    },
+    {
+        id: 'planetscale.select.group_by',
+        area: 'select', title: 'GROUP BY (columns, select aliases, positions) with HAVING, groups in first-seen order and functionally dependent columns read from the group',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url, clicks) VALUES ('a', 'https://x.test', 1), ('b', 'https://y.test', 5), ('c', 'https://x.test', 2)");
+            const grouped = await q('SELECT url, COUNT(*) AS n, SUM(clicks) AS total FROM Link GROUP BY url ORDER BY url');
+            const having = await q('SELECT url AS u, COUNT(*) FROM Link GROUP BY u HAVING COUNT(*) > 1');
+            const positional = await q('SELECT url, MAX(clicks) FROM Link GROUP BY 1 ORDER BY 2 DESC');
+            const empty = await q("SELECT url, COUNT(*) FROM Link WHERE `key` = 'zzz' GROUP BY url");
+            return grouped.rows.map((r) => r.join(':')).join(',') === 'https://x.test:2:3,https://y.test:1:5'
+                && having.rows.length === 1 && having.rows[0].join(':') === 'https://x.test:2'
+                && positional.rows.map((r) => r.join(':')).join(',') === 'https://y.test:5,https://x.test:2'
+                && ok(empty) && empty.rows.length === 0;
+        }),
+    },
+    {
+        id: 'planetscale.select.aggregates',
+        area: 'select', title: 'COUNT([DISTINCT]) / SUM / AVG / MIN / MAX / JSON_ARRAYAGG with MySQL result types (SUM/AVG of an integer is DECIMAL, AVG adds 4 digits of scale) and NULL over an empty set',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url, clicks, archived) VALUES ('a', 'https://x.test', 1, 1), ('b', 'https://y.test', 2, NULL), ('c', 'https://x.test', 4, 0)");
+            const all = await q('SELECT COUNT(DISTINCT url), SUM(clicks), AVG(clicks), MIN(`key`), MAX(clicks), COUNT(archived) FROM Link');
+            const none = await q("SELECT SUM(clicks), MAX(clicks), COUNT(*), JSON_ARRAYAGG(`key`) FROM Link WHERE `key` = 'zzz'");
+            const agg = await q("SELECT JSON_ARRAYAGG(`key`) FROM Link WHERE url = 'https://x.test'");
+            return all.rows[0].join('|') === '2|7|2.3333|a|4|2'
+                && all.fields[1].type === 'DECIMAL' && all.fields[2].type === 'DECIMAL' && all.fields[4].type === 'INT32' && all.fields[0].type === 'INT64'
+                && none.rows.length === 1 && none.rows[0].join('|') === '||0|' && none.rows[0][0] === null
+                && agg.rows[0][0] === '["a", "c"]' && agg.fields[0].type === 'JSON';
+        }),
+    },
+    {
+        id: 'planetscale.select.subqueries',
+        area: 'select', title: 'scalar, IN, NOT IN and [NOT] EXISTS subqueries, correlated or not (Prisma cursor pagination and relation filters), with errno 1242 for a scalar subquery of several rows',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q('CREATE TABLE LinkTag (linkId BIGINT NOT NULL, tagId VARCHAR(8) NOT NULL, PRIMARY KEY (linkId, tagId))');
+            await q("INSERT INTO Link (`key`, url) VALUES ('a', 'https://a.test'), ('b', 'https://b.test'), ('c', 'https://c.test')");
+            await q("INSERT INTO LinkTag (linkId, tagId) VALUES (1, 't1'), (3, 't1'), (3, 't2')");
+            // Prisma's `startingAfter` cursor and its `tags: { some }` / `{ none }` relation filters, in shape.
+            const cursor = await q("SELECT `twin`.`Link`.`key` FROM `twin`.`Link` WHERE `twin`.`Link`.`id` <= (SELECT `twin`.`Link`.`id` FROM `twin`.`Link` WHERE (`twin`.`Link`.`id`) = (2)) ORDER BY `twin`.`Link`.`id` DESC");
+            const some = await q("SELECT `key` FROM Link WHERE EXISTS(SELECT `t0`.`linkId` FROM LinkTag AS `t0` WHERE (`t0`.`tagId` IN ('t1') AND (Link.id) = (`t0`.`linkId`)))");
+            const none = await q('SELECT `key` FROM Link WHERE NOT EXISTS(SELECT 1 FROM LinkTag t0 WHERE t0.linkId = Link.id)');
+            const inSub = await q("SELECT `key` FROM Link WHERE id IN (SELECT linkId FROM LinkTag WHERE tagId = 't2')");
+            const notIn = await q('SELECT `key` FROM Link WHERE id NOT IN (SELECT linkId FROM LinkTag)');
+            const counted = await q('SELECT `key`, (SELECT COUNT(*) FROM LinkTag WHERE LinkTag.linkId = Link.id) AS tags FROM Link');
+            const tooMany = await q('SELECT (SELECT linkId FROM LinkTag) FROM Link');
+            return cursor.rows.map((r) => r[0]).join(',') === 'b,a'
+                && some.rows.map((r) => r[0]).join(',') === 'a,c'
+                && none.rows.map((r) => r[0]).join(',') === 'b'
+                && inSub.rows.map((r) => r[0]).join(',') === 'c'
+                && notIn.rows.map((r) => r[0]).join(',') === 'b'
+                && counted.rows.map((r) => r.join(':')).join(',') === 'a:1,b:0,c:2'
+                && failed(tooMany, 'INVALID_ARGUMENT', 'Subquery returns more than 1 row');
+        }),
+    },
+    {
+        id: 'planetscale.select.row_constructors',
+        area: 'select', title: 'row constructors: `(a, b) IN ((…), (…))` and `(a, b) = (c, d)` compare element-wise (Prisma composite-key relation loads)',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q('CREATE TABLE Enrollment (programId VARCHAR(8) NOT NULL, partnerId VARCHAR(8) NOT NULL, tenantId VARCHAR(8) NULL, PRIMARY KEY (programId, partnerId))');
+            await q("INSERT INTO Enrollment (programId, partnerId, tenantId) VALUES ('p1', 'a', 't1'), ('p1', 'b', NULL), ('p2', 'a', 't3')");
+            const loaded = await q("SELECT tenantId FROM Enrollment WHERE (Enrollment.programId, Enrollment.partnerId) IN (('p1','a'),('p2','a'),('p9','z'))");
+            const equal = await q("SELECT partnerId FROM Enrollment WHERE (programId, partnerId) = ('p1', 'b')");
+            const nullRow = await q("SELECT (tenantId, partnerId) = (NULL, 'a') FROM Enrollment WHERE programId = 'p2'");
+            const width = await q("SELECT * FROM Enrollment WHERE (programId, partnerId) IN (('p1'))");
+            return loaded.rows.map((r) => r[0]).join(',') === 't1,t3' && equal.rows.length === 1 && equal.rows[0][0] === 'b'
+                && nullRow.rows[0][0] === null && failed(width, 'INVALID_ARGUMENT', 'Operand should contain 2 column(s)');
+        }),
+    },
+    {
+        id: 'planetscale.select.distinct',
+        area: 'select', title: 'SELECT DISTINCT over stored tables and joins, applied before LIMIT',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url, clicks) VALUES ('a', 'https://x.test', 1), ('b', 'https://x.test', 1), ('c', 'https://y.test', 1)");
+            const urls = await q('SELECT DISTINCT url FROM Link ORDER BY url');
+            const limited = await q('SELECT DISTINCT url, clicks FROM Link ORDER BY url LIMIT 1 OFFSET 1');
+            return urls.rows.map((r) => r[0]).join(',') === 'https://x.test,https://y.test' && limited.rows.length === 1 && limited.rows[0][0] === 'https://y.test';
+        }),
+    },
+    {
+        id: 'planetscale.select.clustered_order',
+        area: 'select', title: 'a full scan with no ORDER BY returns rows in PRIMARY KEY order (InnoDB\'s clustered index; MySQL promises no order, and a secondary-index scan there differs)',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q('CREATE TABLE Item (id VARCHAR(16) NOT NULL, n INT NOT NULL, PRIMARY KEY (id))');
+            await q("INSERT INTO Item (id, n) VALUES ('item_3', 3), ('item_1', 1), ('item_2', 2)");
+            await q("UPDATE Item SET n = 10 WHERE id = 'item_1'");
+            const all = await q('SELECT id FROM Item');
+            const listed = await q("SELECT id FROM Item WHERE id IN ('item_3', 'item_2', 'item_1')");
+            const deleted = await q('DELETE FROM Item LIMIT 1');
+            const rest = await q('SELECT id FROM Item');
+            return all.rows.map((r) => r[0]).join(',') === 'item_1,item_2,item_3' && listed.rows.map((r) => r[0]).join(',') === 'item_1,item_2,item_3'
+                && deleted.rowsAffected === 1 && rest.rows.map((r) => r[0]).join(',') === 'item_2,item_3';
+        }),
+    },
+    todo('planetscale.select.union', 'select', 'UNION / UNION ALL', 'common'),
+    {
+        id: 'planetscale.select.for_update',
+        area: 'select', title: 'SELECT … FOR UPDATE / FOR SHARE / LOCK IN SHARE MODE return the current rows and lock them until the transaction ends',
+        dimension: 'api', tier: 'niche', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url) VALUES ('a', 'https://a.test'), ('b', 'https://b.test')");
+            const s1 = (await q('BEGIN', { session: null })).session;
+            const locked = await q("SELECT `key` FROM Link WHERE `key` = 'a' FOR UPDATE", { session: s1 });
+            let done = false;
+            const blocked = q("UPDATE Link SET clicks = 5 WHERE `key` = 'a'", { session: null }).then((r) => { done = true; return r; });
+            const other = await q("UPDATE Link SET clicks = 1 WHERE `key` = 'b'", { session: null });
+            const share = await q("SELECT `key` FROM Link WHERE `key` = 'b' LOCK IN SHARE MODE", { session: null });
+            const waited = !done;
+            await q('COMMIT', { session: s1 });
+            const released = await blocked;
+            const after = await q("SELECT clicks FROM Link WHERE `key` = 'a'", { session: null });
+            return locked.rows.length === 1 && waited && other.rowsAffected === 1 && share.rows.length === 1
+                && released.rowsAffected === 1 && after.rows[0][0] === '5';
+        }),
+    },
+    todo('planetscale.select.window_functions', 'select', 'window functions (ROW_NUMBER, RANK, OVER)', 'niche'),
+    todo('planetscale.select.fulltext', 'select', 'MATCH … AGAINST full-text search', 'niche'),
+    todo('planetscale.select.explain', 'select', 'EXPLAIN <statement> / EXPLAIN ANALYZE and the Vitess query plan they return (refused as unmodeled today — §9 round one found it mis-parsed as DESCRIBE)', 'common'),
+    todo('planetscale.select.index_hints', 'select', 'FORCE/USE/IGNORE INDEX and PARTITION (…) selection — accepted by the vendor, refused as unmodeled here because this engine has exactly one access path (a scan), so honouring a hint would be theatre', 'common'),
+    todo('planetscale.select.vitess_literal_normalization', 'select', "Vitess query normalization — a literal becomes the bind variable `:vtg1` and the column is NAMED `:vtg1` rather than by its literal text", 'niche'),
+    // ── update ──────────────────────────────────────────────────────────────────────────────────
+    {
+        id: 'planetscale.update.set_where_limit',
+        area: 'update', title: 'UPDATE … SET … WHERE … LIMIT writes the matching rows and only those',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url, clicks) VALUES ('a', 'https://a.test', 1), ('b', 'https://b.test', 2), ('c', 'https://c.test', 3)");
+            const one = await q("UPDATE Link SET url = 'https://new.test' WHERE `key` = 'b'");
+            const expr = await q('UPDATE Link SET clicks = clicks * 10 WHERE clicks < 3');
+            const limited = await q('UPDATE Link SET clicks = 99 ORDER BY id LIMIT 1');
+            const read = await q('SELECT `key`, url, clicks FROM Link ORDER BY id');
+            return one.rowsAffected === 1 && expr.rowsAffected === 2 && limited.rowsAffected === 1
+                && read.rows.map((r) => r.join(':')).join(',')
+                    === 'a:https://a.test:99,b:https://new.test:20,c:https://c.test:3';
+        }),
+    },
+    {
+        id: 'planetscale.update.counts_only_changed_rows',
+        area: 'update', title: 'rowsAffected counts rows whose values actually CHANGED, as MySQL does',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url, clicks) VALUES ('a', 'https://a.test', 5), ('b', 'https://b.test', 5)");
+            const changed = await q('UPDATE Link SET clicks = 7');
+            const unchanged = await q('UPDATE Link SET clicks = 7');
+            const partial = await q("UPDATE Link SET clicks = 7 WHERE `key` = 'a'");
+            return changed.rowsAffected === 2 && unchanged.rowsAffected === 0 && partial.rowsAffected === 0;
+        }),
+    },
+    {
+        id: 'planetscale.update.constraint_errors',
+        area: 'update', title: 'an UPDATE into a duplicate key, a NULL in a NOT NULL column, or an unknown column is refused',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url) VALUES ('a', 'https://a.test'), ('b', 'https://b.test')");
+            const dup = await q("UPDATE Link SET `key` = 'a' WHERE `key` = 'b'");
+            const nul = await q("UPDATE Link SET url = NULL WHERE `key` = 'a'");
+            const unknown = await q("UPDATE Link SET nope = 1 WHERE `key` = 'a'");
+            const read = await q('SELECT `key`, url FROM Link ORDER BY id');
+            // A row updating to ITS OWN key must still be allowed — the conflict check must exclude the
+            // row it is rewriting, or every idempotent UPSERT would start failing.
+            const selfSame = await q("UPDATE Link SET `key` = 'a', clicks = 1 WHERE `key` = 'a'");
+            return failed(dup, 'ALREADY_EXISTS', "Duplicate entry 'a' for key 'Link.key_unique'")
+                && failed(nul, 'INVALID_ARGUMENT', "Column 'url' cannot be null")
+                && failed(unknown, 'INVALID_ARGUMENT', "Unknown column 'nope' in 'field list'")
+                && read.rows.map((r) => r.join('=')).join(',') === 'a=https://a.test,b=https://b.test'
+                && ok(selfSame) && selfSame.rowsAffected === 1;
+        }),
+    },
+    {
+        id: 'planetscale.update.multi_table',
+        area: 'update', title: 'multiple-table UPDATE: aliased joins, each matching row updated once, only changed rows counted, a table under two aliases takes both, ORDER BY/LIMIT 1221, an unknown qualifier 1054, a subquery reading a target 1093',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            // the shape of Dub's payout claim (aggregate-due-commissions): UPDATE Commission c INNER JOIN Payout p ON … SET c.… WHERE …
+            await q('CREATE TABLE Payout (id VARCHAR(20) PRIMARY KEY, status VARCHAR(20) NOT NULL)');
+            await q('CREATE TABLE Commission (id VARCHAR(20) PRIMARY KEY, status VARCHAR(20) NOT NULL, payoutId VARCHAR(20) NULL, earnings INT NOT NULL)');
+            await q("INSERT INTO Payout (id, status) VALUES ('po_1', 'pending'), ('po_2', 'processing')");
+            await q("INSERT INTO Commission (id, status, earnings) VALUES ('c1', 'pending', 10), ('c2', 'pending', 20), ('c3', 'paid', 5)");
+            const claimed = await q("UPDATE Commission c INNER JOIN Payout p ON p.id = 'po_1' SET c.status = 'processed', c.payoutId = 'po_1' WHERE c.id IN ('c1', 'c2', 'c3') AND c.status = 'pending' AND p.status IN ('pending')");
+            const locked = await q("UPDATE Commission c INNER JOIN Payout p ON p.id = 'po_2' SET c.payoutId = 'po_2' WHERE c.id = 'c3' AND p.status IN ('pending')");
+            // a row matched by two join rows is updated once; a comma join with a value from the other table
+            await q("UPDATE Commission c, Payout p SET c.status = p.status WHERE c.payoutId = 'po_1' AND p.id = 'po_1'");
+            const rows = await q('SELECT id, status, payoutId FROM Commission ORDER BY id');
+            const ordered = await q("UPDATE Commission c INNER JOIN Payout p ON p.id = c.payoutId SET c.earnings = 1 ORDER BY c.id");
+            // a row two join rows match is updated once, from its first match; the PRIMARY KEY clause spells the column in
+            // another case than its definition
+            await q('CREATE TABLE T (Id INT NOT NULL, v INT, w INT, PRIMARY KEY (id))');
+            await q('CREATE TABLE U (id INT PRIMARY KEY, tid INT)');
+            await q('INSERT INTO T VALUES (1, 0, 0), (2, 0, 0)');
+            await q('INSERT INTO U VALUES (10, 1), (11, 1), (12, 2)');
+            const once = await q('UPDATE T a JOIN U b ON b.tid = a.Id SET a.v = b.id');
+            const onceRows = await q('SELECT Id, v FROM T ORDER BY Id');
+            // one table under two aliases takes the assignments of both
+            await q('UPDATE T a JOIN T b ON a.Id = b.Id SET a.v = 7, b.w = 8');
+            const both = await q('SELECT v, w FROM T ORDER BY Id');
+            const unknown = await q('UPDATE T a JOIN U b ON b.tid = a.Id SET z.v = 1');
+            const reads = await q('UPDATE T a JOIN U b ON b.tid = a.Id SET a.v = (SELECT MAX(v) FROM T)');
+            return claimed.rowsAffected === 2 && locked.rowsAffected === 0
+                && JSON.stringify(rows.rows) === JSON.stringify([['c1', 'pending', 'po_1'], ['c2', 'pending', 'po_1'], ['c3', 'paid', null]])
+                && (ordered.error?.message ?? '').includes('Incorrect usage of UPDATE and ORDER BY (errno 1221)')
+                && once.rowsAffected === 2 && JSON.stringify(onceRows.rows) === JSON.stringify([['1', '10'], ['2', '12']])
+                && JSON.stringify(both.rows) === JSON.stringify([['7', '8'], ['7', '8']])
+                && (unknown.error?.message ?? '').includes("Unknown column 'z.v' in 'field list' (errno 1054)")
+                && (reads.error?.message ?? '').includes('(errno 1093)');
+        }),
+    },
+    {
+        id: 'planetscale.update.aliased_single_table',
+        area: 'update', title: 'a single table under an alias is the single-table UPDATE: qualified SET and WHERE, ORDER BY and LIMIT, a wrong qualifier 1054',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q('CREATE TABLE T (id INT PRIMARY KEY, v INT)');
+            await q('INSERT INTO T VALUES (1, 0), (2, 0), (3, 0)');
+            const limited = await q('UPDATE T x SET x.v = 5 WHERE x.id > 1 ORDER BY x.id DESC LIMIT 1');
+            const wrong = await q('UPDATE T x SET y.v = 5');
+            const rows = await q('SELECT id, v FROM T ORDER BY id');
+            return limited.rowsAffected === 1 && JSON.stringify(rows.rows) === JSON.stringify([['1', '0'], ['2', '0'], ['3', '5']])
+                && (wrong.error?.message ?? '').includes("Unknown column 'y.v' in 'field list' (errno 1054)");
+        }),
+    },
+    // ── delete ──────────────────────────────────────────────────────────────────────────────────
+    {
+        id: 'planetscale.delete.where_and_limit',
+        area: 'delete', title: 'DELETE removes the matching rows, honours LIMIT, and reports rowsAffected',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url) VALUES ('a', 'https://a.test'), ('b', 'https://b.test'), ('c', 'https://c.test')");
+            const one = await q("DELETE FROM Link WHERE `key` = 'b'");
+            const none = await q("DELETE FROM Link WHERE `key` = 'zzz'");
+            const limited = await q('DELETE FROM Link LIMIT 1');
+            const read = await q('SELECT `key` FROM Link ORDER BY id');
+            return one.rowsAffected === 1 && none.rowsAffected === 0 && limited.rowsAffected === 1
+                && read.rows.map((r) => r[0]).join(',') === 'c';
+        }),
+    },
+    {
+        id: 'planetscale.delete.recreate_after_delete',
+        area: 'delete', title: 'a deleted row can be re-created with the same unique key (no sticky tombstone)',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url) VALUES ('a', 'https://first.test')");
+            await q("DELETE FROM Link WHERE `key` = 'a'");
+            // Deliberate DIRTY STATE: a delete that only marked a tombstone would make this collide, and
+            // a delete that left the row visible would make the read wrong. Both are real bugs this pins.
+            const readd = await q("INSERT INTO Link (`key`, url) VALUES ('a', 'https://second.test')");
+            const read = await q("SELECT id, url FROM Link WHERE `key` = 'a'");
+            const count = await q('SELECT COUNT(*) FROM Link');
+            return ok(readd) && readd.insertId === '2'
+                && read.rows.length === 1 && read.rows[0].join(':') === '2:https://second.test'
+                && count.rows[0][0] === '1';
+        }),
+    },
+    {
+        id: 'planetscale.delete.no_such_table',
+        area: 'delete', title: 'DELETE from a missing table raises errno 1146 rather than succeeding silently',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            const res = await q('DELETE FROM Nope WHERE id = 1');
+            return failed(res, 'NOT_FOUND', "Table 'twin.Nope' doesn't exist") && res.rowsAffected === 0;
+        }),
+    },
+    // ── transactions ────────────────────────────────────────────────────────────────────────────
+    {
+        id: 'planetscale.transactions.commit',
+        area: 'transactions', title: 'BEGIN … COMMIT makes the buffered writes visible in one step',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q('BEGIN');
+            await q("INSERT INTO Link (`key`, url) VALUES ('a', 'https://a.test')");
+            await q("INSERT INTO Link (`key`, url) VALUES ('b', 'https://b.test')");
+            const inTx = await q('SELECT COUNT(*) FROM Link');
+            const inTxSession = inTx.session;
+            await q('COMMIT');
+            const after = await q('SELECT `key` FROM Link ORDER BY id');
+            const afterSession = after.session;
+            return inTx.rows[0][0] === '2'
+                && inTxSession.vitessSession?.inTransaction === true && inTxSession.vitessSession.autocommit === false
+                && after.rows.map((r) => r[0]).join(',') === 'a,b'
+                && afterSession.vitessSession?.inTransaction === false;
+        }),
+    },
+    {
+        id: 'planetscale.transactions.rollback',
+        area: 'transactions', title: 'ROLLBACK discards every buffered write and leaves committed state untouched',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url) VALUES ('keep', 'https://keep.test')");
+            await q('BEGIN');
+            await q("INSERT INTO Link (`key`, url) VALUES ('drop', 'https://drop.test')");
+            await q("UPDATE Link SET url = 'https://changed.test' WHERE `key` = 'keep'");
+            await q("DELETE FROM Link WHERE `key` = 'keep'");
+            const inside = await q('SELECT COUNT(*) FROM Link');
+            await q('ROLLBACK');
+            const after = await q('SELECT `key`, url FROM Link');
+            // Every one of the three buffered writes is gone — including the DELETE, which is the one a
+            // naive "only buffer inserts" implementation would have applied straight through.
+            return inside.rows[0][0] === '1'
+                && after.rows.length === 1 && after.rows[0].join('=') === 'keep=https://keep.test';
+        }),
+    },
+    {
+        id: 'planetscale.transactions.read_your_writes',
+        area: 'transactions', title: 'statements inside a transaction see its own uncommitted writes',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q('BEGIN');
+            await q("INSERT INTO Link (`key`, url) VALUES ('a', 'https://a.test')");
+            const seen = await q("SELECT url FROM Link WHERE `key` = 'a'");
+            await q("UPDATE Link SET clicks = 5 WHERE `key` = 'a'");
+            const updated = await q("SELECT clicks FROM Link WHERE `key` = 'a'");
+            // A uniqueness violation must be detected against the BUFFER too, not only against committed
+            // rows — otherwise a transaction could stage two rows sharing a unique key.
+            const dup = await q("INSERT INTO Link (`key`, url) VALUES ('a', 'https://dup.test')");
+            await q('COMMIT');
+            const committed = await q("SELECT clicks FROM Link WHERE `key` = 'a'");
+            return seen.rows[0][0] === 'https://a.test' && updated.rows[0][0] === '5'
+                && failed(dup, 'ALREADY_EXISTS', "Duplicate entry 'a'")
+                && committed.rows[0][0] === '5';
+        }),
+    },
+    {
+        id: 'planetscale.transactions.session_isolation',
+        area: 'transactions', title: 'an uncommitted transaction is invisible to another session',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q('BEGIN');
+            await q("INSERT INTO Link (`key`, url) VALUES ('a', 'https://a.test')");
+            const txSession = (await q('SELECT COUNT(*) FROM Link')).session;
+            // A SECOND session, explicitly null so a fresh one is minted.
+            const outside = await q('SELECT COUNT(*) FROM Link', { session: null });
+            const inside = await q('SELECT COUNT(*) FROM Link', { session: txSession });
+            await q('COMMIT', { session: txSession });
+            const afterOutside = await q('SELECT COUNT(*) FROM Link', { session: null });
+            return outside.rows[0][0] === '0' && inside.rows[0][0] === '1' && afterOutside.rows[0][0] === '1';
+        }),
+    },
+    {
+        id: 'planetscale.transactions.begin_implicitly_commits',
+        area: 'transactions', title: 'BEGIN inside an open transaction implicitly COMMITs the one in flight',
+        dimension: 'api', tier: 'niche', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q('BEGIN');
+            await q("INSERT INTO Link (`key`, url) VALUES ('first', 'https://1.test')");
+            await q('BEGIN'); // MySQL commits the first transaction here
+            await q("INSERT INTO Link (`key`, url) VALUES ('second', 'https://2.test')");
+            await q('ROLLBACK');
+            const after = await q('SELECT `key` FROM Link');
+            return after.rows.map((r) => r[0]).join(',') === 'first';
+        }),
+    },
+    {
+        id: 'planetscale.transactions.ddl_inside_transaction',
+        area: 'transactions', title: 'DDL buffered in a transaction is visible to it and discarded by ROLLBACK',
+        dimension: 'api', tier: 'niche', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q('BEGIN');
+            await q('CREATE TABLE Temp (id INT NOT NULL PRIMARY KEY, name VARCHAR(16) NOT NULL)');
+            await q("INSERT INTO Temp (id, name) VALUES (1, 'x')");
+            const inside = await q('SELECT name FROM Temp');
+            await q('ROLLBACK');
+            const after = await q('SELECT * FROM Temp');
+            // NOTE (honest divergence, filed as planetscale.transactions.ddl_implicit_commit): real MySQL
+            // implicitly COMMITs before DDL, so a rolled-back CREATE TABLE would persist there. This twin
+            // buffers it, which is the SAFER direction for a local twin and is stated rather than hidden.
+            return inside.rows[0][0] === 'x' && failed(after, 'NOT_FOUND', "Table 'twin.Temp' doesn't exist");
+        }),
+    },
+    todo('planetscale.transactions.ddl_implicit_commit', 'transactions', "MySQL's implicit COMMIT before a DDL statement (this twin buffers DDL inside the transaction instead)", 'niche'),
+    todo('planetscale.transactions.autoinc_gap_on_rollback', 'transactions', 'InnoDB does NOT roll back the AUTO_INCREMENT counter, so a rolled-back insert leaves a permanent id gap (this twin reuses the id)', 'niche'),
+    todo('planetscale.transactions.savepoints', 'transactions', 'SAVEPOINT / ROLLBACK TO SAVEPOINT / RELEASE SAVEPOINT', 'niche'),
+    {
+        id: 'planetscale.transactions.row_locks',
+        area: 'transactions', title: "an open transaction's written rows block other sessions' writes until it ends, which then run on the committed rows (no lost update); plain reads never wait; a lock cycle is errno 1213 and rolls the waiter back",
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url) VALUES ('a', 'https://a.test'), ('b', 'https://b.test')");
+            const s1 = (await q('BEGIN', { session: null })).session;
+            await q("UPDATE Link SET clicks = clicks + 1 WHERE `key` = 'a'", { session: s1 });
+            let done = false;
+            const blocked = q("UPDATE Link SET clicks = clicks + 1 WHERE `key` = 'a'", { session: null }).then((r) => { done = true; return r; });
+            const read = await q("SELECT clicks FROM Link WHERE `key` = 'a'", { session: null });
+            const waited = !done;
+            await q('COMMIT', { session: s1 });
+            await blocked;
+            const both = await q("SELECT clicks FROM Link WHERE `key` = 'a'", { session: null });
+            // A lock cycle: s2 holds a and waits for b; s3 holds b and asks for a.
+            const s2 = (await q('BEGIN', { session: null })).session;
+            const s3 = (await q('BEGIN', { session: null })).session;
+            await q("UPDATE Link SET clicks = 10 WHERE `key` = 'a'", { session: s2 });
+            await q("UPDATE Link SET clicks = 20 WHERE `key` = 'b'", { session: s3 });
+            const first = q("UPDATE Link SET clicks = 11 WHERE `key` = 'b'", { session: s2 });
+            await q('SELECT 1', { session: null }); // s2 is waiting by the time this has run
+            const cycle = await q("UPDATE Link SET clicks = 21 WHERE `key` = 'a'", { session: s3 });
+            const firstRan = await first;
+            await q('COMMIT', { session: s2 });
+            const final = await q('SELECT clicks FROM Link ORDER BY id', { session: null });
+            return read.rows[0][0] === '0' && waited && both.rows[0][0] === '2'
+                && failed(cycle, 'ABORTED', 'Deadlock found when trying to get lock') && cycle.error.message.includes('1213')
+                && ok(firstRan) && final.rows.map((r) => r[0]).join(',') === '10,11';
+        }),
+    },
+    todo('planetscale.transactions.isolation_levels', 'transactions', "the four MySQL isolation levels' distinct read semantics: SET TRANSACTION ISOLATION LEVEL parses and is accepted, but every transaction reads the latest committed rows plus its own writes (no REPEATABLE READ snapshot, no SERIALIZABLE shared locks on plain reads)", 'niche'),
+    todo('planetscale.transactions.autocommit_toggle', 'transactions', 'SET autocommit = 0 and its implicit transaction', 'niche'),
+    {
+        id: 'planetscale.transactions.timeout',
+        area: 'transactions', title: 'the published 20s transaction timeout measured against the World clock',
+        dimension: 'api', tier: 'niche', expected: 'todo',
+    },
+    // ── functions / expressions ─────────────────────────────────────────────────────────────────
+    {
+        id: 'planetscale.functions.arithmetic',
+        area: 'functions', title: 'arithmetic (+ - * / % DIV) evaluates with MySQL\'s result types (exact DECIMAL/BIGINT, DOUBLE for approximate operands), NULL on division by zero',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            const one = async (expr) => (await q(`SELECT ${expr} AS v FROM dual`)).rows[0][0];
+            return await one('2 + 3') === '5'
+                && await one('10 - 4') === '6'
+                && await one('6 * 7') === '42'
+                && await one('9 / 2') === '4.5000' // exact: scale of 9 plus div_precision_increment (4)
+                && await one('1 / 3') === '0.3333'
+                && await one('0.1 + 0.2') === '0.3'
+                && await one('0.1e0 + 0.2e0') === '0.30000000000000004' // DOUBLE stays DOUBLE
+                && await one('9 DIV 2') === '4'
+                && await one('9 % 4') === '1'
+                && await one('1 / 0') === null // MySQL returns NULL, not an error
+                && await one('-5 + 1') === '-4'
+                && await one('(2 + 3) * 4') === '20';
+        }),
+    },
+    {
+        id: 'planetscale.functions.null_handling',
+        area: 'functions', title: 'COALESCE / IFNULL / NULLIF / IF behave like MySQL over NULL',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url, archived) VALUES ('a', 'https://a.test', NULL)");
+            const one = async (expr) => (await q(`SELECT ${expr} AS v FROM Link`)).rows[0][0];
+            return await one('COALESCE(archived, 7)') === '7'
+                && await one('COALESCE(NULL, NULL, 3)') === '3'
+                && await one('IFNULL(archived, 0)') === '0'
+                && await one("NULLIF(`key`, 'a')") === null
+                && await one("NULLIF(`key`, 'b')") === 'a'
+                && await one("IF(archived IS NULL, 'unset', 'set')") === 'unset'
+                && await one('1 + archived') === null; // NULL propagates through arithmetic
+        }),
+    },
+    {
+        id: 'planetscale.functions.string_functions',
+        area: 'functions', title: 'LOWER / UPPER / CONCAT / LENGTH / TRIM evaluate over real column data',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url) VALUES ('  MiXeD  ', 'https://a.test')");
+            const one = async (expr) => (await q(`SELECT ${expr} AS v FROM Link`)).rows[0][0];
+            return await one('LOWER(`key`)') === '  mixed  '
+                && await one('UPPER(`key`)') === '  MIXED  '
+                && await one('TRIM(`key`)') === 'MiXeD'
+                && await one('LENGTH(TRIM(`key`))') === '5'
+                && await one("CONCAT(TRIM(`key`), '-', url)") === 'MiXeD-https://a.test'
+                && await one("CONCAT(TRIM(`key`), NULL)") === null; // CONCAT with NULL is NULL
+        }),
+    },
+    {
+        id: 'planetscale.functions.byte_vs_char_length',
+        area: 'functions', title: 'LENGTH() counts BYTES and CHAR_LENGTH() counts CHARACTERS, as MySQL defines them',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            // Found while walking §9's revert matrix: both used to return the JavaScript string length,
+            // so LENGTH('日') was 1 where MySQL says 3. `functions.string_functions` never caught it
+            // because its verify only used ASCII, where the two agree — the same "a verify that exercises
+            // only the easy case" class round one flagged twice.
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url) VALUES ('鍵🔑', 'https://a.test')");
+            const text = await q('SELECT LENGTH(`key`) AS bytes, CHAR_LENGTH(`key`) AS chars FROM Link');
+            const literal = await q("SELECT LENGTH('日') AS b, CHAR_LENGTH('日') AS c FROM dual");
+            const ascii = await q("SELECT LENGTH('abc') AS b, CHAR_LENGTH('abc') AS c FROM dual");
+            // '鍵' is 3 UTF-8 bytes and '🔑' is 4, so 7 bytes — and 2 CHARACTERS (code points), which is
+            // also where a naive `.length` would answer 3, since '🔑' is a surrogate PAIR in JavaScript.
+            return text.rows[0].join(',') === '7,2'
+                && literal.rows[0].join(',') === '3,1'
+                && ascii.rows[0].join(',') === '3,3'
+                && (await q('SELECT LENGTH(archived) AS n FROM Link')).rows[0][0] === null;
+        }),
+    },
+    {
+        id: 'planetscale.functions.database',
+        area: 'functions', title: 'DATABASE() returns the schema this connection is bound to',
+        dimension: 'api', tier: 'niche', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            const dflt = await q('SELECT DATABASE() AS db FROM dual');
+            const other = decode(await q.raw({ body: JSON.stringify({ query: 'SELECT DATABASE() AS db FROM dual' }), database: 'shop' }));
+            return dflt.rows[0][0] === 'twin' && other.rows[0][0] === 'shop';
+        }),
+    },
+    {
+        id: 'planetscale.functions.clock',
+        area: 'functions', title: 'NOW(fsp) and its synonyms, UTC_TIMESTAMP(), CURDATE() and UNIX_TIMESTAMP() read the World clock instant of the statement, typed as MySQL types them',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            // Dub's payout aggregation (`UPDATE … JOIN … SET c.updatedAt = NOW()`) and every `WHERE at < NOW()` read it.
+            const at = { at: '2026-03-04T05:06:07.890Z' };
+            const read = await q('SELECT NOW() AS a, NOW(3) AS b, CURRENT_TIMESTAMP AS c, CURDATE() AS d, UNIX_TIMESTAMP() AS e', at);
+            await q('CREATE TABLE Ev (id INT NOT NULL, at DATETIME(3) NULL, PRIMARY KEY (id))');
+            await q("INSERT INTO Ev (id, at) VALUES (1, NOW(3)), (2, '2026-03-04 05:06:07.000'), (3, '2027-01-01 00:00:00.000')", at);
+            const before = await q('SELECT id FROM Ev WHERE at < NOW(3) ORDER BY id', at);
+            const stored = await q('SELECT at FROM Ev WHERE id = 1');
+            // unbound, in INSERT values, a clock value keeps its type: NOW() + 0 is its YYYYMMDDhhmmss number
+            await q('CREATE TABLE Num (id INT PRIMARY KEY, n BIGINT)');
+            await q('INSERT INTO Num VALUES (1, NOW() + 0)', at);
+            const numeric = await q('SELECT n FROM Num');
+            // NOW's precision is a bare number in MySQL's grammar
+            const twoArgs = await q('SELECT NOW(1, 2)', at);
+            const stringFsp = await q("SELECT NOW('3')", at);
+            return ok(read) && JSON.stringify(read.rows[0]) === JSON.stringify(['2026-03-04 05:06:07', '2026-03-04 05:06:07.890', '2026-03-04 05:06:07', '2026-03-04', '1772600767'])
+                && read.fields.map((f) => f.type).join() === 'DATETIME,DATETIME,DATETIME,DATE,INT64'
+                && JSON.stringify(before.rows) === '[["2"]]' && stored.rows[0][0] === '2026-03-04 05:06:07.890'
+                && numeric.rows[0][0] === '20260304050607'
+                && (twoArgs.error?.message ?? '').includes('(errno 1064)') && (stringFsp.error?.message ?? '').includes('(errno 1064)');
+        }),
+    },
+    {
+        id: 'planetscale.functions.entropy',
+        area: 'functions', title: 'RAND() / UUID() served from seeded entropy (today refused)',
+        dimension: 'api', tier: 'core', expected: 'todo',
+    },
+    {
+        id: 'planetscale.functions.entropy_refusal_is_real',
+        area: 'functions', title: 'the entropy functions are genuinely REFUSED, not silently frozen',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            // The refusal above is a CLAIM; this is its proof. A refusal note is worthless if the
+            // twin quietly answers anyway with a fabricated constant.
+            for (const fn of ['RAND()', 'UUID()']) {
+                const res = await q(`SELECT ${fn} AS v FROM dual`);
+                if (!failed(res, 'UNIMPLEMENTED', 'unsupported:'))
+                    return false;
+                if (!res.error.message.includes('serves no randomness'))
+                    return false;
+                if (res.rows.length !== 0)
+                    return false;
+            }
+            return true;
+        }),
+    },
+    {
+        id: 'planetscale.functions.date_format_convert_tz',
+        area: 'functions', title: "DATE_FORMAT (all specifiers but the week ones) and CONVERT_TZ between offsets and named zones, NULL for an unknown zone (Dub's partner-analytics timeseries)",
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q('CREATE TABLE C (id INT NOT NULL, createdAt DATETIME(3) NOT NULL, earnings INT NOT NULL, PRIMARY KEY (id))');
+            await q("INSERT INTO C (id, createdAt, earnings) VALUES (1, '2026-03-04 23:30:00.000', 100), (2, '2026-03-05 02:00:00.000', 250), (3, '2026-03-05 12:00:00.000', 7)");
+            const series = await q("SELECT DATE_FORMAT(CONVERT_TZ(createdAt, '+00:00', '-05:00'), '%Y-%m-%d') AS start, SUM(earnings) AS earnings FROM C GROUP BY start ORDER BY start ASC");
+            const named = await q("SELECT DATE_FORMAT(CONVERT_TZ('2026-07-01 12:00:00', 'UTC', 'America/New_York'), '%Y-%m-%d %H:00'), CONVERT_TZ('2026-07-01 12:00:00', '+00:00', 'Nowhere/Nope')");
+            const words = await q("SELECT DATE_FORMAT('2026-03-01 15:04:05.25', '%W %M %D %y, %l:%i:%s %p %f %j %%')");
+            return series.rows.map((r) => r.join(':')).join(',') === '2026-03-04:350,2026-03-05:7'
+                && named.rows[0][0] === '2026-07-01 08:00' && named.rows[0][1] === null
+                && words.rows[0][0] === 'Sunday March 1st 26, 3:04:05 PM 250000 060 %';
+        }),
+    },
+    todo('planetscale.functions.date_functions', 'functions', 'the rest of the date library: DATE_ADD / DATE_SUB / INTERVAL, DATEDIFF, STR_TO_DATE, YEAR/MONTH/DAY, the DATE_FORMAT week specifiers', 'common'),
+    {
+        id: 'planetscale.functions.json_functions',
+        area: 'functions', title: 'JSON_CONTAINS (Prisma `array_contains`), JSON_TYPE, JSON_EXTRACT, JSON_UNQUOTE, the -> and ->> operators, JSON_LENGTH, JSON_ARRAY and JSON_OBJECT over JSON documents, printed as MySQL prints JSON',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q('CREATE TABLE Webhook (id INT NOT NULL, triggers JSON NOT NULL, meta JSON NULL, PRIMARY KEY (id))');
+            await q(`INSERT INTO Webhook (id, triggers, meta) VALUES (1, '["link.created","link.deleted"]', '{"b": {"c": 2}, "a": "x"}'), (2, '["lead.created"]', NULL)`);
+            // Prisma's `triggers: { array_contains: ['link.created'] }`, verbatim in shape.
+            const contains = await q(`SELECT id FROM Webhook WHERE (JSON_CONTAINS(Webhook.triggers, '["link.created"]') AND (JSON_TYPE(Webhook.triggers) = 'ARRAY'))`);
+            const scalar = await q(`SELECT JSON_CONTAINS('{"a": 1, "b": [1, 2]}', '{"b": [2]}'), JSON_CONTAINS('[1, 2]', '3'), JSON_CONTAINS(meta, '2', '$.b.c') FROM Webhook WHERE id = 1`);
+            const extract = await q(`SELECT JSON_EXTRACT(meta, '$.b'), meta->'$.a', meta->>'$.a', JSON_LENGTH(triggers), JSON_EXTRACT(triggers, '$[*]') FROM Webhook WHERE id = 1`);
+            const built = await q(`SELECT JSON_OBJECT('id', id, 'ok', 'yes'), JSON_ARRAY(1, 'two', NULL) FROM Webhook WHERE id = 2`);
+            const invalid = await q(`SELECT JSON_CONTAINS('not json', '1')`);
+            return contains.rows.map((r) => r[0]).join(',') === '1'
+                && scalar.rows[0].join('|') === '1|0|1'
+                && extract.rows[0].join('|') === '{"c": 2}|"x"|x|2|["link.created", "link.deleted"]'
+                && built.rows[0].join('|') === '{"id": 2, "ok": "yes"}|[1, "two", null]'
+                && failed(invalid, 'INVALID_ARGUMENT', 'Invalid JSON text') && invalid.error.message.includes('3141');
+        }),
+    },
+    todo('planetscale.functions.json_modification', 'functions', 'JSON_SET / JSON_INSERT / JSON_REPLACE / JSON_REMOVE / JSON_ARRAY_APPEND / JSON_MERGE_PATCH and the other document-modifying JSON functions', 'common'),
+    {
+        id: 'planetscale.functions.json_normalized_storage',
+        area: 'functions', title: 'a JSON column is validated on write (errno 3140) and stored normalized — members in MySQL order, integers exact, doubles as doubles — and read back so',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q('CREATE TABLE Doc (id INT PRIMARY KEY, body JSON)');
+            await q(`INSERT INTO Doc VALUES (1, '{"zeta":1,"a":[1.50,2],"id":12345678901234567890}')`);
+            const bad = await q("INSERT INTO Doc VALUES (2, 'not json')");
+            const number = await q('INSERT INTO Doc VALUES (3, 5)');
+            const read = await q('SELECT body, body->>\'$.id\' FROM Doc');
+            return read.rows[0][0] === '{"a": [1.5, 2], "id": 12345678901234567890, "zeta": 1}' && read.rows[0][1] === '12345678901234567890'
+                && failed(bad, 'INVALID_ARGUMENT', `Invalid JSON text: "Invalid value." at position 0 in value for column 'Doc.body'.`) && bad.error.message.includes('3140')
+                && failed(number, 'INVALID_ARGUMENT', 'not a JSON text, may need CAST');
+        }),
+    },
+    {
+        id: 'planetscale.functions.case_when',
+        area: 'functions', title: 'CASE … WHEN … THEN … ELSE … END, searched and simple forms, NULL without a matching WHEN or ELSE',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url, clicks) VALUES ('a', 'https://a.test', 0), ('b', 'https://b.test', 5), ('c', 'https://c.test', 50)");
+            const searched = await q("SELECT CASE WHEN clicks >= 10 THEN 'hot' WHEN clicks > 0 THEN 'warm' ELSE 'cold' END AS heat FROM Link");
+            const simple = await q("SELECT CASE `key` WHEN 'a' THEN 1 WHEN 'b' THEN 2 END FROM Link");
+            return searched.rows.map((r) => r[0]).join(',') === 'cold,warm,hot' && searched.fields[0].name === 'heat'
+                && simple.rows.map((r) => r[0]).join(',') === '1,2,';
+        }),
+    },
+    todo('planetscale.functions.substring_replace', 'functions', 'SUBSTRING / REPLACE / LEFT / RIGHT / LOCATE / LPAD', 'common'),
+    {
+        id: 'planetscale.functions.cast_convert',
+        area: 'functions', title: 'CAST(… AS type) and CONVERT(…, type) / CONVERT(… USING charset) with MySQL\'s conversions and result types',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            const r = await q("SELECT CAST('2024-01-01 10:00:00' AS DATE), CAST(1.5 AS SIGNED), CAST('1.7' AS SIGNED), CAST(-1 AS UNSIGNED), CAST('12.345' AS DECIMAL(5,2)), CAST('{\"b\":1,\"a\":2}' AS JSON), CONVERT(42, CHAR), CAST('2024-01-01T10:00:00.5' AS DATETIME(1)) FROM dual");
+            const bad = await q("SELECT CAST('x' AS JSON) FROM dual");
+            return JSON.stringify(r.rows[0]) === JSON.stringify(['2024-01-01', '2', '1', '18446744073709551615', '12.35', '{"a": 2, "b": 1}', '42', '2024-01-01 10:00:00.5'])
+                && r.fields.map((f) => f.type).join(',') === 'DATE,INT64,INT64,UINT64,DECIMAL,JSON,VARCHAR,DATETIME'
+                && failed(bad, 'INVALID_ARGUMENT', 'Invalid JSON text in argument 1 to function cast_as_json');
+        }),
+    },
+    todo('planetscale.functions.regexp', 'functions', 'REGEXP / RLIKE and REGEXP_REPLACE', 'niche'),
+    // ── errors ──────────────────────────────────────────────────────────────────────────────────
+    {
+        id: 'planetscale.errors.query_error_arrives_at_http_200',
+        area: 'errors', title: 'a query error is HTTP 200 carrying {session, error:{code,message}}',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            const res = await q('SELECT * FROM Nope');
+            const body = res.raw.body;
+            // The 200 is load-bearing: the CLIENT synthesizes status 400 from this shape
+            // (dist/index.js `execute`). Serving a real 400 would change the status every consumer sees.
+            return res.status === 200 && body.error?.code === 'NOT_FOUND' && body.result === undefined
+                && body.session !== undefined
+                && typeof body.session.vitessSession.sessionUUID === 'string';
+        }),
+    },
+    {
+        id: 'planetscale.errors.parse_error',
+        area: 'errors', title: 'a syntax error raises errno 1064 with a position, like MySQL',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            const truncated = await q('SELECT * FROM');
+            const empty = await q('');
+            const unclosed = await q("SELECT 'unterminated FROM dual");
+            const trailing = await q('DESCRIBE Link and some junk');
+            // §9 round one, finding 14b: this used to open by asserting that `SELEKT * FROM Link` answers
+            // UNIMPLEMENTED — the OPPOSITE of the title, since real MySQL gives 1064 for a mistyped verb.
+            // That case now lives in `errors.unmodeled_statement`, where it belongs, and this capability
+            // asserts only genuine 1064 parse errors. `trailing` is the branch §9 finding 12 found
+            // silently accepted (DESCRIBE returned without calling finish()).
+            return failed(trailing, 'INVALID_ARGUMENT', 'syntax error at position')
+                && failed(truncated, 'INVALID_ARGUMENT', 'syntax error at position')
+                && truncated.error.message.includes('(errno 1064) (sqlstate 42000)')
+                && failed(empty, 'INVALID_ARGUMENT', 'syntax error at position 1')
+                && failed(unclosed, 'INVALID_ARGUMENT', 'syntax error at position');
+        }),
+    },
+    {
+        id: 'planetscale.errors.errno_sqlstate_suffix',
+        area: 'errors', title: 'every query error message carries MySQL\'s `(errno N) (sqlstate S)` suffix',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            const pairs = [
+                ['SELECT * FROM Nope', 1146, '42S02'],
+                ['SELECT nope FROM Link', 1054, '42S22'],
+                ["INSERT INTO Link (`key`) VALUES ('x')", 1364, 'HY000'],
+                ['CREATE TABLE Link (id INT PRIMARY KEY)', 1050, '42S01'],
+            ];
+            for (const [sql, errno, sqlstate] of pairs) {
+                const res = await q(sql);
+                if (res.error === undefined)
+                    return false;
+                if (!res.error.message.endsWith(`(errno ${errno}) (sqlstate ${sqlstate})`))
+                    return false;
+            }
+            return true;
+        }),
+    },
+    {
+        id: 'planetscale.errors.unmodeled_statement',
+        area: 'errors', title: 'a statement family this twin does not model raises Vitess\'s `unsupported:` UNIMPLEMENTED',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            const cases = [
+                'ALTER TABLE Link DROP COLUMN domain', 'CREATE DATABASE other', 'GRANT ALL ON *.* TO x',
+                'SET autocommit = 0', 'SHOW DATABASES',
+                // A mistyped verb is an unknown STATEMENT FAMILY to this parser, so it takes this channel
+                // rather than 1064 (§9 round one, finding 14b — it used to be asserted under the
+                // parse-error capability, whose title claims the opposite).
+                'SELEKT * FROM Link',
+                // §9 round one, finding 12: `EXPLAIN <statement>` used to be parsed as `DESCRIBE SELECT`
+                // and answered a confidently wrong errno 1146 naming a table called "SELECT".
+                'EXPLAIN SELECT * FROM Link', 'EXPLAIN ANALYZE SELECT * FROM Link',
+            ];
+            for (const sql of cases) {
+                const res = await q(sql);
+                if (res.error?.code !== 'UNIMPLEMENTED')
+                    return false;
+                if (!res.error.message.startsWith('unsupported: '))
+                    return false;
+                // Never a fabricated success: no rows, no rowsAffected.
+                if (res.rows.length !== 0 || res.rowsAffected !== 0)
+                    return false;
+            }
+            return true;
+        }),
+    },
+    todo('planetscale.errors.vttablet_prefix', 'errors', "the vttablet routing prefix real errors carry (`target: <keyspace>.<shard>.<tablet_type>: vttablet: rpc error: code = … desc = `) — deliberately not fabricated, since a local twin has no keyspace or shard", 'niche'),
+    todo('planetscale.errors.warnings', 'errors', 'SHOW WARNINGS and the warning list a lenient statement produces', 'niche'),
+    // ── readonly ────────────────────────────────────────────────────────────────────────────────
+    {
+        id: 'planetscale.readonly.refuses_writes',
+        area: 'readonly', title: 'a read-only twin refuses every write with MySQL errno 1290 and still serves reads',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url) VALUES ('a', 'https://a.test')");
+            const reads = await q('SELECT `key` FROM Link', { readOnly: true });
+            for (const sql of [
+                "INSERT INTO Link (`key`, url) VALUES ('b', 'https://b.test')",
+                "UPDATE Link SET clicks = 1 WHERE `key` = 'a'",
+                "DELETE FROM Link WHERE `key` = 'a'",
+                'DROP TABLE Link',
+                'TRUNCATE TABLE Link',
+                'CREATE TABLE Other (id INT PRIMARY KEY)',
+            ]) {
+                const res = await q(sql, { readOnly: true });
+                if (!failed(res, 'FAILED_PRECONDITION', '--read-only option'))
+                    return false;
+                if (!res.error.message.includes('(errno 1290) (sqlstate HY000)'))
+                    return false;
+            }
+            // …and NOTHING landed: the refusals must precede the write, not follow it.
+            const after = await q('SELECT `key`, clicks FROM Link');
+            return reads.rows[0][0] === 'a' && after.rows.length === 1 && after.rows[0].join(':') === 'a:0';
+        }),
+    },
+    // ── §9 ROUND-ONE PINS ───────────────────────────────────────────────────────────────────────
+    // Each of these exists because round one REFUTED a claim or found a defect by reading. They are
+    // the revert-matrix cells: re-introduce the named bug and the named capability must go red.
+    {
+        id: 'planetscale.wire.binary_column_stores_text_as_utf8_bytes',
+        area: 'wire', title: 'text bound to a binary column is stored as UTF-8 BYTES — the table never becomes unreadable',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            // §9 ROUND ONE, FINDING 3. `INSERT INTO B (p) VALUES ('日')` used to store the raw JS string;
+            // the next READ threw a plain Error out of the wire packer, which is not a SqlError, so it
+            // escaped the handler entirely and the server answered HTTP 500 — forever, for that table.
+            // Real MySQL stores the UTF-8 bytes. The engine now coerces at write time (`storeValue`).
+            await q('CREATE TABLE B (id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, p VARBINARY(64) NULL, note VARCHAR(16) NOT NULL)');
+            const inserted = await q("INSERT INTO B (p, note) VALUES ('日', 'after')");
+            const read = await q('SELECT p, note FROM B');
+            if (!ok(inserted) || !ok(read))
+                return false;
+            const bytes = Array.from(Uint8Array.from(read.rows[0][0], (c) => c.charCodeAt(0)));
+            // THE ASSERTIONS THAT GIVE THIS PIN TEETH (added after the §9 revert matrix found the first
+            // version HOLLOW). Reverting `storeValue` alone does NOT change the wire bytes, because
+            // `encodeCell`'s UTF-8 fallback — the other half of the same fix — re-encodes at pack time
+            // and lands on the identical payload. So asserting the bytes cannot distinguish the two.
+            // What DOES distinguish them is the STORED FORM, and MySQL makes it observable twice:
+            //   • a binary column compares equal to its own hex representation, because what is stored
+            //     IS the bytes. With `storeValue` reverted the cell is a 1-character JS string and this
+            //     match fails.
+            //   • LENGTH()/CHAR_LENGTH() over a binary column count BYTES: 3, not 1.
+            const matched = await q("SELECT note FROM B WHERE p = x'E697A5'");
+            const lengths = await q('SELECT LENGTH(p) AS l, CHAR_LENGTH(p) AS c FROM B');
+            // …and the STORED CELL itself, read straight off the projection. §9 ROUND TWO (finding 1)
+            // proved the first version of this pin HOLLOW: every assertion read through the packer, and
+            // the fix's other half — `encodeCell`'s UTF-8 fallback — re-encodes at pack time to the
+            // identical bytes, so reverting `storeValue` was invisible. Two independent changes need two
+            // independent assertions, and this is the one that can only pass if the ENGINE coerced.
+            const stored = readDatabase(q.root).rows.get('b')?.[0]?.cells.p ?? null;
+            // The packer's own guarantee, asserted directly rather than through a query: it must NEVER
+            // throw, whatever it is handed. That is the half that turned one INSERT into a permanently
+            // unreadable table.
+            let packerThrew = false;
+            try {
+                packRow([{ name: 'p', type: 'VARBINARY', charset: 63 }], ['🔑']);
+            }
+            catch {
+                packerThrew = true;
+            }
+            // A hex literal is ALREADY bytes and must NOT be re-encoded.
+            await q("UPDATE B SET p = x'00ff41' WHERE id = 1");
+            const hex = await q('SELECT p FROM B');
+            const hexBytes = Array.from(Uint8Array.from(hex.rows[0][0], (c) => c.charCodeAt(0)));
+            return bytes.join(',') === '230,151,165' // '日' = E6 97 A5
+                && read.rows[0][1] === 'after' // the LATER column is still aligned
+                && matched.rows.length === 1 && matched.rows[0][0] === 'after'
+                && lengths.rows[0].join(',') === '3,3'
+                && stored !== null && stored.length === 3 // THREE characters in the cell, not one
+                && !packerThrew
+                && hexBytes.join(',') === '0,255,65'
+                && read.fields[0].charset === 63;
+        }),
+    },
+    {
+        id: 'planetscale.select.expression_column_typing',
+        area: 'select', title: 'a computed column is typed from the WHOLE column, and a binary expression reports charset 63',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            // §9 ROUND ONE, FINDINGS 4 AND 5 — both "the twin serves bytes the client decodes wrongly".
+            await q('CREATE TABLE M (id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, v VARCHAR(16) NOT NULL)');
+            await q("INSERT INTO M (v) VALUES ('1.5'), ('abc')");
+            // FINDING 4: the type used to come from row ZERO, so this column was typed FLOAT64 and the
+            // client's own cast turned 'abc' into NaN. A numeric type may only be claimed when EVERY
+            // non-null value has that shape.
+            const mixed = await q('SELECT CONCAT(v) AS c FROM M ORDER BY id');
+            // …and a genuinely all-integer column still gets INT64, so the fix did not just give up.
+            const ints = await q('SELECT id + 0 AS n FROM M ORDER BY id');
+            // FINDING 5: `binary` used to be `isNumericVitessType`, which is FALSE for VARBINARY — so a
+            // hex literal went out with charset 45, the packer UTF-8-expanded it to 4 bytes, and the
+            // client returned a mojibake string instead of a Uint8Array.
+            const hex = await q("SELECT x'00ff41' AS b FROM dual");
+            const raw = (hex.raw.body.result?.rows ?? [])[0];
+            return mixed.fields[0].type === 'VARCHAR' && mixed.fields[0].charset === 45
+                && mixed.rows.map((r) => r[0]).join(',') === '1.5,abc'
+                && ints.fields[0].type === 'INT64'
+                && hex.fields[0].type === 'VARBINARY' && hex.fields[0].charset === 63
+                && raw?.lengths[0] === '3' && raw.values === btoa('\x00\xff\x41');
+        }),
+    },
+    {
+        id: 'planetscale.select.unknown_column_in_where',
+        area: 'select', title: 'an unknown column in WHERE/ORDER BY is errno 1054 even over an EMPTY table',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            // §9 ROUND ONE, FINDING 7. `readColumn` only runs PER ROW, so on an empty table the reference
+            // was never checked and the twin answered `[]` — which reads to a caller as "ran fine,
+            // matched nothing", the fabricated success this pack's own header forbids, and which makes a
+            // renamed-column schema drift invisible. Validation now precedes the scan.
+            await q(LINK_DDL);
+            const emptySelect = await q('SELECT * FROM Link WHERE nosuch = 1');
+            const emptyDelete = await q('DELETE FROM Link WHERE nosuch = 1');
+            const emptyUpdate = await q('UPDATE Link SET clicks = 1 WHERE nosuch = 1');
+            const emptyOrder = await q('SELECT * FROM Link ORDER BY nosuch');
+            // …and the same over a table that DOES have rows, so the fix is not empty-table-only.
+            await q("INSERT INTO Link (`key`, url) VALUES ('a', 'https://a.test')");
+            const populated = await q('SELECT * FROM Link WHERE nosuch = 1');
+            // A LEGAL query over the same shapes must still work — the guard must not over-reject.
+            const legal = await q("SELECT `key` FROM Link WHERE clicks = 0 ORDER BY id");
+            return failed(emptySelect, 'INVALID_ARGUMENT', "Unknown column 'nosuch' in 'where clause'")
+                && emptySelect.error.message.includes('(errno 1054) (sqlstate 42S22)')
+                && failed(emptyDelete, 'INVALID_ARGUMENT', "Unknown column 'nosuch'") && emptyDelete.rowsAffected === 0
+                && failed(emptyUpdate, 'INVALID_ARGUMENT', "Unknown column 'nosuch'")
+                && failed(emptyOrder, 'INVALID_ARGUMENT', "Unknown column 'nosuch' in 'order clause'")
+                && failed(populated, 'INVALID_ARGUMENT', "Unknown column 'nosuch'")
+                && ok(legal) && legal.rows[0][0] === 'a';
+        }),
+    },
+    {
+        id: 'planetscale.transactions.failed_statement_keeps_it_open',
+        area: 'transactions', title: 'a failed statement does NOT end the transaction, and the echoed session says so',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            // §9 ROUND ONE, FINDING 10. The error path used to echo a flat `inTransaction: false`, so a
+            // statement that failed inside an open transaction told the caller it had ended — while the
+            // server still held the buffer and a later COMMIT still landed everything. MySQL does not end
+            // a transaction on a failed statement; the wire must not claim otherwise.
+            await q(LINK_DDL);
+            await q('BEGIN');
+            await q("INSERT INTO Link (`key`, url) VALUES ('a', 'https://a.test')");
+            const failedStmt = await q('SELECT * FROM NoSuchTable');
+            const stillOpen = failedStmt.session.vitessSession;
+            // The transaction really IS still open: a second write buffers, and COMMIT lands both.
+            await q("INSERT INTO Link (`key`, url) VALUES ('b', 'https://b.test')");
+            const outside = await q('SELECT COUNT(*) FROM Link', { session: null });
+            await q('COMMIT');
+            const after = await q('SELECT `key` FROM Link ORDER BY id', { session: null });
+            // …and OUTSIDE a transaction a failed statement still reports false, so this is not a constant.
+            const plain = await q('SELECT * FROM NoSuchTable', { session: null });
+            const plainSession = plain.session.vitessSession;
+            return failedStmt.error?.code === 'NOT_FOUND'
+                && stillOpen?.inTransaction === true && stillOpen.autocommit === false
+                && outside.rows[0][0] === '0'
+                && after.rows.map((r) => r[0]).join(',') === 'a,b'
+                && plainSession?.inTransaction === false;
+        }),
+    },
+    {
+        id: 'planetscale.select.unmodeled_clauses_take_the_right_channel',
+        area: 'select', title: 'index hints, PARTITION and set operations are UNIMPLEMENTED, not a syntax error',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            // §9 ROUND ONE, FINDINGS 13 AND 14a. `SELECT * FROM t FORCE INDEX (PRIMARY)` used to swallow
+            // FORCE as the table ALIAS and then answer a bare syntax error — a confidently wrong reply to
+            // legal MySQL an ORM emits. `SELECT 1 UNION SELECT 2` answered 1064 even though
+            // `planetscale.select.union` is a filed todo, so the pack knew the surface exists and still
+            // told the caller their SQL was malformed. Unmodeled surface takes the `unsupported:` channel.
+            await q(LINK_DDL);
+            const cases = [
+                ['SELECT * FROM Link FORCE INDEX (PRIMARY)', 'index hints'],
+                ['SELECT * FROM Link USE INDEX (key_unique)', 'index hints'],
+                ['SELECT * FROM Link IGNORE INDEX (key_unique)', 'index hints'],
+                ['SELECT * FROM Link PARTITION (p0)', 'PARTITION'],
+                ['SELECT 1 FROM dual UNION SELECT 2 FROM dual', 'UNION'],
+                ['SELECT 1 FROM dual INTERSECT SELECT 2 FROM dual', 'INTERSECT'],
+            ];
+            for (const [sql, fragment] of cases) {
+                const res = await q(sql);
+                if (!failed(res, 'UNIMPLEMENTED', 'unsupported:'))
+                    return false;
+                if (!res.error.message.includes(fragment))
+                    return false;
+                if (res.rows.length !== 0)
+                    return false;
+            }
+            // A genuine syntax error must STILL be 1064 — the fix must not turn every parse failure into
+            // UNIMPLEMENTED, which would be the opposite over-correction.
+            return failed(await q('SELECT * FROM'), 'INVALID_ARGUMENT', 'syntax error at position');
+        }),
+    },
+    {
+        id: 'planetscale.ddl.bare_key_is_primary_key',
+        area: 'ddl', title: 'a bare `KEY` in a column definition is PRIMARY KEY, as MySQL defines it',
+        dimension: 'api', tier: 'niche', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            // §9 ROUND ONE, FINDING 15: this branch was EMPTY behind a comment claiming it was
+            // implemented, so `CREATE TABLE k (id INT KEY)` answered a syntax error.
+            const created = await q('CREATE TABLE K (id INT KEY, name VARCHAR(16) NOT NULL)');
+            const described = await q('DESCRIBE K');
+            await q("INSERT INTO K (id, name) VALUES (1, 'a')");
+            const dup = await q("INSERT INTO K (id, name) VALUES (1, 'b')");
+            // A table-level `KEY (col)` still means a NON-unique index — the two spellings differ, and
+            // conflating them would make every secondary index a uniqueness constraint.
+            await q('CREATE TABLE S (id INT NOT NULL PRIMARY KEY, tag VARCHAR(8) NOT NULL, KEY tag_idx (tag))');
+            await q("INSERT INTO S (id, tag) VALUES (1, 'x'), (2, 'x')");
+            const shared = await q('SELECT COUNT(*) FROM S');
+            return ok(created)
+                && described.rows.find((r) => r[0] === 'id')?.[3] === 'PRI'
+                && failed(dup, 'ALREADY_EXISTS', "Duplicate entry '1' for key 'K.PRIMARY'")
+                && shared.rows[0][0] === '2';
+        }),
+    },
+    {
+        id: 'planetscale.functions.mysql_string_truthiness',
+        area: 'functions', title: "a non-numeric string is FALSE in a boolean context, as MySQL coerces it",
+        dimension: 'api', tier: 'niche', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            // §9 ROUND ONE, FINDING 16: `truthy` used to return "any non-empty string is TRUE", so
+            // `WHERE 'abc'` and `WHERE some_text_column` selected rows real MySQL skips. MySQL coerces a
+            // string by its LEADING NUMERIC PREFIX.
+            const rows = async (where) => (await q(`SELECT 1 AS n FROM dual WHERE ${where}`)).rows.length;
+            return await rows("'abc'") === 0
+                && await rows("'0abc'") === 0
+                && await rows("'0'") === 0
+                && await rows("''") === 0
+                && await rows("'1abc'") === 1
+                && await rows("'2'") === 1
+                // 'Infinity' is the case that separates MySQL's LEADING-NUMERIC-PREFIX rule from
+                // JavaScript's `parseFloat`, which additionally accepts it. §9 round two (finding 13) caught
+                // the twin selecting a row MySQL skips — and the REVERT MATRIX then caught this pin staying
+                // green against that exact revert, because it never asserted the one input that differs.
+                // A pin that does not cover the bug it names is not a pin.
+                && await rows("'Infinity'") === 0
+                && await rows("'-Infinity'") === 0
+                && await rows("'NaN'") === 0
+                && await rows("IF('abc', 1, 0)") === 0
+                && await rows("IF('Infinity', 1, 0)") === 0
+                && await rows("IF('1abc', 1, 0)") === 1;
+        }),
+    },
+    // ── §9 ROUND-TWO PINS ───────────────────────────────────────────────────────────────────────
+    // Round two attacked round one's FIXES and found three of them had introduced defects of the very
+    // classes they were closing. These pin the repairs.
+    {
+        id: 'planetscale.wire.binary_values_survive_re_assignment',
+        area: 'wire', title: 'UPDATE p = p is a NO-OP on a binary column, and a DEFAULT stores the same bytes as a literal',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            // §9 ROUND TWO, FINDING 2 — a REGRESSION introduced by round one's own fix. `storeValue`
+            // decided "already bytes?" from the source's expression KIND, so anything that was not a hex
+            // literal got UTF-8-encoded again over an already-encoded value: `UPDATE b SET p = p` — a
+            // no-op in MySQL — doubled the length every time (3 → 6 → 12 → 24 bytes), and
+            // `ON DUPLICATE KEY UPDATE p = p`, the canonical upsert-touch idiom, did the same. The
+            // predicate is now the source's STATIC TYPE, which is MySQL's own rule.
+            await q("CREATE TABLE B (id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, p VARBINARY(64) NULL, d VARBINARY(8) DEFAULT 'é', k VARCHAR(8) NOT NULL UNIQUE)");
+            await q("INSERT INTO B (p, k) VALUES ('日', 'a')");
+            const first = await q('SELECT LENGTH(p) AS n FROM B');
+            await q('UPDATE B SET p = p');
+            await q('UPDATE B SET p = p');
+            await q("INSERT INTO B (p, k) VALUES ('日', 'a') ON DUPLICATE KEY UPDATE p = p");
+            const stable = await q('SELECT LENGTH(p) AS n FROM B');
+            // A DEFAULT and the identical literal in VALUES must store the SAME bytes — they used to
+            // differ, because the default took a Latin-1 short-circuit.
+            const viaDefault = await q('SELECT LENGTH(d) AS n FROM B');
+            await q("INSERT INTO B (p, d, k) VALUES ('x', 'é', 'b')");
+            const viaLiteral = await q("SELECT LENGTH(d) AS n FROM B WHERE k = 'b'");
+            return first.rows[0][0] === '3' && stable.rows[0][0] === '3'
+                && viaDefault.rows[0][0] === '2' && viaLiteral.rows[0][0] === '2';
+        }),
+    },
+    {
+        id: 'planetscale.select.binariness_propagates_through_expressions',
+        area: 'select', title: 'CONCAT/UPPER over a binary column stay binary — the column and expression paths agree',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            // §9 ROUND TWO, FINDING 3 — the second regression from round one's fix, and the same
+            // wrong-bytes-to-the-client class round one had refuted as ITS finding 5, re-entering through
+            // the expression door. Because a binary cell is stored one char per byte, an expression over
+            // it LOOKS like text to a shape sniffer: `CONCAT(p)` was typed VARCHAR at charset 45, the
+            // packer UTF-8-expanded the bytes (6 instead of 3), and the client's own `cast` handed the
+            // caller the mojibake string `æ—¥` instead of a Uint8Array. `UPPER(p)` additionally
+            // case-folded a BYTE (0xE6 → 0xC6), corrupting binary data.
+            await q('CREATE TABLE B (id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, p VARBINARY(64) NULL, t VARCHAR(16) NOT NULL)');
+            await q("INSERT INTO B (p, t) VALUES ('日', 'mixed')");
+            const bare = await q('SELECT p FROM B');
+            const concat = await q('SELECT CONCAT(p) AS c FROM B');
+            const upper = await q('SELECT UPPER(p) AS u FROM B');
+            const text = await q('SELECT UPPER(t) AS u FROM B');
+            const bytesOf = (row) => Array.from(row[0], (c) => c.charCodeAt(0)).join(',');
+            return bare.fields[0].charset === 63 && bare.fields[0].type === 'VARBINARY'
+                // The expression path must agree with the column path, in BOTH type and charset.
+                && concat.fields[0].charset === 63 && concat.fields[0].type === 'VARBINARY'
+                && bytesOf(concat.rows[0]) === '230,151,165'
+                && upper.fields[0].charset === 63 && bytesOf(upper.rows[0]) === '230,151,165'
+                // …while UPPER over TEXT still folds, so the fix did not just disable the function.
+                && text.rows[0][0] === 'MIXED';
+        }),
+    },
+    {
+        id: 'planetscale.select.order_by_select_alias',
+        area: 'select', title: 'ORDER BY may name a select-list alias, as MySQL allows',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            // §9 ROUND TWO, FINDING 4: round one's pre-scan column validation turned this from an
+            // intermittent wrong answer into a DETERMINISTIC errno 1054 — for legal SQL that every ORM
+            // emits for a computed sort key.
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url, clicks) VALUES ('a', 'https://a.test', 3), ('b', 'https://b.test', 1)");
+            const byAlias = await q('SELECT `key`, clicks AS c FROM Link ORDER BY c');
+            const computed = await q('SELECT `key`, clicks * -1 AS neg FROM Link ORDER BY neg DESC');
+            // An alias that shadows a real column WINS in ORDER BY: MySQL 8 manual, SELECT, "MySQL
+            // resolves an unqualified column or alias reference in an ORDER BY clause by searching in the
+            // select_expr values, then in the columns of the tables in the FROM clause" (GROUP BY is the
+            // reverse). So this sorts by url.
+            const shadowed = await q('SELECT `key`, url AS clicks FROM Link ORDER BY clicks');
+            // …and an unknown name is still errno 1054, so the fix did not disable the guard.
+            const unknown = await q('SELECT `key` AS c FROM Link ORDER BY nosuch');
+            return byAlias.rows.map((r) => r[0]).join(',') === 'b,a'
+                && computed.rows.map((r) => r[0]).join(',') === 'b,a'
+                && shadowed.rows.map((r) => r[0]).join(',') === 'a,b'
+                && failed(unknown, 'INVALID_ARGUMENT', "Unknown column 'nosuch' in 'order clause'");
+        }),
+    },
+    {
+        id: 'planetscale.update.order_by_decides_which_rows_limit_touches',
+        area: 'update', title: 'UPDATE/DELETE … ORDER BY … LIMIT touches the rows the ORDER BY names',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            // §9 ROUND TWO, FINDING 12: both statements PARSED their ORDER BY and threw it away, so
+            // `DELETE FROM t ORDER BY created_at LIMIT 1` — the delete-the-oldest idiom — deleted
+            // whichever row came first in the projection instead. Silently ignoring a clause that decides
+            // WHICH row a LIMIT touches is a fabricated success.
+            await q(LINK_DDL);
+            await q("INSERT INTO Link (`key`, url, clicks) VALUES ('mid', 'https://m.test', 20), ('old', 'https://o.test', 10), ('new', 'https://n.test', 30)");
+            const deleted = await q('DELETE FROM Link ORDER BY clicks LIMIT 1');
+            const left = await q('SELECT `key` FROM Link ORDER BY clicks');
+            const updated = await q("UPDATE Link SET url = 'https://touched.test' ORDER BY clicks DESC LIMIT 1");
+            const touched = await q("SELECT `key` FROM Link WHERE url = 'https://touched.test'");
+            // An unknown column in the ORDER BY must be errno 1054 here too — it used to be swallowed.
+            const unknown = await q('DELETE FROM Link ORDER BY nosuch LIMIT 1');
+            return deleted.rowsAffected === 1 && left.rows.map((r) => r[0]).join(',') === 'mid,new'
+                && updated.rowsAffected === 1 && touched.rows[0][0] === 'new'
+                && failed(unknown, 'INVALID_ARGUMENT', "Unknown column 'nosuch' in 'order clause'");
+        }),
+    },
+    {
+        id: 'planetscale.errors.internal_faults_stay_on_the_protocol',
+        area: 'errors', title: 'an internal fault answers a Connect-shaped error, never an escaped exception',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            // §9 ROUND TWO, FINDING 11: anything that was not a `SqlError` was RE-THROWN out of the
+            // handler — the same door round one's finding 3 came through, fixed there at the one site it
+            // was found rather than as a class. A deeply-nested expression still walked out of it as a
+            // RangeError. The wire must never be the crash surface.
+            const deep = `SELECT ${'('.repeat(6000)}1${')'.repeat(6000)} FROM dual`;
+            const res = await q.raw({ body: JSON.stringify({ query: deep }) });
+            const body = res.body;
+            // A Connect transport envelope — a code and a message, and NOT a fabricated result.
+            const contained = (res.status === 400 || res.status === 500) && typeof body.code === 'string' && body.result === undefined;
+            // …and the twin is still alive afterwards: the fault was request-scoped.
+            const alive = await q('SELECT 1 AS n FROM dual');
+            return contained && ok(alive) && alive.rows[0][0] === '1';
+        }),
+    },
+    {
+        id: 'planetscale.transactions.concurrent_statements_are_serialized',
+        area: 'transactions', title: 'concurrent statements on one root all land, with distinct rows and ordinals',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q, root) => {
+            // §9 ROUND TWO, FINDING 7: the serialization fix had NO test anywhere in the pack, so the
+            // property three documents assert was still unverified. `executeSql` reads the whole
+            // projection (snapshotting the per-subject `_rev` watermarks and the row ids) and writes it
+            // back with `await` points in between, so overlapping requests on one root would compute the
+            // same next `_rev` and the same `nextRowId` from one stale snapshot — and a write would be
+            // swallowed by the kernel's content dedupe or land on another's subject.
+            await q('CREATE TABLE C (id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, n VARCHAR(8) NOT NULL)');
+            const ctx = { root, occurredAt: AT }; // ONE pinned instant, so only the gate can order them
+            await Promise.all(['a', 'b', 'c', 'd', 'e', 'f'].map((n) => executeSql(ctx, `INSERT INTO C (n) VALUES ('${n}')`, null)));
+            const all = await q('SELECT id, n FROM C ORDER BY id');
+            const rowids = (readDatabase(root).rows.get('c') ?? []).map((r) => r.rowid);
+            return all.rows.length === 6
+                && all.rows.map((r) => r[1]).sort().join(',') === 'a,b,c,d,e,f'
+                && all.rows.map((r) => r[0]).join(',') === '1,2,3,4,5,6' // six DISTINCT auto ids
+                && new Set(rowids).size === 6; // …and six distinct subjects
+        }),
+    },
+    {
+        id: 'planetscale.connector.pull_keeps_duplicate_rows_distinct',
+        area: 'connector', title: 'a keyless table’s DUPLICATE rows stay distinct subjects',
+        dimension: 'connector', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q, root) => {
+            // §9 ROUND TWO, FINDING 6 — the third regression from round one's fix, and the sharpest,
+            // because it was CERTAIN rather than probabilistic: MySQL permits duplicate rows in a keyless
+            // table, and hashing the row's identity folded them into ONE twin subject every time. The
+            // scheme round one replaced handled this correctly. An ordinal now disambiguates them.
+            const ledger = join(root, 'rate-budget.json');
+            const { client } = fakeClient({
+                'SHOW TABLES': { rows: [{ t: 'Keyless' }] },
+                'DESCRIBE `Keyless`': describeRows([['a', 'varchar(8)', 'YES', '', null, ''], ['b', 'varchar(8)', 'YES', '', null, '']]),
+                'SELECT * FROM `Keyless` LIMIT 500': { rows: [{ a: '1', b: 'x' }, { a: '1', b: 'x' }, { a: '2', b: 'y' }] },
+            });
+            const pulled = await syncPlanetscaleFromReal(client, { root, occurredAt: AT, budgetOptions: { path: ledger } });
+            const served = await q('SELECT a, b FROM Keyless');
+            const subjects = new Set((readDatabase(root).rows.get('keyless') ?? []).map((r) => r.rowid));
+            // THREE real rows, THREE subjects, THREE rows served — not two.
+            return pulled.observed === 4 && served.rows.length === 3 && subjects.size === 3
+                && served.rows.map((r) => r.join(':')).sort().join(',') === '1:x,1:x,2:y';
+        }),
+    },
+    // ── connector ───────────────────────────────────────────────────────────────────────────────
+    {
+        id: 'planetscale.connector.pull_tables',
+        area: 'connector', title: 'the connector discovers the real database\'s tables with SHOW TABLES',
+        dimension: 'connector', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            const { client, calls } = fakeClient({
+                'SHOW TABLES': { rows: [{ Tables_in_shop: 'Link' }, { Tables_in_shop: 'Domain' }] },
+            });
+            const names = await pullPlanetscaleTables(client, { budgetOptions: { path: join(q.root, 'rate-budget.json') } });
+            return names.join(',') === 'Link,Domain' && calls.join(',') === 'SHOW TABLES';
+        }),
+    },
+    {
+        id: 'planetscale.connector.pull_schema_and_rows',
+        area: 'connector', title: 'a pull folds the real schema AND its rows into the twin, which then serves them',
+        dimension: 'connector', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q, root) => {
+            const { client } = fakeClient({
+                'SHOW TABLES': { rows: [{ Tables_in_shop: 'Link' }] },
+                'DESCRIBE `Link`': describeRows([
+                    ['id', 'bigint', 'NO', 'PRI', null, 'auto_increment'],
+                    ['key', 'varchar(255)', 'NO', 'UNI', null, ''],
+                    ['url', 'text', 'NO', '', null, ''],
+                    ['clicks', 'int', 'NO', '', '0', ''],
+                ]),
+                // The rows are shaped as the REAL client emits them: already cast (INT64 → string,
+                // INT32 → number), keyed by column name.
+                'SELECT * FROM `Link` ORDER BY `id` LIMIT 500': { rows: [
+                        { id: '7', key: 'dub', url: 'https://dub.co', clicks: 12 },
+                        { id: '9', key: 'ref', url: 'https://ref.test', clicks: 0 },
+                    ] },
+            });
+            const ledger = join(q.root, 'rate-budget.json');
+            const pulled = await syncPlanetscaleFromReal(client, { root, occurredAt: AT, budgetOptions: { path: ledger } });
+            // Proven THROUGH THE TWIN, not by inspecting the connector's return value: the pulled state
+            // must be served by the real handler, or the pull folded into nothing.
+            const served = await q('SELECT id, `key`, url, clicks FROM Link ORDER BY id');
+            const described = await q('DESCRIBE Link');
+            // …and a local INSERT must NOT collide with the pulled id 9 — the "create after pull" class.
+            const minted = await q("INSERT INTO Link (`key`, url) VALUES ('new', 'https://new.test')");
+            return pulled.observed === 3 && pulled.deltasAppended === 3
+                && served.rows.map((r) => r.join(':')).join(',') === '7:dub:https://dub.co:12,9:ref:https://ref.test:0'
+                && served.fields[0].type === 'INT64' && served.fields[3].type === 'INT32'
+                && described.rows.length === 4
+                && minted.insertId === '10';
+        }),
+    },
+    {
+        id: 'planetscale.connector.pull_after_local_create',
+        area: 'connector', title: 'a SECOND pull never lands on a locally-created row, and never loses a new real one',
+        dimension: 'connector', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q, root) => {
+            // §9 ROUND ONE, FINDING 6 — reproduced end-to-end by the reviewer. The pull used to assign
+            // `rowid = i + 1`, POSITIONALLY over an unordered SELECT and into the SAME namespace
+            // `nextRowId` mints from. Pull 1 -> rowids 1,2. A local INSERT -> 3. Pull 2, now returning a
+            // third real row, positionally assigned it 3 as well — so it landed on the LOCAL row's
+            // subject, the real row was SILENTLY DROPPED, and syncPull reported deltas that changed
+            // nothing. Pulled ids are now derived from the real row's identity, in a disjoint band.
+            const ledger = join(root, 'rate-budget.json');
+            const describe = describeRows([
+                ['id', 'bigint', 'NO', 'PRI', null, 'auto_increment'],
+                ['key', 'varchar(255)', 'NO', 'UNI', null, ''],
+            ]);
+            const first = fakeClient({
+                'SHOW TABLES': { rows: [{ t: 'Link' }] },
+                'DESCRIBE `Link`': describe,
+                'SELECT * FROM `Link` ORDER BY `id` LIMIT 500': { rows: [{ id: '7', key: 'a' }, { id: '9', key: 'b' }] },
+            });
+            await syncPlanetscaleFromReal(first.client, { root, occurredAt: AT, budgetOptions: { path: ledger } });
+            // The pulled schema is (id, key) — the DESCRIBE fixture above — so the local insert names
+            // only those columns; naming a column the pulled schema lacks would be errno 1054.
+            const minted = await q("INSERT INTO Link (`key`) VALUES ('LOCAL')");
+            // The real database has since gained a THIRD row. The old bug lost it here.
+            const second = fakeClient({
+                'SHOW TABLES': { rows: [{ t: 'Link' }] },
+                'DESCRIBE `Link`': describe,
+                'SELECT * FROM `Link` ORDER BY `id` LIMIT 500': { rows: [{ id: '7', key: 'a' }, { id: '9', key: 'b' }, { id: '11', key: 'c' }] },
+            });
+            const result = await syncPlanetscaleFromReal(second.client, { root, occurredAt: laterAt(1000), budgetOptions: { path: ledger } });
+            const all = await q('SELECT `key` FROM Link ORDER BY id');
+            const keys = all.rows.map((r) => r[0]).join(',');
+            // ALL FOUR rows survive: the two originally pulled, the LOCAL one, and the newly-observed 'c'.
+            // A pull that REORDERS its rows must also change nothing — identity, not position.
+            const reordered = fakeClient({
+                'SHOW TABLES': { rows: [{ t: 'Link' }] },
+                'DESCRIBE `Link`': describe,
+                'SELECT * FROM `Link` ORDER BY `id` LIMIT 500': { rows: [{ id: '11', key: 'c' }, { id: '7', key: 'a' }, { id: '9', key: 'b' }] },
+            });
+            const third = await syncPlanetscaleFromReal(reordered.client, { root, occurredAt: laterAt(2000), budgetOptions: { path: ledger } });
+            const stable = await q('SELECT `key` FROM Link ORDER BY id');
+            // Keyed local rows and observations now share semantic identity. Four distinct keys must
+            // remain four subjects, and each must have the identity a subsequent refresh will derive.
+            const projected = readDatabase(root).rows.get('link') ?? [];
+            return projected.length === 4 && new Set(projected.map(r => r.rowid)).size === 4
+                && projected.every(r => r.rowid === keyedRowId({ name: 'Link', primaryKey: ['id'] }, r.cells))
+                && minted.insertId === '10'
+                && keys === 'a,b,LOCAL,c'
+                && result.deltasAppended > 0 // the newly-observed real row really landed
+                && third.deltasAppended === 0 // a REORDERED pull of identical state appends nothing
+                && stable.rows.map((r) => r[0]).join(',') === 'a,b,LOCAL,c';
+        }),
+    },
+    {
+        id: 'planetscale.connector.pull_idempotent',
+        area: 'connector', title: 're-pulling identical state appends ZERO deltas',
+        dimension: 'connector', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q, root) => {
+            const script = {
+                'SHOW TABLES': { rows: [{ t: 'Link' }] },
+                'DESCRIBE `Link`': describeRows([['id', 'bigint', 'NO', 'PRI', null, 'auto_increment'], ['key', 'varchar(255)', 'NO', 'UNI', null, '']]),
+                'SELECT * FROM `Link` ORDER BY `id` LIMIT 500': { rows: [{ id: '1', key: 'a' }] },
+            };
+            const ledger = join(q.root, 'rate-budget.json');
+            const { client } = fakeClient(script);
+            const first = await syncPlanetscaleFromReal(client, { root, occurredAt: AT, budgetOptions: { path: ledger } });
+            // A LATER instant, deliberately: a second pull at a different time must still append nothing,
+            // which is what proves the dedup is over CONTENT rather than an artefact of a pinned clock.
+            const second = await syncPlanetscaleFromReal(client, { root, occurredAt: laterAt(60_000), budgetOptions: { path: ledger } });
+            const served = await q('SELECT `key` FROM Link');
+            const updated = await q("UPDATE Link SET `key` = 'LOCAL' WHERE id = 1");
+            const third = await syncPlanetscaleFromReal(client, { root, occurredAt: laterAt(120_000), budgetOptions: { path: ledger } });
+            const fourth = await syncPlanetscaleFromReal(client, { root, occurredAt: laterAt(180_000), budgetOptions: { path: ledger } });
+            const local = await q('SELECT `key` FROM Link');
+            return first.deltasAppended === 2 && second.observed === 2 && second.deltasAppended === 0
+                && served.rows[0][0] === 'a' && updated.rowsAffected === 1
+                && third.deltasAppended === 0 && fourth.deltasAppended === 0
+                && local.rows[0][0] === 'LOCAL';
+        }),
+    },
+    {
+        id: 'planetscale.connector.pull_row_limit',
+        area: 'connector', title: 'the pull ALWAYS bounds rows read — the LIMIT is in the statement, never optional',
+        dimension: 'connector', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            const describe = describeRows([['id', 'bigint', 'NO', 'PRI', null, 'auto_increment']]);
+            const ledger = join(q.root, 'rate-budget.json');
+            const { client, calls } = fakeClient({
+                'SHOW TABLES': { rows: [{ t: 'Link' }] },
+                'DESCRIBE `Link`': describe,
+                'SELECT * FROM `Link` ORDER BY `id` LIMIT 500': { rows: [{ id: '1' }] },
+                'SELECT * FROM `Link` ORDER BY `id` LIMIT 3': { rows: [{ id: '1' }] },
+            });
+            await pullPlanetscaleDatabase(client, { budgetOptions: { path: ledger } });
+            await pullPlanetscaleDatabase(client, { rowLimit: 3, budgetOptions: { path: ledger } });
+            // PlanetScale meters ROWS READ, so an unbounded `SELECT *` is the expensive mistake this
+            // guards. Both the default and the caller's limit must appear IN THE STATEMENT.
+            return calls.includes('SELECT * FROM `Link` ORDER BY `id` LIMIT 500') && calls.includes('SELECT * FROM `Link` ORDER BY `id` LIMIT 3')
+                && !calls.some((c) => c.startsWith('SELECT * FROM `Link`') && !c.includes('LIMIT'));
+        }),
+    },
+    {
+        id: 'planetscale.connector.pull_skips_a_vanished_table',
+        area: 'connector', title: 'a failed schema read aborts the refresh without observing a partial database',
+        dimension: 'connector', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q, root) => {
+            const ledger = join(q.root, 'rate-budget.json');
+            // First pull: two tables, both readable.
+            const full = fakeClient({
+                'SHOW TABLES': { rows: [{ t: 'Link' }, { t: 'Domain' }] },
+                'DESCRIBE `Link`': describeRows([['id', 'bigint', 'NO', 'PRI', null, 'auto_increment'], ['key', 'varchar(255)', 'NO', 'UNI', null, '']]),
+                'DESCRIBE `Domain`': describeRows([['id', 'bigint', 'NO', 'PRI', null, 'auto_increment'], ['slug', 'varchar(255)', 'NO', 'UNI', null, '']]),
+                'SELECT * FROM `Link` ORDER BY `id` LIMIT 500': { rows: [{ id: '1', key: 'a' }] },
+                'SELECT * FROM `Domain` ORDER BY `id` LIMIT 500': { rows: [{ id: '1', slug: 'dub.sh' }] },
+            });
+            await syncPlanetscaleFromReal(full.client, { root, occurredAt: AT, budgetOptions: { path: ledger } });
+            // Second pull: Domain's DESCRIBE now FAILS (it was dropped between discovery and read).
+            const partial = fakeClient({
+                'SHOW TABLES': { rows: [{ t: 'Link' }, { t: 'Domain' }] },
+                'DESCRIBE `Link`': describeRows([['id', 'bigint', 'NO', 'PRI', null, 'auto_increment'], ['key', 'varchar(255)', 'NO', 'UNI', null, '']]),
+                'SELECT * FROM `Link` ORDER BY `id` LIMIT 500': { rows: [{ id: '1', key: 'a' }] },
+            }, { fail: new Set(['DESCRIBE `Domain`']) });
+            let failed = false;
+            try {
+                await syncPlanetscaleFromReal(partial.client, { root, occurredAt: laterAt(1000), budgetOptions: { path: ledger } });
+            }
+            catch {
+                failed = true;
+            }
+            // The vanished table must be left ALONE — recording it as an empty account would let a later
+            // push delete a real table's rows.
+            const domain = await q('SELECT slug FROM Domain');
+            return failed && domain.rows[0][0] === 'dub.sh';
+        }),
+    },
+    {
+        id: 'planetscale.connector.pull_refuses_a_failed_query',
+        area: 'connector', title: 'a refused SELECT throws — it is never mapped to an empty result set',
+        dimension: 'connector', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q, root) => {
+            const ledger = join(q.root, 'rate-budget.json');
+            const good = fakeClient({
+                'SHOW TABLES': { rows: [{ t: 'Link' }] },
+                'DESCRIBE `Link`': describeRows([['id', 'bigint', 'NO', 'PRI', null, 'auto_increment'], ['key', 'varchar(255)', 'NO', 'UNI', null, '']]),
+                'SELECT * FROM `Link` ORDER BY `id` LIMIT 500': { rows: [{ id: '1', key: 'a' }] },
+            });
+            await syncPlanetscaleFromReal(good.client, { root, occurredAt: AT, budgetOptions: { path: ledger } });
+            const broken = fakeClient({
+                'SHOW TABLES': { rows: [{ t: 'Link' }] },
+                'DESCRIBE `Link`': describeRows([['id', 'bigint', 'NO', 'PRI', null, 'auto_increment'], ['key', 'varchar(255)', 'NO', 'UNI', null, '']]),
+            }, { fail: new Set(['SELECT * FROM `Link` ORDER BY `id` LIMIT 500']) });
+            let threw = false;
+            try {
+                await syncPlanetscaleFromReal(broken.client, { root, occurredAt: laterAt(1000), budgetOptions: { path: ledger } });
+            }
+            catch {
+                threw = true;
+            }
+            // The refusal must NOT have emptied the twin: a connector that caught it and folded `[]` would
+            // hand syncPull an empty account to fold over real observed state.
+            const survived = await q('SELECT `key` FROM Link');
+            return threw && survived.rows[0][0] === 'a';
+        }),
+    },
+    {
+        id: 'planetscale.connector.map_describe_row',
+        area: 'connector', title: 'mapDescribeRow reads MySQL\'s DESCRIBE output into a faithful ColumnDef',
+        dimension: 'connector', tier: 'common', expected: 'done',
+        verify: () => withRoot(async () => {
+            const auto = mapDescribeRow({ Field: 'id', Type: 'bigint unsigned', Null: 'NO', Key: 'PRI', Default: null, Extra: 'auto_increment' });
+            const withDefault = mapDescribeRow({ Field: 'clicks', Type: 'int', Null: 'NO', Key: '', Default: '0', Extra: '' });
+            const nullable = mapDescribeRow({ Field: 'archived', Type: 'tinyint(1)', Null: 'YES', Key: '', Default: null, Extra: '' });
+            const unique = mapDescribeRow({ Field: 'slug', Type: 'varchar(191)', Null: 'NO', Key: 'UNI', Default: null, Extra: '' });
+            // The distinction that matters: `id` has NO default (errno 1364 territory) while `archived`
+            // defaults to NULL. Flattening both to `null` loses a real MySQL behaviour.
+            return auto.dataType === 'BIGINT' && auto.unsigned && auto.primaryKey && auto.autoIncrement
+                && !auto.nullable && auto.defaultValue === undefined && auto.columnType === 'bigint unsigned'
+                && withDefault.defaultValue === '0' && withDefault.length === null
+                && nullable.nullable && nullable.defaultValue === null && nullable.length === 1
+                && unique.unique && !unique.primaryKey && unique.length === 191;
+        }),
+    },
+    {
+        id: 'planetscale.connector.identity_collision_refusal',
+        area: 'connector', title: 'hash collisions are refused before local row loss or pull observation',
+        dimension: 'connector', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q, root) => {
+            const keys = ['customer-2479052881', 'customer-2205617487'];
+            await q('CREATE TABLE notes (id VARCHAR(64) PRIMARY KEY)');
+            const inserted = await q(`INSERT INTO notes VALUES ('${keys[0]}'),('${keys[1]}')`);
+            if (!inserted.error?.message.includes('row identity hash collision') || (await q('SELECT * FROM notes')).rows.length !== 0)
+                return false;
+            const remote = (ids) => fakeClient({
+                'SHOW TABLES': { rows: [{ Tables_in_twin: 'notes' }] },
+                'DESCRIBE `notes`': { rows: [{ Field: 'id', Type: 'varchar(64)', Null: 'NO', Key: 'PRI', Default: null, Extra: '' }] },
+                'SELECT * FROM `notes` ORDER BY `id` LIMIT 500': { rows: ids.map(id => ({ id })) },
+            }).client;
+            const pull = (root, ids) => syncPlanetscaleFromReal(remote(ids), { root, budgetOptions: { path: join(root, 'collision-budget') } });
+            const refuses = async (root, ids) => { try {
+                await pull(root, ids);
+                return false;
+            }
+            catch (e) {
+                return String(e).includes('row identity hash collision');
+            } };
+            if (!await refuses(root, keys) || (await q('SELECT * FROM notes')).rows.length !== 0)
+                return false;
+            await q(`INSERT INTO notes VALUES ('${keys[0]}')`);
+            if (!await refuses(root, [keys[1]]) || (await q('SELECT id FROM notes')).rows[0]?.[0] !== keys[0])
+                return false;
+            return withRoot(async (q2, root2) => {
+                await pull(root2, [keys[0]]);
+                if (!await refuses(root2, [keys[1]]) || (await q2('SELECT id FROM notes')).rows[0]?.[0] !== keys[0])
+                    return false;
+                await q2('DELETE FROM notes');
+                // The local tombstone must not hide an upstream collision from the next observation.
+                return await refuses(root2, [keys[1]]) && (await q2('SELECT * FROM notes')).rows.length === 0;
+            });
+        }),
+    },
+    {
+        id: 'planetscale.connector.exact_beforeimages',
+        area: 'connector', title: 'captured beforeimages compare bytes with CAST AS BINARY, including case and trailing spaces',
+        dimension: 'connector', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q, root) => {
+            await q('CREATE TABLE notes (id INT PRIMARY KEY, label VARCHAR(64), n INT)');
+            await q("INSERT INTO notes VALUES (1,'a',10)");
+            await q('UPDATE notes SET n=11');
+            const calls = [];
+            const tx = { execute: async (sql) => { calls.push(sql); return { rows: [], rowsAffected: 1 }; } };
+            await applyPlanetscaleRows({ ...tx, transaction: async (fn) => fn(tx) }, deployableEntries('planetscale', root).at(-1).input?.plan, { budgetOptions: { path: join(root, 'binary-budget') } });
+            const cast = await q("SELECT CAST('a' AS BINARY) = CAST('A' AS BINARY) AS c, CAST('a' AS BINARY) = CAST('a ' AS BINARY) AS s, CAST('日' AS BINARY) = X'e697a5' AS u, CAST('日' AS BINARY) = X'e69c88' AS different, CAST('01' AS BINARY) = X'31' AS digits FROM dual");
+            return calls.length === 1 && calls[0].includes("CAST(`label` AS BINARY) = CAST('a' AS BINARY)")
+                && JSON.stringify(cast.rows) === JSON.stringify([['0', '0', '1', '0', '0']]);
+        }),
+    },
+    {
+        id: 'planetscale.connector.complete_plan_budget',
+        area: 'connector', title: 'known row fanout reserves its full call cost before the transaction begins',
+        dimension: 'connector', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q, root) => {
+            await q('CREATE TABLE notes (id INT PRIMARY KEY)');
+            await q(`INSERT INTO notes VALUES ${Array.from({ length: 27 }, (_, i) => `(${i})`).join(',')}`);
+            let calls = 0;
+            const tx = { execute: async () => { calls++; return { rows: [], rowsAffected: 1 }; } };
+            const client = { ...tx, transaction: async (fn) => { calls++; return fn(tx); } };
+            try {
+                await applyPlanetscaleRows(client, deployableEntries('planetscale', root).at(-1).input?.plan, { budgetOptions: { path: join(root, 'batch-budget') } });
+                return false;
+            }
+            catch (e) {
+                return String(e).includes('budget') && calls === 0;
+            }
+        }),
+    },
+    {
+        id: 'planetscale.connector.executor_cooldown',
+        area: 'connector', title: 'executor throttling preserves status and headers even when the body is not JSON',
+        dimension: 'connector', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q, root) => {
+            await q('CREATE TABLE notes (id INT PRIMARY KEY)');
+            await q('INSERT INTO notes VALUES (1)');
+            const plan = deployableEntries('planetscale', root).at(-1).input?.plan;
+            for (const mode of ['text', 'rollback']) {
+                let calls = 0;
+                const execute = async (req) => {
+                    calls++;
+                    if (mode === 'rollback' && req.path.endsWith('CreateSession'))
+                        return { status: 200, headers: {}, body: '{"session":{"id":"s"}}' };
+                    if (mode === 'rollback' && JSON.parse(String(req.body)).query === 'BEGIN')
+                        return { status: 200, headers: {}, body: '{"result":{}}' };
+                    return { status: 429, headers: { 'retry-after': '60' }, body: 'slow down' };
+                };
+                const opts = { budgetOptions: { path: join(root, `cooldown-budget-${mode}`) } };
+                let failures = 0;
+                for (let i = 0; i < 2; i++)
+                    try {
+                        await applyPlanetscaleRows(planetscaleClientOver(execute), plan, opts);
+                    }
+                    catch {
+                        failures++;
+                    }
+                if (failures !== 2 || calls !== (mode === 'text' ? 1 : 4))
+                    return false;
+            }
+            return true;
+        }),
+    },
+    {
+        id: 'planetscale.connector.key_representation',
+        area: 'connector', title: 'a noncanonical integer key deploys as the integer MySQL stored, never under its captured spelling',
+        dimension: 'connector', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q, root) => {
+            // MySQL converts the string '01' assigned to an INT column to the integer 1 (MySQL 8.0
+            // Reference Manual §12.3, Type Conversion in Expression Evaluation), so the captured row image is `1`.
+            await q('CREATE TABLE notes (id INT PRIMARY KEY)');
+            await q("INSERT INTO notes VALUES ('01')");
+            const calls = [];
+            const tx = { execute: async (sql) => { calls.push(sql); return { rows: [], rowsAffected: 1 }; } };
+            await applyPlanetscaleRows({ ...tx, transaction: async (fn) => fn(tx) }, deployableEntries('planetscale', root).at(-1).input?.plan, { budgetOptions: { path: join(root, 'representation-budget') } });
+            return JSON.stringify(calls) === JSON.stringify(["INSERT INTO `notes` (`id`) VALUES ('1')"])
+                && JSON.stringify((await q('SELECT id FROM notes')).rows) === '[["1"]]';
+        }),
+    },
+    {
+        id: 'planetscale.connector.special_key_representation',
+        area: 'connector', title: 'an AUTO_INCREMENT zero key deploys the generated value; a ZEROFILL key cannot silently acquire another identity',
+        dimension: 'connector', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q, root) => {
+            // Inserting 0 into an AUTO_INCREMENT column generates the next sequence value unless
+            // NO_AUTO_VALUE_ON_ZERO is set (MySQL 8.0 Reference Manual §3.6.9, Using AUTO_INCREMENT), so the captured
+            // key is the generated 1 and that is what deploys.
+            await q('CREATE TABLE notes (id INT PRIMARY KEY AUTO_INCREMENT)');
+            await q('INSERT INTO notes VALUES (0)');
+            const calls = [];
+            const generated = { execute: async (sql) => { calls.push(sql); return { rows: [], rowsAffected: 1 }; } };
+            await applyPlanetscaleRows({ ...generated, transaction: async (fn) => fn(generated) }, deployableEntries('planetscale', root).at(-1).input?.plan, { budgetOptions: { path: join(root, 'key-budget') } });
+            if (JSON.stringify(calls) !== JSON.stringify(["INSERT INTO `notes` (`id`) VALUES ('1')"]))
+                return false;
+            const tx = { execute: async () => { throw new Error('unexpected vendor call'); } };
+            const refuse = async (root) => {
+                try {
+                    await applyPlanetscaleRows({ ...tx, transaction: async (fn) => fn(tx) }, deployableEntries('planetscale', root).at(-1).input?.plan, { budgetOptions: { path: join(root, 'key-budget') } });
+                    return false;
+                }
+                catch (e) {
+                    return String(e).includes('primary-key representation');
+                }
+            };
+            return withRoot(async (q2, root2) => {
+                const { client } = fakeClient({ 'SHOW TABLES': { rows: [{ Tables_in_twin: 'notes' }] },
+                    'DESCRIBE `notes`': { rows: [{ Field: 'id', Type: 'int(4) unsigned zerofill', Null: 'NO', Key: 'PRI', Default: null, Extra: '' }] },
+                    'SELECT * FROM `notes` ORDER BY `id` LIMIT 500': { rows: [] } });
+                await syncPlanetscaleFromReal(client, { root: root2, budgetOptions: { path: join(root2, 'pull-budget') } });
+                await q2('INSERT INTO notes VALUES (5)');
+                return refuse(root2);
+            });
+        }),
+    },
+    {
+        id: 'planetscale.insert.upsert_constraint_recheck',
+        area: 'insert', title: 'upsert assignments cannot violate another primary or unique key or erase the occupied row',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            await q('CREATE TABLE notes (id INT PRIMARY KEY, label VARCHAR(64) UNIQUE, n INT)');
+            await q("INSERT INTO notes VALUES (1,'a',10),(2,'b',20)");
+            const primary = await q("INSERT INTO notes VALUES (3,'a',30) ON DUPLICATE KEY UPDATE id=2");
+            const unique = await q("INSERT INTO notes VALUES (1,'c',30) ON DUPLICATE KEY UPDATE label='b'");
+            return failed(primary, 'ALREADY_EXISTS', 'Duplicate entry') && failed(unique, 'ALREADY_EXISTS', 'Duplicate entry')
+                && JSON.stringify((await q('SELECT * FROM notes ORDER BY id')).rows) === JSON.stringify([['1', 'a', '10'], ['2', 'b', '20']]);
+        }),
+    },
+    {
+        id: 'planetscale.connector.storage_conversion',
+        area: 'connector', title: 'rounding, padding and AUTO_INCREMENT generation deploy the value MySQL stored; floating point refuses the entire plan before IO',
+        dimension: 'connector', tier: 'core', expected: 'done',
+        verify: async () => {
+            // The stored representations, per the MySQL 8.0 Reference Manual: a zero (after conversion) in an
+            // AUTO_INCREMENT column generates the next value (§3.6.9); a string assigned to INT is rounded,
+            // half away from zero (§12.25.4, Rounding Behavior); DECIMAL(4,2) rounds to its scale (§11.1.3);
+            // CHAR drops trailing spaces on retrieval (§11.3.2); BINARY(n) right-pads with 0x00 (§11.3.3).
+            for (const [type, value, next, stored] of [['INT UNIQUE AUTO_INCREMENT', '0', '4', "'1'"], ['INT UNIQUE AUTO_INCREMENT', "'00'", '4', "'1'"], ['INT UNIQUE AUTO_INCREMENT', "'0.0'", '4', "'1'"], ['INT UNIQUE AUTO_INCREMENT', "'-0'", '4', "'1'"], ['INT', "'2.5'", '4', "'3'"], ['DECIMAL(4,2)', "'1.235'", '2', "'1.24'"], ['CHAR(4)', "'a '", "'b'", "'a'"], ['BINARY(4)', "X'61'", "X'62626262'", "X'61000000'"]]) {
+                if (!await withRoot(async (q, root) => {
+                    await q(`CREATE TABLE notes (id INT PRIMARY KEY, n ${type})`);
+                    await q('BEGIN');
+                    await q(`INSERT INTO notes VALUES (1,${value})`);
+                    await q(`UPDATE notes SET n=${next} WHERE id=1`);
+                    await q('COMMIT');
+                    const calls = [];
+                    const tx = { execute: async (sql) => { calls.push(sql); return { rows: [], rowsAffected: 1 }; } };
+                    await applyPlanetscaleRows({ ...tx, transaction: async (fn) => fn(tx) }, deployableEntries('planetscale', root).at(-1).input?.plan, { budgetOptions: { path: join(root, 'conversion-budget') } });
+                    return calls.length === 2 && calls[0] === `INSERT INTO \`notes\` (\`id\`, \`n\`) VALUES ('1', ${stored})`;
+                }))
+                    return false;
+            }
+            // FLOAT's stored single-precision value has no vendor-faithful codec here: the plan refuses.
+            return withRoot(async (q, root) => {
+                await q('CREATE TABLE notes (id INT PRIMARY KEY, n FLOAT)');
+                await q('BEGIN');
+                await q('INSERT INTO notes VALUES (1,0.1)');
+                await q('UPDATE notes SET n=0.2 WHERE id=1');
+                await q('COMMIT');
+                let calls = 0;
+                const tx = { execute: async () => { calls++; return { rows: [], rowsAffected: 1 }; } };
+                try {
+                    await applyPlanetscaleRows({ ...tx, transaction: async (fn) => fn(tx) }, deployableEntries('planetscale', root).at(-1).input?.plan, { budgetOptions: { path: join(root, 'conversion-budget') } });
+                    return false;
+                }
+                catch (e) {
+                    return String(e).includes('Unsupported stored representation') && calls === 0;
+                }
+            });
+        },
+    },
+    {
+        id: 'planetscale.connector.numeric_beforeimages',
+        area: 'connector', title: 'numeric guards accept normalized values without DOUBLE coercion of adjacent BIGINTs',
+        dimension: 'connector', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q, root) => {
+            await q('CREATE TABLE notes (id INT PRIMARY KEY, n BIGINT)');
+            await q('BEGIN');
+            await q("INSERT INTO notes VALUES (1,'01')");
+            await q('UPDATE notes SET n=2');
+            await q('COMMIT');
+            const calls = [];
+            const tx = { execute: async (sql) => { calls.push(sql); return { rows: [], rowsAffected: 1 }; } };
+            const client = { ...tx, transaction: async (fn) => fn(tx) };
+            await applyPlanetscaleRows(client, deployableEntries('planetscale', root).at(-1).input?.plan, { budgetOptions: { path: join(root, 'numeric-budget') } });
+            // '01' is stored as the BIGINT 1 (MySQL 8.0 Reference Manual §12.3); the guard is that exact, unquoted integer.
+            if (!calls[1]?.endsWith('WHERE `id` = 1 AND `n` = 1 LIMIT 1'))
+                return false;
+            await q("INSERT INTO notes VALUES (2,'9007199254740992')");
+            await q('UPDATE notes SET n=7 WHERE id=2');
+            calls.length = 0;
+            await applyPlanetscaleRows(client, deployableEntries('planetscale', root).at(-1).input?.plan, { budgetOptions: { path: join(root, 'numeric-budget') } });
+            // This exact unquoted literal keeps MySQL's integer comparison exact above 2^53.
+            return calls.length === 1 && calls[0].includes('WHERE `id` = 2 AND `n` = 9007199254740992 LIMIT 1');
+        }),
+    },
+    {
+        id: 'planetscale.connector.captured_transaction',
+        area: 'connector', title: 'one committed action carries ordered row effects; rollback and sessions never deploy',
+        dimension: 'connector', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q, root) => {
+            await q('CREATE TABLE notes (id INT PRIMARY KEY, n INT)');
+            const baseline = deployableEntries('planetscale', root).length;
+            await q('BEGIN');
+            await q('INSERT INTO notes VALUES (9,9)');
+            await q('ROLLBACK');
+            if (deployableEntries('planetscale', root).length !== baseline)
+                return false;
+            await q('BEGIN');
+            await q('INSERT INTO notes VALUES (1,10),(2,20)');
+            await q('UPDATE notes SET n=n+1 ORDER BY id');
+            await q('DELETE FROM notes WHERE id=2');
+            await q('COMMIT');
+            const entries = deployableEntries('planetscale', root);
+            if (entries.length !== baseline + 1)
+                throw new Error(`captured count ${entries.length}/${baseline}`);
+            const action = entries.at(-1);
+            const calls = [];
+            let transactions = 0;
+            const tx = { execute: async (sql) => { calls.push(sql); return { rows: [], rowsAffected: 1 }; } };
+            await applyPlanetscaleRows({ ...tx, transaction: async (fn) => { transactions++; return fn(tx); } }, action.input?.plan, { budgetOptions: { path: join(root, 'captured-budget') } });
+            return transactions === 1 && calls.length === 5 && calls[0].startsWith('INSERT')
+                && calls[2].includes("`n` = 10") && calls[4].startsWith('DELETE')
+                && calls[4].includes("`n` = 21") && (await q('SELECT * FROM notes')).rows.length === 1;
+        }),
+    },
+    {
+        id: 'planetscale.connector.push_row',
+        area: 'connector', title: 'push inserts a captured keyed row without overwriting a conflict and confirms the action',
+        dimension: 'connector', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q, root) => {
+            await q('CREATE TABLE Link (`key` VARCHAR(64) PRIMARY KEY, url VARCHAR(255))');
+            await q("INSERT INTO Link VALUES ('o\\'brien', 'https://x.test')");
+            const action = deployableEntries('planetscale', root).at(-1);
+            const ledger = join(root, 'rate-budget.json');
+            const expected = "INSERT INTO `Link` (`key`, `url`) VALUES ('o\\'brien', 'https://x.test')";
+            const { client, calls } = fakeClient({ [expected]: { rows: [], rowsAffected: 1 } });
+            const res = await pushPlanetscaleAction(client, { ...action, subjectType: action.subject.type, subjectId: action.subject.id }, { root, occurredAt: AT, budgetOptions: { path: ledger } });
+            return res.pushed && res.statement === expected && calls.length === 1 && calls[0] === expected
+                && !deployableEntries('planetscale', root).some(e => e.id === action.id)
+                && parentEntries('planetscale', root).some(e => e.landsId === action.id && e.receipt?.status === 'deployed');
+        }),
+    },
+    {
+        id: 'planetscale.connector.push_delete_and_refusals',
+        area: 'connector', title: 'push issues a bounded DELETE and refuses entries without captured plans',
+        dimension: 'connector', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (_q, root) => {
+            const ledger = join(root, 'rate-budget.json');
+            const expected = "DELETE FROM `Link` WHERE CAST(`key` AS BINARY) = CAST('a' AS BINARY) AND CAST(`url` AS BINARY) = CAST('https://a.test' AS BINARY) LIMIT 1";
+            const { client, calls } = fakeClient({ [expected]: { rows: [], rowsAffected: 1 } });
+            const deleted = await pushPlanetscaleAction(client, {
+                id: 'act-2', operation: 'row.delete', subjectType: 'row', subjectId: 'row:link:1',
+                fields: { table_name: 'Link', rowid: 1, cells: { key: 'a', url: 'https://a.test' }, gone: true, _rev: 2 },
+                input: { plan: { version: 1, statements: [], refusals: [], changes: [{ table: 'Link', primaryKey: ['key'], binary: [], before: { key: 'a', url: 'https://a.test' } }] } },
+            }, { root, occurredAt: AT, budgetOptions: { path: ledger } });
+            const refusals = [];
+            for (const action of [
+                { id: 'act-3', operation: 'table.write', subjectType: 'table', subjectId: 'table:link', fields: { name: 'Link' } },
+                { id: 'act-4', operation: 'row.delete', subjectType: 'row', subjectId: 'row:link:2', fields: { table_name: 'Link', rowid: 2, cells: {}, gone: true } },
+            ]) {
+                try {
+                    await pushPlanetscaleAction(client, action, { root, occurredAt: AT, budgetOptions: { path: ledger } });
+                    refusals.push('NOT REFUSED');
+                }
+                catch (e) {
+                    refusals.push(String(e.message));
+                }
+            }
+            // The DELETE carries a LIMIT and a full WHERE — an unqualified DELETE against a real database
+            // is the single most destructive thing this connector could emit, so it is refused by name.
+            return deleted.pushed && calls.length === 1 && calls[0] === expected
+                && refusals[0].includes('no captured row plan')
+                && refusals[1].includes('no captured row plan');
+        }),
+    },
+    {
+        id: 'planetscale.connector.rate_budget_fail_closed',
+        area: 'connector', title: 'the client-side budget refuses past its ceiling with the call count UNCHANGED',
+        dimension: 'connector', tier: 'core', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            const ledger = join(q.root, 'rate-budget.json');
+            let now = 1_800_000_000_000;
+            const calls = [];
+            const raw = {
+                async execute(query) { calls.push(query); return { rows: [] }; },
+            };
+            const budget = new PlanetscaleBudget({ path: ledger, now: () => now });
+            const client = guardPlanetscaleClient(raw, { budget });
+            // LITERALS, not the pack's own constants (§9 round one, finding 18): importing the numbers
+            // the guard is built from makes both sides drift together, so the assertion could never catch
+            // the ceiling being loosened. 60 units / weight 2 = 30 calls per minute — and the declaration
+            // is separately checked against the KERNEL fallback in planetscale-budget.test.ts.
+            const allowed = 30;
+            if (PLANETSCALE_BUDGET_CEILING !== 60 || PLANETSCALE_CALL_WEIGHTS.other !== 2)
+                return false;
+            for (let i = 0; i < allowed; i++)
+                await client.execute('SELECT 1');
+            const before = calls.length;
+            let refused = false;
+            try {
+                await client.execute('SELECT 1');
+            }
+            catch {
+                refused = true;
+            }
+            // "It threw" is not the proof — the COUNT is. An unchanged count is what shows the refusal
+            // happened BEFORE the request, not after it.
+            const after = calls.length;
+            // …and the window really rolls: advancing past it restores the allowance.
+            now += 61_000;
+            await client.execute('SELECT 1');
+            return before === allowed && refused && after === before && calls.length === allowed + 1;
+        }),
+    },
+    {
+        id: 'planetscale.connector.budget_guard_is_unavoidable',
+        area: 'connector', title: 'the guard is idempotent, refuses an impostor budget, and re-guards a derived connection',
+        dimension: 'connector', tier: 'common', expected: 'done',
+        verify: () => withRoot(async (q) => {
+            const ledger = join(q.root, 'rate-budget.json');
+            const calls = [];
+            const inner = { async execute(q) { calls.push(q); return { rows: [] }; } };
+            // A client shaped like the real `Client`: `connection()` hands back a NEW Connection whose
+            // `execute` would otherwise escape the budget entirely.
+            const raw = { ...inner, connection: () => inner };
+            const budget = new PlanetscaleBudget({ path: ledger });
+            const guarded = guardPlanetscaleClient(raw, { budget });
+            const twice = guardPlanetscaleClient(guarded, { budget });
+            let refusedImpostor = false;
+            try {
+                guardPlanetscaleClient(raw, { budget: { checkBudget: () => ({}), weightFor: () => 0, recordCall: () => { } } });
+            }
+            catch {
+                refusedImpostor = true;
+            }
+            const derived = guarded.connection();
+            await derived.execute('SELECT 2');
+            const spentAfterDerived = budget.snapshot().spend;
+            return twice === guarded && refusedImpostor && calls.join(',') === 'SELECT 2'
+                // 2 for `connection()` itself + 2 for the derived `execute`, as a LITERAL 4 (§9 round one,
+                // finding 18) — the derived connection is genuinely behind the same ledger rather than
+                // escaping it, and an unguarded one would spend 2.
+                && spentAfterDerived === 4;
+        }),
+    },
+    {
+        id: 'planetscale.connector.pull_pagination', area: 'connector', dimension: 'connector', tier: 'common', expected: 'done',
+        title: 'bounded keyset pages report completion, preserve composite-key identity and retain partial scans',
+        verify: () => withRoot(async (q, root) => {
+            const schema = describeRows([['tenant', 'varchar(20)', 'NO', 'PRI', null, ''], ['id', 'bigint', 'NO', 'PRI', null, '']]);
+            const script = {
+                'SHOW TABLES': { rows: [{ t: 'items' }] }, 'DESCRIBE `items`': schema,
+                'SELECT * FROM `items` ORDER BY `tenant`, `id` LIMIT 2': { rows: [{ tenant: "a'b", id: '9007199254740992' }, { tenant: "a'b", id: '9007199254740993' }] },
+                "SELECT * FROM `items` WHERE (`tenant` > 'a\\'b') OR (`tenant` = 'a\\'b' AND `id` > 9007199254740993) ORDER BY `tenant`, `id` LIMIT 2": { rows: [{ tenant: 'z', id: '1' }] },
+            };
+            const { client, calls } = fakeClient(script);
+            const opts = { root, rowLimit: 2, budgetOptions: { path: join(root, 'pages-budget') } };
+            const full = await syncPlanetscaleFromReal(client, opts);
+            assert.deepEqual(full.completeTables, ['items']);
+            assert.deepEqual(full.partialTables, []);
+            assert.equal((await q('SELECT * FROM items')).rows.length, 3);
+            assert.equal(calls.filter(c => c.startsWith('SELECT')).length, 2);
+            const partial = await syncPlanetscaleFromReal(client, { ...opts, maxPages: 1 });
+            assert.deepEqual(partial.completeTables, []);
+            assert.deepEqual(partial.partialTables, ['items']);
+            assert.equal(partial.removed, 0);
+            assert.equal((await q('SELECT * FROM items')).rows.length, 3);
+            return true;
+        }),
+    },
+    {
+        id: 'planetscale.connector.pull_row_deletion', area: 'connector', dimension: 'connector', tier: 'common', expected: 'done',
+        title: 'completed reads confirm missing upstream rows, preserve local edits and honor table scope',
+        verify: () => withRoot(async (q, root) => {
+            const schema = describeRows([['id', 'int', 'NO', 'PRI', null, ''], ['label', 'varchar(20)', 'YES', '', null, '']]);
+            const script = {
+                'SHOW TABLES': { rows: [{ t: 'items' }, { t: 'outside' }] },
+                'DESCRIBE `items`': schema, 'DESCRIBE `outside`': schema,
+                'SELECT * FROM `items` ORDER BY `id` LIMIT 500': { rows: [{ id: 1, label: 'delete' }, { id: 2, label: 'edit' }, { id: 3, label: 'stay' }] },
+                'SELECT * FROM `outside` ORDER BY `id` LIMIT 500': { rows: [{ id: 9, label: 'outside' }] },
+                'SELECT * FROM `items` WHERE `id` = 1 LIMIT 2': { rows: [] },
+                'SELECT * FROM `items` WHERE `id` = 2 LIMIT 2': { rows: [] },
+            };
+            const { client, calls } = fakeClient(script);
+            const opts = { root, budgetOptions: { path: join(root, 'delete-budget') } };
+            await syncPlanetscaleFromReal(client, opts);
+            await q("UPDATE items SET label='LOCAL' WHERE id=2");
+            await q("INSERT INTO items VALUES (4,'new-local')");
+            script['SELECT * FROM `items` ORDER BY `id` LIMIT 500'] = { rows: [{ id: 3, label: 'stay' }] };
+            const result = await syncPlanetscaleFromReal(client, { ...opts, tables: ['items'] });
+            assert.equal(result.removed, 2);
+            assert.equal(result.deltasAppended, 2);
+            assert.deepEqual((await q('SELECT id,label FROM items ORDER BY id')).rows, [['2', 'LOCAL'], ['3', 'stay'], ['4', 'new-local']]);
+            assert.equal((await q('SELECT * FROM outside')).rows.length, 1);
+            assert(calls.includes('SELECT * FROM `items` WHERE `id` = 1 LIMIT 2'));
+            assert(!calls.some(c => c.includes('WHERE `id` = 4')));
+            assert.equal((await syncPlanetscaleFromReal(client, { ...opts, tables: ['items'] })).deltasAppended, 0);
+            return true;
+        }),
+    },
+    {
+        id: 'planetscale.connector.refresh_atomicity', area: 'connector', dimension: 'connector', tier: 'core', expected: 'done',
+        title: 'page, schema, budget and absence-check failures append no partial observation',
+        verify: () => withRoot(async (q, root) => {
+            const schema = describeRows([['id', 'int', 'NO', 'PRI', null, ''], ['label', 'varchar(20)', 'YES', '', null, '']]);
+            const initial = fakeClient({ 'SHOW TABLES': { rows: [{ t: 'items' }] }, 'DESCRIBE `items`': schema,
+                'SELECT * FROM `items` ORDER BY `id` LIMIT 500': { rows: [{ id: 1, label: 'old' }, { id: 2, label: 'old' }] } }).client;
+            await syncPlanetscaleFromReal(initial, { root, budgetOptions: { path: join(root, 'initial-budget') } });
+            const before = parentEntries('planetscale', root);
+            const cases = [
+                { 'SELECT * FROM `items` ORDER BY `id` LIMIT 1': { rows: [{ id: 1, label: 'new' }] } }, // next page fails
+                { 'SELECT * FROM `items` ORDER BY `id` LIMIT 500': { rows: [{ id: 1, label: 'new' }] } }, // point lookup fails
+                { 'SELECT * FROM `items` ORDER BY `id` LIMIT 500': { rows: [{ id: 1, label: 'new' }] }, 'SELECT * FROM `items` WHERE `id` = 2 LIMIT 2': { rows: [{ id: 2, label: 'moved' }] } },
+                { 'DESCRIBE `items`': { rows: [] } },
+                { 'SELECT * FROM `items` ORDER BY `id` LIMIT 500': { rows: [{ id: 1 }] } },
+                { 'SHOW TABLES': { rows: [{}] } },
+                { 'DESCRIBE `items`': { rows: [{ Field: 'id', Type: 'int' }] } },
+                { 'SELECT * FROM `items` ORDER BY `id` LIMIT 500': { rows: [{ id: 1, label: 'new', added_column: 'schema moved' }] } },
+            ];
+            for (const [i, changes] of cases.entries()) {
+                const { client } = fakeClient({ 'SHOW TABLES': { rows: [{ t: 'items' }] }, 'DESCRIBE `items`': schema, ...changes });
+                await assert.rejects(() => syncPlanetscaleFromReal(client, { root, ...(i === 0 ? { rowLimit: 1 } : {}), budgetOptions: { path: join(root, `failure-${i}`) } }));
+                assert.deepEqual(parentEntries('planetscale', root), before);
+            }
+            await assert.rejects(() => syncPlanetscaleFromReal(initial, { root, budgetOptions: { path: join(root, 'exhausted'), ceiling: 2 } }));
+            assert.deepEqual(parentEntries('planetscale', root), before);
+            assert.deepEqual((await q('SELECT label FROM items')).rows, [['old'], ['old']]);
+            return true;
+        }),
+    },
+    {
+        id: 'planetscale.connector.refresh_bounds', area: 'connector', dimension: 'connector', tier: 'common', expected: 'done',
+        title: 'invalid bounds refuse before IO; keyless scans never continue past a full page',
+        verify: () => withRoot(async (_q, root) => {
+            const { client, calls } = fakeClient({ 'SHOW TABLES': { rows: [{ t: 'items' }] },
+                'DESCRIBE `items`': describeRows([['label', 'varchar(20)', 'YES', '', null, '']]),
+                'SELECT * FROM `items` LIMIT 1': { rows: [{ label: 'a' }] } });
+            for (const option of ['rowLimit', 'maxPages', 'maxMissingChecks']) {
+                for (const value of [0, -1, 1.5, NaN, Infinity, null, '1; DROP TABLE items', 10001]) {
+                    await assert.rejects(() => pullPlanetscaleSnapshot(client, { [option]: value, budgetOptions: { path: join(root, 'bounds-budget') } }));
+                }
+            }
+            assert.equal(calls.length, 0);
+            const scan = await pullPlanetscaleSnapshot(client, { rowLimit: 1, budgetOptions: { path: join(root, 'bounds-budget') } });
+            assert.deepEqual(scan.partialTables, ['items']);
+            assert.deepEqual(scan.completeTables, []);
+            assert.equal(calls.length, 3);
+            await assert.rejects(() => syncPlanetscaleFromReal({}, { root, budgetOptions: { path: join(root, 'empty-client-budget') } }));
+            assert.equal(parentEntries('planetscale', root).length, 0);
+            return true;
+        }),
+    },
+    {
+        id: 'planetscale.connector.refresh_empty_database', area: 'connector', dimension: 'connector', tier: 'common', expected: 'done',
+        title: 'an empty discovered database removes upstream tables and rows but an empty table selection does not',
+        verify: () => withRoot(async (_q, root) => {
+            const schema = describeRows([['id', 'int', 'NO', 'PRI', null, '']]);
+            const opts = { root, budgetOptions: { path: join(root, 'empty-budget') } };
+            await syncPlanetscaleFromReal(fakeClient({ 'SHOW TABLES': { rows: [{ t: 'items' }] }, 'DESCRIBE `items`': schema,
+                'SELECT * FROM `items` ORDER BY `id` LIMIT 500': { rows: [{ id: 1 }] } }).client, opts);
+            const { client } = fakeClient({ 'SHOW TABLES': { rows: [] } });
+            assert.equal((await syncPlanetscaleFromReal(client, { ...opts, tables: [] })).removed, 0);
+            assert.equal(readDatabase(root).tables.size, 1);
+            assert.equal((await syncPlanetscaleFromReal(client, opts)).removed, 2);
+            assert.equal(readDatabase(root).tables.size, 0);
+            assert.equal((await syncPlanetscaleFromReal(client, opts)).deltasAppended, 0);
+            return true;
+        }),
+    },
+    {
+        id: 'planetscale.connector.refresh_read_metadata', area: 'connector', dimension: 'connector', tier: 'core', expected: 'done',
+        title: 'a DDL-shaped empty wire result cannot prove table or row absence',
+        verify: () => withRoot(async (_q, root) => {
+            const schema = describeRows([['id', 'int', 'NO', 'PRI', null, '']]);
+            const good = fakeClient({ 'SHOW TABLES': { rows: [{ t: 'items' }] }, 'DESCRIBE `items`': schema,
+                'SELECT * FROM `items` ORDER BY `id` LIMIT 500': { rows: [{ id: 1 }] } }).client;
+            await syncPlanetscaleFromReal(good, { root, budgetOptions: { path: join(root, 'metadata-initial') } });
+            const before = parentEntries('planetscale', root);
+            const wire = planetscaleClientOver(async (req) => ({ status: 200, headers: {}, body: JSON.stringify(req.path.endsWith('CreateSession') ? { session: { id: 's' } } : { result: {} }) }));
+            await assert.rejects(() => syncPlanetscaleFromReal(wire, { root, budgetOptions: { path: join(root, 'metadata-wire') } }), /field metadata/);
+            const { client } = fakeClient({ 'SHOW TABLES': { rows: [{ t: 'items' }] }, 'DESCRIBE `items`': schema,
+                'SELECT * FROM `items` ORDER BY `id` LIMIT 500': { rows: [] },
+                'SELECT * FROM `items` WHERE `id` = 1 LIMIT 2': { rows: [], fields: [] } });
+            await assert.rejects(() => syncPlanetscaleFromReal(client, { root, budgetOptions: { path: join(root, 'metadata-point') } }), /field metadata/);
+            assert.deepEqual(parentEntries('planetscale', root), before);
+            return true;
+        }),
+    },
+    {
+        id: 'planetscale.connector.refresh_identity_changes', area: 'connector', dimension: 'connector', tier: 'common', expected: 'done',
+        title: 'stable collation spelling and primary-key definition changes retire old identities without endless retries',
+        verify: () => withRoot(async (q, root) => {
+            const original = describeRows([['id', 'varchar(20)', 'NO', 'PRI', null, ''], ['label', 'varchar(20)', 'NO', '', null, '']]);
+            const script = { 'SHOW TABLES': { rows: [{ t: 'items' }] }, 'DESCRIBE `items`': original,
+                'SELECT * FROM `items` ORDER BY `id` LIMIT 500': { rows: [{ id: 'a', label: 'one' }] },
+                // An independent case-insensitive peer: the old spelling resolves to the new row.
+                "SELECT * FROM `items` WHERE `id` = 'a' LIMIT 2": { rows: [{ id: 'A', label: 'one' }] } };
+            const { client } = fakeClient(script);
+            const opts = { root, budgetOptions: { path: join(root, 'identity-budget') } };
+            await syncPlanetscaleFromReal(client, opts);
+            script['SELECT * FROM `items` ORDER BY `id` LIMIT 500'] = { rows: [{ id: 'A', label: 'one' }] };
+            assert.equal((await syncPlanetscaleFromReal(client, opts)).removed, 1);
+            assert.deepEqual((await q('SELECT * FROM items')).rows, [['A', 'one']]);
+            assert.equal((await syncPlanetscaleFromReal(client, opts)).deltasAppended, 0);
+            script['DESCRIBE `items`'] = describeRows([['id', 'varchar(20)', 'NO', 'PRI', null, ''], ['label', 'varchar(20)', 'NO', 'PRI', null, '']]);
+            script['SELECT * FROM `items` ORDER BY `id`, `label` LIMIT 500'] = { rows: [{ id: 'A', label: 'one' }] };
+            script["SELECT * FROM `items` WHERE `id` = 'A' AND `label` = 'one' LIMIT 2"] = { rows: [{ id: 'A', label: 'one' }] };
+            assert.equal((await syncPlanetscaleFromReal(client, opts)).removed, 1);
+            script['DESCRIBE `items`'] = describeRows([['id', 'varchar(20)', 'NO', '', null, ''], ['label', 'varchar(20)', 'NO', '', null, ''], ['surrogate', 'int', 'NO', 'PRI', null, '']]);
+            script['SELECT * FROM `items` ORDER BY `surrogate` LIMIT 500'] = { rows: [{ id: 'A', label: 'one', surrogate: 10 }] };
+            assert.equal((await syncPlanetscaleFromReal(client, opts)).removed, 1);
+            assert.deepEqual((await q('SELECT * FROM items')).rows, [['A', 'one', '10']]);
+            return true;
+        }),
+    },
+    {
+        id: 'planetscale.connector.exact_numeric_paging', area: 'connector', dimension: 'connector', tier: 'core', expected: 'done',
+        title: 'actual SQL continuation distinguishes adjacent BIGINT keys instead of rounding through DOUBLE',
+        verify: () => withRoot(async (q, root) => withRoot(async (remote) => {
+            await remote('CREATE TABLE items (id BIGINT PRIMARY KEY)');
+            await remote('INSERT INTO items VALUES (9007199254740993),(9007199254740992),(-9007199254740992),(-9007199254740993)');
+            const client = { execute: async (sql) => {
+                    const r = await remote(sql);
+                    assert(!r.error, JSON.stringify(r.error));
+                    return { fields: r.fields, rows: r.rows.map(row => Object.fromEntries(r.fields.map((f, i) => [f.name, row[i]]))) };
+                } };
+            const result = await syncPlanetscaleFromReal(client, { root, rowLimit: 1, budgetOptions: { path: join(root, 'bigint-budget') } });
+            assert.deepEqual(result.completeTables, ['items']);
+            assert.deepEqual((await q('SELECT id FROM items ORDER BY id')).rows, [['-9007199254740993'], ['-9007199254740992'], ['9007199254740992'], ['9007199254740993']]);
+            return true;
+        })),
+    },
+    {
+        id: 'planetscale.connector.pending_delete_collision', area: 'connector', dimension: 'connector', tier: 'core', expected: 'done',
+        title: 'pending local deletion cannot free a hash address still occupied by a distinct upstream key',
+        verify: () => withRoot(async (q, root) => {
+            const keys = ['customer-2479052881', 'customer-2205617487'];
+            const remote = fakeClient({ 'SHOW TABLES': { rows: [{ t: 'notes' }] },
+                'DESCRIBE `notes`': describeRows([['id', 'varchar(64)', 'NO', 'PRI', null, '']]),
+                'SELECT * FROM `notes` ORDER BY `id` LIMIT 500': { rows: [{ id: keys[0] }] } }).client;
+            const opts = { root, budgetOptions: { path: join(root, 'pending-collision-budget') } };
+            await syncPlanetscaleFromReal(remote, opts);
+            await q('DELETE FROM notes');
+            const before = deployableEntries('planetscale', root).length;
+            const inserted = await q(`INSERT INTO notes VALUES ('${keys[1]}')`);
+            assert(inserted.error?.message.includes('row identity hash collision'));
+            assert.equal(deployableEntries('planetscale', root).length, before);
+            assert.equal((await syncPlanetscaleFromReal(remote, opts)).deltasAppended, 0);
+            assert.deepEqual((await q('SELECT * FROM notes')).rows, []);
+            return true;
+        }),
+    },
+    {
+        id: 'planetscale.connector.refresh_check_cap', area: 'connector', dimension: 'connector', tier: 'common', expected: 'done',
+        title: 'exhausting the missing-row check cap aborts before any observation',
+        verify: () => withRoot(async (_q, root) => {
+            const script = { 'SHOW TABLES': { rows: [{ t: 'items' }] },
+                'DESCRIBE `items`': describeRows([['id', 'int', 'NO', 'PRI', null, '']]),
+                'SELECT * FROM `items` ORDER BY `id` LIMIT 500': { rows: [{ id: 1 }, { id: 2 }] },
+                'SELECT * FROM `items` WHERE `id` = 1 LIMIT 2': { rows: [] },
+                'SELECT * FROM `items` WHERE `id` = 2 LIMIT 2': { rows: [] } };
+            const { client, calls } = fakeClient(script);
+            const opts = { root, budgetOptions: { path: join(root, 'cap-budget') } };
+            await syncPlanetscaleFromReal(client, opts);
+            const before = parentEntries('planetscale', root);
+            script['SELECT * FROM `items` ORDER BY `id` LIMIT 500'] = { rows: [] };
+            await assert.rejects(() => syncPlanetscaleFromReal(client, { ...opts, maxMissingChecks: 1 }), /check limit/);
+            assert.equal(calls.filter(c => c.includes(' WHERE ')).length, 1);
+            assert.deepEqual(parentEntries('planetscale', root), before);
+            return true;
+        }),
+    },
+    {
+        id: 'planetscale.connector.partial_identity_transition', area: 'connector', dimension: 'connector', tier: 'common', expected: 'done',
+        title: 'incomplete primary-key changes leave schema and rows untouched until a complete refresh',
+        verify: () => withRoot(async (q, root) => {
+            const script = { 'SHOW TABLES': { rows: [{ t: 'items' }] },
+                'DESCRIBE `items`': describeRows([['id', 'int', 'NO', 'PRI', null, '']]),
+                'SELECT * FROM `items` ORDER BY `id` LIMIT 500': { rows: [{ id: 1 }] } };
+            const { client } = fakeClient(script);
+            const opts = { root, budgetOptions: { path: join(root, 'partial-key-budget') } };
+            await syncPlanetscaleFromReal(client, opts);
+            const before = parentEntries('planetscale', root);
+            script['DESCRIBE `items`'] = describeRows([['id', 'int', 'NO', '', null, ''], ['surrogate', 'int', 'NO', 'PRI', null, '']]);
+            script['SELECT * FROM `items` ORDER BY `surrogate` LIMIT 1'] = { rows: [{ id: 1, surrogate: 10 }] };
+            script['SELECT * FROM `items` ORDER BY `surrogate` LIMIT 500'] = { rows: [{ id: 1, surrogate: 10 }] };
+            await assert.rejects(() => syncPlanetscaleFromReal(client, { ...opts, rowLimit: 1, maxPages: 1 }), /Incomplete PlanetScale primary-key change/);
+            assert.deepEqual(parentEntries('planetscale', root), before);
+            assert.equal((await syncPlanetscaleFromReal(client, opts)).removed, 1);
+            assert.deepEqual((await q('SELECT * FROM items')).rows, [['1', '10']]);
+            return true;
+        }),
+    },
+    {
+        id: 'planetscale.connector.buffered_collision', area: 'connector', dimension: 'connector', tier: 'core', expected: 'done',
+        title: 'COMMIT and implicit commit recheck buffered row identities after an intervening refresh',
+        verify: async () => {
+            for (const hidden of [false, true])
+                for (const commit of ['COMMIT', 'BEGIN']) {
+                    const passed = await withRoot(async (q, root) => {
+                        const script = { 'SHOW TABLES': { rows: [{ t: 'notes' }] },
+                            'DESCRIBE `notes`': describeRows([['id', 'varchar(64)', 'NO', 'PRI', null, '']]),
+                            'SELECT * FROM `notes` ORDER BY `id` LIMIT 500': { rows: [] } };
+                        const { client } = fakeClient(script);
+                        const opts = { root, budgetOptions: { path: join(root, 'buffered-collision-budget') } };
+                        await syncPlanetscaleFromReal(client, opts);
+                        await q('BEGIN');
+                        await q("INSERT INTO notes VALUES ('customer-2205617487')");
+                        script['SELECT * FROM `notes` ORDER BY `id` LIMIT 500'] = { rows: [{ id: 'customer-2479052881' }] };
+                        await syncPlanetscaleFromReal(client, opts);
+                        // A local tombstone can hide upstream from the projected-row check. The independent
+                        // upstream check must still protect its occupied address at commit.
+                        if (hidden)
+                            assert(!((await q('DELETE FROM notes', { session: null })).error));
+                        const before = deployableEntries('planetscale', root).length;
+                        const result = await q(commit);
+                        assert(result.error?.message.includes('row identity hash collision'));
+                        assert.equal(deployableEntries('planetscale', root).length, before);
+                        await q('ROLLBACK');
+                        assert.deepEqual((await q('SELECT id FROM notes')).rows, hidden ? [] : [['customer-2479052881']]);
+                        return true;
+                    });
+                    if (!passed)
+                        return false;
+                }
+            return true;
+        },
+    },
+    {
+        id: 'planetscale.connector.key_column_case', area: 'connector', dimension: 'connector', tier: 'common', expected: 'done',
+        title: 'case-only primary-key column renaming still permits confirmed row deletion',
+        verify: () => withRoot(async (q, root) => {
+            const script = { 'SHOW TABLES': { rows: [{ t: 'items' }] },
+                'DESCRIBE `items`': describeRows([['id', 'int', 'NO', 'PRI', null, '']]),
+                'SELECT * FROM `items` ORDER BY `id` LIMIT 500': { rows: [{ id: 1 }, { id: 2 }] } };
+            const { client, calls } = fakeClient(script);
+            const opts = { root, budgetOptions: { path: join(root, 'column-case-budget') } };
+            await syncPlanetscaleFromReal(client, opts);
+            script['DESCRIBE `items`'] = describeRows([['ID', 'int', 'NO', 'PRI', null, '']]);
+            script['SELECT * FROM `items` ORDER BY `ID` LIMIT 500'] = { rows: [{ ID: 1 }] };
+            script['SELECT * FROM `items` WHERE `ID` = 2 LIMIT 2'] = { rows: [] };
+            assert.equal((await syncPlanetscaleFromReal(client, opts)).removed, 1);
+            assert(calls.includes('SELECT * FROM `items` WHERE `ID` = 2 LIMIT 2'));
+            assert.deepEqual((await q('SELECT ID FROM items')).rows, [['1']]);
+            return true;
+        }),
+    },
+    {
+        id: 'planetscale.select.numeric_operand_types', area: 'select', dimension: 'api', tier: 'common', expected: 'done',
+        title: 'comparisons of exact integers and decimals are exact, while a string against a number or a DOUBLE compares as DOUBLE',
+        verify: () => withRoot(async (q) => {
+            assert.deepEqual((await q("SELECT '9223372036854775807' = 9223372036854775806 FROM dual")).rows, [['1']]);
+            assert.deepEqual((await q('SELECT 9223372036854775807 = 9223372036854775806 FROM dual')).rows, [['0']]);
+            assert.deepEqual((await q('SELECT 9007199254740992.1 = 9007199254740992.2 FROM dual')).rows, [['0']]);
+            assert.deepEqual((await q('SELECT .10000000000000001 = .1 FROM dual')).rows, [['0']]);
+            assert.deepEqual((await q('SELECT -.10000000000000001 = -.1 FROM dual')).rows, [['0']]);
+            assert.deepEqual((await q('SELECT 9007199254740993. = 9007199254740992. FROM dual')).rows, [['0']]);
+            assert.deepEqual((await q('SELECT -9007199254740993 = -9007199254740992 FROM dual')).rows, [['0']]);
+            await q('CREATE TABLE floating (n DOUBLE)');
+            await q('INSERT INTO floating VALUES (9007199254740993)');
+            assert.deepEqual((await q('SELECT n = 9007199254740992 FROM floating')).rows, [['1']]);
+            return true;
+        }),
+    },
+    {
+        id: 'planetscale.transactions.buffered_identity_collision', area: 'transactions', dimension: 'api', tier: 'core', expected: 'done',
+        title: 'buffered commit cannot overwrite a distinct key committed by another local session',
+        verify: async () => {
+            for (const bufferedPeer of [false, true])
+                for (const commit of ['COMMIT', 'BEGIN']) {
+                    const passed = await withRoot(async (q, root) => {
+                        await q('CREATE TABLE notes (id VARCHAR(64) PRIMARY KEY)');
+                        await q('BEGIN');
+                        assert(!((await q("INSERT INTO notes VALUES ('customer-2205617487')")).error));
+                        const peer = bufferedPeer ? (await q('BEGIN', { session: null })).session : null;
+                        assert(!((await q("INSERT INTO notes VALUES ('customer-2479052881')", { session: peer })).error));
+                        if (bufferedPeer)
+                            assert(!((await q('COMMIT', { session: peer })).error));
+                        const before = deployableEntries('planetscale', root).length;
+                        const result = await q(commit);
+                        assert(result.error?.message.includes('row identity hash collision'));
+                        assert.equal(deployableEntries('planetscale', root).length, before);
+                        await q('ROLLBACK');
+                        assert.deepEqual((await q('SELECT id FROM notes')).rows, [['customer-2479052881']]);
+                        return true;
+                    });
+                    if (!passed)
+                        return false;
+                }
+            return true;
+        },
+    },
+    todo('planetscale.connector.rowid_hash_collision', 'connector', "the residual after the §9 rowid rework: a pulled row's internal id is a 32-bit FNV-1a digest of its PRIMARY KEY values (plus an ordinal that disambiguates the identical rows a KEYLESS table may hold — §9 round two found that case merging deterministically, not probabilistically), shared by local keyed writes and refresh. Two DISTINCT rows can still collide at ~2^-32 per pair; local writes and pull now refuse such collisions before projecting anything. A wider digest removes this refusal", 'niche'),
+    todo('planetscale.connector.push_type_normalization', 'connector', 'Deployment of values requiring integer/decimal rounding, padding, floating-point, temporal or JSON storage normalization needs a vendor-faithful codec; captured plans refuse those conversions before IO today', 'common'),
+    todo('planetscale.connector.push_ddl', 'connector', "pushing a local SCHEMA change — PlanetScale schema changes go through its branch/deploy-request workflow, not an ad-hoc ALTER, so push refuses DDL by name today", 'common'),
+    todo('planetscale.connector.auto_increment_watermark', 'connector', 'reading the real AUTO_INCREMENT counter (SHOW TABLE STATUS) instead of deriving a floor from the rows actually observed', 'common'),
+    todo('planetscale.connector.pull_indexes', 'connector', 'pulling composite PRIMARY/UNIQUE keys and secondary indexes via SHOW INDEX (today only single-column keys are derived from DESCRIBE)', 'common'),
+    {
+        id: 'planetscale.auth.password_roles',
+        area: 'auth', title: "a branch password's role is enforced: a reader cannot write, a writer cannot query, a readwriter cannot change schema (errno 1142, the password-roles page's words); a credential no password names acts as the World's own",
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: async () => {
+            const root = mkdtempSync(join(tmpdir(), 'planetscale-roles-'));
+            try {
+                const f = createPlanetscaleTwinFetch({ root, now: () => '2026-03-04T05:06:07.000Z' });
+                const auth = { authorization: 'tokenid:pscale_tkn_twin', 'content-type': 'application/json' };
+                const base = 'http://api.planetscale.com/v1/organizations/acme/databases/shop/branches/main/passwords';
+                await f(new Request('http://api.planetscale.com/v1/organizations/acme/databases', { method: 'POST', headers: auth, body: JSON.stringify({ name: 'shop', cluster_size: 'PS_10' }) }));
+                const pw = {};
+                for (const role of ['reader', 'writer', 'readwriter', 'admin'])
+                    pw[role] = await (await f(new Request(base, { method: 'POST', headers: auth, body: JSON.stringify({ role }) }))).json();
+                const exec = async (user, pass, query) => (await (await f(new Request('http://twin/psdb.v1alpha1.Database/Execute', { method: 'POST', headers: { authorization: `Basic ${btoa(`${user}:${pass}`)}` }, body: JSON.stringify({ query }) }))).json());
+                const as = (role, query) => exec(pw[role].username, pw[role].plain_text, query);
+                const ddl = await as('admin', 'CREATE TABLE customers (id INT PRIMARY KEY)');
+                const rwDdl = await as('readwriter', 'CREATE TABLE other (id INT PRIMARY KEY)');
+                const rwInsert = await as('readwriter', 'INSERT INTO customers VALUES (1)');
+                const readerInsert = await as('reader', 'INSERT INTO customers VALUES (2)');
+                const readerSelect = await as('reader', 'SELECT * FROM customers');
+                const writerSelect = await as('writer', 'SELECT * FROM customers');
+                const world = await exec('twin', 'twin', 'INSERT INTO customers VALUES (3)');
+                return ddl.error === undefined && rwInsert.error === undefined && readerSelect.error === undefined && world.error === undefined
+                    && rwDdl.error?.message === "DDL command denied to user 'planetscale-writer' for table 'other' (ACL check error) (errno 1142) (sqlstate 42000)"
+                    && readerInsert.error?.message === "Insert command denied to user 'planetscale-reader' for table 'customers' (ACL check error) (errno 1142) (sqlstate 42000)"
+                    && writerSelect.error?.message === "Select command denied to user 'planetscale-writer-only' for table 'customers' (ACL check error) (errno 1142) (sqlstate 42000)";
+            }
+            finally {
+                rmSync(root, { recursive: true, force: true });
+            }
+        },
+    },
+    // ── management API (api.planetscale.com — the control plane; a branch's backups modeled) ────────
+    todo('planetscale.management.list_databases', 'management', "GET /v1/organizations/{org}/databases — list databases, and a database's settings (create, read and delete are served)", 'core'),
+    todo('planetscale.management.branches', 'management', 'branch create/list/delete and branch promotion', 'core'),
+    todo('planetscale.management.deploy_requests', 'management', 'deploy requests: open, diff, deploy, revert', 'core'),
+    todo('planetscale.management.schema_diff', 'management', 'GET /branches/{branch}/schema and the branch schema diff', 'common'),
+    {
+        id: 'planetscale.management.backups',
+        area: 'management', title: "a branch's backups through the management API: create (201, pending until the World clock runs and completes it; retention validated, emergency 422 for MySQL), list with its filters, read (a deleted one too), delete; service-token auth; other management paths refused 404; never pushed to a real branch",
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: async () => {
+            const root = mkdtempSync(join(tmpdir(), 'planetscale-mgmt-'));
+            try {
+                const f = createPlanetscaleTwinFetch({ root, now: () => '2026-03-04T05:06:07.000Z' });
+                const base = 'http://api.planetscale.com/v1/organizations/dub/databases/dub/branches/main/backups';
+                const auth = { authorization: 'tokenid:pscale_tkn_twin', 'content-type': 'application/json' };
+                // Dub's backup cron, verbatim in shape (apps/web/app/(ee)/api/cron/trigger-backup/route.ts)
+                const made = await f(new Request(base, { method: 'POST', headers: auth, body: JSON.stringify({ name: 'cron-backup-1', retention_value: 7, retention_unit: 'day' }) }));
+                const backup = await made.json();
+                const listed = await (await f(new Request(base, { headers: auth }))).json();
+                const read = await f(new Request(`${base}/${String(backup.id)}`, { headers: auth }));
+                const deleted = await f(new Request(`${base}/${String(backup.id)}`, { method: 'DELETE', headers: auth }));
+                const after = await (await f(new Request(base, { headers: auth }))).json();
+                const unauth = await f(new Request(base, { method: 'POST', body: '{}' }));
+                const tooLong = await f(new Request(base, { method: 'POST', headers: auth, body: JSON.stringify({ retention_value: 5000 }) }));
+                const other = await f(new Request('http://api.planetscale.com/v1/organizations/dub/databases', { headers: auth }));
+                const emergency = await f(new Request(base, { method: 'POST', headers: auth, body: JSON.stringify({ emergency: true }) }));
+                await f(new Request(base, { method: 'POST', headers: auth, body: JSON.stringify({ name: 'cron-backup-2' }) }));
+                const later = await (await f(new Request(`${base}?from=2026-03-04T05:06:07.000Z`, { headers: auth }))).json();
+                const earlier = await (await f(new Request(`${base}?to=2026-03-04T05:06:07.000Z`, { headers: auth }))).json();
+                const kept = await (await f(new Request(`${base}?from=2026-03-04T05:00:00.000Z&to=2026-03-04T06:00:00.000Z`, { headers: auth }))).json();
+                const withDeleted = await (await f(new Request(`${base}?all=true`, { headers: auth }))).json();
+                const deletedRead = await f(new Request(`${base}/${String(backup.id)}`, { headers: auth }));
+                // a backup is the twin's bookkeeping: nothing of it is pushed to a real branch
+                const pushable = deployableEntries('planetscale', root).filter((a) => a.subject.type.includes('backup'));
+                // a new backup is pending until the World clock runs and completes it; the clock here stands still
+                return made.status === 201 && backup.name === 'cron-backup-1' && backup.state === 'pending' && backup.expires_at === null
+                    && listed.type === 'list' && listed.total_count === 1 && listed.data[0]?.id === backup.id && read.status === 200
+                    && deleted.status === 204 && after.total_count === 0 && unauth.status === 401 && tooLong.status === 422 && other.status === 404
+                    && emergency.status === 422 && later.total_count === 0 && earlier.total_count === 0 && kept.total_count === 0 && withDeleted.total_count === 2
+                    && deletedRead.status === 200 && pushable.length === 0;
+            }
+            finally {
+                rmSync(root, { recursive: true, force: true });
+            }
+        },
+    },
+    {
+        id: 'planetscale.management.passwords',
+        area: 'management', title: "a branch's passwords through the management API: create with a role (admin when none is sent: the reference marks none required and gives no default), plain_text shown once; list, delete; psdb authenticates them, refuses a deleted one, and a deleted database takes its passwords with it",
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: async () => {
+            const root = mkdtempSync(join(tmpdir(), 'planetscale-pw-'));
+            try {
+                const f = createPlanetscaleTwinFetch({ root, now: () => '2026-03-04T05:06:07.000Z' });
+                const auth = { authorization: 'tokenid:pscale_tkn_twin', 'content-type': 'application/json' };
+                const org = 'http://api.planetscale.com/v1/organizations/acme';
+                const exec = async (user, pass) => (await f(new Request('http://twin/psdb.v1alpha1.Database/Execute', { method: 'POST', headers: { authorization: `Basic ${btoa(`${user}:${pass}`)}` }, body: JSON.stringify({ query: 'SELECT 1' }) }))).status;
+                await f(new Request(`${org}/databases`, { method: 'POST', headers: auth, body: JSON.stringify({ name: 'shop', cluster_size: 'PS_10' }) }));
+                const made = await f(new Request(`${org}/databases/shop/branches/main/passwords`, { method: 'POST', headers: auth, body: JSON.stringify({ name: 'app', role: 'readwriter' }) }));
+                const pw = await made.json();
+                const listed = await (await f(new Request(`${org}/databases/shop/branches/main/passwords`, { headers: auth }))).json();
+                const works = await exec(pw.username, pw.plain_text);
+                const wrong = await exec(pw.username, 'pscale_pw_wrong');
+                const deleted = await f(new Request(`${org}/databases/shop/branches/main/passwords/${pw.id}`, { method: 'DELETE', headers: auth }));
+                const afterDelete = await exec(pw.username, pw.plain_text);
+                const second = await (await f(new Request(`${org}/databases/shop/branches/main/passwords`, { method: 'POST', headers: auth, body: JSON.stringify({ role: 'admin' }) }))).json();
+                await f(new Request(`${org}/databases/shop`, { method: 'DELETE', headers: auth }));
+                const afterDrop = await exec(second.username, second.plain_text);
+                return made.status === 201 && pw.role === 'readwriter' && pw.plain_text.startsWith('pscale_pw_') && listed.data.length === 1 && listed.data[0].plain_text === null
+                    && works === 200 && wrong === 401 && deleted.status === 204 && afterDelete === 401 && afterDrop === 401;
+            }
+            finally {
+                rmSync(root, { recursive: true, force: true });
+            }
+        },
+    },
+    todo('planetscale.management.backup_restore', 'management', 'restore a backup to a new branch', 'common'),
+    todo('planetscale.management.insights', 'management', 'query insights / performance metrics', 'niche'),
+    todo('planetscale.management.oauth', 'management', 'the OAuth application flow for PlanetScale API access', 'niche'),
+    todo('planetscale.management.webhooks', 'management', 'organization webhooks for deploy-request and branch events', 'niche'),
+    // ── the MySQL type system (§9 engine review: the done checks used Dub's shapes; these use the
+    //    neighbouring ones the review found wrong) ──────────────────────────────────────────────
+    {
+        id: 'planetscale.select.expression_comparison_types', area: 'select', dimension: 'api', tier: 'core', expected: 'done',
+        title: 'an expression compares and sorts by its MySQL type: COALESCE/CASE/IF/GREATEST, scalar subqueries and arithmetic over numbers are numeric',
+        verify: () => withRoot(async (q) => {
+            await q('CREATE TABLE Score (id INT PRIMARY KEY, pts INT, bonus INT)');
+            await q('INSERT INTO Score VALUES (1, 9, 1), (2, 10, 1), (3, NULL, 100)');
+            await q('CREATE TABLE Hit (id INT PRIMARY KEY, sid INT)');
+            await q('INSERT INTO Hit VALUES (1, 1), (2, 1), (3, 2)');
+            const ids = async (sql) => (await q(sql)).rows.map((r) => r[0]).join(',');
+            return await ids('SELECT id FROM Score ORDER BY COALESCE(pts, 0) DESC') === '2,1,3'
+                && await ids('SELECT id FROM Score ORDER BY CASE WHEN id = 1 THEN 10 ELSE 9 END') === '2,3,1'
+                && await ids('SELECT id FROM Score ORDER BY GREATEST(pts, bonus)') === '3,1,2'
+                && await ids('SELECT s.id FROM Score s ORDER BY (SELECT COUNT(*) FROM Hit h WHERE h.sid = s.id) DESC, s.id') === '1,2,3'
+                && await ids('SELECT id FROM Score WHERE (SELECT COUNT(*) FROM Hit h WHERE h.sid = Score.id) > (SELECT 1 FROM dual)') === '1'
+                && await ids('SELECT id FROM Score WHERE IFNULL(pts, 0) + 0 > 9') === '2';
+        }),
+    },
+    {
+        id: 'planetscale.select.temporal_values', area: 'select', dimension: 'api', tier: 'core', expected: 'done',
+        title: 'DATE/DATETIME/TIMESTAMP/TIME are stored canonically at their fsp from any literal form MySQL accepts (the `T` form @planetscale/database sends included) and compare as points in time',
+        verify: () => withRoot(async (q) => {
+            await q('CREATE TABLE Ev (id INT PRIMARY KEY, at DATETIME(3) NOT NULL, day DATE, t TIME)');
+            await q("INSERT INTO Ev VALUES (1, '2024-01-01 23:00:00.000', '2024-01-01', '9:05'), (2, '2024-01-02T01:00:00.0005', 20240102, '101500')");
+            const since = await q("SELECT id FROM Ev WHERE at >= '2024-01-01T00:00:00.000' ORDER BY id");
+            const day = await q("SELECT id FROM Ev WHERE day = '2024-01-01 00:00:00'");
+            const read = await q('SELECT at, day, t FROM Ev ORDER BY at');
+            const bad = await q("INSERT INTO Ev (id, at) VALUES (3, '2024-02-30 00:00:00')");
+            const zero = await q("INSERT INTO Ev (id, at) VALUES (4, '0000-00-00 00:00:00')");
+            return since.rows.map((r) => r[0]).join(',') === '1,2' && JSON.stringify(day.rows) === '[["1"]]'
+                && JSON.stringify(read.rows) === JSON.stringify([['2024-01-01 23:00:00.000', '2024-01-01', '09:05:00'], ['2024-01-02 01:00:00.001', '2024-01-02', '10:15:00']])
+                && failed(bad, 'INVALID_ARGUMENT', "Incorrect datetime value: '2024-02-30 00:00:00' for column 'at' at row 1") && bad.error.message.includes('1292')
+                && failed(zero, 'INVALID_ARGUMENT', 'Incorrect datetime value');
+        }),
+    },
+    {
+        id: 'planetscale.functions.exact_arithmetic', area: 'functions', dimension: 'api', tier: 'core', expected: 'done',
+        title: 'exact-value arithmetic stays exact (manual 14.24 "Precision Math"): DECIMAL scales, BIGINTs beyond 2^53, rounding on store, errno 1690 on overflow, 1365 for a division by zero written to a row',
+        verify: () => withRoot(async (q) => {
+            await q('CREATE TABLE Wallet (id BIGINT PRIMARY KEY, bal DECIMAL(10,2) NOT NULL)');
+            await q('INSERT INTO Wallet VALUES (9007199254740993, 0.1)');
+            await q('UPDATE Wallet SET bal = bal + 0.2');
+            const read = await q('SELECT bal, bal * 3, bal / 3, id + 1, id DIV 2 FROM Wallet');
+            const overflow = await q('SELECT 9223372036854775807 + 1 FROM dual');
+            const divWrite = await q('UPDATE Wallet SET bal = 1 / 0');
+            const divRead = await q('SELECT 1 / 0, 5 % 0 FROM dual');
+            return JSON.stringify(read.rows[0]) === JSON.stringify(['0.30', '0.90', '0.100000', '9007199254740994', '4503599627370496'])
+                && read.fields.map((f) => f.type).join(',') === 'DECIMAL,DECIMAL,DECIMAL,INT64,INT64'
+                && failed(overflow, 'INVALID_ARGUMENT', "BIGINT value is out of range in '(9223372036854775807 + 1)'")
+                && failed(divWrite, 'INVALID_ARGUMENT', 'Division by 0') && JSON.stringify(divRead.rows) === '[[null,null]]';
+        }),
+    },
+    {
+        id: 'planetscale.insert.strict_type_conversion', area: 'insert', dimension: 'api', tier: 'core', expected: 'done',
+        title: "a written value is converted to its column's type under MySQL 8's default strict sql_mode: 1366 for a non-number, 1265 for a partial one, 1292 for a bad temporal, 3140 for bad JSON, 1048 for NULL",
+        verify: () => withRoot(async (q) => {
+            await q('CREATE TABLE Val (id INT PRIMARY KEY, n INT NOT NULL DEFAULT 0, d DECIMAL(6,2), f DOUBLE, j JSON, at DATETIME)');
+            const word = await q("INSERT INTO Val (id, n) VALUES (1, 'abc')");
+            const partial = await q("INSERT INTO Val (id, d) VALUES (2, '12abc')");
+            const temporal = await q("INSERT INTO Val (id, at) VALUES (3, 'garbage')");
+            const json = await q("INSERT INTO Val (id, j) VALUES (4, '{bad')");
+            const nul = await q('INSERT INTO Val (id, n) VALUES (5, NULL)');
+            const converted = await q("INSERT INTO Val (id, n, d, f, at) VALUES (6, 1.7, 1.5, '2.50', 20240102030405)");
+            const ignored = await q("INSERT IGNORE INTO Val (id, n) VALUES (7, NULL)");
+            const rows = await q('SELECT n, d, f, at FROM Val ORDER BY id');
+            return failed(word, 'INVALID_ARGUMENT', "Incorrect integer value: 'abc' for column 'n' at row 1") && word.error.message.includes('1366')
+                && failed(partial, 'INVALID_ARGUMENT', "Data truncated for column 'd' at row 1")
+                && failed(temporal, 'INVALID_ARGUMENT', "Incorrect datetime value: 'garbage' for column 'at' at row 1")
+                && failed(json, 'INVALID_ARGUMENT', "for column 'Val.j'") && json.error.message.includes('3140')
+                && failed(nul, 'INVALID_ARGUMENT', "Column 'n' cannot be null") && ok(converted) && ok(ignored)
+                && JSON.stringify(rows.rows) === JSON.stringify([['2', '1.50', '2.5', '2024-01-02 03:04:05'], ['0', null, null, null]]);
+        }),
+    },
+    {
+        id: 'planetscale.select.json_comparison', area: 'select', dimension: 'api', tier: 'common', expected: 'done',
+        title: 'a JSON value compares with a non-JSON one as JSON (manual 13.5): `j->\'$.name\' = \'bob\'` matches a JSON string, JSON 2 is not the string \'2\', 1 equals 1.0',
+        verify: () => withRoot(async (q) => {
+            await q('CREATE TABLE Person (id INT PRIMARY KEY, j JSON)');
+            await q(`INSERT INTO Person VALUES (1, '{"name":"bob","n":1,"tags":["a","b"]}'), (2, '{"name":"al","n":2.0}')`);
+            const ids = async (w) => (await q(`SELECT id FROM Person WHERE ${w} ORDER BY id`)).rows.map((r) => r[0]).join(',');
+            return await ids("j->'$.name' = 'bob'") === '1' && await ids("j->'$.n' = '2'") === '' && await ids("j->'$.n' = 2") === '2'
+                && await ids("j->'$.tags[0]' = 'a'") === '1' && await ids("'b' MEMBER OF (j->'$.tags')") === '1'
+                && await ids("JSON_EXTRACT(j, '$.tags[last-1]') = 'a'") === '1';
+        }),
+    },
+    {
+        id: 'planetscale.select.bigint_exact_keys', area: 'select', dimension: 'api', tier: 'common', expected: 'done',
+        title: 'BIGINTs beyond 2^53 stay distinct in DISTINCT, GROUP BY and COUNT(DISTINCT), and JSON integers stay exact in JSON_EXTRACT and JSON_CONTAINS',
+        verify: () => withRoot(async (q) => {
+            await q('CREATE TABLE Snow (id INT PRIMARY KEY, uid BIGINT NOT NULL, j JSON)');
+            await q(`INSERT INTO Snow VALUES (1, 1234567890123456789, '{"id": 1234567890123456789}'), (2, 1234567890123456790, '{}'), (3, 1234567890123456789, '{}')`);
+            const distinct = await q('SELECT DISTINCT uid FROM Snow ORDER BY uid');
+            const groups = await q('SELECT uid, COUNT(*) FROM Snow GROUP BY uid ORDER BY uid');
+            const count = await q('SELECT COUNT(DISTINCT uid) FROM Snow');
+            const json = await q("SELECT j->>'$.id', JSON_CONTAINS(j, '1234567890123456788', '$.id') FROM Snow WHERE id = 1");
+            return distinct.rows.length === 2 && JSON.stringify(groups.rows) === JSON.stringify([['1234567890123456789', '2'], ['1234567890123456790', '1']])
+                && count.rows[0][0] === '2' && JSON.stringify(json.rows[0]) === JSON.stringify(['1234567890123456789', '0']);
+        }),
+    },
+    {
+        id: 'planetscale.select.is_boolean', area: 'select', dimension: 'api', tier: 'common', expected: 'done',
+        title: 'IS [NOT] TRUE / FALSE / UNKNOWN test truthiness and never return NULL (manual 14.4.2)',
+        verify: () => withRoot(async (q) => {
+            await q('CREATE TABLE Flag (id INT PRIMARY KEY, on_ BOOLEAN)');
+            await q('INSERT INTO Flag VALUES (1, 1), (2, NULL), (3, 0), (4, 2)');
+            const ids = async (w) => (await q(`SELECT id FROM Flag WHERE ${w} ORDER BY id`)).rows.map((r) => r[0]).join(',');
+            const consts = await q('SELECT 2 IS TRUE, NULL IS TRUE, NULL IS NOT TRUE, NULL IS NOT FALSE, NULL IS UNKNOWN FROM dual');
+            return await ids('on_ IS TRUE') === '1,4' && await ids('on_ IS NOT TRUE') === '2,3' && await ids('on_ IS FALSE') === '3'
+                && await ids('on_ IS UNKNOWN') === '2' && JSON.stringify(consts.rows[0]) === JSON.stringify(['1', '0', '1', '1', '1']);
+        }),
+    },
+    {
+        id: 'planetscale.select.sql_mode_refusals', area: 'select', dimension: 'api', tier: 'core', expected: 'done',
+        title: "MySQL 8's default sql_mode refusals: ONLY_FULL_GROUP_BY (1055/1140, with functional dependence on keys and equalities), DISTINCT + ORDER BY (3065), LIMIT in an IN subquery (1235), a subquery on the updated table (1093); @@sql_mode reports it",
+        verify: () => withRoot(async (q) => {
+            await q('CREATE TABLE Team (id INT PRIMARY KEY, name VARCHAR(20), city VARCHAR(20))');
+            await q('CREATE TABLE Member (id INT PRIMARY KEY, team INT, score INT)');
+            await q("INSERT INTO Team VALUES (1, 'a', 'x'), (2, 'b', 'y')");
+            await q('INSERT INTO Member VALUES (1, 1, 5), (2, 1, 7), (3, 2, 1)');
+            const nonGrouped = await q('SELECT city, COUNT(*) FROM Team GROUP BY name');
+            const noGroupBy = await q('SELECT name, COUNT(*) FROM Team');
+            const byKey = await q('SELECT t.*, SUM(m.score) FROM Team t JOIN Member m ON m.team = t.id GROUP BY t.id ORDER BY t.id');
+            const byEquality = await q("SELECT name, COUNT(*) FROM Team WHERE name = 'a'");
+            const distinctOrder = await q('SELECT DISTINCT name FROM Team ORDER BY city');
+            const limitIn = await q('SELECT id FROM Team WHERE id IN (SELECT team FROM Member LIMIT 1)');
+            const selfUpdate = await q('DELETE FROM Member WHERE id IN (SELECT id FROM Member WHERE score > 5)');
+            const derived = await q('DELETE FROM Member WHERE id IN (SELECT id FROM (SELECT id FROM Member WHERE score > 5) x)');
+            const mode = await q('SELECT @@sql_mode FROM dual');
+            return failed(nonGrouped, 'INVALID_ARGUMENT', "Expression #1 of SELECT list is not in GROUP BY clause and contains nonaggregated column 'twin.Team.city'")
+                && nonGrouped.error.message.includes('1055')
+                && failed(noGroupBy, 'INVALID_ARGUMENT', 'In aggregated query without GROUP BY') && noGroupBy.error.message.includes('1140')
+                && JSON.stringify(byKey.rows) === JSON.stringify([['1', 'a', 'x', '12'], ['2', 'b', 'y', '1']]) && ok(byEquality)
+                && failed(distinctOrder, 'INVALID_ARGUMENT', 'incompatible with DISTINCT') && distinctOrder.error.message.includes('3065')
+                && limitIn.error?.message.includes("doesn't yet support 'LIMIT & IN/ALL/ANY/SOME subquery'") === true
+                && failed(selfUpdate, 'INVALID_ARGUMENT', "You can't specify target table") && selfUpdate.error.message.includes('1093')
+                && ok(derived) && derived.rowsAffected === 1
+                && mode.rows[0][0] === 'ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION';
+        }),
+    },
+    {
+        id: 'planetscale.select.mysql_type_conversion', area: 'select', dimension: 'api', tier: 'common', expected: 'done',
+        title: "mixed comparisons follow manual 14.3: 'abc' = 0 and '1abc' = 1 are true, 'abc' + 1 is 1; NOT BETWEEN with a NULL bound; 1242 only when a subquery is evaluated; GROUP_CONCAT cut at 1024 bytes",
+        verify: () => withRoot(async (q) => {
+            await q('CREATE TABLE Word (id INT PRIMARY KEY, w VARCHAR(600))');
+            await q(`INSERT INTO Word VALUES (1, '${'x'.repeat(600)}'), (2, '${'y'.repeat(600)}')`);
+            const mixed = await q("SELECT 'abc' = 0, '1abc' = 1, 'abc' + 1, '10' > '9', 10 > '9', 10 NOT BETWEEN NULL AND 5 FROM dual");
+            const lazy = await q('SELECT (SELECT id FROM Word) FROM Word WHERE 1 = 0');
+            const eager = await q('SELECT (SELECT id FROM Word) FROM Word');
+            const concat = await q('SELECT LENGTH(GROUP_CONCAT(w)) FROM Word');
+            return JSON.stringify(mixed.rows[0]) === JSON.stringify(['1', '1', '1', '0', '1', '1'])
+                && ok(lazy) && lazy.rows.length === 0 && failed(eager, 'INVALID_ARGUMENT', 'Subquery returns more than 1 row')
+                && concat.rows[0][0] === '1024';
+        }),
+    },
+    {
+        id: 'planetscale.select.operator_forms', area: 'select', dimension: 'api', tier: 'common', expected: 'done',
+        title: "MySQL's other operator forms: `!`, XOR, the bit operators, MEMBER OF, LIKE … ESCAPE, JSON path ranges and `last`; JSON_ARRAYAGG(DISTINCT) and a bare `$**` are MySQL's errors",
+        verify: () => withRoot(async (q) => {
+            const r = await q("SELECT !1, 1 XOR 1, 5 & 3, 5 | 3, 5 ^ 3, 1 << 3, ~0, 'a_c' LIKE 'a!_c' ESCAPE '!', 2 MEMBER OF ('[1, 2]'), JSON_EXTRACT('[10, 20, 30]', '$[1 to last]'), JSON_EXTRACT('[10, 20, 30]', '$[last-1]') FROM dual");
+            const agg = await q('SELECT JSON_ARRAYAGG(DISTINCT 1) FROM dual');
+            const path = await q("SELECT JSON_EXTRACT('[1]', '$**') FROM dual");
+            return JSON.stringify(r.rows[0]) === JSON.stringify(['0', '0', '1', '7', '6', '8', '18446744073709551615', '1', '1', '[20, 30]', '20'])
+                && failed(agg, 'INVALID_ARGUMENT', 'syntax error') && failed(path, 'INVALID_ARGUMENT', 'Invalid JSON path expression');
+        }),
+    },
+    {
+        id: 'planetscale.select.information_schema_name_case', area: 'select', dimension: 'api', tier: 'common', expected: 'done',
+        title: 'INFORMATION_SCHEMA name columns compare case-insensitively, as the engine resolves table names (lower_case_table_names = 2)',
+        verify: () => withRoot(async (q) => {
+            await q('CREATE TABLE Mixed (Id INT PRIMARY KEY)');
+            const upper = await q("SELECT TABLE_NAME, COLUMN_NAME FROM information_schema.COLUMNS WHERE TABLE_NAME = 'MIXED' AND COLUMN_NAME = 'id'");
+            const read = await q('SELECT id FROM MIXED');
+            const lcn = await q('SELECT @@lower_case_table_names FROM dual');
+            return JSON.stringify(upper.rows) === JSON.stringify([['Mixed', 'Id']]) && ok(read) && lcn.rows[0][0] === '2';
+        }),
+    },
+    {
+        id: 'planetscale.transactions.access_mode', area: 'transactions', dimension: 'api', tier: 'common', expected: 'done',
+        title: 'SET [SESSION] TRANSACTION READ ONLY and START TRANSACTION READ ONLY are honoured (a write is errno 1792); SET TRANSACTION inside a transaction is 1568',
+        verify: () => withRoot(async (q) => {
+            await q('CREATE TABLE Ledger (id INT PRIMARY KEY)');
+            await q('SET TRANSACTION READ ONLY');
+            const nextOnly = await q('INSERT INTO Ledger VALUES (1)');
+            const spent = await q('INSERT INTO Ledger VALUES (2)');
+            await q('START TRANSACTION READ ONLY');
+            const read = await q('SELECT id FROM Ledger');
+            const inRo = await q('DELETE FROM Ledger');
+            const change = await q('SET TRANSACTION READ WRITE');
+            await q('ROLLBACK');
+            await q('SET SESSION TRANSACTION READ ONLY');
+            const session = await q('INSERT INTO Ledger VALUES (3)');
+            await q('SET SESSION TRANSACTION READ WRITE');
+            const back = await q('INSERT INTO Ledger VALUES (3)');
+            return failed(nextOnly, 'INVALID_ARGUMENT', 'Cannot execute statement in a READ ONLY transaction') && nextOnly.error.message.includes('1792')
+                && ok(spent) && ok(read) && failed(inRo, 'INVALID_ARGUMENT', 'READ ONLY transaction')
+                && failed(change, 'FAILED_PRECONDITION', "Transaction characteristics can't be changed while a transaction is in progress")
+                && failed(session, 'INVALID_ARGUMENT', 'READ ONLY transaction') && ok(back);
+        }),
+    },
+    {
+        id: 'planetscale.transactions.lost_on_restart', area: 'transactions', dimension: 'api', tier: 'core', expected: 'done',
+        title: 'a transaction left open by a process that is gone is rolled back, never committed over rows other sessions wrote once its locks were gone',
+        verify: async () => {
+            // The row locks live in the serving process. Serving a copy of the root reproduces a restart:
+            // the stored session is still in its transaction, but no lock of it survives.
+            const root = mkdtempSync(join(tmpdir(), 'planetscale-cap-'));
+            const restarted = mkdtempSync(join(tmpdir(), 'planetscale-cap-'));
+            try {
+                const exec = async (at, sql, sid) => executeSql({ root: at === 'a' ? root : restarted, occurredAt: AT }, sql, sid);
+                const first = await exec('a', 'CREATE TABLE Stock (id INT PRIMARY KEY, n INT)', null);
+                await exec('a', 'INSERT INTO Stock VALUES (1, 1)', first.session.id);
+                await exec('a', 'BEGIN', first.session.id);
+                await exec('a', 'UPDATE Stock SET n = 100 WHERE id = 1', first.session.id);
+                cpSync(root, restarted, { recursive: true });
+                const other = await exec('b', 'UPDATE Stock SET n = 7 WHERE id = 1', null);
+                const commit = await exec('b', 'COMMIT', first.session.id).then(() => null, (e) => e);
+                const after = await exec('b', 'SELECT n FROM Stock', other.session.id);
+                return commit instanceof SqlError && commit.errno === 2013 && JSON.stringify(after.outcome.rows) === '[["7"]]';
+            }
+            finally {
+                rmSync(root, { recursive: true, force: true });
+                rmSync(restarted, { recursive: true, force: true });
+            }
+        },
+    },
+    // ── conformance ─────────────────────────────────────────────────────────────────────────────
+    {
+        id: 'planetscale.conformance.endpoint_probe',
+        area: 'conformance', title: 'every claimed endpoint is probed with a real request and graded on its OUTCOME',
+        dimension: 'api', tier: 'common', expected: 'done',
+        verify: async () => {
+            const report = await checkPlanetscaleConformance();
+            return report.ok && report.endpointsChecked >= 5 && report.routerSurfaceChecked >= 9 && report.resourceTypesChecked === 4;
+        },
+    },
+    // ── native ──────────────────────────────────────────────────────────────────────────────────
+    // MySQL's binary wire protocol, served by `serve --mysql` as a FRONTEND of the same psdb state
+    // (planetscale-mysql.ts). Dub reaches one database through Prisma (native) AND the HTTP driver
+    // (volter-ai/twin#255); the census lists what a native client can send that the frontend refuses.
+    {
+        id: 'planetscale.native.shared_state',
+        area: 'native', title: 'a native MySQL client and the HTTP driver read and write ONE database through one root',
+        dimension: 'api', tier: 'core', expected: 'done',
+        verify: async () => {
+            const [{ createPlanetscaleTwinServer, createPlanetscaleTwinFetch }, { startPlanetscaleMysql }] = await Promise.all([import("./planetscale-server.js"), import("./planetscale-mysql.js")]);
+            const root = mkdtempSync(join(tmpdir(), 'planetscale-native-'));
+            const http = await createPlanetscaleTwinServer({ root });
+            const native = await startPlanetscaleMysql({ upstream: `http://twin:twin@127.0.0.1:${http.port}` });
+            // The HTTP door itself, not the store: the same POST the @planetscale/database client sends,
+            // handed IN-PROCESS to the fetch handler the server wraps — the pack issues no request of its own.
+            const wire = createPlanetscaleTwinFetch({ root });
+            const viaHttp = async (query) => {
+                const res = await wire(new Request(`http://twin${EXECUTE}`, { method: 'POST', body: JSON.stringify({ query }),
+                    headers: { authorization: `Basic ${Buffer.from('twin:twin').toString('base64')}`, 'content-type': 'application/json' } }));
+                const body = await res.json();
+                return (body.result?.rows ?? []).map((row) => unpackRow(row));
+            };
+            // The native door driven over a raw socket — the manifest never imports a vendor client
+            // (the smtp pack's precedent); planetscale-mysql.test.ts drives the unmodified mysql2 client.
+            const db = await rawMysqlClient(native.port);
+            try {
+                await db.query('CREATE TABLE shared (id BIGINT PRIMARY KEY, title TEXT)');
+                await db.query("INSERT INTO shared (id, title) VALUES (1, 'native')");
+                const read = await viaHttp('SELECT title FROM shared WHERE id = 1');
+                await viaHttp("UPDATE shared SET title = 'http' WHERE id = 1");
+                const rows = await db.query('SELECT title FROM shared WHERE id = 1');
+                await db.query('DELETE FROM shared WHERE id = 1');
+                const gone = await viaHttp('SELECT id FROM shared');
+                return JSON.stringify(read) === '[["native"]]' && JSON.stringify(rows) === '[["http"]]' && gone.length === 0;
+            }
+            finally {
+                db.end();
+                await native.stop();
+                http.stop();
+                rmSync(root, { recursive: true, force: true });
+            }
+        },
+    },
+    todo('planetscale.native.binary_time_results', 'native', 'TIME columns in a binary (prepared) result set', 'niche'),
+    todo('planetscale.native.cursors', 'native', 'COM_STMT_EXECUTE cursor flags and COM_STMT_FETCH', 'niche'),
+    todo('planetscale.native.send_long_data', 'native', 'COM_STMT_SEND_LONG_DATA streamed parameters', 'niche'),
+    todo('planetscale.native.large_packets', 'native', 'packets above 16 MiB split across the wire (refused by closing the connection today)', 'niche'),
+    todo('planetscale.native.caching_sha2_password', 'native', 'caching_sha2_password (MySQL 8 default) — only mysql_native_password is served', 'niche'),
+    todo('planetscale.native.multi_statements', 'native', 'CLIENT_MULTI_STATEMENTS batches', 'niche'),
+];
+export function planetscaleCapabilities() {
+    return checkCapabilities('planetscale', PLANETSCALE_CAPABILITIES);
+}