@volter/twin-planetscale 0.1.0

package/src/planetscale-mysql.ts

@@ -0,0 +1,339 @@
+// Native MySQL frontend for the SAME psdb state owner. No database or kernel writes live here.
+// Wire reference: https://dev.mysql.com/doc/dev/mysql-server/latest/PAGE_PROTOCOL.html
+// Prepared parameters/result rows follow page_protocol_com_stmt_execute.html and
+// page_protocol_binary_resultset.html; parameter types are cached per prepared statement.
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { parseStatement, SERVER_VERSION, SqlError, SYSTEM_VARIABLES, tokenize } from './planetscale-sql.ts';
+import type { TwinStream, TwinStreamConnection } from '@volter/world-core';
+import type { WireField, WireQueryResult, WireSession } from './planetscale-wire.ts';
+
+const MAX_PACKET = 16 * 1024 * 1024 - 2;
+const MAX_STATEMENTS = 1024;
+const CAPABILITIES = 1 | 4 | 8 | 512 | 8192 | 32768 | 131072 | 262144 | 524288;
+class MysqlError extends Error {
+  constructor(message: string, readonly errno = 1235, readonly state = '42000') { super(message); }
+}
+const integer = (value: number | bigint, bytes: number): Buffer => {
+  const out = Buffer.alloc(bytes);
+  if (bytes === 8) out.writeBigUInt64LE(BigInt.asUintN(64, BigInt(value)));
+  else out.writeUIntLE(Number(value), 0, bytes);
+  return out;
+};
+const length = (n: number): Buffer => n < 251 ? integer(n, 1) : n < 65536 ? Buffer.concat([Buffer.from([252]), integer(n, 2)])
+  : n < 16777216 ? Buffer.concat([Buffer.from([253]), integer(n, 3)]) : Buffer.concat([Buffer.from([254]), integer(n, 8)]);
+const string = (value: string | Buffer): Buffer => { const bytes = Buffer.isBuffer(value) ? value : Buffer.from(value); return Buffer.concat([length(bytes.length), bytes]); };
+
+class Reader {
+  offset = 0;
+  constructor(readonly buffer: Buffer) {}
+  bytes(n: number): Buffer {
+    if (!Number.isSafeInteger(n) || n < 0 || this.offset + n > this.buffer.length) throw new MysqlError('Malformed MySQL packet', 1835, 'HY000');
+    const value = this.buffer.subarray(this.offset, this.offset + n); this.offset += n; return value;
+  }
+  uint(n: number): number { return this.bytes(n).readUIntLE(0, n); }
+  len(): number { const first = this.uint(1); return first < 251 ? first : first === 252 ? this.uint(2) : first === 253 ? this.uint(3) : first === 254 ? Number(this.bytes(8).readBigUInt64LE()) : (() => { throw new MysqlError('Invalid length', 1835); })(); }
+  str(): Buffer { return this.bytes(this.len()); }
+  zero(): string { const end = this.buffer.indexOf(0, this.offset); if (end < 0) throw new MysqlError('Unterminated string', 1835); const result = this.bytes(end - this.offset).toString(); this.bytes(1); return result; }
+}
+
+/** Placeholders only in executable SQL. A prepare never executes a mutation. */
+export function mysqlPlaceholders(sql: string): number[] {
+  const positions: number[] = [];
+  let quote = ''; let comment = '';
+  for (let i = 0; i < sql.length; i++) {
+    const c = sql[i]!; const next = sql[i + 1];
+    if (comment === 'line') { if (c === '\n') comment = ''; continue; }
+    if (comment === 'block') { if (c === '*' && next === '/') { comment = ''; i++; } continue; }
+    if (quote) {
+      if (c === '\\' && quote !== '`') { i++; continue; }
+      if (c === quote) { if (next === quote) i++; else quote = ''; }
+      continue;
+    }
+    if (c === "'" || c === '"' || c === '`') quote = c;
+    else if (c === '#' || (c === '-' && next === '-')) { comment = 'line'; }
+    else if (c === '/' && next === '*') { comment = 'block'; i++; }
+    else if (c === '?') positions.push(i);
+  }
+  return positions;
+}
+function bind(sql: string, positions: number[], values: string[]): string {
+  let result = ''; let previous = 0;
+  positions.forEach((position, i) => { result += sql.slice(previous, position) + values[i]; previous = position + 1; });
+  return result + sql.slice(previous);
+}
+const quote = (value: Buffer): string => {
+  const text = value.toString('utf8');
+  if (!Buffer.from(text).equals(value)) return `X'${value.toString('hex')}'`;
+  return `'${text.replace(/\\/g, '\\\\').replace(/'/g, "''").replace(/\0/g, '\\0')}'`;
+};
+const TYPES: Record<string, number> = { NULL_TYPE: 6, INT8: 1, UINT8: 1, INT16: 2, UINT16: 2, INT24: 9, UINT24: 9,
+  INT32: 3, UINT32: 3, INT64: 8, UINT64: 8, FLOAT32: 4, FLOAT64: 5, TIMESTAMP: 7, DATE: 10, TIME: 11,
+  DATETIME: 12, YEAR: 13, DECIMAL: 246, TEXT: 252, BLOB: 252, VARCHAR: 253, VARBINARY: 253, CHAR: 254,
+  BINARY: 254, BIT: 16, ENUM: 254, SET: 254, JSON: 245 };
+function column(field: WireField): Buffer {
+  const fixed = Buffer.concat([integer(field.charset ?? 45, 2), integer(field.columnLength ?? 1024, 4),
+    integer(TYPES[field.type ?? 'NULL_TYPE'] ?? 253, 1), integer(field.flags ?? 0, 2), Buffer.from([0, 0, 0])]);
+  return Buffer.concat([string('def'), string(field.database ?? ''), string(field.table ?? ''), string(field.orgTable ?? ''),
+    string(field.name), string(field.orgName ?? field.name), Buffer.from([12]), fixed]);
+}
+function dateValue(reader: Reader, type: number): string {
+  const size = reader.uint(1);
+  if (size === 0) return "'0000-00-00 00:00:00'";
+  if (type === 11) {
+    if (size !== 8 && size !== 12) throw new MysqlError('Invalid TIME parameter', 1835);
+    const sign = reader.uint(1); const days = reader.uint(4); const hours = days * 24 + reader.uint(1);
+    const minute = reader.uint(1); const second = reader.uint(1); const micro = size === 12 ? reader.uint(4) : 0;
+    return `'${sign ? '-' : ''}${hours}:${String(minute).padStart(2, '0')}:${String(second).padStart(2, '0')}.${String(micro).padStart(6, '0')}'`;
+  }
+  if (![4, 7, 11].includes(size)) throw new MysqlError('Invalid date parameter', 1835);
+  const year = reader.uint(2); const month = reader.uint(1); const day = reader.uint(1);
+  const h = size >= 7 ? reader.uint(1) : 0; const m = size >= 7 ? reader.uint(1) : 0; const s = size >= 7 ? reader.uint(1) : 0;
+  const micro = size === 11 ? reader.uint(4) : 0;
+  return `'${year}-${String(month).padStart(2, '0')}-${String(day).padStart(2, '0')} ${String(h).padStart(2, '0')}:${String(m).padStart(2, '0')}:${String(s).padStart(2, '0')}.${String(micro).padStart(6, '0')}'`;
+}
+type Prepared = { sql: string; positions: number[]; types?: Array<{ type: number; unsigned: boolean }> };
+function parameters(reader: Reader, statement: Prepared): string[] {
+  const n = statement.positions.length;
+  if (n === 0) return [];
+  const nulls = reader.bytes(Math.ceil(n / 8));
+  const fresh = reader.uint(1);
+  if (fresh === 1) statement.types = Array.from({ length: n }, () => ({ type: reader.uint(1), unsigned: (reader.uint(1) & 128) !== 0 }));
+  else if (fresh !== 0) throw new MysqlError('Invalid parameter bind flag', 1835);
+  if (!statement.types) throw new MysqlError('Parameter types were not bound', 2031, 'HY000');
+  return statement.types.map(({ type, unsigned }, i) => {
+    if ((nulls[Math.floor(i / 8)]! & (1 << (i % 8))) || type === 6) return 'NULL';
+    const width = type === 1 ? 1 : type === 2 || type === 13 ? 2 : type === 3 || type === 9 ? 4 : 0;
+    if (width) { const bytes = reader.bytes(width); return String(unsigned ? bytes.readUIntLE(0, width) : bytes.readIntLE(0, width)); }
+    if (type === 8) { const bytes = reader.bytes(8); return String(unsigned ? bytes.readBigUInt64LE() : bytes.readBigInt64LE()); }
+    if (type === 4 || type === 5) { const bytes = reader.bytes(type === 4 ? 4 : 8); const value = type === 4 ? bytes.readFloatLE() : bytes.readDoubleLE(); if (!Number.isFinite(value)) throw new MysqlError('Non-finite parameter', 1366); return String(value); }
+    if ([7, 10, 11, 12].includes(type)) return dateValue(reader, type);
+    if ([0, 15, 16, 245, 246, 249, 250, 251, 252, 253, 254].includes(type)) return quote(reader.str());
+    throw new MysqlError(`Parameter type ${type} is not supported`);
+  });
+}
+function binaryCell(field: WireField, bytes: Buffer): Buffer {
+  const type = TYPES[field.type ?? 'NULL_TYPE'] ?? 253;
+  const text = bytes.toString(); const unsigned = ((field.flags ?? 0) & 32) !== 0;
+  const width = type === 1 ? 1 : type === 2 || type === 13 ? 2 : type === 3 || type === 9 ? 4 : 0;
+  if (width) { const out = Buffer.alloc(width); if (unsigned) out.writeUIntLE(Number(text), 0, width); else out.writeIntLE(Number(text), 0, width); return out; }
+  if (type === 8) return integer(BigInt(text), 8);
+  if (type === 4 || type === 5) { const out = Buffer.alloc(type === 4 ? 4 : 8); if (type === 4) out.writeFloatLE(Number(text)); else out.writeDoubleLE(Number(text)); return out; }
+  if ([7, 10, 12].includes(type)) {
+    const parts = text.match(/^(\d{4})-(\d\d)-(\d\d)(?:[ T](\d\d):(\d\d):(\d\d)(?:\.(\d+))?)?/);
+    if (!parts) throw new MysqlError('Invalid stored datetime', 1292, '22007');
+    const values = parts.slice(1, 7).map((part) => Number(part ?? 0)); const micro = Number((parts[7] ?? '').padEnd(6, '0').slice(0, 6));
+    return Buffer.concat([Buffer.from([type === 10 ? 4 : 11]), integer(values[0]!, 2), Buffer.from(values.slice(1, 3)),
+      ...(type === 10 ? [] : [Buffer.from(values.slice(3)), integer(micro, 4)])]);
+  }
+  if (type === 11) throw new MysqlError('Binary TIME results are not modeled');
+  return string(bytes);
+}
+
+export type MysqlFrontendOptions = { port?: number; upstream: string; database?: string; username?: string; password?: string; onQuery?: (sql: string) => void };
+/** The MySQL wire over any byte transport (the kernel's `TwinStream`), answering from the psdb HTTP
+ *  twin through `upstream`: the loopback listener below hands it a socket's bytes and `fetch`, a
+ *  hosted World a WebSocket's bytes and the twin's own in-process wire. */
+export type MysqlStreamOptions = { upstream: (request: Request) => Promise<Response>; authorization?: string; database?: string; username?: string; password?: string; onQuery?: (sql: string) => void };
+export function createPlanetscaleMysqlStream(options: MysqlStreamOptions): TwinStream {
+  const authorization = options.authorization ?? `Basic ${Buffer.from(`${options.username || 'twin'}:${options.password || 'twin'}`).toString('base64')}`;
+  let connectionId = 0;
+  return (socket) => {
+    let buffer = Buffer.alloc(0); let sequence = 0; let authenticated = false; let closing = false; let gone = false;
+    let session: WireSession | undefined; let autocommit = true; let queue = Promise.resolve(); let queued = 0;
+    let nextStatement = 0; const statements = new Map<number, Prepared>(); let longData: MysqlError | undefined;
+    const salt = randomBytes(20);
+    const end = (): void => { if (!gone) { gone = true; socket.end(); } };
+    const inTransaction = () => session?.vitessSession.inTransaction === true;
+    const status = () => (autocommit ? 2 : 0) | (inTransaction() ? 1 : 0);
+    const send = (payload: Buffer): void => {
+      if (payload.length > MAX_PACKET) throw new MysqlError('Result packet too large', 1153, '08S01');
+      socket.write(Buffer.concat([integer(payload.length, 3), integer(sequence++ % 256, 1), payload]));
+    };
+    const ok = (rows = 0, insert = 0): void => send(Buffer.concat([Buffer.from([0]), length(rows), length(insert), integer(status(), 2), integer(0, 2)]));
+    const eof = (): void => send(Buffer.concat([Buffer.from([254]), integer(0, 2), integer(status(), 2)]));
+    const fail = (error: unknown): void => {
+      // A statement the frontend parses itself (a prepare) fails with the engine's own errno.
+      const e = error instanceof MysqlError ? error : error instanceof SqlError ? new MysqlError(error.message, error.errno, error.sqlState) : new MysqlError(String(error), 1105, 'HY000');
+      send(Buffer.concat([Buffer.from([255]), integer(e.errno, 2), Buffer.from(`#${e.state}${e.message}`)]));
+    };
+    const rpc = async (method: string, body: Record<string, unknown>): Promise<Record<string, unknown>> => {
+      const response = await options.upstream(new Request(`http://twin/psdb.v1alpha1.Database/${method}`, {
+        method: 'POST', headers: { authorization, 'content-type': 'application/json' }, body: JSON.stringify(body), signal: AbortSignal.timeout(30000),
+      }));
+      const data = await response.json() as Record<string, unknown>;
+      const returned = data.session as WireSession | undefined;
+      if (returned && session && returned.vitessSession.sessionUUID !== session.vitessSession.sessionUUID) {
+        // The upstream twin no longer knows this session (it restarted or the session was closed):
+        // it minted a fresh one, so any buffered transaction is gone. A real server would have
+        // dropped the connection; do the same rather than continue on a silently different session.
+        session = undefined; end();
+        throw new MysqlError('Lost connection to the PlanetScale twin during query: the upstream session was replaced', 2013, 'HY000');
+      }
+      if (returned) session = returned;
+      const error = data.error as { message?: string } | undefined;
+      if (!response.ok || error) {
+        const message = error?.message ?? String(data.message ?? `HTTP ${response.status}`);
+        throw new MysqlError(message, Number(message.match(/errno (\d+)/)?.[1] ?? 1105), message.match(/sqlstate ([A-Z0-9]+)/)?.[1] ?? 'HY000');
+      }
+      return data;
+    };
+    const normalize = (query: string): string => {
+      // The engine's own system variables (the psdb wire reads the same table), with this
+      // connection's autocommit state.
+      const variables: Record<string, string> = Object.fromEntries(Object.entries({ ...SYSTEM_VARIABLES, max_allowed_packet: MAX_PACKET, autocommit: autocommit ? 1 : 0 })
+        .map(([k, v]) => [k, typeof v === 'number' ? String(v) : `'${String(v).replace(/'/g, "''")}'`]));
+      let out = query;
+      const tokens = tokenize(query);
+      for (let i = tokens.length - 1; i >= 0; i--) {
+        const token = tokens[i]!;
+        if (token.kind !== 'ident' || !token.value.startsWith('@@')) continue;
+        let name = token.value.slice(2).toLowerCase(); let end = token.pos - 1 + token.value.length;
+        // @@session.x / @@global.x / @@local.x: the tokenizer yields the scope, a '.', then the name.
+        const scoped = ['session', 'global', 'local'].includes(name) && tokens[i + 1]?.kind === 'punct' && tokens[i + 1]!.value === '.' && tokens[i + 2]?.kind === 'ident';
+        if (scoped) { const target = tokens[i + 2]!; name = target.value.toLowerCase(); end = target.pos - 1 + target.value.length; }
+        if (!(name in variables)) throw new MysqlError(`Unknown system variable '${name}'`, 1193, 'HY000');
+        out = out.slice(0, token.pos - 1) + variables[name] + out.slice(end);
+      }
+      return out;
+    };
+    const execute = async (query: string): Promise<WireQueryResult> => {
+      options.onQuery?.(query);
+      // Connection encoding is UTF-8. Other session settings stay loud instead of being no-ops.
+      if (/^SET NAMES (?:utf8mb4|utf8)\s*;?$/i.test(query.trim())) return {};
+      const auto = query.trim().match(/^SET (?:@@(?:session\.)?)?autocommit\s*=\s*([01])\s*;?$/i);
+      if (auto) { if (auto[1] === '1' && inTransaction()) await rpc('Execute', { query: 'COMMIT', session }); autocommit = auto[1] === '1'; return {}; }
+      if (!autocommit && !inTransaction() && !/^\s*(?:BEGIN|START TRANSACTION|COMMIT|ROLLBACK)\b/i.test(query)) await rpc('Execute', { query: 'BEGIN', session });
+      return read(query);
+    };
+    // A statement run for its result only: no autocommit bookkeeping (MySQL opens no transaction
+    // on a prepare), so the prepare probe below cannot start one.
+    const read = async (query: string): Promise<WireQueryResult> => (await rpc('Execute', { query: normalize(query), session })).result as WireQueryResult ?? {};
+    const result = (value: WireQueryResult, binary: boolean): void => {
+      const fields = value.fields ?? [];
+      if (!fields.length) { ok(Number(value.rowsAffected ?? 0), Number(value.insertId ?? 0)); return; }
+      send(length(fields.length)); fields.forEach((field) => send(column(field))); eof();
+      for (const row of value.rows ?? []) {
+        const data = Buffer.from(row.values ?? '', 'base64'); let offset = 0;
+        const nulls = Buffer.alloc(Math.ceil((fields.length + 2) / 8));
+        const values = row.lengths.map((n, i) => {
+          const count = Number(n);
+          if (count < 0) { nulls[Math.floor((i + 2) / 8)]! |= 1 << ((i + 2) % 8); return binary ? Buffer.alloc(0) : Buffer.from([251]); }
+          const bytes = data.subarray(offset, offset + count); offset += count;
+          return binary ? binaryCell(fields[i]!, bytes) : string(bytes);
+        });
+        send(Buffer.concat(binary ? [Buffer.from([0]), nulls, ...values] : values));
+      }
+      eof();
+    };
+    const closeSession = async (): Promise<void> => { if (session) { try { await rpc('CloseSession', { session }); } finally { session = undefined; } } };
+    const handshake = Buffer.concat([Buffer.from([10]), Buffer.from(`${SERVER_VERSION}\0`), integer(++connectionId, 4), salt.subarray(0, 8), Buffer.from([0]),
+      integer(CAPABILITIES & 65535, 2), Buffer.from([45]), integer(2, 2), integer(CAPABILITIES >>> 16, 2), Buffer.from([21]), Buffer.alloc(10), salt.subarray(8), Buffer.from('\0mysql_native_password\0')]);
+    send(handshake);
+    const command = async (payload: Buffer, incomingSequence: number): Promise<void> => {
+      sequence = (incomingSequence + 1) % 256;
+      const r = new Reader(payload);
+      if (!authenticated) {
+        const capabilities = r.uint(4); r.bytes(4); const charset = r.uint(1); r.bytes(23);
+        if ((capabilities & 512) === 0 || ![33, 45, 46, 224, 255].includes(charset)) throw new MysqlError('Unsupported handshake or character set', 1047, '08S01');
+        const username = r.zero(); const auth = capabilities & 32768 ? r.bytes(r.uint(1)) : Buffer.from(r.zero(), 'binary');
+        const database = capabilities & 8 ? r.zero() : '';
+        if (!username || !auth.length || options.username && username !== options.username) throw new MysqlError('Access denied', 1045, '28000');
+        if (options.password) {
+          const sha = (bytes: Buffer) => createHash('sha1').update(bytes).digest();
+          const first = sha(Buffer.from(options.password)); const scramble = sha(Buffer.concat([salt, sha(first)]));
+          const expected = Buffer.from(first.map((byte, i) => byte ^ scramble[i]!));
+          if (auth.length !== expected.length || !timingSafeEqual(auth, expected)) throw new MysqlError('Access denied', 1045, '28000');
+        }
+        if (options.database && database && database !== options.database) throw new MysqlError(`Unknown database '${database}'`, 1049, '42000');
+        await rpc('CreateSession', {}); authenticated = true; ok(); return;
+      }
+      const op = r.uint(1);
+      if (op === 1) { closing = true; await closeSession(); end(); return; }
+      if (op === 14) { ok(); return; }
+      if (op === 2) { const database = payload.subarray(1).toString(); if (options.database && database !== options.database) throw new MysqlError(`Unknown database '${database}'`, 1049); ok(); return; }
+      if (op === 3) { result(await execute(payload.subarray(1).toString()), false); return; }
+      if (op === 22) {
+        if (statements.size >= MAX_STATEMENTS) throw new MysqlError('Too many prepared statements', 1461);
+        const sql = payload.subarray(1).toString(); const positions = mysqlPlaceholders(sql);
+        const probe = normalize(bind(sql, positions, positions.map(() => '0')));
+        const parsed = parseStatement(probe);
+        const fields = parsed.kind === 'select' ? (await read(probe)).fields ?? [] : [];
+        const id = ++nextStatement; statements.set(id, { sql, positions });
+        send(Buffer.concat([Buffer.from([0]), integer(id, 4), integer(fields.length, 2), integer(positions.length, 2), Buffer.from([0]), integer(0, 2)]));
+        positions.forEach(() => send(column({ name: '?', type: 'VARCHAR' }))); if (positions.length) eof();
+        fields.forEach((field) => send(column(field))); if (fields.length) eof(); return;
+      }
+      if (op === 25) { statements.delete(r.uint(4)); return; }
+      if (op === 26) { const statement = statements.get(r.uint(4)); if (!statement) throw new MysqlError('Unknown prepared statement', 1243); statement.types = undefined; ok(); return; }
+      if (op === 24) { longData = new MysqlError('COM_STMT_SEND_LONG_DATA is not modeled'); return; } // the protocol defines no reply; the next execute answers
+      if (op === 23) {
+        if (longData) { const error = longData; longData = undefined; throw error; }
+        const statement = statements.get(r.uint(4)); if (!statement) throw new MysqlError('Unknown prepared statement', 1243);
+        if (r.uint(1) !== 0 || r.uint(4) !== 1) throw new MysqlError('Prepared cursors/iterations are not modeled');
+        const values = parameters(r, statement); // mysql2 reserves allocation padding for NULL parameters; it is not another parameter.
+        result(await execute(bind(statement.sql, statement.positions, values)), true); return;
+      }
+      throw new MysqlError(`MySQL command ${op} is not modeled`, 1047, '08S01');
+    };
+    const connection: TwinStreamConnection = {
+      settled: () => queue,
+      data(bytes) {
+        if (closing || gone) return;
+        buffer = Buffer.concat([buffer, Buffer.from(bytes)]);
+        if (buffer.length > MAX_PACKET + 4) { closing = true; end(); return; }
+        while (buffer.length >= 4) {
+          const size = buffer.readUIntLE(0, 3);
+          if (size > MAX_PACKET || ++queued > 64) { closing = true; end(); return; }
+          if (buffer.length < size + 4) { queued--; break; }
+          const seq = buffer[3]!; const payload = Buffer.from(buffer.subarray(4, size + 4)); buffer = buffer.subarray(size + 4);
+          queue = queue.then(async () => { if (!closing) await command(payload, seq); }).catch((error) => { if (!gone) fail(error); if (!authenticated) end(); }).finally(() => { queued--; });
+        }
+      },
+      close() {
+        closing = true; gone = true;
+        queue = queue.then(closeSession).catch(() => { /* upstream shutdown also disposes sessions */ });
+      },
+    };
+    return connection;
+  };
+}
+
+export async function startPlanetscaleMysql(options: MysqlFrontendOptions): Promise<{ port: number; stop: () => Promise<void> }> {
+  const { createServer } = await import('node:net');
+  const upstream = new URL(options.upstream);
+  if (!['http:', 'https:'].includes(upstream.protocol) || !['127.0.0.1', 'localhost', '[::1]'].includes(upstream.hostname)) throw new Error('PlanetScale native frontend requires a local HTTP twin URL');
+  const authorization = `Basic ${Buffer.from(`${decodeURIComponent(upstream.username) || options.username || 'twin'}:${decodeURIComponent(upstream.password) || options.password || 'twin'}`).toString('base64')}`;
+  upstream.username = ''; upstream.password = '';
+  const stream = createPlanetscaleMysqlStream({
+    upstream: async (request) => fetch(new URL(new URL(request.url).pathname, upstream), { method: request.method, headers: request.headers, body: await request.text(), signal: request.signal }),
+    authorization,
+    ...(options.database !== undefined ? { database: options.database } : {}),
+    ...(options.username !== undefined ? { username: options.username } : {}),
+    ...(options.password !== undefined ? { password: options.password } : {}),
+    ...(options.onQuery ? { onQuery: options.onQuery } : {}),
+  });
+  const connections = new Map<import('node:net').Socket, TwinStreamConnection>(); const pending = new Set<Promise<void>>();
+  const server = createServer((socket) => {
+    socket.setTimeout(28_800_000, () => socket.destroy());
+    const connection = stream({ write: (bytes) => { if (!socket.destroyed) socket.write(bytes); }, end: () => { socket.end(); } }, socket.remoteAddress ?? '');
+    connections.set(socket, connection);
+    socket.on('data', (chunk: Buffer) => connection.data(chunk));
+    socket.on('error', () => { socket.destroy(); });
+    socket.on('close', () => {
+      connections.delete(socket); connection.close();
+      const cleanup = connection.settled();
+      pending.add(cleanup); void cleanup.finally(() => pending.delete(cleanup));
+    });
+  });
+  await new Promise<void>((resolve, reject) => { server.once('error', reject); server.listen(options.port ?? 0, '127.0.0.1', () => { server.off('error', reject); resolve(); }); });
+  return { port: (server.address() as { port: number }).port, stop: async () => {
+    await new Promise<void>((resolve, reject) => { server.close((error) => error ? reject(error) : resolve()); for (const socket of connections.keys()) socket.destroy(); });
+    await Promise.all([...pending]);
+  } };
+}
+
+/** The MySQL wire a hosted World serves on its stream door: answered by the twin's own wire, whose
+ *  World token already admitted the stream. */
+export function createPlanetscaleTwinStream(options: { root?: string; wire: (request: Request) => Promise<Response> }): TwinStream {
+  return createPlanetscaleMysqlStream({ upstream: options.wire });
+}

