@volter/twin-planetscale 0.1.0

package/dist/src/index.d.ts

@@ -0,0 +1,26 @@
+export { handlePlanetscaleTwinRequest, planetscaleTwinSnapshot, extractBasicCredential, PSDB_SERVICE, PSDB_METHODS, PLANETSCALE_UNAUTHENTICATED, PLANETSCALE_RESOURCE_TYPES, } from './planetscale-twin.js';
+export type { PlanetscaleRequest, PlanetscaleResponse, PlanetscaleTwinSnapshot } from './planetscale-twin.js';
+export { runSql, execStatement, parseStatement, tokenize, evalExpr, likeMatch, emptyDatabase, findTable, tableRows, tableKey, nextRowId, vitessTypeFor, fieldForColumn, isNumericVitessType, unsupported, parseError, SqlError, PLANETSCALE_LIMITS, VITESS_TYPES, BINARY_CHARSET, UTF8MB4_CHARSET, FLAG_NOT_NULL, FLAG_PRI_KEY, FLAG_UNIQUE_KEY, FLAG_UNSIGNED, FLAG_BINARY, FLAG_AUTO_INCREMENT, } from './planetscale-sql.js';
+export type { Cell, ColumnDef, Database, Expr, Field, QueryOutcome, RowRec, Statement, TableDef, VitessType, Write } from './planetscale-sql.js';
+export { packRow, unpackRow, packBytes, encodeCell, encodeField, encodeQueryResult, makeSession, sessionIdOf, } from './planetscale-wire.js';
+export type { WireField, WireRow, WireQueryResult, WireError, WireSession, WireExecuteResponse, WireCreateSessionResponse } from './planetscale-wire.js';
+export { SERVICE, DEFAULT_BRANCH, DEFAULT_DATABASE, loadState, readDatabase, executeSql, createSession, closeSession, mintSessionId, applyWritesToImage, } from './planetscale-store.js';
+export type { ExecuteContext, ExecuteResult, SessionState, PlanetscaleResourceType } from './planetscale-store.js';
+export { createPlanetscaleTwinFetch, createPlanetscaleTwinServer } from './planetscale-server.js';
+export { createPlanetscaleMysqlStream, createPlanetscaleTwinStream } from './planetscale-mysql.js';
+export type { PlanetscaleServerOptions, PlanetscaleTwinFetchOptions } from './planetscale-server.js';
+export { mapTable, mapRow, mapDescribeRow, encodeCellValue, quoteSqlLiteral, quoteIdent, pollTimestamp, pullPlanetscaleTables, pullPlanetscaleDatabase, pullPlanetscaleSnapshot, type PlanetscalePullReport, type PlanetscaleRefreshReport, syncPlanetscaleFromReal, syncPlanetscaleFromRemote, performPlanetscaleAction, pushPlanetscaleAction, pushPlanetscaleActions, } from './planetscale-connector.js';
+export type { PlanetscaleLikeClient, PlanetscaleRealTable, PlanetscaleExecutedQuery, PlanetscalePullOptions } from './planetscale-connector.js';
+export { PLANETSCALE_BUDGETED_METHODS, PLANETSCALE_BUDGET_CEILING, PLANETSCALE_BUDGET_MAX_RETRY_AFTER_S, PLANETSCALE_BUDGET_WINDOW_MS, PLANETSCALE_CALL_WEIGHTS, PLANETSCALE_RATE_BUDGET, PlanetscaleBudget, PlanetscaleBudgetError, planetscaleBudgetPath, planetscaleCallWeight, planetscaleClientBudget, guardPlanetscaleClient, } from './planetscale-budget.js';
+export type { PlanetscaleBudgetErrorKind, PlanetscaleBudgetOptions, PlanetscaleBudgetReservation, PlanetscaleBudgetSnapshot, PlanetscaleBudgetedOptions, } from './planetscale-budget.js';
+import { type TwinPack } from '@volter/world-core';
+export declare const pack: TwinPack;
+/**
+ * How a journey reads an answer of this pack (a step's `view`, scripts/behavior-journey.ts). `rows` decodes an Execute
+ * answer into what MySQL's client prints for it: `fields`, the result's column names in order; `rows`, each row as an
+ * array of its cells as text (MySQL's text protocol spelling: numbers as their digits, NULL as null), in the order the
+ * answer holds them; `rowsAffected` and `insertId` as numbers where psdb answers them (0 when it omits them, as its
+ * protojson does for a zero); and `error`, `{code, message}`, when the statement was refused. Cells are the packed bytes
+ * decoded as UTF-8.
+ */
+export declare const answerViews: Record<string, (body: unknown) => unknown>;

package/dist/src/index.js

