@volter/twin-planetscale 0.1.0

package/dist/src/planetscale-sql.d.ts

@@ -0,0 +1,701 @@
+import { type Collation, type DT } from './planetscale-collation.js';
+/**
+ * One stored cell. ALWAYS the MySQL TEXT representation of the value, or null.
+ *
+ * This is not a shortcut — it is the wire's own model. psdb packs every column of every row as raw
+ * bytes with a per-column byte length (`row.lengths`/`row.values`), and the CLIENT casts those
+ * bytes by the field's declared type (dist/cast.js: INT32 → parseInt, FLOAT64 → parseFloat, JSON →
+ * JSON.parse, INT64 → left as a string, BLOB → Uint8Array). Storing text plus the column's type is
+ * therefore isomorphic to what the vendor stores as far as this protocol can ever observe.
+ */
+export type Cell = string | null;
+/** Vitess `query.Type` enum names, as protojson spells them — the values `Field.type` carries. */
+export declare const VITESS_TYPES: readonly ["NULL", "INT8", "UINT8", "INT16", "UINT16", "INT24", "UINT24", "INT32", "UINT32", "INT64", "UINT64", "FLOAT32", "FLOAT64", "TIMESTAMP", "DATE", "TIME", "DATETIME", "YEAR", "DECIMAL", "TEXT", "BLOB", "VARCHAR", "VARBINARY", "CHAR", "BINARY", "BIT", "ENUM", "SET", "GEOMETRY", "JSON", "EXPRESSION"];
+export type VitessType = (typeof VITESS_TYPES)[number];
+/** MySQL's binary collation id. `@planetscale/database`'s `cast` treats charset 63 as BINARY and
+ *  returns a `Uint8Array` for it (dist/cast.js `isBinary`), so getting this wrong changes the
+ *  JavaScript type an integrator receives. utf8mb4_general_ci is 45, which is what a text column
+ *  on a PlanetScale database reports. */
+export declare const BINARY_CHARSET = 63;
+export declare const UTF8MB4_CHARSET = 45;
+/** MySQL column flags, as `Field.flags` reports them (mysql_com.h). Only the ones this engine
+ *  actually sets are named; the rest are deliberately absent rather than guessed. */
+export declare const FLAG_NOT_NULL = 1;
+export declare const FLAG_PRI_KEY = 2;
+export declare const FLAG_UNIQUE_KEY = 4;
+export declare const FLAG_BLOB = 16;
+export declare const FLAG_UNSIGNED = 32;
+export declare const FLAG_BINARY = 128;
+export declare const FLAG_AUTO_INCREMENT = 512;
+/** The published PlanetScale system limits this engine ENFORCES, with the page they came from.
+ *  Live-read 2026-08-31 from planetscale.com/docs/reference/planetscale-system-limits. */
+export declare const PLANETSCALE_LIMITS: {
+    readonly source: "https://planetscale.com/docs/reference/planetscale-system-limits (read 2026-08-31)";
+    /** "Per-query rows returned, updated, or deleted: 100k". */
+    readonly maxRowsPerQuery: 100000;
+    /** "Tables per database schema (including views): 2048". */
+    readonly maxTablesPerSchema: 2048;
+    /** "Columns per table: 1017". */
+    readonly maxColumnsPerTable: 1017;
+};
+/** The version string both wires report (`VERSION()`, `@@version`, the native handshake). */
+export declare const SERVER_VERSION = "8.0.0-volter-twin";
+/** MySQL 8's default sql_mode (manual 7.1.11), which PlanetScale runs with and this engine
+ *  enforces: strict writes, no zero dates, division by zero an error on write, full GROUP BY. */
+export declare const SQL_MODE = "ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION";
+/**
+ * The system variables a client can read (`SELECT @@name`, `@@session.name`), with the values this
+ * engine's behaviour actually has: `lower_case_table_names` is 2 because table names keep their
+ * declared lettercase and compare case-insensitively; `transaction_isolation` is READ-COMMITTED
+ * because every statement reads the latest committed rows (no REPEATABLE READ snapshot). Any other
+ * name is MySQL's errno 1193.
+ */
+export declare const SYSTEM_VARIABLES: Record<string, string | number>;
+/**
+ * A query failure, carrying BOTH halves of what PlanetScale actually returns: the vtrpc code that
+ * lands in `ExecuteResponse.error.code` and the MySQL errno/sqlstate that MySQL clients key on.
+ *
+ * WHAT IS DELIBERATELY NOT FABRICATED: a real PlanetScale error message is prefixed with the
+ * vttablet routing context — `target: <keyspace>.<shard>.<tablet_type>: vttablet: rpc error: code =
+ * … desc = ` — which encodes the keyspace, shard and tablet type of the deployment that answered.
+ * A local twin has no keyspace or shard, so inventing that prefix would be asserting a fact about a
+ * cluster that does not exist. The MySQL half (message text, `(errno N) (sqlstate S)`) IS real and
+ * is reproduced verbatim; `planetscale.errors.vttablet_prefix` files the omission as a todo.
+ */
+export declare class SqlError extends Error {
+    /** the vtrpc code, protojson-spelled (`NOT_FOUND`, `INVALID_ARGUMENT`, `ALREADY_EXISTS`, …). */
+    readonly code: string;
+    readonly errno: number;
+    readonly sqlState: string;
+    constructor(message: string, 
+    /** the vtrpc code, protojson-spelled (`NOT_FOUND`, `INVALID_ARGUMENT`, `ALREADY_EXISTS`, …). */
+    code: string, errno: number, sqlState: string);
+}
+export declare const parseError: (position: number, near: string) => SqlError;
+/**
+ * An operation this twin does not model. Vitess's own refusal for a statement its planner cannot
+ * build — the message begins `unsupported: ` and the vtrpc code is UNIMPLEMENTED. A twin MUST take
+ * this path rather than answering an empty result set: a fabricated `[]` reads to the caller as
+ * "the query ran and matched nothing", which is the exact fake-success the bar forbids.
+ */
+export declare const unsupported: (what: string) => SqlError;
+export type ColumnDef = {
+    name: string;
+    /** the base type, uppercased and length-stripped: `VARCHAR`, `BIGINT`, `JSON`, … */
+    dataType: string;
+    /** the full MySQL rendering, as `Field.columnType` reports it: `varchar(255)`, `bigint unsigned`. */
+    columnType: string;
+    length: number | null;
+    unsigned: boolean;
+    nullable: boolean;
+    /** `undefined` = the column declared no DEFAULT (distinct from `DEFAULT NULL`, which is `null`). */
+    defaultValue?: Cell;
+    /** Was the DEFAULT written as a hex literal (`DEFAULT x'00ff'`)? Then it is already bytes and
+     *  `execCreateTable` must not UTF-8-encode it. */
+    defaultIsBinaryLiteral?: boolean;
+    /** `DEFAULT CURRENT_TIMESTAMP[(fsp)]`: the fractional-seconds precision. The value is read from
+     *  the World clock (`ExecOptions.now`) when a row is inserted, never from the wall clock. */
+    defaultCurrentTimestamp?: number;
+    /** An expression default, `DEFAULT (expr)` (MySQL 8.0.13+): its text as COLUMN_DEFAULT reports it,
+     *  with the literal value it evaluates to held in `defaultValue`. */
+    defaultExpression?: string;
+    autoIncrement: boolean;
+    primaryKey: boolean;
+    unique: boolean;
+    /** A character column's character set and collation, resolved at CREATE TABLE from the column's
+     *  own `CHARACTER SET`/`COLLATE`/`BINARY`, else the table's, else the database default. */
+    charset?: string;
+    collation?: string;
+    /** Parse-time only: the column's `BINARY` attribute (its charset's _bin collation). */
+    binaryAttribute?: boolean;
+    /** Parse-time only: how the DEFAULT was written — a number literal, a string literal, or a
+     *  parenthesised expression — which decides how CREATE TABLE converts it to the column's type. */
+    defaultLiteral?: 'number' | 'string' | 'expression';
+};
+/** One column of an index: its name, an optional prefix length and its direction. */
+export type IndexPart = {
+    name: string;
+    length?: number;
+    desc?: boolean;
+};
+/** A non-unique secondary index. It changes access paths, not results — this engine has one access
+ *  path (a scan) — but it is part of the catalog INFORMATION_SCHEMA.STATISTICS reports. */
+export type IndexDef = {
+    name: string;
+    columns: IndexPart[];
+    type: 'BTREE' | 'FULLTEXT';
+};
+export type TableDef = {
+    name: string;
+    columns: ColumnDef[];
+    /** column names forming the PRIMARY KEY, in declaration order. Empty = no primary key. */
+    primaryKey: string[];
+    /** each UNIQUE constraint as `{ name, columns }` — the name is what errno 1062 reports. `parts`
+     *  keeps each column's prefix length and direction for the catalog. */
+    uniques: Array<{
+        name: string;
+        columns: string[];
+        parts?: IndexPart[];
+    }>;
+    /** non-unique secondary and FULLTEXT indexes, in declaration order. */
+    indexes?: IndexDef[];
+    /** the table's declared default character set and collation (`DEFAULT CHARSET=… COLLATE=…`). */
+    charset?: string;
+    collation?: string;
+    /** the persisted AUTO_INCREMENT watermark. InnoDB 8.0 persists this across restarts, and so does
+     *  this engine — which is also what stops a delete-then-insert from reusing a retired id. */
+    autoIncrement: number;
+};
+export type RowRec = {
+    /** the engine's internal row identity — never a column, never exposed on the wire. Minted from
+     *  the MAX rowid present in the table (see `nextRowId`), never from a row COUNT: a count-mint
+     *  collides the instant a row above the count exists, which is what silently clobbers a
+     *  connector-pulled row. */
+    rowid: number;
+    cells: Record<string, Cell>;
+};
+/** The in-memory image one statement executes against. */
+export type Database = {
+    /** the schema/database name — what `Field.database` reports and what errno 1146 names. */
+    name: string;
+    tables: Map<string, TableDef>;
+    rows: Map<string, RowRec[]>;
+};
+export declare const emptyDatabase: (name: string) => Database;
+/** MySQL identifiers are case-insensitive on the platforms PlanetScale runs (lower_case_table_names
+ *  = 1), so tables are keyed lowercase while the DECLARED spelling is preserved for display. */
+export declare const tableKey: (name: string) => string;
+export declare function findTable(db: Database, name: string): TableDef;
+export declare function tableRows(db: Database, name: string): RowRec[];
+/**
+ * Row ids at or above this belong to the CONNECTOR: a pulled row's id is derived from the real
+ * row's own identity (see `planetscale-connector.ts`, `pulledRowId`), not from its position in a
+ * `SELECT`, so a re-pull re-derives the same subject and a new real row gets a new one.
+ *
+ * The band exists because the two minting rules must never meet. §9 round one reproduced the
+ * collision end-to-end when they shared a namespace: pull 1 → rowids 1,2; a local INSERT →
+ * `nextRowId` = 3; pull 2, now returning a third real row, positionally assigned it rowid 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. Disjoint bands make that unrepresentable rather than
+ * unlikely.
+ */
+export declare const PULLED_ROWID_BASE: number;
+/**
+ * The next LOCAL row id: MAX(existing local) + 1 — entropy-free, and collision-free in both
+ * directions. Pulled ids are skipped (they live in their own band, above), so a local mint can
+ * never land on a pulled row and a pull can never land on a local one.
+ *
+ * Never a row COUNT: a count-mint collides the moment a row above the count exists.
+ */
+export declare function nextRowId(rows: RowRec[]): number;
+/**
+ * The mapping the whole protocol rests on. `@planetscale/database`'s `cast` (dist/cast.js) branches
+ * ONLY on `field.type` and `field.charset`, so this table decides what JavaScript type an
+ * integrator receives: INT32 → `number`, INT64 → `string` (bigint-safe, deliberately NOT cast),
+ * FLOAT64 → `number`, JSON → a parsed object, DATETIME/DATE/TIME → the raw string, anything with
+ * charset 63 → `Uint8Array`, everything else → a decoded UTF-8 string.
+ */
+export declare function vitessTypeFor(column: {
+    dataType: string;
+    unsigned: boolean;
+}): VitessType;
+export declare const isNumericVitessType: (t: VitessType) => boolean;
+/**
+ * Does a column of this vitess type report charset 63?
+ *
+ * TWO families do, and conflating them was a §9 round-one defect: the NUMERIC types report binary
+ * because MySQL has no collation for a number, and the BLOB/BINARY/VARBINARY family reports it
+ * because the value genuinely IS bytes. `@planetscale/database`'s `cast` branches on
+ * `field.charset === 63` alone (dist/cast.js, `isBinary`), so a VARBINARY expression served with
+ * charset 45 comes back to the caller as a mojibake STRING instead of a `Uint8Array` — and its
+ * payload is UTF-8-expanded, so the byte lengths are wrong too.
+ */
+export declare const isBinaryCharsetType: (t: VitessType) => boolean;
+/**
+ * UTF-8-encode a string into this engine's byte-string form (one character per byte).
+ *
+ * A BINARY column's cell is always held this way, because that is what the wire packs verbatim and
+ * what `LENGTH()` counts. Text arriving for such a column is encoded HERE, at write time.
+ */
+export declare function toByteString(value: string): string;
+/** The wire-shape of one result column. Mirrors `@planetscale/database`'s exported `Field`. */
+export type Field = {
+    name: string;
+    type: VitessType;
+    table?: string;
+    orgTable?: string;
+    database?: string;
+    orgName?: string;
+    columnLength?: number;
+    charset?: number;
+    flags?: number;
+    columnType?: string;
+    /** Engine-internal, never on the wire: the collation a character result column compares under
+     *  (a derived table's column or an IN subquery's operand reads it back). */
+    collation?: string;
+};
+export declare function fieldForColumn(db: Database, table: TableDef, column: ColumnDef, alias?: string): Field;
+type TokKind = 'ident' | 'quoted-ident' | 'string' | 'number' | 'hex' | 'punct' | 'eof';
+type Token = {
+    kind: TokKind;
+    value: string;
+    pos: number;
+};
+/** `noBackslashEscapes`: the session's NO_BACKSLASH_ESCAPES SQL mode ("Disable the use of the backslash character (\\) as
+ *  an escape character within strings … backslash becomes an ordinary character like any other", manual 7.1.11). */
+export declare function tokenize(sql: string, noBackslashEscapes?: boolean): Token[];
+export type Expr = 
+/** `collation` is an introducer's (`_utf8mb4'x'`); a plain string literal takes the connection's. */
+{
+    kind: 'literal';
+    value: Cell;
+    hint: VitessType;
+    collation?: string;
+    hex?: true;
+}
+/** `expr COLLATE name`: an EXPLICIT collation for the comparison it takes part in. */
+ | {
+    kind: 'collate';
+    arg: Expr;
+    collation: string;
+} | {
+    kind: 'column';
+    table?: string;
+    name: string;
+} | {
+    kind: 'star';
+    table?: string;
+} | {
+    kind: 'unary';
+    op: 'NOT' | '-' | 'BINARY' | '~';
+    arg: Expr;
+}
+/** `x IS [NOT] TRUE | FALSE | UNKNOWN`: a truth test that is never NULL (manual 14.4.2). */
+ | {
+    kind: 'is';
+    arg: Expr;
+    value: 'TRUE' | 'FALSE' | 'UNKNOWN';
+    negated: boolean;
+}
+/** `x MEMBER OF (json_array)` (8.0.17+). */
+ | {
+    kind: 'member';
+    arg: Expr;
+    doc: Expr;
+}
+/** `CAST(x AS type)` / `CONVERT(x, type)` / `CONVERT(x USING charset)`: `to` is the target type. */
+ | {
+    kind: 'cast';
+    arg: Expr;
+    to: ColumnDef;
+    atTimeZone?: string;
+} | {
+    kind: 'binary';
+    op: string;
+    left: Expr;
+    right: Expr;
+} | {
+    kind: 'isnull';
+    arg: Expr;
+    negated: boolean;
+}
+/** `x IN (a, b)`, or `x IN (SELECT …)` when `subquery` is set (then `list` is empty). */
+ | {
+    kind: 'in';
+    arg: Expr;
+    list: Expr[];
+    negated: boolean;
+    subquery?: SelectStatement;
+    run?: SubqueryRun;
+} | {
+    kind: 'like';
+    arg: Expr;
+    pattern: Expr;
+    negated: boolean;
+    escape?: Expr;
+} | {
+    kind: 'between';
+    arg: Expr;
+    low: Expr;
+    high: Expr;
+    negated: boolean;
+} | {
+    kind: 'call';
+    name: string;
+    args: Expr[];
+    star: boolean;
+    distinct?: boolean;
+    order?: OrderTerm[];
+    separator?: string;
+}
+/** A row constructor, `(a, b)`, compared element-wise (`=`, `<`, `IN`). */
+ | {
+    kind: 'row';
+    items: Expr[];
+}
+/** A scalar subquery, `(SELECT …)`. `run` is attached when the statement is bound for execution. */
+ | {
+    kind: 'subquery';
+    select: SelectStatement;
+    run?: SubqueryRun;
+} | {
+    kind: 'exists';
+    select: SelectStatement;
+    run?: SubqueryRun;
+} | {
+    kind: 'case';
+    operand?: Expr;
+    whens: Array<{
+        when: Expr;
+        then: Expr;
+    }>;
+    otherwise?: Expr;
+}
+/** A column BOUND to one source of the executing statement: `src` indexes the row tuple and
+ *  `def` carries the column's declared type. Produced by binding, never by the parser. */
+ | {
+    kind: 'slot';
+    src: number;
+    col: string;
+    def: ColumnDef;
+};
+/** A bound subquery's evaluator: its result set, given the (outer) row it is evaluated for. */
+export type SubqueryRun = ((row: EvalRow) => {
+    fields: Field[];
+    rows: Cell[][];
+}) & {
+    /** the result columns, typed statically: known before (and without) running it. */
+    fields: () => Field[];
+};
+export type SelectItem = {
+    expr: Expr;
+    alias?: string;
+    text: string;
+};
+export type OrderTerm = {
+    expr: Expr;
+    desc: boolean;
+};
+/** One table in FROM: a stored table (or INFORMATION_SCHEMA view), or a DERIVED TABLE, a
+ *  parenthesised subquery MySQL requires an alias for (errno 1248), materialised once and then read
+ *  exactly as a table is. */
+export type TableFactor = {
+    table: string;
+    schema?: string;
+    alias?: string;
+} | {
+    derived: SelectStatement;
+    alias: string;
+};
+/** A joined table: `[INNER|CROSS] JOIN t [ON …]` or `LEFT [OUTER] JOIN t ON …`. */
+export type JoinClause = {
+    kind: 'inner' | 'left';
+    factor: TableFactor;
+    on?: Expr;
+};
+/** One comma-separated FROM item: a table factor and the joins chained onto it. */
+export type FromItem = {
+    factor: TableFactor;
+    joins: JoinClause[];
+};
+export type SelectStatement = {
+    kind: 'select';
+    items: SelectItem[];
+    distinct?: boolean;
+    from?: FromItem[];
+    where?: Expr;
+    groupBy?: Expr[];
+    having?: Expr;
+    order: OrderTerm[];
+    limit?: number;
+    offset?: number;
+    /** `FOR UPDATE` / `FOR SHARE` / `LOCK IN SHARE MODE`: a locking read. */
+    lock?: 'update' | 'share';
+};
+export type IsolationLevel = 'READ UNCOMMITTED' | 'READ COMMITTED' | 'REPEATABLE READ' | 'SERIALIZABLE';
+export type Statement = SelectStatement
+/** `alias`/`aliasColumns`: the new row's name in ON DUPLICATE KEY UPDATE (`VALUES … AS new [(a, b)]`, 8.0.19+). */
+ | {
+    kind: 'insert';
+    table: string;
+    columns: string[];
+    rows: Expr[][];
+    ignore: boolean;
+    onDuplicate?: Array<{
+        column: string;
+        value: Expr;
+    }>;
+    alias?: string;
+    aliasColumns?: string[];
+} | {
+    kind: 'update';
+    table: string;
+    alias?: string;
+    set: Array<{
+        table?: string;
+        column: string;
+        value: Expr;
+    }>;
+    where?: Expr;
+    order: OrderTerm[];
+    limit?: number;
+}
+/** The multiple-table form: `UPDATE table_references SET [t.]col = expr, … [WHERE …]` (execUpdateMulti). */
+ | {
+    kind: 'update-multi';
+    from: FromItem[];
+    set: Array<{
+        table?: string;
+        column: string;
+        value: Expr;
+    }>;
+    where?: Expr;
+} | {
+    kind: 'delete';
+    table: string;
+    where?: Expr;
+    order: OrderTerm[];
+    limit?: number;
+} | {
+    kind: 'create-table';
+    table: string;
+    ifNotExists: boolean;
+    columns: ColumnDef[];
+    primaryKey: string[];
+    uniques: TableDef['uniques'];
+    indexes: IndexDef[];
+    charset?: string;
+    collation?: string;
+} | {
+    kind: 'drop-table';
+    table: string;
+    ifExists: boolean;
+} | {
+    kind: 'create-table-select';
+    table: string;
+    ifNotExists: boolean;
+    select: SelectStatement;
+}
+/** `ALTER TABLE t ADD [COLUMN] col_def [FIRST | AFTER c], …`: the one alteration this engine models. */
+ | {
+    kind: 'alter-add-columns';
+    table: string;
+    adds: Array<{
+        column: ColumnDef;
+        first?: boolean;
+        after?: string;
+    }>;
+}
+/** `ALTER TABLE t DROP [COLUMN] c, …`: a statement of drops only. */
+ | {
+    kind: 'alter-drop-columns';
+    table: string;
+    drops: string[];
+} | {
+    kind: 'truncate';
+    table: string;
+} | {
+    kind: 'show-tables';
+} | {
+    kind: 'show-warnings';
+} | {
+    kind: 'show-create-table';
+    table: string;
+} | {
+    kind: 'describe';
+    table: string;
+}
+/** `SET [SESSION] TRANSACTION ISOLATION LEVEL …` / `SET [SESSION] TRANSACTION READ ONLY|WRITE`. */
+ | {
+    kind: 'set-transaction';
+    isolation?: IsolationLevel;
+    access?: 'READ WRITE' | 'READ ONLY';
+    scope: 'next' | 'session';
+}
+/** `SET @var := expr, …` and `SET [SESSION] sql_mode = expr`: the session's user variables and its SQL mode. */
+ | {
+    kind: 'set-vars';
+    user: Array<{
+        name: string;
+        value: Expr;
+    }>;
+    sqlMode?: Expr;
+    timeZone?: Expr;
+    names?: {
+        charset: string;
+        collation?: string;
+    };
+} | {
+    kind: 'begin';
+    access?: 'READ WRITE' | 'READ ONLY';
+} | {
+    kind: 'commit';
+} | {
+    kind: 'rollback';
+};
+/** A stored table's character columns with their collations filled in from the table's (for a
+ *  catalog written before columns carried their own). Lenient: an unrecognised stored name leaves
+ *  the column to the database default rather than failing the whole image. */
+export declare function withColumnCollations(table: TableDef): TableDef;
+export declare function parseStatement(sql: string, sqlMode?: string): Statement;
+/**
+ * Is this expression's RESULT binary — i.e. bytes rather than text?
+ *
+ * MySQL propagates binariness through an expression: `CONCAT(binary_col, …)` is binary, `UPPER` on
+ * a binary value is a no-op that stays binary, and a hex literal is binary. This ONE predicate
+ * governs storage (a source already in bytes is not re-encoded: `UPDATE b SET p = p` must not
+ * double the value), the result type and charset of an expression (charset 63, so the client
+ * returns a `Uint8Array`), and LENGTH / CHAR_LENGTH (bytes are counted, not re-encoded).
+ *
+ * `table` may be undefined (the constant-row `SELECT … FROM dual` path), where no column exists.
+ */
+export declare function staticBinary(e: Expr | undefined, table: TableDef | undefined): boolean;
+/** A row under evaluation: the table's cells, plus the schema needed to type a comparison. A
+ *  statement bound over several sources (joins, subqueries) reads its `slot` columns from `tuple`,
+ *  one cell record per source, where a missing record is a LEFT JOIN's null extension. */
+export type EvalRow = {
+    cells: Record<string, Cell>;
+    table?: TableDef;
+    database?: string;
+    tuple?: Tuple;
+    /** Evaluating a value an INSERT or UPDATE stores: under strict mode with ERROR_FOR_DIVISION_BY_ZERO
+     *  (MySQL 8's default sql_mode) a division by zero there is errno 1365, not NULL. */
+    write?: boolean;
+    /** ON DUPLICATE KEY UPDATE: the row the INSERT proposed, read by `VALUES(col)` and through the
+     *  row alias (`AS new` → `new.col`, or its column aliases, `AS new (m, n)` → `m`). */
+    values?: Record<string, Cell>;
+    valuesAlias?: string;
+    /** lowercased column alias → the table column it names (only with `AS new (m, n)`). */
+    valuesNames?: Map<string, string>;
+    /** The World clock's instant for the statement, which the clock functions read (INSERT values). */
+    now?: string;
+};
+export type Tuple = Array<Record<string, Cell> | undefined>;
+/** MySQL `LIKE`: `%` = any sequence, `_` = any single character, `\` escapes both, every other
+ *  character matched per character under `collation` (default: the connection's, utf8mb4_0900_ai_ci). */
+export declare function likeMatch(value: string, pattern: string, collation?: Collation): boolean;
+type Cls = 'int' | 'decimal' | 'double' | 'string' | 'binary' | 'temporal' | 'json' | 'null';
+/** An operand of a comparison: its type, the class it compares in, and (for strings) the
+ *  collation and derivation it brings. */
+type Operand = {
+    cls: Cls;
+    dt: DT;
+    type: ColumnDef | null;
+};
+/** The key a UNIQUE/PRIMARY KEY value of `column` is enforced (and locked) under: two values
+ *  collide exactly when the column's collation calls them equal (MySQL errno 1062). */
+export declare function uniqueKeyPart(column: ColumnDef | undefined, value: string): string;
+export declare function evalExpr(e: Expr, row: EvalRow): Cell;
+/** The context of a value being stored: MySQL's messages name the column and the row. */
+export type StoreContext = {
+    /** strict mode (MySQL 8's default STRICT_TRANS_TABLES): an invalid or out-of-range value is an
+     *  error; without it (INSERT IGNORE) the value is adjusted to the nearest valid one. */
+    strict: boolean;
+    /** 1-based row number within the statement, as the messages print it. */
+    row: number;
+    table: string;
+    /** the World clock's instant (a TIME stored into a DATETIME takes today's date). */
+    now?: string;
+};
+/** The value a NOT NULL column takes when a non-strict write (INSERT IGNORE) supplies NULL: its
+ *  type's implicit default (manual 13.6 "Data Type Default Values"). */
+export declare function implicitDefault(col: ColumnDef): string;
+/**
+ * Convert a value to `col`'s type for storage, as MySQL 8 does under its default sql_mode
+ * (STRICT_TRANS_TABLES, NO_ZERO_IN_DATE, NO_ZERO_DATE; manual 7.1.11 "Server SQL Modes", 13
+ * "Data Types"): integers rounded and range-checked (1264), strings that are not numbers refused
+ * (1366, or 1265 when only a prefix is numeric), DECIMAL rounded to its scale and padded, DOUBLE
+ * and FLOAT stored at their precision, temporals read from any accepted spelling and stored
+ * canonically at the column's fsp (1292 for an unreadable or zero date), JSON validated and stored
+ * normalized (3140), strings and binary strings checked against their length (1406), ENUM/SET
+ * checked against their members (1265). Without strict mode the value is adjusted instead.
+ */
+export declare function storeValue(col: ColumnDef, value: Cell, src: Operand, c: StoreContext): Cell;
+/** What one statement produced, in engine terms. `planetscale-wire.ts` turns this into protojson. */
+export type QueryOutcome = {
+    fields: Field[];
+    rows: Cell[][];
+    rowsAffected: number;
+    insertId: number;
+    /** subject writes the caller must persist. Empty for a pure read. */
+    writes: Write[];
+    /** the transaction verb this statement is, if any — the store owns the session bookkeeping. */
+    transaction?: 'begin' | 'commit' | 'rollback';
+    /** START TRANSACTION's access mode, or SET TRANSACTION's characteristics, for the store to hold. */
+    access?: 'READ WRITE' | 'READ ONLY';
+    setTransaction?: {
+        scope: 'next' | 'session';
+        access?: 'READ WRITE' | 'READ ONLY';
+        isolation?: IsolationLevel;
+    };
+    /** the stored rows a locking read (`FOR UPDATE` / `FOR SHARE`) returned; the store locks them. */
+    locked?: Array<{
+        table: string;
+        rowid: number;
+    }>;
+    /** the session's variables after a SET of them, for the caller to carry in the session it answers */
+    vars?: SessionVars;
+};
+export type Write = {
+    kind: 'table';
+    table: TableDef;
+} | {
+    kind: 'drop-table';
+    table: string;
+} | {
+    kind: 'row';
+    table: string;
+    row: RowRec;
+} | {
+    kind: 'delete-row';
+    table: string;
+    rowid: number;
+};
+export type ExecOptions = {
+    /** `readOnly` twins refuse every write with MySQL's own errno 1290 — never a silent no-op. */
+    readOnly?: boolean;
+    /** The World clock's instant for this statement (ISO-8601). `DEFAULT CURRENT_TIMESTAMP` reads
+     *  it; without it such a default is refused rather than taken from the wall clock. */
+    now?: string;
+    /** The statement runs in a READ ONLY transaction: a write is MySQL's errno 1792. */
+    transactionReadOnly?: boolean;
+    /** The session's user variables and SQL mode, as the client's session carries them (SessionVars). */
+    vars?: SessionVars;
+};
+/** A user variable's value and the type it holds (manual 11.4: "User variables can be assigned a value from a limited set
+ *  of data types: integer, decimal, floating-point, binary or nonbinary string, or NULL value"), as a Vitess BindVariable
+ *  types it. */
+export type UserVariable = {
+    value: Cell;
+    type: VitessType;
+};
+/** What a session holds between statements: its user variables (by lowercased name; manual 11.4: "User variable names are
+ *  not case-sensitive") and its sql_mode, when it set one. */
+export type SessionVars = {
+    user: Record<string, UserVariable>;
+    sqlMode?: string;
+    collationConnection?: string;
+    timeZone?: string;
+    warnings?: Array<{
+        level: string;
+        code: number;
+        message: string;
+    }>;
+};
+export declare function execStatement(db: Database, stmt: Statement, opts?: ExecOptions): QueryOutcome;
+export type SelectPlan = {
+    correlated: boolean;
+    /** the result columns, typed statically from the select list (no row is read to type them). */
+    fields: () => Field[];
+    execute: (outer: Tuple | undefined) => {
+        fields: Field[];
+        rows: Cell[][];
+        locked: Array<{
+            table: string;
+            rowid: number;
+        }>;
+    };
+};
+/** Parse and execute in one step — the entry point the store and every test use. */
+export declare function runSql(db: Database, sql: string, opts?: ExecOptions): QueryOutcome;
+export {};