package/src/planetscale-roles.ts

@@ -0,0 +1,71 @@
+// A branch password's ROLE, enforced on the psdb data plane. The management lane (api/) issues passwords with a role;
+// psdb authenticates a Basic credential against them and refuses what the role does not allow.
+//
+// PlanetScale's password-roles page (https://planetscale.com/docs/vitess/connecting/password-roles): Read-only "Can query
+// rows", Write-only "Can modify rows", Read/write "Can query and modify rows", Admin "All read/write permissions and can
+// modify schema"; its permissions table gives schema changes to Admin alone, inserts, updates and deletes to every role
+// but Read-only, and queries to every role but Write-only. Its examples of the refusal, verbatim:
+//   "Select command denied to user 'planetscale-writer-only for table 'customers' (ACL check error)"
+//   "Insert command denied to user 'planetscale-reader' for table 'customers' (ACL check error)"
+//   "Delete command denied to user 'planetscale-reader' for table 'customers' (ACL check error)"
+//   "DDL command denied to user 'planetscale-writer' for table my-new-table' (ACL check error)"
+// so the user a refusal names is the role's (reader: planetscale-reader, writer: planetscale-writer-only, readwriter:
+// planetscale-writer; admin is refused nothing), never the password's username.
+//
+// Where the page stops: it gives no errno or code. The message is MySQL 8.0's ER_TABLEACCESS_DENIED_ERROR, "%s command
+// denied to user '%s'@'%s' for table '%s'", errno 1142, SQLSTATE 42000 (dev.mysql.com, server error reference), so the
+// refusal takes that errno and SQLSTATE, and Vitess's PERMISSION_DENIED code. The twin judges a statement by its kind and
+// the table it names first (a subquery an UPDATE reads is not judged as a query); a statement naming no table (`SELECT 1`,
+// `SHOW TABLES`, BEGIN) and a read of INFORMATION_SCHEMA are allowed to every role.
+import { SqlError, type Statement, type TableFactor } from './planetscale-sql.ts';
+
+export type PasswordRole = 'reader' | 'writer' | 'readwriter' | 'admin';
+
+const ROLE_USER: Record<Exclude<PasswordRole, 'admin'>, string> = { reader: 'planetscale-reader', writer: 'planetscale-writer-only', readwriter: 'planetscale-writer' };
+const ALLOWED: Record<PasswordRole, ReadonlySet<'Select' | 'Insert' | 'Update' | 'Delete' | 'DDL'>> = {
+  reader: new Set(['Select']),
+  writer: new Set(['Insert', 'Update', 'Delete']),
+  readwriter: new Set(['Select', 'Insert', 'Update', 'Delete']),
+  admin: new Set(['Select', 'Insert', 'Update', 'Delete', 'DDL']),
+};
+
+const baseTable = (factor: TableFactor | undefined): string | undefined =>
+  factor && 'table' in factor && factor.schema?.toLowerCase() !== 'information_schema' ? factor.table : undefined;
+
+/** The command a statement is and the table it names first, or undefined for one no role is refused. */
+function commandOf(stmt: Statement): { command: Command; table: string } | undefined {
+  if (stmt.kind === 'select' || stmt.kind === 'update-multi') {
+    const t = baseTable(stmt.from?.[0]?.factor);
+    return t === undefined ? undefined : { command: stmt.kind === 'select' ? 'Select' : 'Update', table: t };
+  }
+  const command = TABLE_COMMAND[stmt.kind];
+  return command === undefined || !('table' in stmt) ? undefined : { command, table: stmt.table };
+}
+
+type Command = 'Select' | 'Insert' | 'Update' | 'Delete' | 'DDL';
+/** The command each single-table statement is, by kind. */
+const TABLE_COMMAND: Partial<Record<Statement['kind'], Command>> = {
+  describe: 'Select', 'show-create-table': 'Select', insert: 'Insert', update: 'Update', delete: 'Delete',
+  'create-table': 'DDL', 'create-table-select': 'DDL', 'drop-table': 'DDL', truncate: 'DDL', 'alter-add-columns': 'DDL', 'alter-drop-columns': 'DDL',
+};
+
+/** Whether a statement changes schema: what a branch with safe migrations refuses. */
+export const isDdl = (stmt: Statement): boolean => TABLE_COMMAND[stmt.kind] === 'DDL';
+
+/** A branch with safe migrations refuses DDL: "You'll see a `ERROR 1105 (HY000): direct DDL is disabled` message if you
+ *  attempt to make schema changes in a branch with safe migrations enabled"
+ *  (https://planetscale.com/docs/vitess/schema-changes/branching). Where the page stops: the message as the HTTP driver
+ *  reports it; the twin answers the page's errno, SQLSTATE and words. */
+export const directDdlDisabled = (): SqlError => new SqlError('direct DDL is disabled', 'FAILED_PRECONDITION', 1105, 'HY000');
+
+/** The refusal a role gives a statement, or undefined when the role allows it. */
+export function roleRefusal(role: PasswordRole, stmt: Statement): SqlError | undefined {
+  if (role === 'admin') return undefined;
+  const c = commandOf(stmt);
+  return c === undefined || ALLOWED[role].has(c.command) ? undefined : commandDenied(role, c);
+}
+
+/** MySQL's ER_TABLEACCESS_DENIED_ERROR (1142), as the password-roles page prints it. */
+function commandDenied(role: Exclude<PasswordRole, 'admin'>, c: { command: string; table: string }): SqlError {
+  return new SqlError(`${c.command} command denied to user '${ROLE_USER[role]}' for table '${c.table}' (ACL check error)`, 'PERMISSION_DENIED', 1142, '42000');
+}