@@ -0,0 +1,156 @@
+// @volter/twin-planetscale — the PlanetScale psdb HTTP-API twin, built on the shared @volter/world-core
+// kernel. PlanetScale's serverless driver does not speak MySQL's binary protocol: it speaks
+// `psdb.v1alpha1.Database`, a Connect RPC service addressed with unary JSON POSTs
+// (`/psdb.v1alpha1.Database/CreateSession`, `/Execute`, `/CloseSession`) under HTTP Basic auth,
+// with results packed as protojson `QueryResult` — base64 row bytes plus per-column byte lengths,
+// `-1` for NULL, and every zero-valued field OMITTED.
+//
+// Behind that protocol is a REAL DATABASE: a stateful MySQL-subset engine with schemas
+// (CREATE/DROP/TRUNCATE TABLE, SHOW TABLES, DESCRIBE), DML (INSERT/SELECT/UPDATE/DELETE with WHERE,
+// ORDER BY, LIMIT/OFFSET, COUNT(*), ON DUPLICATE KEY UPDATE), MySQL's own errno/sqlstate errors
+// (1146 no-such-table, 1062 duplicate entry, 1048 not-null, 1064 parse error, 1054 unknown column),
+// AUTO_INCREMENT that survives deletes, NULL three-valued logic, and REAL TRANSACTIONS — so the
+// unmodified client's `conn.transaction(async (tx) => …)`, which is nothing but BEGIN/…/COMMIT over
+// the same session, genuinely commits or rolls back.
+//
+// THE HONEST CARVE-OUTS: a twin cannot make a wall clock pass or run a storage engine. `NOW()`
+// and the other clock functions read the World clock's instant for the statement;
+// `RAND()` and `UUID()` are REFUSED rather than frozen to a constant
+// (the serve path must be a pure function of (request, stored state)); real elapsed query `timing`
+// is never emitted; real Vitess sharding/resharding and MySQL's storage-engine physics are todos.
+// PlanetScale's branches are modelled: a password acts on its own branch, `main` is the World's one
+// image and every other branch a scope of its own (planetscale-store.ts, "BRANCH SCOPES"), and the
+// `api` lane deploys a branch's schema changes into its base (api/src/semantics/deploy-requests.ts).
+// The twin's limit: every database's `main` shares the one image. See README ## Coverage.
+//
+// State lives ENTIRELY in the kernel action log (no side-store): every table and every row is one
+// kernel subject, so a restart against the same root answers the same `SELECT`.
+export { handlePlanetscaleTwinRequest, planetscaleTwinSnapshot, extractBasicCredential, PSDB_SERVICE, PSDB_METHODS, PLANETSCALE_UNAUTHENTICATED, PLANETSCALE_RESOURCE_TYPES, } from "./planetscale-twin.js";
+// The SQL core — exported so a caller (or a reviewer) can drive MySQL semantics in-process,
+// without HTTP. `runSql` over an image is the whole engine; nothing about the protocol is required
+// to exercise it.
+export { runSql, execStatement, parseStatement, tokenize, evalExpr, likeMatch, emptyDatabase, findTable, tableRows, tableKey, nextRowId, vitessTypeFor, fieldForColumn, isNumericVitessType, unsupported, parseError, SqlError, PLANETSCALE_LIMITS, VITESS_TYPES, BINARY_CHARSET, UTF8MB4_CHARSET, FLAG_NOT_NULL, FLAG_PRI_KEY, FLAG_UNIQUE_KEY, FLAG_UNSIGNED, FLAG_BINARY, FLAG_AUTO_INCREMENT, } from "./planetscale-sql.js";
+// The wire codec. Exported because faithful row packing is a headline claim of this pack and a
+// consumer (or a reviewer) must be able to decode a served response without the SDK.
+export { packRow, unpackRow, packBytes, encodeCell, encodeField, encodeQueryResult, makeSession, sessionIdOf, } from "./planetscale-wire.js";
+// The kernel binding — the projection and the session/transaction book.
+export { SERVICE, DEFAULT_BRANCH, DEFAULT_DATABASE, loadState, readDatabase, executeSql, createSession, closeSession, mintSessionId, applyWritesToImage, } from "./planetscale-store.js";
+export { createPlanetscaleTwinFetch, createPlanetscaleTwinServer } from "./planetscale-server.js";
+export { createPlanetscaleMysqlStream, createPlanetscaleTwinStream } from "./planetscale-mysql.js";
+export { mapTable, mapRow, mapDescribeRow, encodeCellValue, quoteSqlLiteral, quoteIdent, pollTimestamp, pullPlanetscaleTables, pullPlanetscaleDatabase, pullPlanetscaleSnapshot, syncPlanetscaleFromReal, syncPlanetscaleFromRemote, performPlanetscaleAction, pushPlanetscaleAction, pushPlanetscaleActions, } from "./planetscale-connector.js";
+// The client-side rate budget — the fail-closed backstop every live call goes through. The
+// MECHANISM is the kernel's shared, vendor-agnostic `RateBudget`; what lives here is this vendor's
+// DECLARATION plus `guardPlanetscaleClient`, the choke point the connector entrypoints apply
+// unconditionally. There is deliberately no export that disables the guard.
+export { PLANETSCALE_BUDGETED_METHODS, PLANETSCALE_BUDGET_CEILING, PLANETSCALE_BUDGET_MAX_RETRY_AFTER_S, PLANETSCALE_BUDGET_WINDOW_MS, PLANETSCALE_CALL_WEIGHTS, PLANETSCALE_RATE_BUDGET, PlanetscaleBudget, PlanetscaleBudgetError, planetscaleBudgetPath, planetscaleCallWeight, planetscaleClientBudget, guardPlanetscaleClient, } from "./planetscale-budget.js";
+// Registry descriptor: the pack self-describes so tooling can discover it.
+import { registerPack } from '@volter/world-core';
+import { performPlanetscaleAction, syncPlanetscaleFromRemote } from "./planetscale-connector.js";
+import { PLANETSCALE_RATE_BUDGET as RATE_BUDGET } from "./planetscale-budget.js";
+export const pack = {
+    protocol: '2',
+    stateSystem: { perform: performPlanetscaleAction, refresh: syncPlanetscaleFromRemote },
+    refresh: { onDemand: { atMost: '60s' } },
+    roundTrip: [
+        { method: 'POST', path: '/psdb.v1alpha1.Database/Execute', headers: { authorization: 'Basic dHdpbjp0d2lu' }, body: { query: 'CREATE TABLE IF NOT EXISTS round_trip (id BIGINT PRIMARY KEY AUTO_INCREMENT, body VARCHAR(255))' } },
+        { method: 'POST', path: '/psdb.v1alpha1.Database/Execute', headers: { authorization: 'Basic dHdpbjp0d2lu' }, body: { query: "INSERT INTO round_trip (body) VALUES ('round trip')" } },
+    ],
+    parityOrigin: 'http://twin',
+    // The SAME object planetscale-budget.ts declares at module load — one source of truth, so
+    // registering the pack and importing the connector can never arm two different ceilings.
+    rateBudget: RATE_BUDGET,
+    vendor: 'planetscale',
+    transport: 'rest',
+    nativeTransport: { protocol: 'mysql', flag: '--mysql', upstreamEnv: 'PLANETSCALE_TWIN_URL' },
+    endpointEnv: {
+        name: 'PLANETSCALE_TWIN_URL',
+        templates: { PLANETSCALE_DATABASE_URL: 'http://twin:twin@${host}:${port}' },
+        note: 'the @planetscale/database client reads PLANETSCALE_DATABASE_URL and honours http:; the injector also redirects *.psdb.cloud.',
+    },
+    // PRISMA — dub's `new PrismaClient({ omit })` names no adapter; on Prisma's client-engine
+    // build (the tab's, and the edge client's) that refuses to construct. The injector supplies
+    // this adapter, from the application's own `@prisma/adapter-planetscale`, over the endpoint
+    // template's PLANETSCALE_DATABASE_URL, which `@planetscale/database` honours as http:.
+    prismaAdapter: { adapter: '@prisma/adapter-planetscale', export: 'PrismaPlanetScale', urlEnv: 'PLANETSCALE_DATABASE_URL' },
+    archetype: 'crud',
+    bin: 'world-planetscale',
+    resources: ['table', 'row', '_session', '_backup'],
+    // ADOPTION — declared HERE, not in world-runtime's central SDK_TWINS / ENV_STEM_VENDORS tables
+    // (adding-a-twin.md §3; declaring a fact in both homes THROWS). `@planetscale/database` is the
+    // only official client of this API surface. `PLANETSCALE` is the credential-env stem: dub reads
+    // `PLANETSCALE_DATABASE_URL` (apps/web/lib/planetscale/connection.ts) — the exact var whose
+    // DATABASE_URL shape made `volter-world init` bin this vendor as generic infra and report the
+    // repo fully covered while a real call escaped (volter-ai/twin#255).
+    adoption: {
+        // No Python client for the psdb HTTP data API - `@planetscale/database` is JS-only, and Python
+        // callers reach PlanetScale over the MySQL wire protocol (a generic driver, not a vendor client).
+        pypi: [],
+        sdks: ['@planetscale/database'],
+        envStems: ['PLANETSCALE'],
+    },
+    // INTERCEPTION — the SDK addresses ONE host: whatever `config.host` resolves to from the
+    // connection URL (dist/index.js's constructor takes `url.hostname`, then `buildURL` rebuilds the
+    // request against it). PlanetScale's psdb data plane lives on per-region subdomains of
+    // `psdb.cloud` — `aws.connect.psdb.cloud`, `gcp.connect.psdb.cloud`, `<region>.connect.psdb.cloud`
+    // — so a SUFFIX matcher is required; an exact host would miss every region but one.
+    //
+    // `api.planetscale.com` is the MANAGEMENT API, the pack's `api` lane (api/src/, derived from PlanetScale's own
+    // Swagger document): the pack claims its /v1/organizations tree, where the lane serves databases, a branch's
+    // passwords and backups, and service tokens, and answers PlanetScale's 404 for every other operation; the host's
+    // other paths are unclaimed.
+    // app.planetscale.com's sign-in and service tokens page are screens the lane serves (api/src/screens/).
+    hosts: [{ suffix: '.psdb.cloud' }, { host: 'api.planetscale.com', pathPattern: '^/v1/organizations(/|$)' }, { host: 'app.planetscale.com', pathPattern: '^/(sign-in|[^/]+/settings/service-tokens)(/|$)' }],
+    // No endpoint env, and none INVENTED. `@planetscale/database` reads no environment variable of
+    // its own — `connect({url})` takes the URL from the application, which chooses the var name
+    // (dub's is PLANETSCALE_DATABASE_URL, Vercel's template uses DATABASE_URL). Interception here is
+    // the injector's, via the `hosts` suffix above, so an app-read endpoint var is not needed;
+    // emitting one anyway would let `covers` report coverage for an app that reads a different name.
+    pullPosture: 'on-demand',
+    pullPostureReason: 'PlanetScale meters ROWS READ rather than requests, so a scheduled full-table pull is unbounded in cost by '
+        + 'construction: one SELECT can read millions of billable rows. Pull it explicitly when someone asks, '
+        + 'through the guarded connector and its mandatory row limit.',
+    specSource: 'the installed @planetscale/database@1.20.1 package source (npm pack: dist/index.js, dist/cast.js, '
+        + 'dist/sanitization.js, dist/text.js, dist/index.d.ts) as the authoritative wire contract + its own test '
+        + 'fixtures for the error envelopes + github.com/mattrobenolt/ps-http-sim (the simulator upstream dub devs '
+        + 'run) and the psdb.v1alpha1 Connect service it implements + '
+        + 'planetscale.com/docs/reference/planetscale-system-limits for the published scalar limits; see '
+        + 'spec-sources.json.',
+    description: "PlanetScale psdb HTTP-API twin — a real stateful MySQL-subset database (DDL, INSERT/SELECT/UPDATE/DELETE, "
+        + 'WHERE/ORDER BY/LIMIT, COUNT(*), ON DUPLICATE KEY UPDATE, AUTO_INCREMENT, NULL three-valued logic, real '
+        + "BEGIN/COMMIT/ROLLBACK transactions, MySQL errno/sqlstate errors) served over PlanetScale's Connect-JSON "
+        + 'wire protocol: POST /psdb.v1alpha1.Database/{CreateSession,Execute,CloseSession}, HTTP Basic auth, '
+        + 'protojson QueryResult with base64 row packing and -1 NULL lengths, query errors at HTTP 200 in the '
+        + '{error:{code,message}} envelope and auth failures at 401 in the same one. Non-deterministic SQL (NOW, '
+        + 'RAND, UUID) is refused, never frozen. Kernel-backed.',
+    browserRouting: { apiPathPrefix: '/psdb.v1alpha1.Database/', loaderHost: 'https://aws.connect.psdb.cloud' },
+};
+registerPack(pack);
+/**
+ * How a journey reads an answer of this pack (a step's `view`, scripts/behavior-journey.ts). `rows` decodes an Execute
+ * answer into what MySQL's client prints for it: `fields`, the result's column names in order; `rows`, each row as an
+ * array of its cells as text (MySQL's text protocol spelling: numbers as their digits, NULL as null), in the order the
+ * answer holds them; `rowsAffected` and `insertId` as numbers where psdb answers them (0 when it omits them, as its
+ * protojson does for a zero); and `error`, `{code, message}`, when the statement was refused. Cells are the packed bytes
+ * decoded as UTF-8.
+ */
+export const answerViews = {
+    rows: (body) => {
+        const b = (body ?? {});
+        if (b.error)
+            return { error: b.error };
+        const r = b.result ?? {};
+        const rows = (r.rows ?? []).map((row) => {
+            const bytes = Uint8Array.from(atob(row.values ?? ''), (c) => c.charCodeAt(0));
+            let at = 0;
+            return (row.lengths ?? []).map((size) => {
+                const width = Number(size);
+                if (width < 0)
+                    return null;
+                const cell = new TextDecoder().decode(bytes.subarray(at, at + width));
+                at += width;
+                return cell;
+            });
+        });
+        return { fields: (r.fields ?? []).map((f) => f.name ?? ''), rows, rowsAffected: Number(r.rowsAffected ?? 0), insertId: Number(r.insertId ?? 0) };
+    },
+};

