@volter/twin-planetscale 0.1.0

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

@@ -0,0 +1,48 @@
+import { PLANETSCALE_RESOURCE_TYPES } from './planetscale-store.js';
+export type PlanetscaleRequest = {
+    method: string;
+    path: string;
+    body?: string;
+    headers?: Record<string, string>;
+    occurredAt?: string;
+    root?: string;
+    readOnly?: boolean;
+    /** The password this twin demands. Omit to accept any non-empty credential (still 401s a missing
+     *  one) — the honest default for a local twin that holds no real secret. */
+    password?: string;
+    /** The username this twin demands. Omit to accept any non-empty username. */
+    username?: string;
+    /** The schema name the twin presents (`Field.database`, errno 1146). */
+    database?: string;
+    /** The branch name `CreateSession` reports. */
+    branch?: string;
+};
+export type PlanetscaleResponse = {
+    status: number;
+    body: unknown;
+    headers?: Record<string, string>;
+};
+/** The Connect service this twin serves. The path is `/<fully-qualified service>/<Method>`. */
+export declare const PSDB_SERVICE = "psdb.v1alpha1.Database";
+/** Every method the real service declares, so an unknown one is distinguishable from a known-but-
+ *  unmodeled one — the difference between Connect's `unimplemented` and its `not_found`. */
+export declare const PSDB_METHODS: readonly ["CreateSession", "Execute", "StreamExecute", "CloseSession", "Prepare"];
+/** The literal 401 body the client's own suite fixtures. Identical for a missing, blank or wrong
+ *  credential: the vendor draws no distinction between them, so neither does this twin. */
+export declare const PLANETSCALE_UNAUTHENTICATED: {
+    readonly code: "unauthenticated";
+    readonly message: "invalid auth credentials";
+};
+/** The endpoint inventory `planetscale-conformance.ts` probes. */
+export type PlanetscaleTwinSnapshot = {
+    service: string;
+    implementedEndpoints: string[];
+    resourceTypes: readonly string[];
+};
+export declare function planetscaleTwinSnapshot(): PlanetscaleTwinSnapshot;
+export declare function extractBasicCredential(headers: Record<string, string> | undefined): {
+    username: string;
+    password: string;
+} | null;
+export declare function handlePlanetscaleTwinRequest(req: PlanetscaleRequest): Promise<PlanetscaleResponse>;
+export { PLANETSCALE_RESOURCE_TYPES };

package/dist/src/planetscale-twin.js

