@volter/twin-planetscale 0.1.0

package/dist/src/planetscale-collation.js

@@ -0,0 +1,391 @@
+// MySQL 8 COLLATIONS — how two strings compare, sort, group and collide. Collation changes
+// comparison only: stored bytes and returned values stay exactly as written.
+//
+// Reference: MySQL 8.0 Reference Manual, chapter 10 "Character Sets, Collations, Unicode":
+//   10.3.1 Collation Naming Conventions (_ai/_as, _ci/_cs, _bin; the 0900 = UCA 9.0.0 collations),
+//   10.8.4 Collation Coercibility in Expressions (derivations and the aggregation rules below),
+//   10.8.5 The binary Collation Compared to _bin Collations,
+//   10.10.1 Unicode Character Sets (utf8mb4_general_ci, utf8mb4_unicode_ci = UCA 4.0.0,
+//           utf8mb4_0900_ai_ci = UCA 9.0.0; PAD SPACE for all but the 0900 family, which is NO PAD),
+//   12.8.1 String Comparison Functions (LIKE compares per character under the collation).
+// The weights are the published tables those collations are built from (planetscale-collation-
+// weights.gen.ts): DUCET 9.0.0 for utf8mb4_0900_*, DUCET 4.0.0 primaries for *_unicode_ci and the
+// MySQL 8.0 `my_unicase_default` sort table for *_general_ci.
+//
+// WHAT IS MODELLED OF THE WEIGHT TABLES: the DUCET entries for U+0000..U+052F (Latin, IPA, Greek,
+// Cyrillic, combining diacritics), 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, including DUCET's expansions (ß = ss, æ = ae, fi = fi under
+// utf8mb4_0900_ai_ci) and its contractions in those ranges. Every other character takes UCA's
+// implicit weight derived from its code point, which is the weight MySQL gives an UNASSIGNED
+// character: it equals only itself and sorts after the modelled ranges. For assigned characters
+// outside the ranges (Arabic, Hebrew, Indic, kana, Hangul, emoji, …) that is not MySQL's answer —
+// their case/width/accent equivalences and their order are not modelled
+// (planetscale.collation.uca_full_weight_table).
+import { GENERAL_CI, UCA_400, UCA_900 } from "./planetscale-collation-weights.gen.js";
+let ducet900;
+let uca400;
+let general;
+function loadDucet900() {
+    if (ducet900 !== undefined)
+        return ducet900;
+    const single = new Map();
+    const contractions = new Map();
+    for (const entry of UCA_900.split(' ')) {
+        const [keyText, body] = entry.split(':');
+        const cps = keyText.split('+').map((h) => parseInt(h, 16));
+        const ces = [];
+        for (const ce of body === '' ? [] : body.split(',')) {
+            const [p, s, t] = ce.split('.').map((h) => parseInt(h, 16));
+            ces.push(p, s ?? 0x20, t ?? 0x2);
+        }
+        if (cps.length === 1)
+            single.set(cps[0], ces);
+        else {
+            const list = contractions.get(cps[0]) ?? [];
+            list.push({ rest: cps.slice(1), ces });
+            list.sort((a, b) => b.rest.length - a.rest.length);
+            contractions.set(cps[0], list);
+        }
+    }
+    return (ducet900 = { single, contractions });
+}
+function loadUca400() {
+    if (uca400 !== undefined)
+        return uca400;
+    const map = new Map();
+    for (const entry of UCA_400.split(' ')) {
+        const [cp, body] = entry.split(':');
+        map.set(parseInt(cp, 16), body === '' ? [] : body.split(',').map((h) => parseInt(h, 16)));
+    }
+    return (uca400 = map);
+}
+function loadGeneral() {
+    if (general !== undefined)
+        return general;
+    const map = new Map();
+    for (const entry of GENERAL_CI.split(' ')) {
+        const [cp, sort] = entry.split(':');
+        map.set(parseInt(cp, 16), parseInt(sort, 16));
+    }
+    return (general = map);
+}
+const codePoints = (s) => { const out = []; for (const ch of s)
+    out.push(ch.codePointAt(0)); return out; };
+/** The twelve CJK Compatibility Ideographs that are Unified_Ideograph (UCA "core Han"). */
+const COMPAT_UNIFIED = new Set([0xfa0e, 0xfa0f, 0xfa11, 0xfa13, 0xfa14, 0xfa1f, 0xfa21, 0xfa23, 0xfa24, 0xfa27, 0xfa28, 0xfa29]);
+/** UCA 9.0.0 implicit weights (UTS #10 §10.1.3): [AAAA.0020.0002][BBBB.0000.0000]. */
+function implicit900(cp) {
+    if (cp >= 0x17000 && cp <= 0x18aff)
+        return [0xfb00, 0x20, 0x2, (cp - 0x17000) | 0x8000, 0, 0];
+    let base = 0xfbc0;
+    if ((cp >= 0x4e00 && cp <= 0x9fd5) || COMPAT_UNIFIED.has(cp))
+        base = 0xfb40;
+    else if ((cp >= 0x3400 && cp <= 0x4db5) || (cp >= 0x20000 && cp <= 0x2a6d6) || (cp >= 0x2a700 && cp <= 0x2b734)
+        || (cp >= 0x2b740 && cp <= 0x2b81d) || (cp >= 0x2b820 && cp <= 0x2cea1))
+        base = 0xfb80;
+    return [base + (cp >> 15), 0x20, 0x2, (cp & 0x7fff) | 0x8000, 0, 0];
+}
+/** The DUCET 9.0.0 collation elements of a string, flat [p, s, t, p, s, t, …]. */
+function elements900(cps) {
+    const { single, contractions } = loadDucet900();
+    const out = [];
+    for (let i = 0; i < cps.length; i++) {
+        const cp = cps[i];
+        const candidates = contractions.get(cp);
+        let matched = false;
+        if (candidates !== undefined) {
+            for (const c of candidates) {
+                if (c.rest.every((r, k) => cps[i + 1 + k] === r)) {
+                    out.push(...c.ces);
+                    i += c.rest.length;
+                    matched = true;
+                    break;
+                }
+            }
+        }
+        if (matched)
+            continue;
+        out.push(...(single.get(cp) ?? implicit900(cp)));
+    }
+    return out;
+}
+/** A multi-level UCA sort key: each level's non-zero weights, levels separated by 0x0000. One
+ *  weight is one UTF-16 code unit, so comparing keys as strings compares the weights. */
+function ucaKey(ces, levels) {
+    let key = '';
+    for (let level = 0; level < levels; level++) {
+        if (level > 0)
+            key += '\u0000';
+        for (let i = level; i < ces.length; i += 3)
+            if (ces[i] !== 0)
+                key += String.fromCharCode(ces[i]);
+    }
+    return key;
+}
+/** utf8mb4_unicode_ci's primary weights (UCA 4.0.0). MySQL gives every supplementary character
+ *  the weight of U+FFFD; unlisted BMP characters take the UCA 4.0.0 implicit weight. */
+function weights400(cps) {
+    const table = loadUca400();
+    const out = [];
+    for (const cp of cps) {
+        if (cp > 0xffff) {
+            out.push(0xfffd);
+            continue;
+        }
+        const w = table.get(cp);
+        if (w !== undefined) {
+            out.push(...w);
+            continue;
+        }
+        const base = cp >= 0x3400 && cp <= 0x4db5 ? 0xfb80 : (cp >= 0x4e00 && cp <= 0x9fa5) || COMPAT_UNIFIED.has(cp) ? 0xfb40 : 0xfbc0;
+        out.push(base + (cp >> 15), (cp & 0x7fff) | 0x8000);
+    }
+    return out;
+}
+/** utf8mb4_general_ci: one weight per character from `my_unicase_default`; U+FFFD for supplementary. */
+function weightsGeneral(cps) {
+    const table = loadGeneral();
+    return cps.map((cp) => (cp > 0xffff ? 0xfffd : table.get(cp) ?? cp));
+}
+/** PAD SPACE comparison of single-level weights: the shorter string is extended with spaces
+ *  (MySQL's strnncollsp), so trailing spaces never matter and a trailing weight below the space
+ *  weight (a TAB) sorts BEFORE the unpadded string. */
+function padCompare(a, b, space) {
+    const n = Math.min(a.length, b.length);
+    for (let i = 0; i < n; i++)
+        if (a[i] !== b[i])
+            return a[i] < b[i] ? -1 : 1;
+    if (a.length === b.length)
+        return 0;
+    const longer = a.length > b.length ? a : b;
+    const sign = a.length > b.length ? 1 : -1;
+    for (let i = n; i < longer.length; i++)
+        if (longer[i] !== space)
+            return longer[i] < space ? -sign : sign;
+    return 0;
+}
+const padKey = (w, space) => {
+    let end = w.length;
+    while (end > 0 && w[end - 1] === space)
+        end--;
+    let key = '';
+    for (let i = 0; i < end; i++)
+        key += String.fromCodePoint(w[i]);
+    return key;
+};
+function codePointCompare(a, b) {
+    if (a === b)
+        return 0;
+    const x = codePoints(a);
+    const y = codePoints(b);
+    const n = Math.min(x.length, y.length);
+    for (let i = 0; i < n; i++)
+        if (x[i] !== y[i])
+            return x[i] < y[i] ? -1 : 1;
+    return x.length === y.length ? 0 : x.length < y.length ? -1 : 1;
+}
+/** Bounded per-collation memo of sort keys: sorts and group-bys key the same strings repeatedly. */
+function memo(fn) {
+    const cache = new Map();
+    return (s) => {
+        const hit = cache.get(s);
+        if (hit !== undefined)
+            return hit;
+        const k = fn(s);
+        if (cache.size >= 50_000)
+            cache.clear();
+        cache.set(s, k);
+        return k;
+    };
+}
+const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+function uca900(name, id, levels) {
+    const key = memo((s) => ucaKey(elements900(codePoints(s)), levels));
+    return { name, id, charset: 'utf8mb4', pad: false, binsort: false, key, compare: (a, b) => cmp(key(a), key(b)), charKey: (cp) => key(String.fromCodePoint(cp)) };
+}
+function padded(name, id, charset, weights, space, binsort) {
+    const w = memo((s) => weights(codePoints(s)));
+    const key = memo((s) => padKey(w(s), space));
+    return {
+        name, id, charset, pad: true, binsort, key,
+        compare: (a, b) => (a === b ? 0 : padCompare(w(a), w(b), space)),
+        charKey: (cp) => weights([cp]).map((w) => String.fromCodePoint(w)).join(''),
+    };
+}
+const identity = (cps) => cps;
+/** The byte-wise `binary` collation of binary strings. Operands are byte strings (one char per byte). */
+export const BINARY_COLLATION = {
+    name: 'binary', id: 63, charset: 'binary', pad: false, binsort: true,
+    key: (s) => s, compare: cmp, charKey: (cp) => String.fromCharCode(cp),
+};
+const COLLATIONS = [
+    BINARY_COLLATION,
+    uca900('utf8mb4_0900_ai_ci', 255, 1),
+    uca900('utf8mb4_0900_as_ci', 305, 2),
+    uca900('utf8mb4_0900_as_cs', 278, 3),
+    { name: 'utf8mb4_0900_bin', id: 309, charset: 'utf8mb4', pad: false, binsort: true, key: (s) => s, compare: codePointCompare, charKey: (cp) => String.fromCodePoint(cp) },
+    padded('utf8mb4_bin', 46, 'utf8mb4', identity, 0x20, true),
+    padded('utf8mb4_general_ci', 45, 'utf8mb4', weightsGeneral, 0x20, false),
+    padded('utf8mb4_unicode_ci', 224, 'utf8mb4', weights400, 0x209, false),
+    padded('utf8mb3_general_ci', 33, 'utf8mb3', weightsGeneral, 0x20, false),
+    padded('utf8mb3_bin', 83, 'utf8mb3', identity, 0x20, true),
+    padded('utf8mb3_unicode_ci', 192, 'utf8mb3', weights400, 0x209, false),
+];
+const BY_NAME = new Map(COLLATIONS.map((c) => [c.name, c]));
+/** Every collation the engine models (INFORMATION_SCHEMA.COLLATIONS lists them). */
+export const modelledCollations = () => COLLATIONS;
+const BY_ID = new Map(COLLATIONS.map((c) => [c.id, c]));
+/** MySQL 8's default collation per character set (SHOW CHARACTER SET). */
+export const DEFAULT_COLLATION_OF = { utf8mb4: 'utf8mb4_0900_ai_ci', utf8mb3: 'utf8mb3_general_ci', binary: 'binary' };
+/** The database default, and the connection collation string literals take (`SET NAMES utf8mb4`
+ *  selects utf8mb4's default collation, `default_collation_for_utf8mb4` = utf8mb4_0900_ai_ci). */
+export const DATABASE_COLLATION = 'utf8mb4_0900_ai_ci';
+/** The character sets MySQL 8 ships (SHOW CHARACTER SET). Names here that are not modelled are
+ *  refused as unmodelled surface; any other name is MySQL's unknown charset/collation error. */
+const MYSQL_CHARSETS = new Set(['armscii8', 'ascii', 'big5', 'binary', 'cp1250', 'cp1251', 'cp1256', 'cp1257', 'cp850', 'cp852', 'cp866', 'cp932',
+    'dec8', 'eucjpms', 'euckr', 'gb18030', 'gb2312', 'gbk', 'geostd8', 'greek', 'hebrew', 'hp8', 'keybcs2', 'koi8r', 'koi8u', 'latin1', 'latin2',
+    'latin5', 'latin7', 'macce', 'macroman', 'sjis', 'swe7', 'tis620', 'ucs2', 'ujis', 'utf16', 'utf16le', 'utf32', 'utf8', 'utf8mb3', 'utf8mb4']);
+/** `utf8` is MySQL 8.0's alias for utf8mb3, in charset and collation names alike. */
+const canonicalName = (name) => {
+    const n = name.toLowerCase();
+    return n === 'utf8' ? 'utf8mb3' : n.startsWith('utf8_') ? `utf8mb3_${n.slice(5)}` : n;
+};
+export function lookupCollation(name) {
+    const n = canonicalName(name);
+    const c = BY_NAME.get(n);
+    return c !== undefined ? { found: c } : notModelled(n, name);
+}
+/** A collation name the twin does not model: one of MySQL's (named for a MySQL character set) or no collation at all. */
+function notModelled(n, name) {
+    const charset = n.split('_')[0];
+    return MYSQL_CHARSETS.has(charset) && n.includes('_') ? { unmodelled: n } : { unknown: name };
+}
+export function lookupCharset(name) {
+    const n = canonicalName(name);
+    if (n === 'utf8mb4' || n === 'utf8mb3' || n === 'binary')
+        return { found: n };
+    return MYSQL_CHARSETS.has(n) ? { unmodelled: n } : { unknown: name };
+}
+/** A modelled collation by name (canonical names only), or undefined. */
+export const collationNamed = (name) => (name === undefined ? undefined : BY_NAME.get(canonicalName(name)));
+export const collationById = (id) => (id === undefined ? undefined : BY_ID.get(id));
+export const defaultCollation = (charset) => BY_NAME.get(DEFAULT_COLLATION_OF[charset]);
+export const databaseCollation = () => BY_NAME.get(DATABASE_COLLATION);
+/** The `_bin` collation of a charset (a column's `BINARY` attribute). */
+export const binCollation = (charset) => (charset === 'binary' ? BINARY_COLLATION : BY_NAME.get(`${charset}_bin`));
+// ── coercibility (10.8.4) ─────────────────────────────────────────────────────────────────────
+export const EXPLICIT = 0;
+export const NONE = 1;
+export const IMPLICIT = 2;
+export const SYSCONST = 3;
+export const COERCIBLE = 4;
+export const NUMERIC = 5;
+export const IGNORABLE = 6;
+export const DERIVATION_NAMES = ['EXPLICIT', 'NONE', 'IMPLICIT', 'SYSCONST', 'COERCIBLE', 'NUMERIC', 'IGNORABLE'];
+const unicode = (c) => c.charset !== 'binary';
+/** utf8mb4 is a superset of utf8mb3; a Unicode operand of lower derivation absorbs the other. */
+function leftIsSuperset(l, r) {
+    return unicode(l.collation) && (l.derivation < r.derivation
+        || (l.derivation === r.derivation && (!unicode(r.collation) || (l.collation.charset === 'utf8mb4' && r.collation.charset === 'utf8mb3'))));
+}
+/**
+ * The collation two operands are compared under — MySQL's DTCollation::aggregate with the
+ * comparison flags (superset and coercible conversion allowed). A result of derivation NONE is
+ * "Illegal mix of collations": two different non-binary collations of equal derivation, or two
+ * different EXPLICIT ones. A binary string wins over a character string of equal or higher
+ * derivation, and a `_bin` collation wins a tie against a `_ci`/`_cs` one of the same charset.
+ */
+export function aggregate(a, b) {
+    if (a.collation.charset !== b.collation.charset)
+        return binaryOperand(a, b) ?? acrossCharsets(a, b);
+    if (a.derivation < b.derivation)
+        return a;
+    if (b.derivation < a.derivation)
+        return b;
+    return a.collation === b.collation ? a : collationTie(a, b);
+}
+/** Of two operands of different character sets, the binary one: it wins over a character string of equal or higher derivation. */
+const binaryOperand = (a, b) => (a.collation.charset === 'binary' ? (a.derivation <= b.derivation ? a : b) : b.collation.charset === 'binary' ? (b.derivation <= a.derivation ? b : a) : undefined);
+/** Two different collations of one character set at equal derivation: `_bin` wins, two EXPLICIT ones are an illegal mix. */
+function collationTie(a, b) {
+    if (a.derivation === EXPLICIT)
+        return { collation: a.collation, derivation: NONE };
+    if (a.collation.binsort)
+        return a;
+    if (b.collation.binsort)
+        return b;
+    return { collation: binCollation(a.collation.charset), derivation: NONE };
+}
+/** Two character strings of different character sets: the superset, else the coercible side gives way. */
+function acrossCharsets(a, b) {
+    if (leftIsSuperset(a, b))
+        return a;
+    if (leftIsSuperset(b, a))
+        return b;
+    if (a.derivation < COERCIBLE && b.derivation === COERCIBLE)
+        return a;
+    if (b.derivation < COERCIBLE && a.derivation === COERCIBLE)
+        return b;
+    return { collation: BINARY_COLLATION, derivation: NONE };
+}
+/**
+ * LIKE under a collation: `%` matches any run of characters, `_` exactly one, `\` escapes, and
+ * every other pattern character matches one character of equal collation weight. Per character,
+ * so under utf8mb4_0900_ai_ci `'é' LIKE 'e'` holds while `'ß' LIKE 'ss'` does not (MySQL 8
+ * manual, 12.8.1: LIKE performs matching on a per-character basis). Trailing spaces are
+ * significant in LIKE whatever the collation's pad attribute.
+ */
+export function likeMatch(value, pattern, collation) {
+    const toks = [];
+    const p = collation.charset === 'binary' ? [...pattern].map((c) => c.charCodeAt(0)) : codePoints(pattern);
+    for (let i = 0; i < p.length; i++) {
+        const c = p[i];
+        if (c === 0x5c && i + 1 < p.length) {
+            toks.push({ key: collation.charKey(p[++i]) });
+            continue;
+        }
+        if (c === 0x25) {
+            if (!('any' in (toks[toks.length - 1] ?? {})))
+                toks.push({ any: true });
+            continue;
+        }
+        if (c === 0x5f) {
+            toks.push({ one: true });
+            continue;
+        }
+        toks.push({ key: collation.charKey(c) });
+    }
+    const v = (collation.charset === 'binary' ? [...value].map((c) => c.charCodeAt(0)) : codePoints(value)).map((c) => collation.charKey(c));
+    // Iterative wildcard match with single-star backtracking (each `%` resets the anchor).
+    let vi = 0;
+    let ti = 0;
+    let starTi = -1;
+    let starVi = 0;
+    while (vi < v.length) {
+        const t = toks[ti];
+        if (t !== undefined && 'one' in t) {
+            vi++;
+            ti++;
+            continue;
+        }
+        if (t !== undefined && 'key' in t && t.key === v[vi]) {
+            vi++;
+            ti++;
+            continue;
+        }
+        if (t !== undefined && 'any' in t) {
+            starTi = ti++;
+            starVi = vi;
+            continue;
+        }
+        if (starTi >= 0) {
+            ti = starTi + 1;
+            vi = ++starVi;
+            continue;
+        }
+        return false;
+    }
+    while (ti < toks.length && 'any' in toks[ti])
+        ti++;
+    return ti === toks.length;
+}

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