package/dist/src/manifest.d.ts

@@ -0,0 +1,2 @@
+import type { DerivedManifest } from '@volter/world-core';
+export declare const manifest: DerivedManifest;

package/dist/src/manifest.js

@@ -0,0 +1,41 @@
+// ps-http-sim, the simulator PlanetScale's driver authors publish for local development: its CloseSession handler
+// closes the session's connection when the request names one (`closeConn(mysqlConnKey{…})`) and answers the session
+// reset, whatever the connection's state.
+const PS_HTTP_SIM = 'https://github.com/mattrobenolt/ps-http-sim/blob/main/main.go';
+/** A session's `closed`. CreateSession opens one (the initial state); CloseSession closes an open one, discarding any
+ *  uncommitted transaction as a dropped connection does. Closing one already closed moves nothing and answers 200, as
+ *  ps-http-sim answers every close. Not moves of a session, and the twin's decisions where nothing shows the vendor's:
+ *  a CloseSession naming a session the twin never issued answers 200 and writes nothing; an Execute naming a closed
+ *  session runs in a new session the twin opens for it (planetscale-store.ts, `executeSqlUnlocked`), as an Execute
+ *  naming none does (ps-http-sim: "if !clientSession { sess = session.New(…) }"). */
+const sessionClosed = {
+    initial: false,
+    transitions: [
+        { operation: 'CloseSession', from: ['false'], to: 'true', source: PS_HTTP_SIM },
+        { operation: 'CloseSession', from: ['true'], source: PS_HTTP_SIM },
+    ],
+};
+export const manifest = {
+    vendor: 'planetscale',
+    service: 'planetscale',
+    // the driver always sends JSON (`Content-Type: application/json`, @planetscale/database dist/index.js `postJSON`)
+    body: { json: 'always' },
+    // the store mints a session `tws-<n>-<the World instant in ms>` (planetscale-store.ts, `mintSessionId`), stored as
+    // subject `session:<id>`; the core mints none (it owns no operation), so the template names the counted part only
+    ids: { template: '{prefix}-{n}' },
+    time: 'iso',
+    // Connect's transport-level error body: a lowercase code and a message, no wrapper
+    error: { code: '{code}', message: '{message}' },
+    // a whole-operation refusal of a write to a read-only twin; the psdb handlers refuse per statement (errno 1290 in a
+    // 200 `{session, error}`) and never reach this
+    readOnly: { status: 403, code: 'permission_denied', message: 'twin is read-only; omit readOnly to accept writes' },
+    malformedBody: { status: 400, code: 'invalid_argument', message: 'malformed JSON request body' },
+    // Connect's not_found; psdb addresses nothing by id in a path, so no operation answers it
+    notFound: { status: 404, code: 'not_found', message: 'not found' },
+    // psdb has no list operation: an Execute's rows are its QueryResult. Required by the type; nothing reads it.
+    list: { style: 'envelope', envelope: { data: '{data}' }, limit: { param: 'limit', default: 100, max: 100 } },
+    deleted: {},
+    resources: {
+        Session: { storedAs: '_session', idPrefix: 'tws', state: { closed: sessionClosed } },
+    },
+};

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