@@ -0,0 +1,290 @@
+// PLANETSCALE psdb TWIN — THE REQUEST HANDLER. Contract:
+//   handlePlanetscaleTwinRequest({ method, path, body, headers, root, occurredAt, readOnly, ... })
+//     -> { status, body, headers }
+//
+// This file is the TRANSPORT half. Every MySQL semantic lives in `planetscale-sql.ts`, every kernel
+// interaction in `planetscale-store.ts`, and every byte-level encoding rule in
+// `planetscale-wire.ts`.
+//
+// ── THE PROTOCOL, AND WHY IT LOOKS LIKE THIS ──────────────────────────────────────────────────
+// PlanetScale's HTTP driver does not speak MySQL's binary protocol and it is not REST. It is a
+// Connect RPC service — `psdb.v1alpha1.Database` — 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}
+//   POST /psdb.v1alpha1.Database/Prepare         …                      -> unimplemented (real!)
+//
+// with `Authorization: Basic base64(username:password)` and `User-Agent: database-js/<version>`.
+// GROUNDED in the installed `@planetscale/database@1.20.1` source (dist/index.js builds exactly
+// these two URLs and this header set) and in `github.com/mattrobenolt/ps-http-sim`, the simulator
+// upstream integrators run, whose handler implements CreateSession/Execute/StreamExecute/
+// CloseSession and answers Prepare with Connect's `unimplemented`.
+//
+// ── TWO ERROR CHANNELS, AND CONFUSING THEM BREAKS EVERY CONSUMER ──────────────────────────────
+// 1. A QUERY error (unknown table, duplicate key, parse error) is HTTP **200** carrying
+//    `{session, error:{code, message}}`. The client's `execute` sees `error` on an OK response and
+//    throws `DatabaseError(message, 400, error)` — note the **400 it synthesizes itself**, which is
+//    why serving an actual HTTP 400 here would change the status every consumer's tests assert on.
+// 2. An AUTH failure is HTTP **401** with the SAME `{session, error:{code, message}}` envelope —
+//    the client's `postJSON` looks for `parsed?.error` on a non-ok response and throws
+//    `DatabaseError` with the REAL status. This shape is not a guess: it is the literal fixture in
+//    the client's own test suite (`__tests__/index.test.ts`,
+//    `{ code: 'unauthenticated', message: 'invalid auth credentials' }` replied at 401).
+// Anything else — an unknown method, a wrong HTTP verb — takes Connect's own transport-level error
+// body `{code, message}` with a LOWERCASE code, which the client reports as `UnknownError`
+// ("Expected JSON response from database API, got HTTP …"). That is the vendor's behaviour too, and
+// it is deliberately NOT dressed up in the `{error}` envelope to look like a query failure.
+import { closeSession as storeCloseSession, createSession as storeCreateSession, executeSql, scopeOf, sessionState, DEFAULT_BRANCH, DEFAULT_DATABASE, PLANETSCALE_RESOURCE_TYPES, SERVICE, } from "./planetscale-store.js";
+import { createHash } from 'node:crypto';
+import { parseStatement, SqlError } from "./planetscale-sql.js";
+import { directDdlDisabled, isDdl, roleRefusal } from "./planetscale-roles.js";
+import { ownFields, transitionFor, twinResourcesOfType } from '@volter/world-core';
+import { manifest } from "./manifest.js";
+import { encodeQueryResult, makeSession, sessionIdOf, sessionVarsOf, } from "./planetscale-wire.js";
+/** The Connect service this twin serves. The path is `/<fully-qualified service>/<Method>`. */
+export const PSDB_SERVICE = 'psdb.v1alpha1.Database';
+/** Every method the real service declares, so an unknown one is distinguishable from a known-but-
+ *  unmodeled one — the difference between Connect's `unimplemented` and its `not_found`. */
+export const PSDB_METHODS = ['CreateSession', 'Execute', 'StreamExecute', 'CloseSession', 'Prepare'];
+/** The literal 401 body the client's own suite fixtures. Identical for a missing, blank or wrong
+ *  credential: the vendor draws no distinction between them, so neither does this twin. */
+export const PLANETSCALE_UNAUTHENTICATED = { code: 'unauthenticated', message: 'invalid auth credentials' };
+const JSON_HEADERS = { 'content-type': 'application/json' };
+export function planetscaleTwinSnapshot() {
+    return {
+        service: PSDB_SERVICE,
+        implementedEndpoints: [
+            'POST /psdb.v1alpha1.Database/CreateSession',
+            'POST /psdb.v1alpha1.Database/Execute',
+            'POST /psdb.v1alpha1.Database/CloseSession',
+            'POST /psdb.v1alpha1.Database/Prepare (vendor-faithful unimplemented)',
+            'POST /psdb.v1alpha1.Database/StreamExecute (the gap: Connect unimplemented)',
+        ],
+        resourceTypes: PLANETSCALE_RESOURCE_TYPES,
+    };
+}
+function lowerHeaders(h) {
+    const out = {};
+    for (const [k, v] of Object.entries(h ?? {}))
+        out[k.toLowerCase()] = v;
+    return out;
+}
+/**
+ * Decode `Authorization: Basic base64(user:pass)` — the ONLY scheme this wire uses
+ * (dist/index.js `postJSON` builds it with `btoa(`${username}:${password}`)`).
+ *
+ * The password may itself contain `:` (PlanetScale passwords are `pscale_pw_…`, but a
+ * connection-URL password is arbitrary), so the split is on the FIRST colon only. Anything that is
+ * not a well-formed Basic header resolves to null and gets the vendor's 401 — a malformed header
+ * must never fall through and be treated as a bare credential.
+ */
+/** What `atob` decodes (forgiving-base64): base64 characters whose length is not 1 mod 4, with at most the padding that completes a quad. */
+const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}(?:==)?|[A-Za-z0-9+/]{3}=?)?$/;
+/** A Basic credential that is not base64: the vendor's 401, as for any malformed header. */
+function notBase64() {
+    return null;
+}
+export function extractBasicCredential(headers) {
+    const raw = lowerHeaders(headers).authorization;
+    if (raw === undefined)
+        return null;
+    const m = /^basic\s+(\S+)\s*$/i.exec(raw.trim());
+    if (m === null)
+        return null;
+    const decoded = BASE64.test(m[1]) ? atob(m[1]) : notBase64();
+    if (decoded === null)
+        return null;
+    const colon = decoded.indexOf(':');
+    if (colon < 0)
+        return null;
+    const username = decoded.slice(0, colon);
+    const password = decoded.slice(colon + 1);
+    if (username === '' || password === '')
+        return null;
+    return { username, password };
+}
+/** Connect's transport-level error body: a lowercase code and a message, with no `error` wrapper. */
+const connectError = (status, code, message) => ({ status, body: { code, message }, headers: JSON_HEADERS });
+const unauthenticated = (session) => ({ status: 401, body: { ...(session !== undefined ? { session } : {}), error: PLANETSCALE_UNAUTHENTICATED }, headers: JSON_HEADERS });
+export async function handlePlanetscaleTwinRequest(req) {
+    const path = req.path.split('?')[0].replace(/\/+$/, '') || '/';
+    const prefix = `/${PSDB_SERVICE}/`;
+    if (!path.startsWith(prefix))
+        return unknownService(path);
+    const method = path.slice(prefix.length);
+    if (!PSDB_METHODS.includes(method))
+        return unknownMethod(method);
+    // Connect unary RPCs are POST-only; a GET is refused before authentication, as Connect does.
+    if (req.method.toUpperCase() !== 'POST')
+        return postOnly();
+    const credential = extractBasicCredential(req.headers);
+    if (credential === null)
+        return unauthenticated(undefined);
+    if (req.username !== undefined && credential.username !== req.username)
+        return unauthenticated(undefined);
+    if (req.password !== undefined && credential.password !== req.password)
+        return unauthenticated(undefined);
+    // a password the management lane issued authenticates by its secret and acts in its role; a deleted one (or one of a
+    // deleted database) is refused like any bad credential (planetscale-roles.ts)
+    const issued = issuedPassword(req.root, credential, req.occurredAt);
+    if (issued === 'refused')
+        return unauthenticated(undefined);
+    const payload = req.body === undefined || req.body.trim() === '' ? {} : payloadOf(req.body);
+    if (payload === undefined)
+        return malformedBody();
+    const ctx = {
+        ...(req.root !== undefined ? { root: req.root } : {}),
+        occurredAt: req.occurredAt ?? '1970-01-01T00:00:00.000Z',
+        ...(req.readOnly !== undefined ? { readOnly: req.readOnly } : {}),
+        database: req.database ?? DEFAULT_DATABASE,
+        // a password acts on the branch it was made on (M5: "Create new credentials to access a branch's data",
+        // planetscale.com/docs/cli/password); the World's own credential acts on the branch the server was given
+        branch: issued?.branch ?? req.branch ?? DEFAULT_BRANCH,
+        ...(issued?.scope ? { scope: issued.scope } : {}),
+    };
+    const branch = ctx.branch ?? DEFAULT_BRANCH;
+    if (method === 'CreateSession')
+        return createSession(ctx, credential.username, branch);
+    if (method === 'CloseSession')
+        return closeSession(req, ctx, payload, branch);
+    if (method === 'Prepare')
+        return prepareUnimplemented();
+    if (method === 'StreamExecute')
+        return streamExecuteUnmodelled();
+    // ── Execute ────────────────────────────────────────────────────────────────────────────────
+    const query = payload.query;
+    const incoming = sessionIdOf(payload.session);
+    // the session's user variables and SQL mode ride the session the client echoes (vtgate.proto Session
+    // user_defined_variables, system_variables), as Vitess keeps them
+    const vars = sessionVarsOf(payload.session);
+    ctx.vars = vars;
+    if (typeof query !== 'string')
+        return queryNotString();
+    try {
+        if (issued !== undefined) {
+            let stmt;
+            try {
+                stmt = parseStatement(query);
+            }
+            catch {
+                stmt = undefined;
+            } // a statement that does not parse is refused by executeSql
+            const refused = stmt === undefined ? undefined : roleRefusal(issued.role, stmt);
+            if (refused)
+                throw refused;
+            if (stmt !== undefined && issued.safeMigrations && isDdl(stmt))
+                throw directDdlDisabled();
+        }
+        const { outcome, session } = await executeSql(ctx, query, incoming);
+        const body = {
+            session: makeSession(session.id, { branch, inTransaction: session.inTransaction, vars: outcome.vars ?? vars }),
+            result: encodeQueryResult(outcome),
+        };
+        // `timing` is DELIBERATELY omitted: it is an elapsed-wall-clock measurement, and this repo's
+        // serve-path determinism rule forbids one. The client's own `timing ?? 0` handles its absence,
+        // so `ExecutedQuery.time` reads 0 — honestly "not measured" rather than an invented duration.
+        return { status: 200, body, headers: JSON_HEADERS };
+    }
+    catch (error) {
+        if (!(error instanceof SqlError))
+            return internalFault(error);
+        // HTTP 200 — see the header. The client turns this into `DatabaseError(message, 400, error)`.
+        //
+        // The echoed session must report the transaction's REAL state. §9 round one, finding 10: this
+        // used to answer a flat `inTransaction: false`, so a statement that failed INSIDE an open
+        // transaction told the caller the transaction had ended — while the server still held the
+        // buffer and a later COMMIT still landed everything. MySQL does not end a transaction on a
+        // failed statement, and neither does this twin, so the wire must not say otherwise.
+        const open = incoming === null ? undefined : sessionState(req.root, incoming, ctx.database ?? DEFAULT_DATABASE, ctx.scope);
+        const body = {
+            session: makeSession(incoming ?? '', { branch, inTransaction: open?.inTransaction === true, vars }),
+            error: { code: error.code, message: error.message },
+        };
+        return { status: 200, body, headers: JSON_HEADERS };
+    }
+}
+const unknownService = (path) => connectError(404, 'not_found', `unknown service: ${path.replace(/^\//, '').split('/')[0] ?? ''}`);
+const unknownMethod = (method) => connectError(404, 'unimplemented', `${PSDB_SERVICE}/${method} is not implemented`);
+const postOnly = () => connectError(405, 'unimplemented', 'HTTP GET is not supported by this protocol');
+const malformedBody = () => connectError(400, 'invalid_argument', 'malformed JSON request body');
+const queryNotString = () => connectError(400, 'invalid_argument', 'query must be a string');
+/** A request body as a JSON object; undefined when it is not one. */
+function payloadOf(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : undefined;
+}
+/**
+ * A fault inside the twin that is not a `SqlError`, answered as Connect's `internal` transport error. The wire must never
+ * be the crash surface (a deeply nested expression's RangeError once escaped as an HTTP 500 and the client's
+ * `UnknownError`), so the boundary that owns the protocol answers it.
+ */
+const internalFault = (error) => connectError(500, 'internal', `internal twin error: ${error instanceof Error ? error.message : String(error)}`);
+/** VENDOR-FAITHFUL: ps-http-sim answers Prepare with Connect's Unimplemented, and the client never calls it. */
+const prepareUnimplemented = () => connectError(501, 'unimplemented', 'psdb.v1alpha1.Database/Prepare is not implemented');
+/**
+ * A TWIN GAP, stated as one: the real service implements StreamExecute; this twin does not model Connect's
+ * server-streaming envelope framing, and a unary body here would be a fabricated success.
+ */
+const streamExecuteUnmodelled = () => connectError(501, 'unimplemented', 'psdb.v1alpha1.Database/StreamExecute is not modeled by this twin');
+/** CreateSession: a fresh session on the branch, and the user the credential names. */
+async function createSession(ctx, username, branch) {
+    const state = await storeCreateSession(ctx);
+    const body = {
+        branch,
+        user: { username, psid: username },
+        session: makeSession(state.id, { branch, inTransaction: false }),
+    };
+    return { status: 200, body, headers: JSON_HEADERS };
+}
+/**
+ * CloseSession: a session the twin issued moves by the declared machine (manifest.ts): open → closed, or stays closed.
+ * Connect's CloseSessionResponse carries the (now closed) session; a session the twin never issued is NOT an error, as
+ * the real service tolerates it.
+ */
+async function closeSession(req, ctx, payload, branch) {
+    const id = sessionIdOf(payload.session);
+    const held = id === null ? undefined : sessionState(req.root, id, ctx.database ?? DEFAULT_DATABASE, ctx.scope);
+    if (held !== undefined) {
+        const { move } = transitionFor('closed', manifest.resources.Session.state.closed, 'CloseSession', held.closed, undefined, id);
+        if (move === undefined)
+            throw new Error(`CloseSession moves a session from closed=${String(held.closed)}, which the machine does not declare`);
+    }
+    if (id !== null)
+        await storeCloseSession(ctx, id);
+    return { status: 200, body: { session: makeSession(id ?? '', { branch, inTransaction: false }) }, headers: JSON_HEADERS };
+}
+/**
+ * The password a Basic credential names, when the management lane issued one with its username: its role when the secret
+ * matches and it is not deleted, `refused` otherwise. A credential no issued password names is the World's own, as every
+ * credential was before passwords were issued, and acts as admin: an application pointed at the World (Dub) carries
+ * whatever credential its own configuration holds. That rule is the twin's decision.
+ */
+function issuedPassword(root, credential, occurredAt) {
+    const row = twinResourcesOfType(SERVICE, '_password', root).map((r) => ownFields(r))
+        .find((p) => p.username === credential.username);
+    if (row === undefined)
+        return undefined;
+    if (row.deleted_at !== null && row.deleted_at !== undefined)
+        return 'refused';
+    if (row._secret_sha256 !== createHash('sha256').update(credential.password).digest('hex'))
+        return 'refused';
+    // a password whose ttl has passed "will be invalid" (the spec's create_password), refused like any bad credential
+    if (typeof row.expires_at === 'string' && occurredAt !== undefined && Date.parse(row.expires_at) <= Date.parse(occurredAt))
+        return 'refused';
+    // the branch the password was made on (its `database_branch`), and that branch's scope in the store
+    const branch = String(row.database_branch?.name ?? DEFAULT_BRANCH);
+    const scope = scopeOf(String(row._database || DEFAULT_DATABASE), branch);
+    // the branch's safe migrations, as the management lane keeps them on its branch record
+    const database = String(row._database ?? '');
+    const record = twinResourcesOfType(SERVICE, '_branch', root).find((r) => ownFields(r)._database === database && ownFields(r).name === branch && ownFields(r).deleted_at === null);
+    const safeMigrations = record !== undefined && ownFields(record).safe_migrations === true;
+    return { role: row.role, branch, ...(scope ? { scope } : {}), safeMigrations };
+}
+export { PLANETSCALE_RESOURCE_TYPES };

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