@@ -0,0 +1,8 @@
+export type PlanetscaleConformanceReport = {
+    ok: boolean;
+    endpointsChecked: number;
+    routerSurfaceChecked: number;
+    resourceTypesChecked: number;
+    violations: string[];
+};
+export declare function checkPlanetscaleConformance(): Promise<PlanetscaleConformanceReport>;

package/dist/src/planetscale-conformance.js

@@ -0,0 +1,213 @@
+// planetscale conformance (dev-only; lazy-imported by the CLI, NEVER from index.ts/runtime — E2).
+//
+// This is NOT a self-referential snapshot check. Two constants asserting about each other cannot
+// detect a dead handler (§9 has refuted that pattern twice in this repo), so this check ISSUES REAL
+// REQUESTS against a throwaway root and grades the OUTCOME a live handler produces — a status set
+// plus a predicate over the body. A twin whose handler returned `{}` fails every probe.
+//
+// FOUR directions are closed, not two:
+//   1. every PROBE has a matching entry in `implementedEndpoints` (no probe for unclaimed surface);
+//   2. every claimed endpoint has a PROBE (no claim nothing exercises);
+//   3. `ROUTER_SURFACE` — a HAND-WRITTEN census of the method/path pairs the router must REFUSE —
+//      is exercised, and any pair answering something other than the transport-level refusal
+//      envelope is a violation. Probe⇄snapshot alone is blind to SERVED-BUT-UNCLAIMED surface;
+//      this is what catches an endpoint that quietly exists.
+//   3b. `MALFORMED_SURFACE` — the branches where dispatch reaches Execute but the request never
+//      becomes a query. They must answer `invalid_argument`, never a query error and never a result.
+//   4. auth: a credential-less Execute must answer the vendor's 401 envelope. A twin that
+//      authenticated everything would pass every probe above while accepting an anonymous client.
+//
+// §9 round one rewrote direction 3 twice over: its census used to be BUILT FROM `PSDB_METHODS` (the
+// router's own method gate) behind a comment claiming it was hand-enumerated, and its "claimed"
+// half could not fire for any input. Both are documented at `ROUTER_SURFACE`.
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { twinResources } from '@volter/world-core';
+import { createPlanetscaleTwinFetch } from "./planetscale-server.js";
+import { SERVICE } from "./planetscale-store.js";
+import { handlePlanetscaleTwinRequest, planetscaleTwinSnapshot, PSDB_SERVICE, PLANETSCALE_RESOURCE_TYPES, } from "./planetscale-twin.js";
+import { unpackRow } from "./planetscale-wire.js";
+const AT = '2026-01-01T00:00:00.000Z';
+/** `Basic base64('twin:conformance')` — a credential the twin accepts because it is well-formed. */
+const AUTH = { authorization: `Basic ${btoa('twin:conformance')}` };
+const exec = (query, session) => JSON.stringify({ query, ...(session !== undefined ? { session } : {}) });
+/**
+ * The SERVED-BUT-UNCLAIMED census — every method/path pair the router must ANSWER WITH A REFUSAL.
+ *
+ * Probe⇄snapshot (directions 1 and 2) is blind in exactly one direction: surface the router quietly
+ * serves that no snapshot entry claims. This closes it. Anything here answering something other
+ * than the transport-level refusal envelope is a violation.
+ *
+ * HAND-WRITTEN LITERALS, deliberately. §9 round one, finding 8: the first version built five of its
+ * nine entries with `...PSDB_METHODS.map(...)` behind a comment insisting it was hand-enumerated.
+ * `PSDB_METHODS` IS the router's own method gate, so those five drifted in lockstep with the code
+ * they audit — adding a name to that array grew the census and produced no violation. Writing the
+ * paths out is what makes this an INDEPENDENT census; §9 still compares it against the real
+ * dispatch branches by reading.
+ *
+ * The CLAIMED half was deleted with it (finding 9): it could not fire. `Execute` with a `{}` body
+ * answers 400, which is not a refusal status, so the only entries the condition could reach were
+ * the two `unimplemented` ones it explicitly excluded. The PROBES above already assert each claimed
+ * endpoint's real OUTCOME, which is strictly stronger than "did not refuse".
+ */
+const ROUTER_SURFACE = [
+    // Wrong verb: Connect unary RPCs are POST-only, and the refusal precedes authentication.
+    { method: 'GET', path: '/psdb.v1alpha1.Database/Execute' },
+    { method: 'HEAD', path: '/psdb.v1alpha1.Database/Execute' },
+    { method: 'PUT', path: '/psdb.v1alpha1.Database/CreateSession' },
+    { method: 'DELETE', path: '/psdb.v1alpha1.Database/CloseSession' },
+    // A method the service does not declare.
+    { method: 'POST', path: '/psdb.v1alpha1.Database/NoSuchMethod', body: '{}' },
+    { method: 'POST', path: '/psdb.v1alpha1.Database/DropDatabase', body: '{}' },
+    // A different service, and paths shaped like OTHER vendors' that must not be served here.
+    { method: 'POST', path: '/psdb.v2.Database/Execute', body: '{}' },
+    { method: 'POST', path: '/v1/query', body: '{}' },
+    { method: 'POST', path: '/query', body: '{}' },
+    { method: 'POST', path: '/', body: '{}' },
+    { method: 'GET', path: '/' },
+];
+/** The malformed-input branches — see direction 3b below. */
+const MALFORMED_SURFACE = [
+    { label: 'a body that is not JSON', body: '{not json' },
+    { label: 'a JSON array body', body: '[1,2,3]' },
+    { label: 'a non-string query', body: JSON.stringify({ query: 42 }) },
+    { label: 'a missing query', body: JSON.stringify({ session: null }) },
+];
+export async function checkPlanetscaleConformance() {
+    const snapshot = planetscaleTwinSnapshot();
+    const violations = [];
+    const root = mkdtempSync(join(tmpdir(), 'planetscale-conf-'));
+    const call = (method, path, body, headers = AUTH) => handlePlanetscaleTwinRequest({ method, path, headers, root, occurredAt: AT, ...(body !== undefined ? { body } : {}) });
+    const probes = [
+        {
+            label: 'POST /psdb.v1alpha1.Database/CreateSession',
+            method: 'POST', path: `/${PSDB_SERVICE}/CreateSession`, body: '{}',
+            expect: (r) => {
+                const b = r.body;
+                return r.status === 200 && b.branch === 'main' && b.user?.username === 'twin'
+                    && typeof b.session?.vitessSession?.sessionUUID === 'string' && b.session.vitessSession.sessionUUID !== '';
+            },
+        },
+        {
+            label: 'POST /psdb.v1alpha1.Database/Execute',
+            method: 'POST', path: `/${PSDB_SERVICE}/Execute`, body: exec('SELECT 1 AS one FROM dual'),
+            expect: (r) => {
+                const b = r.body;
+                if (r.status !== 200 || b.error !== undefined || b.result === undefined)
+                    return false;
+                // Grade the DECODED VALUE, not the shape: a handler that returned an empty result set, or
+                // packed the row wrongly, fails here.
+                const fields = b.result.fields ?? [];
+                const rows = b.result.rows ?? [];
+                return fields.length === 1 && fields[0].name === 'one' && rows.length === 1
+                    && unpackRow(rows[0])[0] === '1';
+            },
+        },
+        {
+            label: 'POST /psdb.v1alpha1.Database/CloseSession',
+            method: 'POST', path: `/${PSDB_SERVICE}/CloseSession`,
+            body: JSON.stringify({ session: { vitessSession: { sessionUUID: 'tws-1-0' } } }),
+            expect: (r) => {
+                const b = r.body;
+                return r.status === 200 && b.session?.vitessSession?.sessionUUID === 'tws-1-0';
+            },
+        },
+        {
+            label: 'POST /psdb.v1alpha1.Database/Prepare (vendor-faithful unimplemented)',
+            method: 'POST', path: `/${PSDB_SERVICE}/Prepare`, body: '{}',
+            expect: (r) => r.status === 501 && r.body.code === 'unimplemented',
+        },
+        {
+            label: 'POST /psdb.v1alpha1.Database/StreamExecute (the gap: Connect unimplemented)',
+            method: 'POST', path: `/${PSDB_SERVICE}/StreamExecute`, body: exec('SELECT 1'),
+            // this probe calls the request handler, which answers 501; through the pack's fetch it is the gap (psdbGap), 404
+            expect: (r) => r.status === 501 && r.body.code === 'unimplemented',
+        },
+    ];
+    try {
+        for (const probe of probes) {
+            if (!snapshot.implementedEndpoints.includes(probe.label)) {
+                violations.push(`probe '${probe.label}' has no matching entry in implementedEndpoints`);
+                continue;
+            }
+            const response = await call(probe.method, probe.path, probe.body, probe.headers ?? AUTH);
+            if (!probe.expect(response)) {
+                violations.push(`endpoint '${probe.label}' did not answer as declared (status ${response.status}, body ${JSON.stringify(response.body)})`);
+            }
+        }
+        for (const endpoint of snapshot.implementedEndpoints) {
+            if (!probes.some((p) => p.label === endpoint))
+                violations.push(`declared endpoint '${endpoint}' has no conformance probe`);
+        }
+        // Direction 3 — served-but-unclaimed surface. Every entry must answer the TRANSPORT-level
+        // refusal envelope (a Connect `{code, message}` at 404/405/501), never a query envelope and
+        // never a result.
+        for (const entry of ROUTER_SURFACE) {
+            const response = await call(entry.method, entry.path, entry.body);
+            const body = response.body;
+            const refused = (response.status === 404 || response.status === 405 || response.status === 501)
+                && typeof body.code === 'string' && body.error === undefined && body.result === undefined && body.session === undefined;
+            if (!refused) {
+                violations.push(`router surface '${entry.method} ${entry.path}' must answer the transport refusal envelope, got ${response.status} ${JSON.stringify(response.body)} — served-but-unclaimed surface`);
+            }
+        }
+        // Direction 3b — the MALFORMED-INPUT branches. Dispatch reaches Execute, but the request never
+        // becomes a query: it must answer `invalid_argument`, never a query error and never a result.
+        for (const entry of MALFORMED_SURFACE) {
+            const response = await call('POST', `/${PSDB_SERVICE}/Execute`, entry.body);
+            const body = response.body;
+            if (response.status !== 400 || body.code !== 'invalid_argument' || body.error !== undefined || body.result !== undefined) {
+                violations.push(`${entry.label} must answer 400 {code:'invalid_argument'}, got ${response.status} ${JSON.stringify(response.body)}`);
+            }
+        }
+        // Auth is a branch too, and it must refuse — a twin that authenticated everything would pass
+        // every probe above while accepting a credential-less client.
+        const unauth = await call('POST', `/${PSDB_SERVICE}/Execute`, exec('SELECT 1'), {});
+        if (unauth.status !== 401 || unauth.body.error?.code !== 'unauthenticated') {
+            violations.push(`a credential-less Execute must answer 401 {error:{code:'unauthenticated'}}, got ${unauth.status} ${JSON.stringify(unauth.body)}`);
+        }
+        // …and each declared type must be genuinely REACHABLE, not merely declared: DDL writes a table,
+        // DML writes a row, and the round-trip must be readable back through the same handler.
+        await call('POST', `/${PSDB_SERVICE}/Execute`, exec('CREATE TABLE conf (id BIGINT PRIMARY KEY AUTO_INCREMENT, label VARCHAR(64) NOT NULL)'));
+        await call('POST', `/${PSDB_SERVICE}/Execute`, exec("INSERT INTO conf (label) VALUES ('alpha')"));
+        const read = await call('POST', `/${PSDB_SERVICE}/Execute`, exec('SELECT id, label FROM conf'));
+        const result = read.body.result;
+        const values = result?.rows?.[0] === undefined ? [] : unpackRow(result.rows[0]);
+        if (values[0] !== '1' || values[1] !== 'alpha') {
+            violations.push(`the 'table'/'row' resource types are declared but a DDL+DML round trip did not project (got ${JSON.stringify(read.body)})`);
+        }
+        const sessions = await call('POST', `/${PSDB_SERVICE}/CreateSession`, '{}');
+        if (typeof sessions.body.session?.vitessSession?.sessionUUID !== 'string') {
+            violations.push(`the 'session' resource type is declared but CreateSession did not mint one (${JSON.stringify(sessions.body)})`);
+        }
+        // a branch's backup, through the management API (the `api` lane, api/src/)
+        const backup = await createPlanetscaleTwinFetch({ root })(new Request('http://api.planetscale.com/v1/organizations/o/databases/d/branches/main/backups', {
+            method: 'POST', headers: { authorization: 'id:token', 'content-type': 'application/json' }, body: JSON.stringify({ name: 'conf' }),
+        }));
+        if (backup.status !== 201)
+            violations.push(`the '_backup' resource type is declared but creating a backup answered ${backup.status}`);
+        // The inventory must match what the handlers WRITE, in BOTH directions — a missing type is a violation as much
+        // as an extra one. What was written is read back from the root the paths above wrote to, never listed by hand.
+        const written = [...new Set(twinResources(SERVICE, root).map((r) => r.type))];
+        for (const type of PLANETSCALE_RESOURCE_TYPES) {
+            if (!written.includes(type))
+                violations.push(`declared resource type '${type}' is not written by any handler path`);
+        }
+        for (const type of written) {
+            if (!PLANETSCALE_RESOURCE_TYPES.includes(type)) {
+                violations.push(`the handler writes subject type '${type}' but PLANETSCALE_RESOURCE_TYPES does not declare it`);
+            }
+        }
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+    return {
+        ok: violations.length === 0,
+        endpointsChecked: snapshot.implementedEndpoints.length,
+        routerSurfaceChecked: ROUTER_SURFACE.length + MALFORMED_SURFACE.length,
+        resourceTypesChecked: snapshot.resourceTypes.length,
+        violations,
+    };
+}