@@ -0,0 +1,78 @@
+import { RateBudget, type RateBudgetDeclaration, type RateBudgetOptions, type RateBudgetReservation, type RateBudgetSnapshot } from '@volter/world-core';
+import type { PlanetscaleLikeClient } from './planetscale-connector.js';
+/** Rolling window, in ms. Spend older than this is pruned. */
+export declare const PLANETSCALE_BUDGET_WINDOW_MS = 60000;
+/** Weighted units allowed inside one window. See the header for where this number comes from. */
+export declare const PLANETSCALE_BUDGET_CEILING = 60;
+/** Seconds. A `Retry-After` above this means the credential is throttled hard — fail loudly. */
+export declare const PLANETSCALE_BUDGET_MAX_RETRY_AFTER_S = 300;
+/** Per-call cost, keyed by the client method the guard is about to invoke. See the header. */
+export declare const PLANETSCALE_CALL_WEIGHTS: {
+    /** `transaction` — ONE guarded call that runs an unbounded number of statements behind it. */
+    readonly transaction: 8;
+    /** `execute` / `refresh` / anything unclassified. */
+    readonly other: 2;
+};
+/**
+ * The client methods this pack PRICES BY NAME. `@planetscale/database`'s `Client` and `Connection`
+ * expose exactly these three (dist/index.d.ts), and the connector calls only `execute`.
+ *
+ * NOT a closed list: a method absent from it is still priced at `defaultWeight` through the
+ * passthrough proxy. An unmodeled call must never be free — free would also make it invisible.
+ */
+export declare const PLANETSCALE_BUDGETED_METHODS: readonly ["execute", "transaction", "refresh"];
+/** THE PACK'S DECLARATION — pure data, the only PlanetScale-specific thing in the whole budget. */
+export declare const PLANETSCALE_RATE_BUDGET: RateBudgetDeclaration;
+/** Price one PlanetScale call by its client method name (`execute`, `transaction`, …). */
+export declare function planetscaleCallWeight(method: string): number;
+/** Where PlanetScale's ledger lives. Token-keyed and cwd-independent by default (the vendor meters
+ *  per credential, so a cwd-scoped ledger would hand the same credential a fresh allowance in every
+ *  checkout, worktree and CI matrix leg); pass `root` to opt into world-scoped accounting. */
+export declare function planetscaleBudgetPath(opts?: {
+    root?: string;
+    token?: string;
+} | string): string;
+/** Construction options for PlanetScale's budget. The vendor is fixed; everything else may only TIGHTEN. */
+export type PlanetscaleBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+/**
+ * PlanetScale's budget — the shared kernel guard bound to this vendor's declaration. A real
+ * subclass, not an alias, so `budget instanceof PlanetscaleBudget` means "a budget that accounts
+ * against this vendor's ledger under this vendor's ceiling".
+ */
+export declare class PlanetscaleBudget extends RateBudget {
+    constructor(opts?: PlanetscaleBudgetOptions);
+}
+export type { RateBudgetErrorKind as PlanetscaleBudgetErrorKind } from '@volter/world-core';
+export { RateBudgetError as PlanetscaleBudgetError } from '@volter/world-core';
+export type PlanetscaleBudgetReservation = RateBudgetReservation;
+export type PlanetscaleBudgetSnapshot = RateBudgetSnapshot;
+/** What every budgeted connector entrypoint accepts. There is deliberately no option that turns the
+ *  guard OFF — only ones that say WHICH ledger and clock to account against. */
+export type PlanetscaleBudgetedOptions = {
+    /** An existing budget to share across calls. Omit and one is constructed. Cannot be null. */
+    budget?: PlanetscaleBudget;
+    /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+    budgetOptions?: PlanetscaleBudgetOptions;
+};
+/** Pull the budget wiring out of a caller's opts bag, so an entrypoint can forward it verbatim. */
+export declare function planetscaleBudgetOf(opts: PlanetscaleBudgetedOptions): PlanetscaleBudgetedOptions;
+/** Is this client already behind a budget? Returns the budget it is behind, if so. */
+export declare function planetscaleClientBudget(client: unknown): RateBudget | undefined;
+/** Reserve every known row call plus session, BEGIN, COMMIT and possible ROLLBACK before IO. */
+export declare function runPlanetscaleTransaction<T>(client: PlanetscaleLikeClient, statementCount: number, run: (tx: unknown) => Promise<T>, opts?: PlanetscaleBudgetedOptions): Promise<T>;
+/**
+ * Wrap an INJECTED PlanetScale client so EVERY call it makes is charged against the shared budget
+ * BEFORE the request goes out. This pack never constructs the transport itself (the consumer injects
+ * something satisfying `PlanetscaleLikeClient` — a real `Client` or `Connection` is assignable
+ * as-is), so the guard is a DECORATOR rather than a factory, which is exactly why every connector
+ * entrypoint applies it UNCONDITIONALLY instead of trusting the caller.
+ *
+ * IDEMPOTENT: wrapping an already-guarded client returns it unchanged.
+ *
+ * A method that THROWS is still inspected: `@planetscale/database` RAISES `DatabaseError` /
+ * `UnknownError` on a non-2xx rather than returning it, and that error's status and headers are
+ * exactly the signal that must become a persisted cooldown. The original error is always re-raised
+ * afterwards — EXCEPT when the back-off is beyond the cap, where the budget's own louder "stop
+ * calling" error takes precedence.
+ */
+export declare function guardPlanetscaleClient(client: PlanetscaleLikeClient, opts?: PlanetscaleBudgetedOptions): PlanetscaleLikeClient;