package/src/planetscale-row.ts

@@ -0,0 +1,43 @@
+// Shared row identity and SQL quoting for local execution, observation and deployment.
+import { PULLED_ROWID_BASE, tableKey, type Cell } from './planetscale-sql.ts';
+
+export function pulledRowId(table: string, identity: string[], ordinal = 0): number {
+  // JSON tuple encoding distinguishes embedded separators and duplicate keyless rows.
+  let h = 0x811c9dc5;
+  const text = JSON.stringify([tableKey(table), identity, ordinal]);
+  for (let i = 0; i < text.length; i++) {
+    h ^= text.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return PULLED_ROWID_BASE + h;
+}
+
+export function keyedRowIdentity(table: { name: string; primaryKey: string[] }, cells: Record<string, Cell>): string[] {
+  const keys = Object.keys(cells);
+  const identity = table.primaryKey.map(k => k.toLowerCase()).sort().map(k => JSON.stringify([k, cells[keys.find(n => n.toLowerCase() === k) ?? k] ?? null]));
+  return identity;
+}
+
+export function quoteSqlLiteral(value: Cell): string {
+  if (value === null) return 'NULL';
+  const escaped = value.replace(/[\0\b\n\r\t\x1a\\"']/g, (c) => {
+    switch (c) {
+      case '"': return '\\"';
+      case "'": return "\\'";
+      case '\n': return '\\n';
+      case '\r': return '\\r';
+      case '\t': return '\\t';
+      case '\\': return '\\\\';
+      case '\0': return '\\0';
+      case '\b': return '\\b';
+      default: return '\\Z';
+    }
+  });
+  return `'${escaped}'`;
+}
+
+export const quoteIdent = (name: string): string => `\`${name.replace(/`/g, '``')}\``;
+
+export function keyedRowId(table: { name: string; primaryKey: string[] }, cells: Record<string, Cell>): number {
+  return pulledRowId(table.name, keyedRowIdentity(table, cells));
+}