@@ -0,0 +1,139 @@
+/** An exact decimal: `m / 10^s`. Integers are decimals of scale 0. */
+export type Dec = {
+    m: bigint;
+    s: number;
+};
+/** A plain decimal or exponent spelling (`12`, `-0.50`, `.5`, `1.5e3`) as an exact value; null for
+ *  anything else. */
+export declare function parseDec(text: string): Dec | null;
+/** A double as the exact decimal of its shortest round-trip spelling. */
+export declare function decFromNumber(n: number): Dec;
+export declare const decFromBigInt: (n: bigint) => Dec;
+export declare const decAdd: (a: Dec, b: Dec) => Dec;
+export declare const decSub: (a: Dec, b: Dec) => Dec;
+export declare const decMul: (a: Dec, b: Dec) => Dec;
+export declare const decNeg: (a: Dec) => Dec;
+export declare const decIsZero: (a: Dec) => boolean;
+export declare function decCmp(a: Dec, b: Dec): number;
+/** Round half away from zero to `scale` digits (MySQL's rounding for exact values). */
+export declare function decRound(a: Dec, scale: number): Dec;
+/** Truncate toward zero to an integer. */
+export declare const decTrunc: (a: Dec) => bigint;
+/** `a / b` rounded half away from zero to `scale` digits; null on division by zero. */
+export declare function decDiv(a: Dec, b: Dec, scale: number): Dec | null;
+/** The remainder of `a / b` with the sign of `a` (MySQL MOD); null on division by zero. */
+export declare function decMod(a: Dec, b: Dec): Dec | null;
+/** The text of an exact value at its own scale, or at `scale` when given (padded or rounded). */
+export declare function decText(a: Dec, scale?: number): string;
+/** The canonical key of a value: trailing fractional zeros removed, so 1.50 and 1.5 meet. */
+export declare function decKey(a: Dec): string;
+/** Digits before the decimal point (0 for a pure fraction). */
+export declare function decIntDigits(a: Dec): number;
+export declare const decToNumber: (a: Dec) => number;
+/**
+ * A double as MySQL prints one: the shortest digits that round-trip, in positional notation while
+ * the decimal exponent stays within DBL_DIG (15) digits, else `d.ddde±x` without a plus sign
+ * (`1e20`, `1.2345678901234568e17`, `1e-7`).
+ */
+export declare function formatDouble(n: number): string;
+/** A FLOAT (single precision) as MySQL prints it: the shortest digits that round-trip as float32. */
+export declare function formatFloat(n: number): string;
+/** MySQL's string → number conversion: the longest numeric prefix after leading spaces (`'1abc'`
+ *  is 1, `'abc'` is 0), with `complete` saying whether the whole string was that number. */
+export declare function stringNumberPrefix(text: string): {
+    value: number;
+    text: string;
+    complete: boolean;
+};
+export type TemporalKind = 'DATE' | 'DATETIME' | 'TIMESTAMP' | 'TIME';
+/** A temporal value's parts. A TIME uses `h` for its whole hours (up to 838) and `neg` for its sign. */
+export type Temporal = {
+    y: number;
+    mo: number;
+    d: number;
+    h: number;
+    mi: number;
+    s: number;
+    us: number;
+    neg: boolean;
+};
+/** How a parse went: `truncated` when trailing text was ignored (a warning, an error on a strict
+ *  write), `zero` for a date with a zero part (refused on a strict write by NO_ZERO_DATE and
+ *  NO_ZERO_IN_DATE). */
+export type TemporalParse = {
+    t: Temporal;
+    truncated: boolean;
+    zero: boolean;
+};
+/**
+ * A DATE / DATETIME / TIMESTAMP string in any form MySQL accepts (manual 11.1.3 "Date and Time
+ * Literals"): delimited `YYYY-MM-DD[ hh:mm:ss[.fraction]]` with any punctuation as the delimiter
+ * and a space or `T` between date and time (the `T` form is what @planetscale/database sends for a
+ * `Date`), two-digit years (70–99 → 19xx, 00–69 → 20xx), the undelimited `YYYYMMDD[hhmmss]` and
+ * `YYMMDD[hhmmss]` forms, and a trailing `+hh:mm`/`-hh:mm` offset (8.0.19+), converted to UTC, the
+ * session time zone. Null when the text is not a date.
+ */
+export declare function parseDateTimeText(text: string): TemporalParse | null;
+/** A TIME string (manual 11.1.3): `[-][D ]hh:mm[:ss][.fraction]`, `hh:mm`, or undelimited
+ *  `[-]hhmmss`/`mmss`/`ss`. A full DATETIME string is taken as its time of day. Range ±838:59:59. */
+export declare function parseTimeText(text: string): TemporalParse | null;
+/** A number used as a temporal (`20240101`, `20240101103000.5`, `103000` for a TIME). */
+export declare function parseTemporalNumber(text: string, kind: TemporalKind): TemporalParse | null;
+/** The instant (ms) a DATETIME's wall time names in UTC, and the reverse; CONVERT_TZ's arithmetic. */
+export declare const temporalUtcMs: (t: Temporal) => number;
+export declare function temporalFromUtcMs(ms: number, us: number): Temporal;
+/** Round a value's fraction to `fsp` digits, as MySQL does on store (a half rounds up and carries). */
+export declare function roundFsp(t: Temporal, fsp: number, kind: TemporalKind): Temporal;
+/** The canonical text MySQL returns for a value of `kind` with `fsp` fractional digits. */
+export declare function formatTemporal(t: Temporal, kind: TemporalKind, fsp: number): string;
+/** A totally ordered key of a temporal value: DATE/DATETIME/TIMESTAMP as their packed
+ *  `YYYYMMDDhhmmss.ffffff`, a TIME as its signed microseconds. */
+export declare function packTemporal(t: Temporal, kind: TemporalKind): bigint;
+/** A temporal in numeric context: DATE → YYYYMMDD, DATETIME → YYYYMMDDhhmmss[.f], TIME → hhmmss[.f]. */
+export declare function temporalNumberText(t: Temporal, kind: TemporalKind, fsp: number): string;
+/** TIMESTAMP's range: '1970-01-01 00:00:01.000000' to '2038-01-19 03:14:07.999999' UTC. */
+export declare function inTimestampRange(t: Temporal): boolean;
+/** A JSON number. Integers are exact (MySQL keeps int64/uint64); a number with a fraction or an
+ *  exponent, or beyond uint64, is a DOUBLE; a DECIMAL comes only from SQL (JSON_OBJECT('k', 1.50)). */
+export declare class JNum {
+    readonly kind: 'int' | 'double' | 'decimal';
+    readonly int: bigint;
+    readonly dbl: number;
+    readonly dec: Dec | null;
+    private constructor();
+    static int(n: bigint): JNum;
+    static double(n: number): JNum;
+    static decimal(d: Dec): JNum;
+    exact(): Dec;
+}
+/** A JSON object: members in MySQL's normalized order (shorter keys first, then byte order). */
+export declare class JObj {
+    readonly members: Map<string, JV>;
+    constructor(members: Map<string, JV>);
+}
+export type JV = null | boolean | string | JNum | JV[] | JObj;
+export declare class JsonTextError extends Error {
+    readonly reason: string;
+    readonly position: number;
+    constructor(reason: string, position: number);
+}
+/** Parse JSON text (RFC 8259, what MySQL accepts). Throws `JsonTextError` with MySQL's reason. */
+export declare function parseJson(text: string): JV;
+/** A JSON object built from members in any order (JSON_OBJECT), normalized as MySQL stores it. */
+export declare const jsonObject: (members: Map<string, JV>) => JObj;
+/** A JSON value printed as MySQL prints one: `", "` and `": "` separators, normalized member order,
+ *  doubles with a `.0` when they would otherwise read as integers. */
+export declare function printJson(v: JV): string;
+export declare function jsonTypeName(v: JV): string;
+/** Compare two JSON values (manual 13.5, "Comparison and Ordering of JSON Values"). Values of
+ *  different types order by type precedence; numbers compare by value whatever their kind; strings
+ *  by their utf8mb4 bytes; arrays element by element, the shorter first on a tie; booleans false
+ *  first; objects are equal when they have the same members, otherwise ordered deterministically. */
+export declare function compareJson(a: JV, b: JV): number;
+/** A key under which JSON values that compare equal meet (numbers by value, objects by members). */
+export declare function jsonKey(v: JV): string;
+/** JSON_CONTAINS (manual 14.17.3): a scalar contains an equal scalar; an array contains every
+ *  element of a candidate array, or a candidate non-array equal to one of its elements; an object
+ *  contains a candidate object whose every member it contains. */
+export declare function jsonContains(target: JV, candidate: JV): boolean;
+export declare function jsonDepth(v: JV): number;