package/dist/src/planetscale-budget.js

@@ -0,0 +1,305 @@
+// PLANETSCALE'S CLIENT-SIDE RATE BUDGET — the pack's DECLARATION (the numbers) plus
+// `guardPlanetscaleClient`, the choke point every live PlanetScale call goes through. The MECHANISM
+// — the durable token-keyed ledger, the rolling window, reserve-under-lock, the `Retry-After`/429
+// cooldown, fail-CLOSED on a corrupt ledger — lives ONCE in the vendor-agnostic kernel
+// (`@volter/world-core` → `rateBudget.ts`). Read that module's header for the full rationale AND for the
+// honest list of what the guard does NOT guarantee. This module is modeled on
+// `notion-budget.ts` / `upstash-budget.ts`, the reference injected-client decorators.
+//
+// ── THE NUMBER, AND WHY IT IS THE KERNEL FALLBACK RATHER THAN A TRANSCRIBED LIMIT ─────────────
+// PlanetScale publishes system limits and this build LIVE-READ them
+// (planetscale.com/docs/reference/planetscale-system-limits, 2026-08-31). Every published figure is
+// a PER-QUERY or PER-SCHEMA bound, not a rate:
+//     • per-query rows returned/updated/deleted: 100k       • per-query result set: 64 MiB
+//     • autocommit timeout: 900s                            • transaction timeout: 20s
+//     • tables per schema: 2048                             • columns per table: 1017
+// There is NO published requests-per-second or requests-per-minute figure for the psdb HTTP API,
+// and this build did not find one. Per ADDING_A_TWIN's rule for exactly that case, the reason says
+// so plainly and the ceiling stays AT the kernel's austere fallback — 60 units / 60s at the default
+// weight of 2 = 30 calls per minute — rather than dressing a guess up as a vendor fact. Nothing
+// here is more permissive than `DEFAULT_RATE_BUDGET`, so no `VENDOR_BURST_ANCHOR` figure is owed.
+//
+// ── WHAT THE RISK ACTUALLY IS ─────────────────────────────────────────────────────────────────
+// PlanetScale meters ROWS READ, not requests. One `SELECT` against a large table is a single call
+// that can read millions of rows, so a request-count ceiling bounds the SHAPE of a runaway loop
+// without bounding its cost. That is a real limitation of a request-count guard against this vendor
+// and it is stated rather than papered over: the connector's own defence is that every pull takes a
+// hard result `limit` (not a storage rows-examined guarantee), and `transaction` is priced at 4x because ONE guarded call fans out into an
+// unbounded number of statements behind it (`Connection.transaction` in dist/index.js runs the
+// caller's whole callback).
+import { declareRateBudget, rateBudgetPath, rateBudgetWeight, RateBudget, RateBudgetError, } from '@volter/world-core';
+const VENDOR = 'planetscale';
+/** Rolling window, in ms. Spend older than this is pruned. */
+export const PLANETSCALE_BUDGET_WINDOW_MS = 60_000;
+/** Weighted units allowed inside one window. See the header for where this number comes from. */
+export const PLANETSCALE_BUDGET_CEILING = 60;
+/** Seconds. A `Retry-After` above this means the credential is throttled hard — fail loudly. */
+export const PLANETSCALE_BUDGET_MAX_RETRY_AFTER_S = 300;
+/** Per-call cost, keyed by the client method the guard is about to invoke. See the header. */
+export const PLANETSCALE_CALL_WEIGHTS = {
+    /** `transaction` — ONE guarded call that runs an unbounded number of statements behind it. */
+    transaction: 8,
+    /** `execute` / `refresh` / anything unclassified. */
+    other: 2,
+};
+/**
+ * The client methods this pack PRICES BY NAME. `@planetscale/database`'s `Client` and `Connection`
+ * expose exactly these three (dist/index.d.ts), and the connector calls only `execute`.
+ *
+ * NOT a closed list: a method absent from it is still priced at `defaultWeight` through the
+ * passthrough proxy. An unmodeled call must never be free — free would also make it invisible.
+ */
+export const PLANETSCALE_BUDGETED_METHODS = ['execute', 'transaction', 'refresh'];
+/** THE PACK'S DECLARATION — pure data, the only PlanetScale-specific thing in the whole budget. */
+export const PLANETSCALE_RATE_BUDGET = {
+    windowMs: PLANETSCALE_BUDGET_WINDOW_MS,
+    ceiling: PLANETSCALE_BUDGET_CEILING,
+    defaultWeight: PLANETSCALE_CALL_WEIGHTS.other,
+    maxRetryAfterSeconds: PLANETSCALE_BUDGET_MAX_RETRY_AFTER_S,
+    // Ordered: the kernel prices FIRST-MATCH-WINS, so the most expensive tier is listed first.
+    rules: [
+        { match: '(^|\\.)transaction$', weight: PLANETSCALE_CALL_WEIGHTS.transaction },
+    ],
+    reason: 'PlanetScale publishes NO requests-per-second or requests-per-minute limit for the psdb HTTP API. Its '
+        + 'system-limits page (https://planetscale.com/docs/reference/planetscale-system-limits, live-read '
+        + '2026-08-31) publishes only PER-QUERY and PER-SCHEMA bounds: 100k rows returned/updated/deleted per '
+        + 'query, a 64 MiB per-query result set, a 900s autocommit timeout, a 20s transaction timeout, 2048 tables '
+        + 'per schema and 1017 columns per table. None of those is a call rate, so — per the ADDING_A_TWIN rule for '
+        + 'a vendor that publishes no scalar rate — this declaration states that plainly and stays AT the kernel '
+        + "fallback (60 units / 60s at weight 2 = 30 calls per minute) instead of inventing a number. It is "
+        + 'therefore never more permissive than DEFAULT_RATE_BUDGET and owes no VENDOR_BURST_ANCHOR figure. The '
+        + 'real cost driver is metered ROWS READ rather than request count, which a request-count ceiling can only '
+        + 'bound crudely; that limitation is disclosed rather than hidden, and the connector answers it separately '
+        + 'by bounding returned pages on every pull; SQL LIMIT does not cap rows examined or billed. `transaction` is priced at 8 because ONE guarded call runs '
+        + "the caller's entire callback — an unbounded number of statements — behind it "
+        + '(@planetscale/database@1.20.1 dist/index.js, `Connection.transaction`).',
+};
+// Declared at module load, so merely importing this module (which `planetscale-connector.ts` does)
+// is enough to arm the real ceiling.
+declareRateBudget(VENDOR, PLANETSCALE_RATE_BUDGET);
+/** Price one PlanetScale call by its client method name (`execute`, `transaction`, …). */
+export function planetscaleCallWeight(method) {
+    return rateBudgetWeight(VENDOR, method);
+}
+/** Where PlanetScale's ledger lives. Token-keyed and cwd-independent by default (the vendor meters
+ *  per credential, so a cwd-scoped ledger would hand the same credential a fresh allowance in every
+ *  checkout, worktree and CI matrix leg); pass `root` to opt into world-scoped accounting. */
+export function planetscaleBudgetPath(opts = {}) {
+    const o = typeof opts === 'string' ? { root: opts } : opts;
+    // VENDOR spread LAST: a loosely-typed `{ vendor: 'other', … }` slipping through (TypeScript's
+    // excess-property check only catches object literals) must not redirect this pack's ledger.
+    return rateBudgetPath({ ...o, vendor: VENDOR });
+}
+/**
+ * PlanetScale's budget — the shared kernel guard bound to this vendor's declaration. A real
+ * subclass, not an alias, so `budget instanceof PlanetscaleBudget` means "a budget that accounts
+ * against this vendor's ledger under this vendor's ceiling".
+ */
+export class PlanetscaleBudget extends RateBudget {
+    constructor(opts = {}) {
+        super({ ...opts, vendor: VENDOR });
+    }
+}
+export { RateBudgetError as PlanetscaleBudgetError } from '@volter/world-core';
+/** Pull the budget wiring out of a caller's opts bag, so an entrypoint can forward it verbatim. */
+export function planetscaleBudgetOf(opts) {
+    return {
+        ...(opts.budget !== undefined ? { budget: opts.budget } : {}),
+        ...(opts.budgetOptions !== undefined ? { budgetOptions: opts.budgetOptions } : {}),
+    };
+}
+// ── the choke point ─────────────────────────────────────────────────────────────────────────
+/**
+ * Marks a client this module has already wrapped, so guarding twice cannot charge twice.
+ *
+ * A MODULE-PRIVATE `Symbol()`, deliberately not `Symbol.for()`: a global-registry symbol is
+ * reachable BY NAME, so any caller could stamp the brand on a RAW client and the guard would hand it
+ * straight back UNGUARDED — a one-line bypass of the whole budget.
+ */
+const GUARDED = Symbol('@volter/twin-planetscale.budget.guarded');
+/** Is this client already behind a budget? Returns the budget it is behind, if so. */
+export function planetscaleClientBudget(client) {
+    const mark = client?.[GUARDED];
+    return mark instanceof RateBudget ? mark : undefined;
+}
+const NEVER_WRAP = new Set(['then', 'catch', 'finally', 'constructor', 'prototype', 'toJSON', 'toString', 'valueOf', 'inspect']);
+/** The HTTP status a value carries, if it looks like one (an SDK error, or a raw response). */
+function responseStatus(v) {
+    const s = v?.status;
+    return typeof s === 'number' && Number.isFinite(s) ? s : undefined;
+}
+/**
+ * Response/error headers as a plain lower-cased record, or `undefined` when there are none. Accepts
+ * a `Headers` instance, a `Map`, or a plain object — `DatabaseError`/`UnknownError` carry a
+ * `context.headers` record (dist/index.js), and a raw `Response` carries a `Headers`.
+ */
+function responseHeaders(v) {
+    const direct = v?.headers;
+    const nested = v?.context?.headers;
+    const h = direct ?? nested;
+    if (!h || typeof h !== 'object')
+        return undefined;
+    const out = {};
+    if (typeof h.forEach === 'function') {
+        h.forEach((value, key) => { out[String(key).toLowerCase()] = String(value); });
+    }
+    else {
+        for (const [k, value] of Object.entries(h))
+            out[k.toLowerCase()] = String(value);
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+// Guard ownership stays module-private; known deployment batches can reserve once without
+// exposing an unguarded client to callers or interrupting rollback with a second admission.
+const rawClients = new WeakMap();
+function settleBudget(budget, weight, reservation, value) {
+    if (value instanceof AggregateError) {
+        for (const error of value.errors)
+            settleBudget(budget, weight, reservation, error);
+        return;
+    }
+    budget.recordCall(weight, responseHeaders(value), { status: responseStatus(value), reservation });
+}
+/** Settle once the call RESOLVED: PlanetScale has answered. recordCall arms any cooldown before it
+ *  throws (a back-off beyond the cap), so that refusal is swallowed and the result kept — a write
+ *  that committed is never reported failed and run again on retry. A non-2xx status still throws. */
+function settleAnswered(budget, weight, reservation, value) {
+    try {
+        settleBudget(budget, weight, reservation, value);
+    }
+    catch (error) {
+        const status = responseStatus(value);
+        if (!(error instanceof RateBudgetError) || (status !== undefined && (status < 200 || status >= 300)))
+            throw error;
+    }
+}
+async function charged(budget, weight, invoke) {
+    const reservation = budget.checkBudget(weight);
+    try {
+        const result = await invoke();
+        settleAnswered(budget, weight, reservation, result);
+        return result;
+    }
+    catch (error) {
+        settleBudget(budget, weight, reservation, error);
+        throw error;
+    }
+}
+/** Reserve every known row call plus session, BEGIN, COMMIT and possible ROLLBACK before IO. */
+export async function runPlanetscaleTransaction(client, statementCount, run, opts = {}) {
+    if (!Number.isSafeInteger(statementCount) || statementCount < 0)
+        throw new Error('Invalid PlanetScale statement count');
+    const guarded = guardPlanetscaleClient(client, opts);
+    const raw = rawClients.get(guarded);
+    if (!raw?.transaction)
+        throw new Error('PlanetScale deployment requires a transactional client');
+    const budget = planetscaleClientBudget(guarded);
+    return charged(budget, Math.max(budget.weightFor('transaction'), (statementCount + 4) * budget.weightFor('execute')), () => raw.transaction(run));
+}
+/**
+ * Wrap an INJECTED PlanetScale client so EVERY call it makes is charged against the shared budget
+ * BEFORE the request goes out. This pack never constructs the transport itself (the consumer injects
+ * something satisfying `PlanetscaleLikeClient` — a real `Client` or `Connection` is assignable
+ * as-is), so the guard is a DECORATOR rather than a factory, which is exactly why every connector
+ * entrypoint applies it UNCONDITIONALLY instead of trusting the caller.
+ *
+ * IDEMPOTENT: wrapping an already-guarded client returns it unchanged.
+ *
+ * A method that THROWS is still inspected: `@planetscale/database` RAISES `DatabaseError` /
+ * `UnknownError` on a non-2xx rather than returning it, and that error's status and headers are
+ * exactly the signal that must become a persisted cooldown. The original error is always re-raised
+ * afterwards — EXCEPT when the back-off is beyond the cap, where the budget's own louder "stop
+ * calling" error takes precedence.
+ */
+export function guardPlanetscaleClient(client, opts = {}) {
+    // There is no value a caller can pass to end up with an UNGUARDED client. Validated BEFORE the
+    // already-guarded early return, so `guard(alreadyGuarded, { budget: impostor })` is refused too.
+    if (opts.budget !== undefined && opts.budget !== null && !(opts.budget instanceof PlanetscaleBudget)) {
+        throw new Error('guardPlanetscaleClient: `budget` must be a PlanetscaleBudget — refusing to guard a PlanetScale client with an unverified rate guard');
+    }
+    if (planetscaleClientBudget(client))
+        return client;
+    const budget = opts.budget instanceof PlanetscaleBudget
+        ? opts.budget
+        : new PlanetscaleBudget({
+            // The default ledger is keyed by a hash of the credential — the vendor meters per credential,
+            // so a cwd-scoped ledger would hand it a fresh allowance per worktree/CI leg.
+            //
+            // HONESTLY: this pack does NOT hold the credential — the consumer's injected client does — so
+            // `PLANETSCALE_DATABASE_URL` is a BEST-EFFORT stand-in, not the real thing. If it names a
+            // different database than the injected client, spend is booked against the wrong ledger; if it
+            // is unset, every unattributed PlanetScale credential on the machine shares one (over-tight,
+            // the safe direction). A caller who knows the credential says so with `budgetOptions: { token }`,
+            // which is spread last and therefore wins.
+            ...(process.env.PLANETSCALE_DATABASE_URL !== undefined ? { token: process.env.PLANETSCALE_DATABASE_URL } : {}),
+            ...(opts.budgetOptions ?? {}),
+        });
+    /** Settle a reservation from whatever the call produced. May THROW (a back-off past the cap). */
+    const settle = (weight, reservation, value) => settleBudget(budget, weight, reservation, value);
+    /**
+     * Charge, call, settle. Refusing REJECTS rather than throwing synchronously, so
+     * `client.execute(...).catch(…)` behaves exactly as it does on an unguarded client.
+     * `checkBudget` RESERVES under lock, so nothing after its line runs when the budget refuses:
+     * the request is never made.
+     */
+    const chargeAsync = (method, invoke) => async (...args) => charged(budget, budget.weightFor(method), async () => invoke(...args));
+    const guarded = {};
+    for (const name of PLANETSCALE_BUDGETED_METHODS) {
+        const raw = client[name];
+        if (typeof raw !== 'function')
+            continue;
+        // Resolved at CALL time, not here, so a client whose method is swapped later is still charged.
+        guarded[name] = chargeAsync(name, (...args) => client[name].apply(client, args));
+    }
+    Object.defineProperty(guarded, GUARDED, { value: budget, enumerable: false });
+    // A real client has MORE than the three methods above (`connection()`, `config`, …) and a consumer
+    // who needs one must not be forced to keep the RAW client alongside — every call through that
+    // would be unbudgeted. So the guarded object is a Proxy: modeled members come from the map above,
+    // anything else is taken from the real client and PRICED at `defaultWeight`.
+    const proxy = new Proxy(guarded, {
+        get(target, prop, receiver) {
+            if (typeof prop === 'symbol') {
+                const own = Reflect.get(target, prop, receiver);
+                return own !== undefined ? own : client[prop];
+            }
+            const name = String(prop);
+            if (NEVER_WRAP.has(name))
+                return Reflect.get(target, prop, receiver);
+            const own = Reflect.get(target, prop, receiver);
+            if (own !== undefined)
+                return own;
+            const from = client[name];
+            // `connection()` returns a NEW Connection whose `execute` would otherwise escape the budget
+            // entirely, so a function member is charged AND its result is re-guarded when it looks like a
+            // client. Anything else passes through.
+            if (typeof from === 'function') {
+                return (...args) => {
+                    const weight = budget.weightFor(name);
+                    const reservation = budget.checkBudget(weight);
+                    let out;
+                    try {
+                        out = from.apply(client, args);
+                    }
+                    catch (e) {
+                        settle(weight, reservation, e);
+                        throw e;
+                    }
+                    if (out !== null && typeof out === 'object' && typeof out.then === 'function') {
+                        return out.then((res) => { settleAnswered(budget, weight, reservation, res); return res; }, (e) => { settle(weight, reservation, e); throw e; });
+                    }
+                    settle(weight, reservation, undefined);
+                    if (out !== null && typeof out === 'object' && typeof out.execute === 'function') {
+                        return guardPlanetscaleClient(out, { budget });
+                    }
+                    return out;
+                };
+            }
+            return from;
+        },
+        has(target, prop) {
+            return Reflect.has(target, prop) || Reflect.has(client, prop);
+        },
+    });
+    rawClients.set(proxy, client);
+    return proxy;
+}

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

@@ -0,0 +1,10 @@
+import { type CapabilityReport, type CapabilitySpec } from '@volter/world-tooling';
+/**
+ * The AREA CENSUS — enumerated TOP-DOWN from MySQL's own statement families and PlanetScale's own
+ * product surface (the psdb protocol, the branch credential model, the management API), NOT derived
+ * from the manifest below. Deriving it from the manifest would make `assertAreaCensus` a tautology;
+ * enumerating it independently is what gives the check teeth.
+ */
+export declare const PLANETSCALE_AREAS: readonly ["auth", "collation", "conformance", "connector", "ddl", "delete", "errors", "functions", "insert", "limits", "management", "native", "protocol", "readonly", "select", "session", "transactions", "update", "wire"];
+export declare const PLANETSCALE_CAPABILITIES: CapabilitySpec[];
+export declare function planetscaleCapabilities(): Promise<CapabilityReport>;