package/src/planetscale-server.ts

@@ -0,0 +1,162 @@
+// planetscale twin HTTP server — serve the psdb wire twin over HTTP so the real
+// `@planetscale/database` client, pointed at it with nothing but its own public `url`/`host`
+// option, works UNMODIFIED.
+//
+// ── THE ONE THING AN INTEGRATOR MUST KNOW ─────────────────────────────────────────────────────
+// The client forces `https:` for every scheme except a literal `http:` (dist/index.js `protocol`),
+// so a local twin is reachable by passing `url: 'http://user:pass@127.0.0.1:PORT'` — that is
+// CONFIGURATION through the client's own public option, not a modification. `PLANETSCALE_DATABASE_URL`
+// (what dub reads) takes exactly that shape.
+//
+// ── THE INJECTED CLOCK ────────────────────────────────────────────────────────────────────────
+// `now` produces the `occurredAt` the kernel stamps each action with. It defaults to the wall clock
+// (a server has to), but a test passes its own so a run is reproducible. Nothing in a SERVED
+// response is derived from it except the kernel's own action ordinals — the response body is a pure
+// function of (request, stored state), which is why `timing` is never emitted.
+//
+// FETCH-FIRST (runtime contract R12b): the surface is the plain `createPlanetscaleTwinFetch` and
+// the SERVER is one line of `serveHttp` around it. The fetch is the derived dispatch over psdb's
+// proto (`createDerivedFetch`), with the pack's earlier fetch as its `legacy`: psdb replies carry
+// ONLY the handler's own headers (no default `content-type` is added), and the clock is injectable
+// per instance.
+import { serveHttp } from '@volter/world-core';
+import { createPlanetscaleApiLaneFetch } from '../api/src/fetch.ts';
+import { PSDB_METHODS, PSDB_SERVICE } from './planetscale-twin.ts';
+import { psdbHandlers, psdbInternal } from './semantics/psdb.ts';
+import surface from './generated/surface.gen.json' with { type: 'json' };
+import { DEFAULT_BRANCH, DEFAULT_DATABASE, STORE_NAMES, planetscaleStore, type StoreName } from './planetscale-store.ts';
+import { createDerivedFetch, worldNow, statefulTwinManifest, type DerivedFetch, type DerivedSurface } from '@volter/world-core';
+
+export type PlanetscaleServerOptions = {
+  root?: string;
+  port?: number;
+  readOnly?: boolean;
+  /** The username the twin demands. Omit to accept any non-empty username. */
+  username?: string;
+  /** The password the twin demands. Omit to accept any non-empty password (still 401s a missing one). */
+  password?: string;
+  /** The schema name the twin presents. */
+  database?: string;
+  /** The branch name `CreateSession` reports. */
+  branch?: string;
+  /** The injected clock. Returns the ISO instant this request "happens at". */
+  now?: () => string;
+};
+
+/** Options every planetscale-twin HTTP surface needs, independent of who owns the socket. */
+export interface PlanetscaleTwinFetchOptions {
+  root?: string;
+  readOnly?: boolean;
+  /** The username the twin demands. Omit to accept any non-empty username. */
+  username?: string;
+  /** The password the twin demands. Omit to accept any non-empty password (still 401s a missing one). */
+  password?: string;
+  /** The schema name the twin presents. */
+  database?: string;
+  /** The branch name `CreateSession` reports. */
+  branch?: string;
+  /** The injected clock. Returns the ISO instant this request "happens at". */
+  now?: () => string;
+}
+
+/** The twin's own doors, in front of the vendor's dispatch (docs/contributing/architecture.md, "Doors, screens and the
+ *  gap"): `GET /twin`, the discovery manifest, and `GET /twin/store/<tables|rows>`, the store door. Undefined for any
+ *  other request. */
+function twinDoors(request: Request, options: PlanetscaleTwinFetchOptions): Response | undefined {
+  if (request.method !== 'GET') return undefined;
+  const cleanPath = new URL(request.url).pathname.replace(/\/+$/, '') || '/';
+  if (cleanPath === '/twin') return discovery();
+  // THE STORE DOOR: `GET /twin/store/<tables|rows>` — this pack's own named, read-only,
+  // deterministic projection over stored state. The psdb wire is Connect-JSON and unary
+  // Connect is POST-ONLY, so even `Execute` (the vendor's read) is a POST. Nothing in the vendor
+  // surface can observe stored state with a GET, which is what this door is for — and it is what
+  // makes the pack's determinism checkable at the resource level (R9). Twin surface, not vendor
+  // surface: keyless.
+  if (cleanPath.startsWith('/twin/store/')) return storeDoor(cleanPath.slice('/twin/store/'.length), options);
+  return undefined;
+}
+
+/** `GET /twin`. The manifest EDUCATES: it names the store door beside the others, so a caller who only ever sees
+ *  `GET /twin` can find the one GET read this POST-only protocol has. */
+function discovery(): Response {
+  const manifest = statefulTwinManifest({
+    vendor: 'planetscale',
+    twinOf: 'PlanetScale (psdb.v1alpha1.Database HTTP wire protocol)',
+    stores: 'a real MySQL-subset schema and its rows, served over the psdb Connect-JSON envelope',
+  });
+  return Response.json({
+    ...manifest,
+    stores: STORE_NAMES,
+    doors: { ...(manifest.doors as Record<string, unknown>), store: 'GET /twin/store/<name>' },
+  });
+}
+
+/** `GET /twin/store/<tables|rows>`, the store door. */
+function storeDoor(name: string, options: PlanetscaleTwinFetchOptions): Response {
+  if (!(STORE_NAMES as readonly string[]).includes(name)) {
+    return Response.json({ error: 'unknown store', store: name, stores: STORE_NAMES }, { status: 404 });
+  }
+  return Response.json(planetscaleStore(name as StoreName, options.root, options.database ?? DEFAULT_DATABASE));
+}
+
+/**
+ * The gap: Connect's own answer for a request psdb does not serve. A path outside the service is `not_found` naming the
+ * service it asked for; a method the twin does not model is `unimplemented`, as Connect answers a method a service lacks;
+ * a psdb method asked with a verb other than POST is refused, since unary Connect is POST-only. StreamExecute is the gap:
+ * @planetscale/database never calls it (its dist/index.js sends only CreateSession and Execute) though ps-http-sim, the
+ * simulator PlanetScale's driver authors publish, serves it as a server stream of ExecuteResponse.
+ */
+function psdbGap(request: Request): Response {
+  const path = new URL(request.url).pathname.replace(/\/+$/, '') || '/';
+  const prefix = `/${PSDB_SERVICE}/`;
+  const json = (status: number, code: string, message: string): Response => Response.json({ code, message }, { status });
+  if (!path.startsWith(prefix)) return json(404, 'not_found', `unknown service: ${path.replace(/^\//, '').split('/')[0] ?? ''}`);
+  const method = path.slice(prefix.length);
+  if (request.method.toUpperCase() !== 'POST' && (PSDB_METHODS as readonly string[]).includes(method)) {
+    return json(405, 'unimplemented', `HTTP ${request.method.toUpperCase()} is not supported by this protocol`);
+  }
+  return json(404, 'unimplemented', `${PSDB_SERVICE}/${method} is not implemented`);
+}
+
+/** app.planetscale.com's pages the `api` lane serves (its sign-in, the service tokens settings and a deploy request's
+ *  page), and the World's door
+ *  that gives a person their PlanetScale password. */
+const SETTINGS_PAGE = /^\/(?:sign-in|_twin\/users\/[^/]+\/password|[^/]+\/settings\/service-tokens(?:\/.*)?|[^/]+\/[^/]+\/deploy-requests\/\d+(?:\/review)?)$/;
+
+/** The pack's wire (docs/contributing/architecture.md, "Protocol 3"): the twin's doors in front, the management API and
+ *  app.planetscale.com's pages to the `api` lane, and the derived dispatch over psdb's proto: CreateSession, Execute,
+ *  CloseSession and Prepare reach their handlers (semantics/psdb.ts), and everything else is the gap (psdbGap). No
+ *  `around`: manifest.ts says why. */
+export function createPlanetscaleTwinFetch(options: PlanetscaleTwinFetchOptions = {}): DerivedFetch {
+  const now = options.now ?? (() => worldNow());
+  const psdb = createDerivedFetch({
+    surface: surface as DerivedSurface,
+    handlers: psdbHandlers(options, now),
+    gap: (request) => psdbGap(request),
+  });
+  // api.planetscale.com's management API is the pack's `api` lane (../api/src/fetch.ts)
+  const api = createPlanetscaleApiLaneFetch({ ...(options.root !== undefined ? { root: options.root } : {}), readOnly: options.readOnly ?? false, clock: now });
+  return Object.assign(async (request: Request): Promise<Response> => {
+    const door = twinDoors(request, options);
+    if (door) return door;
+    const path = new URL(request.url).pathname;
+    if (path === '/v1/organizations' || path.startsWith('/v1/organizations/') || SETTINGS_PAGE.test(path)) {
+      try { return await api(request); } catch (error) { return psdbInternal(error); }
+    }
+    // a move the World clock makes happens when any request next arrives (a deploy finishing changes the branch psdb
+    // reads), so the management lane catches up before psdb answers
+    try { await api.catchUp(request); } catch (error) { return psdbInternal(error); }
+    return psdb(request);
+  }, { owners: () => psdb.owners() });
+}
+
+export async function createPlanetscaleTwinServer(options: PlanetscaleServerOptions = {}): Promise<{ port: number; stop: () => void }> {
+  const server = await serveHttp({
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    fetch: createPlanetscaleTwinFetch(options),
+  });
+  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}
+
+export { DEFAULT_BRANCH, DEFAULT_DATABASE };