@volter/twin-planetscale 0.1.0

package/src/planetscale-conformance.ts

@@ -0,0 +1,237 @@
+// 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.ts';
+import { SERVICE } from './planetscale-store.ts';
+import {
+  handlePlanetscaleTwinRequest,
+  planetscaleTwinSnapshot,
+  PSDB_SERVICE,
+  PLANETSCALE_RESOURCE_TYPES,
+} from './planetscale-twin.ts';
+import { unpackRow, type WireExecuteResponse } from './planetscale-wire.ts';
+
+export type PlanetscaleConformanceReport = {
+  ok: boolean;
+  endpointsChecked: number;
+  routerSurfaceChecked: number;
+  resourceTypesChecked: number;
+  violations: string[];
+};
+
+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')}` };
+
+type Probe = { label: string; method: string; path: string; body?: string; headers?: Record<string, string>; expect: (r: { status: number; body: unknown }) => boolean };
+
+const exec = (query: string, session?: unknown): string => 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: Array<{ method: string; path: string; body?: string }> = [
+  // 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: Array<{ label: string; body: string }> = [
+  { 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(): Promise<PlanetscaleConformanceReport> {
+  const snapshot = planetscaleTwinSnapshot();
+  const violations: string[] = [];
+  const root = mkdtempSync(join(tmpdir(), 'planetscale-conf-'));
+  const call = (method: string, path: string, body?: string, headers: Record<string, string> = AUTH) =>
+    handlePlanetscaleTwinRequest({ method, path, headers, root, occurredAt: AT, ...(body !== undefined ? { body } : {}) });
+
+  const probes: Probe[] = [
+    {
+      label: 'POST /psdb.v1alpha1.Database/CreateSession',
+      method: 'POST', path: `/${PSDB_SERVICE}/CreateSession`, body: '{}',
+      expect: (r) => {
+        const b = r.body as { branch?: string; user?: { username?: string }; session?: { vitessSession?: { sessionUUID?: string } } };
+        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 as WireExecuteResponse;
+        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 as { session?: { vitessSession?: { sessionUUID?: string } } };
+        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 as { code?: string }).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 as { code?: string }).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 as { code?: string; error?: unknown; result?: unknown; session?: unknown };
+      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 as { code?: string; error?: unknown; result?: unknown };
+      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 as { error?: { code?: string } }).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 as WireExecuteResponse).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 as { session?: { vitessSession?: { sessionUUID?: string } } }).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 as readonly string[]).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,
+  };
+}