@volter/twin-planetscale 0.1.0

package/README.md

@@ -0,0 +1,473 @@
+# @volter/twin-planetscale
+
+A local, stateful, vendor-faithful twin of **PlanetScale's serverless driver API** — the
+`psdb.v1alpha1.Database` HTTP wire protocol that `@planetscale/database` speaks.
+
+PlanetScale's HTTP driver is not MySQL's binary protocol and it is not REST. It is a **Connect RPC
+service addressed with unary JSON POSTs**:
+
+```
+POST /psdb.v1alpha1.Database/CreateSession   {}                  -> { branch, user, session }
+POST /psdb.v1alpha1.Database/Execute         { query, session }  -> { session, result | error }
+POST /psdb.v1alpha1.Database/CloseSession    { session }         -> { session }
+```
+
+with `Authorization: Basic base64(username:password)`, and results packed as protojson
+`QueryResult`: base64-concatenated row bytes plus per-column **byte** lengths, `-1` for NULL, and
+every zero-valued field **omitted** (a DDL statement's whole result is `{}`).
+
+Behind that protocol is a **real database**: a stateful MySQL-subset engine folded out of the
+`@volter/world-core` kernel action log. `SELECT` returns what `INSERT` actually wrote; a duplicate key
+raises MySQL's own `errno 1062`; `AUTO_INCREMENT` survives deletes; and `conn.transaction()` — which
+is nothing but `BEGIN`/…/`COMMIT` over the client's own session — genuinely commits or rolls back.
+
+## Run it
+
+```bash
+bun run packages/twin/planetscale/src/cli.ts serve --port 8080 --root /tmp/psdb
+# then, from an app, with the CLIENT'S OWN public option — no patching:
+PLANETSCALE_DATABASE_URL="http://user:pass@127.0.0.1:8080"
+```
+
+`http://` is honoured by the client itself (`protocol()` in `dist/index.js` passes `http:` through
+and forces every other scheme to `https:`), so pointing an unmodified `connect({ url })` at the twin
+is *configuration*, not modification. That is exactly the shape
+[dub](https://github.com/dubinc/dub) reads in `apps/web/lib/planetscale/connection.ts`, which is the
+demand this pack was built for (volter-ai/twin#255).
+
+Under `volter-world`, no env var is needed at all: the pack declares the `*.psdb.cloud` host suffix
+on its descriptor, so the injector redirects an unmodified client's traffic to the twin.
+
+```bash
+bun run packages/twin/planetscale/src/cli.ts conformance   # endpoint probes + router-surface census
+```
+
+## Native MySQL frontend (`serve --mysql`)
+
+Dub reaches PlanetScale through **two clients over one database**: the HTTP driver above from its
+redirect middleware, and Prisma over MySQL's binary wire protocol from its API routes and its
+deleted-link fallback page (volter-ai/twin#255 named both). The pack serves that second interface
+as a **frontend of the same state owner**, never a second database:
+
+```bash
+# the HTTP twin owns the state; the frontend forwards every native connection to it
+bun run packages/twin/planetscale/src/cli.ts serve --port 8080 --database planetscale
+PLANETSCALE_TWIN_URL=http://127.0.0.1:8080 \
+  bun run packages/twin/planetscale/src/cli.ts serve --mysql --port 3306 --database planetscale
+DATABASE_URL="mysql://twin:twin@127.0.0.1:3306/planetscale"   # an unmodified Prisma/mysql2 client
+```
+
+`volter init` emits exactly this pair for an app whose Prisma datasource is MySQL beside the
+HTTP client (Dub), instead of a managed MySQL container. By hand, declare both as services, the
+HTTP twin first: services see the env of the
+services declared before them, so the `--mysql` service reads the HTTP twin's `PLANETSCALE_TWIN_URL`
+(the descriptor's `nativeTransport.upstreamEnv`) and refuses to start without it. `covers` credits
+the native `mysql:` connection to the `--mysql` service only, never to the HTTP twin by vendor name.
+`--username`/`--password` on the frontend are what native clients present AND what it presents to
+the HTTP twin unless the upstream URL carries its own credentials, so give both services the same
+pair (or none).
+
+Each native connection becomes one real psdb session (`CreateSession` on handshake, `CloseSession`
+on `COM_QUIT`/disconnect, so an unfinished transaction rolls back exactly as the HTTP driver's
+would). SQL text, results and errors come from the same engine: the frontend owns only framing,
+`mysql_native_password` authentication, `COM_STMT_PREPARE`/`EXECUTE`/`CLOSE`/`RESET` with typed
+binary parameters and binary result rows, `COM_PING`, `COM_INIT_DB`, `SET NAMES utf8mb4`,
+`SET autocommit` (an implicit transaction the frontend opens and closes through the same `BEGIN`/
+`COMMIT` the HTTP driver would send) and the `@@`/`@@session.` variables a driver handshake reads
+(the engine's own table, which the HTTP driver reads too: `@@sql_mode` is MySQL 8's default,
+`@@lower_case_table_names` is 2, `@@transaction_isolation` is `READ-COMMITTED`).
+A prepare never executes a mutation and opens no transaction. Everything else a native client can
+send is refused with a MySQL error, never silently accepted: other `SET`s (`SET [SESSION]
+TRANSACTION …` reaches the engine, below), other `@@` variables, cursors, multi-statements,
+`COM_STMT_SEND_LONG_DATA`, packets above 16 MiB and binary `TIME` results; the `native` area of
+the capability manifest lists them. If the HTTP twin replaces a connection's session (it was
+restarted), the frontend drops that connection instead of continuing on a different session. Prisma's `schema.table.column` qualification is accepted by the shared
+parser; the twin owns one schema.
+
+`prisma db push`, `prisma db pull` and Prisma's drift check read the database through
+`INFORMATION_SCHEMA` (below), so Prisma Migrate works against the frontend: Dub's full multi-file
+schema pushes into a fresh twin, a second push reports it already in sync, and `db pull` prints the
+same models back. The one field `db pull` cannot recover is a `Json` `@default`, which Prisma
+applies client-side on MySQL and never writes into the database.
+
+### `INFORMATION_SCHEMA`
+
+`INFORMATION_SCHEMA.<view>` (any case) resolves to MySQL 8's catalog views **derived on every read
+from the engine's own catalog** — never stored, so they cannot drift from the tables they describe
+(`src/planetscale-information-schema.ts`). `TABLES`, `COLUMNS` (MySQL 8.0.19+ `COLUMN_TYPE`
+rendering such as `int`, `tinyint(1)`, `datetime(3)`, `decimal(10,0)`; `COLUMN_KEY`; `EXTRA`
+`auto_increment`/`DEFAULT_GENERATED`; each character column's resolved charset and collation),
+`STATISTICS` (every `PRIMARY`/`UNIQUE`/`KEY`/`FULLTEXT` index with prefix length and direction),
+`TABLE_CONSTRAINTS` and `KEY_COLUMN_USAGE` are derived. The engine has no views, routines,
+triggers, `CHECK` constraints or foreign keys, so `VIEWS`, `ROUTINES`, `TRIGGERS`,
+`CHECK_CONSTRAINTS` and `REFERENTIAL_CONSTRAINTS` answer the truthful empty set; any other view is
+MySQL's errno 1109. The views are read by the same `SELECT` as stored tables (joins, `DISTINCT`,
+the `BINARY` prefix) and may be joined with them. `CREATE_TIME` is `NULL`; the size columns carry a
+fresh InnoDB table's one 16 KiB page per index. Table names keep their declared lettercase and are
+looked up case-insensitively (MySQL's `lower_case_table_names = 2`), and the catalog's identifier
+columns (`TABLE_NAME`, `COLUMN_NAME`, `INDEX_NAME`, …) compare the same way, so `FROM EV` and
+`WHERE TABLE_NAME = 'EV'` agree about a table declared `ev`. MySQL compares them under
+`utf8mb3_tolower_ci`; the twin uses `utf8mb3_general_ci`, which also folds accents.
+
+### Collations
+
+Strings compare the way MySQL 8 compares them: under a collation
+([Character Sets, Collations, Unicode](https://dev.mysql.com/doc/refman/8.0/en/charset.html)),
+implemented in `src/planetscale-collation.ts`. Collation changes comparison only; stored bytes and
+returned values stay exactly as written.
+
+- **Resolution** (§10.3.4–10.3.5). `CREATE TABLE` resolves the table's charset and collation from
+  its `CHARACTER SET`/`COLLATE` options, else the database default `utf8mb4` /
+  `utf8mb4_0900_ai_ci`; each character column (`CHAR`, `VARCHAR`, the `TEXT`s, `ENUM`, `SET`) from
+  its own `CHARACTER SET`/`COLLATE`/`BINARY` attribute, else the table's.
+  `INFORMATION_SCHEMA.COLUMNS.COLLATION_NAME` and `TABLES.TABLE_COLLATION` report the result, so a
+  Prisma schema (whose tables declare `utf8mb4_unicode_ci`) still reports in sync.
+- **Coercibility** (§10.8.4). A comparison runs under one collation chosen from its operands:
+  `COLLATE` (explicit) beats a column (implicit) beats a system constant beats a string literal,
+  which takes the connection collation `utf8mb4_0900_ai_ci` (`@@collation_connection`), beats a
+  number or temporal beats `NULL`. A binary string (`BINARY x`, `CAST(x AS BINARY)`, a
+  `VARBINARY`/`BLOB` column, a hex literal, `_binary'…'`) makes the comparison byte-wise; `utf8mb4`
+  absorbs `utf8mb3`; a `_bin` collation wins a tie; two different non-binary collations of equal
+  derivation are errno 1267 `Illegal mix of collations`. Unknown names are errno 1273/1115.
+  Numbers, temporals and JSON keep their own comparison.
+- **Where it applies**: `=`, `<>`, `<=>`, `<`/`>`/`BETWEEN`, `IN` (lists, row constructors,
+  subqueries), `LIKE`, simple `CASE`, `NULLIF`, join conditions (including the hash join),
+  `ORDER BY`, `GROUP BY`, `DISTINCT`, `MIN`/`MAX`, `COUNT(DISTINCT)` and the other `DISTINCT`
+  aggregates, the clustered primary-key order, and `PRIMARY`/`UNIQUE` enforcement and row locks: a
+  case variant of a stored email in a `_ci` column is errno 1062 (Prisma's P2002), and
+  `findUnique` by a mixed-case email finds the lowercase row.
+- **PAD attribute** (§10.10.1). The `0900` collations and `binary` are NO PAD (`'a ' = 'a'` is 0);
+  `utf8mb4_bin`, `utf8mb4_general_ci` and `utf8mb4_unicode_ci` are PAD SPACE. `LIKE` matches per
+  character under the collation and trailing spaces always count (§12.8.1): `'é' LIKE 'e'` is 1
+  under `utf8mb4_0900_ai_ci`, `'ß' LIKE 'ss'` is 0 although `'ß' = 'ss'` is 1.
+
+Modelled collations: `utf8mb4_0900_ai_ci`, `utf8mb4_0900_as_ci`, `utf8mb4_0900_as_cs`,
+`utf8mb4_0900_bin`, `utf8mb4_bin`, `utf8mb4_general_ci`, `utf8mb4_unicode_ci`,
+`utf8mb3_general_ci`, `utf8mb3_bin`, `utf8mb3_unicode_ci` and `binary` (`utf8` names are
+`utf8mb3`). Any other MySQL charset or collation is refused as `unsupported:`
+(`planetscale.collation.other_collations`).
+
+The weights are the published tables, generated into `src/planetscale-collation-weights.gen.ts` by
+`scripts/generate-collation-weights.ts`: DUCET 9.0.0 (all three levels, with its expansions and
+contractions) for the `0900` family, DUCET 4.0.0 primaries for `unicode_ci`, and MySQL 8.0's
+`my_unicase_default` sort table for `general_ci`. **What of the UCA weight tables is modelled:**
+U+0000–U+052F (Latin, IPA, spacing modifiers, combining diacritics, Greek, Cyrillic),
+U+1E00–U+1FFF, U+2000–U+206F, U+20A0–U+20CF, U+2100–U+218F, U+FB00–U+FB06 and U+FF01–U+FF5E. So
+case, accents, `ß` = `ss`, `æ` = `ae`, `ø` = `o` (`0900` only; `unicode_ci` keeps `ø` and `æ`
+distinct, as UCA 4.0.0 does), ligatures (`fi` = `fi`) and fullwidth ASCII fold as MySQL folds them.
+**What is not:** every other character (Armenian, Hebrew, Arabic, Indic scripts, kana, Hangul,
+CJK, emoji, …) takes the UCA implicit weight of its code point, which is MySQL's weight for an
+*unassigned* character: it equals only itself and sorts after the modelled ranges, so those
+scripts' case, width and accent equivalences and their relative order are not MySQL's
+(`planetscale.collation.uca_full_weight_table`, todo). `unicode_ci` and `general_ci` give every
+supplementary character the weight of U+FFFD, as MySQL does. The connector's refresh reads
+`DESCRIBE`, which carries no collation, so a pulled table's character columns compare under
+`utf8mb4_0900_ai_ci` (`planetscale.connector.column_collations`, todo).
+
+### Types and conversions
+
+A cell is stored as MySQL's text form of its value, and every expression has a MySQL type derived
+from its operands without reading a value (`src/planetscale-values.ts` holds the value arithmetic).
+The type decides how a value compares, sorts, groups and is computed, whether it comes from a
+column, `COALESCE`/`CASE`/`IF`/`GREATEST`, a subquery or arithmetic
+([Type Conversion in Expression Evaluation](https://dev.mysql.com/doc/refman/8.0/en/type-conversion.html)):
+
+- **Numbers.** Integers are exact at any size (BIGINT and BIGINT UNSIGNED beyond 2^53 included, in
+  keys, `DISTINCT`, `GROUP BY` and JSON). Arithmetic over exact operands is exact
+  ([Precision Math](https://dev.mysql.com/doc/refman/8.0/en/precision-math.html)): `+ - *` keep
+  BIGINT or DECIMAL with the manual's scales, `/` adds `div_precision_increment` (4) digits
+  (`9 / 2` is `4.5000`), and an overflow is errno 1690. A DOUBLE or string operand makes the
+  expression DOUBLE, printed as MySQL prints one (`0.1e0 + 0.2e0` is `0.30000000000000004`).
+  Division by zero is `NULL`, and errno 1365 in a value an `INSERT`/`UPDATE` stores.
+- **Mixed comparisons.** Strings under their collation, exact numbers exactly, a temporal against
+  a string as points in time, JSON against anything as JSON, every other mix as DOUBLE with a
+  string read by its numeric prefix: `'abc' = 0` and `'1abc' = 1` are 1, `'abc' + 1` is 1.
+- **Temporals.** `DATE`, `DATETIME(fsp)`, `TIMESTAMP(fsp)`, `TIME` and `YEAR` accept every literal
+  form MySQL accepts (any delimiter, the `T` separator @planetscale/database sends, the
+  undelimited `YYYYMMDD[hhmmss]` forms, a `+hh:mm` offset) and are stored canonically, rounded to
+  the column's fsp; they compare and sort in time.
+- **JSON.** A JSON column is validated and stored normalized (members in MySQL's order, integers
+  exact, a fractional number a DOUBLE); JSON compares per
+  [Comparison and Ordering of JSON Values](https://dev.mysql.com/doc/refman/8.0/en/json.html#json-comparison),
+  a non-JSON operand converted to JSON (`j->'$.name' = 'bob'` matches, JSON `2` is not `'2'`).
+- **Writes** convert to the column's type under MySQL 8's default `sql_mode`
+  (`ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION`):
+  a non-number is errno 1366 (1265 when only a prefix is numeric), a value out of range 1264,
+  DECIMAL is rounded to its scale and padded (`1.5` reads back `1.50`), an invalid or zero date
+  1292, invalid JSON 3140, a string or binary string longer than its column 1406, an ENUM/SET
+  value that is not a member 1265. `INSERT IGNORE` adjusts instead (a `NULL` into `NOT NULL` takes
+  the type's implicit default). A column `DEFAULT` is converted the same way at `CREATE TABLE`
+  (errno 1067 when it does not fit).
+- **`CAST(… AS type)` / `CONVERT(…, type)`** convert with MySQL's non-strict `CAST` rules.
+
+### The `SELECT` surface
+
+One executor serves stored tables, `INFORMATION_SCHEMA` views and derived tables:
+`[INNER|CROSS] JOIN`, `LEFT [OUTER] JOIN … ON` and comma joins with table aliases and `t.*`;
+scalar, `IN`/`NOT IN` and `[NOT] EXISTS` subqueries, correlated or not (Prisma's cursor
+pagination and relation filters); row constructors such as `(a, b) IN ((…), (…))` (Prisma's
+composite-key relation loads); `GROUP BY` (columns, select aliases, positions) with `HAVING` and
+`COUNT([DISTINCT])`, `SUM`, `AVG`, `MIN`, `MAX`, `JSON_ARRAYAGG` and `GROUP_CONCAT` typed as MySQL
+types them (`SUM`/`AVG` of an integer is `DECIMAL`); `DISTINCT`; `CASE`; `JSON_CONTAINS`,
+`JSON_EXTRACT`, `JSON_UNQUOTE`, `->`/`->>`, `JSON_TYPE`, `JSON_LENGTH`, `JSON_ARRAY`, `JSON_OBJECT`.
+A computed column is typed as MySQL 8 types the expression, and that type is its `Field.type`
+on psdb and its column type on the native wire: JSON functions and `JSON_ARRAYAGG` are `JSON`
+(charset 63, flags `BLOB|BINARY`); a scalar subquery takes its column's type; `COALESCE`, `IFNULL`,
+`IF` and `CASE` aggregate their operands' types by the manual's `CASE` rules (literal `NULL`s
+ignored, all-JSON stays `JSON`, JSON mixed with a string is `VARCHAR`, mixed temporals are
+`DATETIME`, a `DECIMAL` widens integers); `NULLIF` takes its first argument's type; a derived-table
+column keeps its inner expression's type. So `COALESCE((SELECT JSON_ARRAYAGG(…) …), JSON_ARRAY())`
+comes back parsed. Arithmetic, comparisons and every other function are typed the same way, so a
+column's type never depends on the rows it happened to return.
+Name resolution is MySQL's: innermost query first, errno 1052 for an ambiguous column, select
+aliases before columns in `ORDER BY`/`HAVING` and after them in `GROUP BY`. A read without
+`ORDER BY` returns rows in primary-key order, the order a full scan of InnoDB's clustered index
+returns; MySQL promises no order there, and an index scan in production may differ. The default
+`sql_mode`'s refusals are MySQL's: a grouped query's column that is not functionally dependent on
+the `GROUP BY` columns (through a table's `PRIMARY KEY` or `NOT NULL UNIQUE` key, or an equality
+in `WHERE` or `ON`) is errno 1055, or 1140 without `GROUP BY`; `SELECT DISTINCT … ORDER BY` a
+column not selected is 3065; `LIMIT` inside an `IN` subquery is 1235; an `UPDATE`/`DELETE` whose
+subquery reads its own table (not through a derived table) is 1093. `UNION`, `RIGHT`/`NATURAL`
+joins, `JOIN … USING`, window functions and `WITH ROLLUP` answer `unsupported:`.
+
+### Transactions and row locks
+
+A transaction buffers its writes in its session and applies them as one action at `COMMIT`;
+`ROLLBACK`, a dropped native connection or `CloseSession` discards them. Until it ends, the
+transaction holds exclusive row locks on every row it wrote and every row a locking read
+(`FOR UPDATE`, `FOR SHARE`, `LOCK IN SHARE MODE`) returned, and on the `PRIMARY`/`UNIQUE` values it
+claimed. Another session's write or locking read that needs one of them waits, then runs against
+what the holder committed, as a blocked InnoDB statement does; plain reads never wait. A wait that
+would close a cycle fails with errno 1213 and rolls the waiting transaction back; a wait past 50 s
+(`innodb_lock_wait_timeout`) fails with errno 1205; that wait is measured in real elapsed time,
+not on the World clock, which only advances between requests. `SET [SESSION] TRANSACTION READ
+ONLY` and `START TRANSACTION READ ONLY` are honoured (a write is errno 1792; `SET TRANSACTION`
+inside a transaction is 1568). `SET [SESSION] TRANSACTION ISOLATION LEVEL …` is accepted, but every
+level reads the latest committed rows plus the transaction's own writes (no `REPEATABLE READ`
+snapshot); `FOR SHARE` is held exclusively, and gap locks are not modeled. Row locks live in the
+serving process: a transaction left open when that process ends is rolled back, as MySQL rolls
+back a dead connection's, and its session's next statement fails with errno 2013 (a `ROLLBACK`
+succeeds), so its buffer can never commit over rows other sessions wrote meanwhile.
+
+`planetscale-mysql.test.ts` drives an unmodified `mysql2` client and the HTTP driver against one
+root: writes, updates and deletes through either are visible through the other, native transaction
+commit/rollback has the same shared visibility, and `SET autocommit = 0`'s implicit transaction
+and a prepare's non-execution are pinned. `planetscale.native.shared_state` holds the cross-client
+proof in the capability manifest too. The motivating #255 scenario — Dub's unmodified Next.js
+server with Prisma (native) serving the fallback page and the link create/delete API while the
+HTTP driver serves the redirect, all against one World — is proven by the story kept with the
+project's Dub evidence, the same place the redirect journey lives; the repo does not carry the
+app checkout.
+
+## The store doors: `GET /twin/store/tables` and `GET /twin/store/rows`
+
+The psdb wire is **Connect-JSON, and unary Connect is POST-only** — `Execute` included, so even a
+`SELECT` is a POST, and the handler refuses a GET on the RPC path before it authenticates (which
+is what ps-http-sim does too). Nothing in the vendor surface observes stored state with a GET.
+
+`GET /twin/store/tables` and `GET /twin/store/rows` are the twin's own **named, read-only,
+deterministic projections** over the same image `Execute` runs against (the twin programming
+model's store door; `GET /twin` names them under `stores`) — the schema with its persisted
+`AUTO_INCREMENT` watermark, and the rows with the engine's internal `rowid`. Both are sorted
+rather than left in `Map` insertion order, so the bytes are a function of the state and not of
+the order the log happened to arrive in. They are twin doors, not vendor surface: keyless, and
+deliberately **absent from the capability manifest**, since counting scaffolding PlanetScale does
+not publish would pad the coverage denominator. They are also what makes this pack's determinism
+checkable at the resource level — the gate's R9 replay reads them back on two fresh roots.
+
+## Refresh
+
+Refresh reads schema and bounded primary-key pages, then folds one observation through the kernel.
+`rowLimit` caps each returned page (default 500, maximum 10,000); `maxPages` caps pages per table
+(default 10, maximum 100). The result names `completeTables` and `partialTables`, with `removed`
+and `deltasAppended` counts. A full final page is partial even if it happens to contain the last row.
+`pullPlanetscaleSnapshot` exposes the same completion metadata alongside resources; the older
+`pullPlanetscaleDatabase` returns resources only.
+
+Like an incremental database scan, this is not a global point-in-time snapshot. Vitess documents
+[different isolation guarantees for single-shard and multi-shard transactions](https://vitess.io/docs/24.0/reference/compatibility/mysql-compatibility/).
+Before removing a missing keyed row from a completed table, refresh checks its primary key again.
+A row found by that check must agree with an already-scanned replacement identity; otherwise
+the refresh fails and should be retried. This handles case-insensitive key spelling changes.
+A completed table with a changed primary-key definition retires its old row addresses, including
+when a new key column was absent from the old rows. An incomplete scan that changes the primary-key
+definition is refused before recording anything; increase the scan bounds to complete that change. A keyless
+table can complete only in one short page. Partial tables never lose rows based on absence.
+An unfiltered successful table listing can also establish a dropped table's absence; selecting
+specific tables leaves all other tables untouched. Local edits remain in the kernel's overlay.
+
+All schema, page and absence-check queries must succeed before observation. Invalid limits,
+malformed responses, unsupported paging keys, collisions, and exhausted budgets fail without
+changing local observed state. Missing-row checks are capped separately by `maxMissingChecks`
+(default 100, maximum 1,000). Integer/decimal, text and binary primary keys support continuation;
+other key types can be read in a short first page but cannot be used for continuation or absence
+checks. Every query uses the rate guard. SQL `LIMIT` bounds returned rows, not rows examined or
+billed by the storage engine; this is not a metered-cost guarantee.
+
+## Deployment
+
+Local SQL statements and committed transactions are recorded as single kernel actions with
+their complete row changes. Deployment applies captured rows, rather than repeating the original
+predicate against a different database. This follows the distinction in MySQL's
+[row-based replication](https://dev.mysql.com/doc/refman/8.0/en/replication-sbr-rbr.html).
+Explicit primary-key values keep inserted rows addressable after refresh. Updates and deletes
+compare captured text using `CAST(... AS BINARY)`, so case and trailing spaces remain significant.
+Numeric fields use validated, unquoted numeric literals to avoid lossy string-to-number comparison. A conflicting or missing row rolls back the transaction. Deployment reserves the whole
+plan's call cost before starting, including session setup and rollback; large plans exceeding the
+current budget are refused before any vendor call.
+
+Session state is local bookkeeping. Schema changes and writes to tables without a primary key
+cannot be deployed through this adapter. Prepare the vendor schema and refresh it before authoring
+data changes; schema deployment remains a separate PlanetScale workflow. Deployment also refuses
+primary-key values whose stored representation is not preserved (such as integer `'01'`, automatic IDs requested as zero, `ZEROFILL`,
+padded binary keys, or decimal/float keys). Hash collisions are refused before local writes or refresh
+can collapse distinct rows. Commit also rechecks buffered identities against both the latest upstream and local
+views, so an intervening refresh or another session cannot hide a collision. Integer and decimal values must fit their declared range and scale
+without rounding. Values needing unmodeled storage conversion—including floating-point, temporal,
+JSON, or padding changes—are refused before any part of the plan executes.
+
+## Coverage
+
+**Partial, and honestly so.** The manifest
+(`src/planetscale-capabilities.ts`) is the *real vendor surface* as the denominator — MySQL's own
+statement families crossed with the psdb protocol **and with PlanetScale's management API, of which
+this pack models the slice its `api` lane serves** (below). Coverage reads low on purpose; growing the denominator later is
+success, not regression. Run `bun scripts/manifest-baseline-one.ts planetscale` for the live count.
+
+### What is modeled
+
+- **The psdb protocol** — CreateSession / Execute / CloseSession, HTTP Basic auth with the vendor's
+  own `401 {error:{code:'unauthenticated'}}` envelope, `Prepare` answering Connect's
+  `unimplemented` (which is the *vendor's* behaviour, reproduced), and the two distinct error
+  channels: a **query** error is HTTP **200** carrying `{error:{code,message}}` (the client
+  synthesizes status 400 from it), an **auth** failure is HTTP **401** carrying the same envelope.
+- **The wire codec** — byte-accurate row packing (a length is the BYTE count; getting this wrong
+  silently shifts every later column), `-1` NULL lengths, omitted `values` on an all-NULL row,
+  protojson zero-value omission, and the `Field` metadata (`type`/`charset`/`flags`/`columnType`)
+  the client's `cast` branches on. INT64/DECIMAL stay strings; INT32 becomes a number; JSON is
+  parsed; charset 63 becomes a `Uint8Array`.
+- **DDL** — `CREATE TABLE` (columns, types, `NOT NULL`, `DEFAULT`, `DEFAULT CURRENT_TIMESTAMP(fsp)`
+  read from the World clock at insert, `AUTO_INCREMENT`, `PRIMARY KEY`, `UNIQUE` (a composite one
+  constrains the tuple), secondary `KEY`/`INDEX` and `FULLTEXT` recorded in the catalog, the table's
+  default charset/collation), `IF NOT EXISTS` / `IF EXISTS`, `DROP TABLE`, `TRUNCATE`
+  (which resets `AUTO_INCREMENT`, unlike `DELETE`), `SHOW TABLES`, `DESCRIBE` / `SHOW COLUMNS`.
+- **DML** — `INSERT` (multi-row, `IGNORE`, `ON DUPLICATE KEY UPDATE` with MySQL's 1/2/0
+  `rowsAffected`), `SELECT` (`*`, projections, aliases, `WHERE` with the comparison/logical
+  operators plus `IN`/`LIKE`/`BETWEEN`/`IS NULL`, `ORDER BY`, `LIMIT`/`OFFSET`, `COUNT(*)`,
+  `FROM dual`), `UPDATE` (expression assignments, `LIMIT`, changed-rows-only counting), `DELETE`.
+- **Real transactions** — `BEGIN`/`COMMIT`/`ROLLBACK` as a per-session write buffer: statements
+  inside see their own uncommitted writes, another session sees none of them, and `ROLLBACK`
+  discards everything including buffered deletes and DDL.
+- **MySQL errors** — `errno`/`sqlstate` under the Vitess vtrpc code: 1146 no-such-table, 1050
+  table-exists, 1062 duplicate entry, 1048 not-null, 1054 unknown column, 1064 parse error, 1136
+  column-count mismatch, 1364 no default, 1290 read-only.
+- **Published system limits** — the 2048-table and 1017-column caps from
+  [planetscale.com/docs/reference/planetscale-system-limits](https://planetscale.com/docs/reference/planetscale-system-limits)
+  (read 2026-08-31), with the 100k-row and 64 MiB figures recorded alongside.
+- **A connector** — `pull` over an **injected** client (`SHOW TABLES` → `DESCRIBE` →
+  `SELECT * … ORDER BY … LIMIT n`), idempotent through the kernel observation path, with bounded
+  pagination and confirmed upstream deletions; and deployment of captured row changes as guarded inserts, updates and deletes.
+- **A fail-closed rate budget** — see below.
+- **A native MySQL frontend** — `serve --mysql`, the same state through MySQL's binary protocol for
+  Prisma/`mysql2` clients (see above).
+- **`INFORMATION_SCHEMA`** — the catalog views Prisma's MySQL describer reads (see above).
+- **Branches** — a password acts on the branch it was made on. `main` is the World's one image; every other branch
+  is a scope of its own (`_branch_table`/`_branch_row`, never pushed to a real branch), made with its parent's schema
+  and no rows, or with a backup's schema and rows. A branch with safe migrations refuses DDL (`ERROR 1105 (HY000):
+  direct DDL is disabled`). The twin's limit: every database's `main` shares the one image.
+- **The management API** — `api.planetscale.com/v1/organizations/…`, the pack's `api` lane (`api/src/`, derived from
+  PlanetScale's Swagger document): databases (create, read, settings, delete), branches (create from a parent or a
+  backup, read, list, delete; safe migrations on and off), a branch's passwords (create with a role and a `ttl`, list,
+  read, delete; the psdb data plane authenticates them and enforces their role), deploy requests (the branch's schema
+  diffed against its parent's, reviews, a serial queue, deploy into the base, a 30-minute revert, close), backups
+  (create, list with its filters, read, delete), backup policies (the Base plan's 12-hourly schedule and added ones),
+  the organization's audit log, and service tokens (create, list, delete; their accesses are granted on the
+  organization's settings page), each operation gated by the service token accesses its spec names. Its pages: the
+  sign-in, the service tokens settings and a deploy request's page with "Approve changes". Its records are the twin's
+  bookkeeping (`_database`, `_branch`, `_password`, `_deploy_request`, `_backup`, `_backup_policy`, `_audit_event`,
+  `_service_token`): never pushed to a real branch — and, like every bookkeeping entry, they do not show in `world log`
+  or `world diff`.
+
+### What is NOT modeled (filed as `todo`, not hidden)
+
+Entropy reads — `RAND()`/`UUID()` — and `ON UPDATE CURRENT_TIMESTAMP`, the 20 s transaction timeout
+and `ExecuteResponse.timing` are todos to be served from seeded entropy and the World's clock; today
+the functions are refused and `timing` is omitted. (The clock functions — `NOW(fsp)` and its
+synonyms, `UTC_TIMESTAMP()`, `CURDATE()`, no-argument `UNIX_TIMESTAMP()` — are served from the World
+clock's instant for the statement: `planetscale.functions.clock`.)
+
+`UNION`, window functions, `EXPLAIN`, index hints (`FORCE`/`USE`/`IGNORE INDEX`) and `PARTITION`
+selection, `ALTER TABLE` beyond `ADD COLUMN` and `DROP COLUMN`, foreign keys, views, generated columns, `SAVEPOINT`, the isolation
+levels' distinct read semantics, the rest of the date, string and JSON-modification function
+libraries, Connect's binary codecs and `StreamExecute`, and **PlanetScale's management API beyond the
+`api` lane's slice** (organizations, members, teams, webhooks, keyspaces, insights, workflows and the rest; every
+other path under `/v1/organizations` answers PlanetScale's 404). Every one has a manifest entry so the denominator stays honest.
+
+**Unmodeled surface is refused, never faked** — and it takes the *right* channel. Legal SQL this
+twin has not built (joins, `GROUP BY`, subqueries, aggregates, `DISTINCT`, set operations, index
+hints, `PARTITION`, `EXPLAIN`, `INTERVAL`, unknown functions, `ALTER TABLE … DROP INDEX`, `CREATE
+VIEW`, …) answers Vitess's own `unsupported: …` `UNIMPLEMENTED`; a genuinely *malformed* statement
+answers MySQL's `errno 1064`. Neither ever answers an empty result set, which would read to a caller
+as "ran fine, matched nothing".
+`planetscale.select.unmodeled_clauses_take_the_right_channel` and
+`planetscale.errors.unmodeled_statement` assert both directions.
+
+Three behaviours differ from real MySQL and are filed rather than papered over: this twin **buffers
+DDL inside a transaction** (MySQL implicitly commits before DDL), it **reuses an `AUTO_INCREMENT` id
+after a rollback** (InnoDB leaves a permanent gap), and it types an integer **literal** `INT64` and
+names the column by its literal text, where real Vitess normalizes the literal into the bind
+variable `:vtg1` and names the column after it. Real error messages also carry a **vttablet routing
+prefix** (`target: <keyspace>.<shard>.<tablet_type>: vttablet: rpc error: …`) that a twin with no
+keyspace or shard deliberately does not fabricate.
+
+### Adversarial review
+
+This pack was built under `../../../docs/contributing/adding-a-twin.md` §9. Round one refuted seven `done` claims and
+found five further defects by reading; every fix earned a **named pin capability**, listed in
+`planetscale-capabilities.test.ts` under *"every §9 round-one refutation has a pin capability"*, so
+re-introducing any of those bugs reddens something specific. The two sharpest were a legal `INSERT`
+of non-ASCII text into a `VARBINARY` column that made the table return HTTP 500 **forever**, and a
+connector that assigned row ids by their position in an unordered `SELECT` — which silently dropped
+a newly-observed real row onto a locally-created one on the second pull.
+
+### No UI mirror
+
+**The API is the product.** When someone does PlanetScale's core job they *write SQL from an
+application*, not click a dashboard: the whole reason `@planetscale/database` exists is that the
+database is reached from serverless code. PlanetScale's console is a provisioning, branching and
+insights dashboard — the *management* surface this pack does not model — not where the data work
+happens and not an agent navigation target. So this pack ships **no mirror and no UI capabilities**;
+coverage is API + connector. (Its `ui-scope.json` entry records `needsUi: false` for the same
+reason, and `planetscale-capabilities.test.ts` asserts that no `dimension: 'ui'` capability exists,
+so the decision is enforced rather than merely stated.)
+
+## Rate budget
+
+PlanetScale publishes **no** requests-per-second or per-minute limit for the psdb HTTP API — its
+system-limits page publishes only per-query and per-schema bounds. Per the repo's rule for exactly
+that case, the declaration says so plainly and stays **at** the kernel's austere fallback (60 units
+/ 60s at weight 2 = 30 calls per minute) rather than inventing a number, so it owes no
+`VENDOR_BURST_ANCHOR` figure. `transaction` is priced 4× because one guarded call runs the caller's
+entire callback behind it.
+
+The real cost driver is metered **rows read**, which a request-count ceiling can only bound crudely.
+That limitation is disclosed rather than hidden; the connector answers it separately by putting a
+hard `LIMIT` in every statement it issues.
+
+## Grounding
+
+- the **installed `@planetscale/database@1.20.1`** package source (`npm pack`) — the authoritative
+  wire contract, and its own test fixtures for the 401 and query-error envelopes;
+- [`github.com/mattrobenolt/ps-http-sim`](https://github.com/mattrobenolt/ps-http-sim) and the
+  `psdb.v1alpha1.Database` Connect service it implements (the simulator upstream dub devs run);
+- [planetscale.com/docs/reference/planetscale-system-limits](https://planetscale.com/docs/reference/planetscale-system-limits).
+
+See `spec-sources.json` for the full provenance record.
+
+## Fidelity
+
+`src/planetscale-sdk.integration.test.ts` drives the **real, unmodified** `@planetscale/database`
+client against the twin over real HTTP — constructed through its own `connect({ url })` and nothing
+else. No `fetch` override, no `cast`/`format` override, no monkey-patching. The client's own
+argument interpolation, base64 row decoder and type casting all run, so everything the test asserts
+is the client's own output.

package/api/src/fetch.ts

@@ -0,0 +1,50 @@
+// The management API lane of the planetscale pack (`api.planetscale.com/v1`), the lane's own dispatch: the pack's router
+// (../../src/planetscale-server.ts) sends every `/v1/organizations` request here, and the organization's service tokens
+// page (`app.planetscale.com/{organization}/settings/service-tokens`, screens/). The generated surface is PlanetScale's
+// own Swagger document; the service-token gate sits in front of the dispatch (token-gate.ts), then the kernel's
+// cross-cutting checks (read-only, a malformed body), then the handlers (semantics/). An operation this lane does not
+// serve answers PlanetScale's 404: the gap.
+import { bindSemantics, compileSurface, coreFor, createDerivedFetch, crossCutting, matchOperation, semanticsContext, type DerivedFetch, type DerivedOperation, type DerivedSurface } from '@volter/world-core';
+import surface from './generated/surface.gen.json' with { type: 'json' };
+import { manifest } from './manifest.ts';
+import { apiSemantics } from './semantics/index.ts';
+import { catchUp } from './semantics/time.ts';
+import { tokenGate } from './token-gate.ts';
+import { serviceTokensPage } from './screens/service-tokens.tsx';
+import { sessionFlow } from './screens/session.tsx';
+import { deployRequestPage } from './screens/deploy-request.tsx';
+
+const SCREEN: DerivedOperation = { id: 'ServiceTokensPage', method: 'POST', path: '/{organization}/settings/service-tokens', class: 'action' };
+const GATE: DerivedOperation = { id: 'TwinTokenGate', method: 'GET', path: '/v1/organizations', class: 'retrieve' };
+
+export function createPlanetscaleApiLaneFetch(options: { root?: string; readOnly?: boolean; clock?: () => string } = {}): DerivedFetch & { catchUp: (request: Request) => Promise<void> } {
+  const scope = { ...(options.root !== undefined ? { root: options.root } : {}), ...(options.clock ? { clock: options.clock } : {}) };
+  const derived = createDerivedFetch({
+    surface: surface as DerivedSurface,
+    handlers: bindSemantics(manifest, apiSemantics, scope),
+    core: coreFor(manifest, scope),
+    around: crossCutting(manifest, { readOnly: options.readOnly ?? false, ...scope }),
+    gap: () => Response.json({ code: 'not_found', message: 'Not Found' }, { status: 404 }),
+  });
+  const routes = compileSurface(surface as DerivedSurface);
+  const contextFor = (request: Request) => semanticsContext(manifest, request, SCREEN, scope);
+  return Object.assign(async (request: Request): Promise<Response> => {
+    // what the World clock has made due (a database turning ready, a backup running and completing) happens first, so
+    // every door reads the lane as it stands now (semantics/time.ts)
+    if (!options.readOnly) await catchUp(await contextFor(new Request(request.url)));
+    // the organization's settings page, where a person makes a token and grants its accesses (screens/service-tokens.tsx)
+    const screen = (await sessionFlow(request.clone(), await contextFor(new Request(request.url))))
+      ?? (await serviceTokensPage(request.clone(), contextFor)) ?? (await deployRequestPage(request, contextFor));
+    if (screen) return screen;
+    const url = new URL(request.url);
+    const matched = matchOperation(routes, request.method, url.pathname, url.searchParams, request.headers);
+    const ctx = await semanticsContext(manifest, new Request(request.url, { headers: request.headers }), matched?.operation ?? GATE, scope);
+    const call = { ...ctx.call, params: matched?.params ?? {} };
+    return tokenGate({ ...ctx, call }, request, matched?.operation.id) ?? derived(request);
+  }, {
+    owners: () => derived.owners(),
+    /** What the World clock has made due, caught up for a request another wire of the pack answers (psdb's Execute reads
+     *  the branch a deploy has just changed): a move time makes happens when any request next arrives. */
+    catchUp: async (request: Request): Promise<void> => { if (!options.readOnly) await catchUp(await contextFor(new Request(request.url))); },
+  });
+}