@volter/twin-planetscale 0.1.0

package/src/planetscale-connector.ts

@@ -0,0 +1,571 @@
+// planetscale CONNECTOR — the live-vendor pull/push path that gives this twin the "git for SaaS"
+// lifecycle over an INJECTED client (the auth boundary). The pack imports NO SDK and holds NO
+// credential; a consumer injects something structurally satisfying `PlanetscaleLikeClient` — a real
+// `@planetscale/database` `Client` or `Connection` is assignable as-is, since its `execute` has
+// exactly this shape.
+//
+// Pulls use bounded keyset pages, like an incremental database scan. Finishing a scan is not
+// a cross-shard snapshot: refresh rechecks missing keyed rows before observing their deletion.
+// Any query failure aborts observation. LIMIT bounds returned rows, NOT storage-engine rows
+// examined or billed; every query also passes through the mandatory request budget.
+//
+// ── THE RATE BUDGET IS NOT OPTIONAL HERE ──────────────────────────────────────────────────────
+// Every entrypoint GUARDS the injected client before touching it (`guardPlanetscaleClient`, which
+// is idempotent). There is deliberately no option that turns the guard off.
+import { confirmAction, deployableEntries, observeResources, readParentTreeMap, twinResources, ownFields } from '@volter/world-core';
+import type { PerformContext, PushOutcome, RemoteExecute, SyncResource, ObservedResource, TwinAction } from '@volter/world-core';
+import { runPlanetscaleTransaction, guardPlanetscaleClient, planetscaleBudgetOf, type PlanetscaleBudgetedOptions } from './planetscale-budget.ts';
+import { tableKey, type Cell, type ColumnDef, type TableDef } from './planetscale-sql.ts';
+
+import { deploymentStatements } from './planetscale-deploy.ts';
+import { pulledRowId, keyedRowId, keyedRowIdentity, quoteIdent, quoteSqlLiteral } from './planetscale-row.ts';
+export { pulledRowId, quoteIdent, quoteSqlLiteral } from './planetscale-row.ts';
+
+const SERVICE = 'planetscale';
+
+export type { PlanetscaleBudgetedOptions };
+
+/**
+ * The subset of a real PlanetScale client this connector calls.
+ *
+ * A `@planetscale/database` `Client`/`Connection` satisfies it structurally. Pulls require
+ * execute; a missing executor is a failure, never evidence of an empty database.
+ */
+export interface PlanetscaleLikeClient {
+  execute?: (query: string, args?: unknown, options?: unknown) => Promise<PlanetscaleExecutedQuery>;
+  transaction?: <T>(fn: (tx: unknown) => Promise<T>) => Promise<T>;
+  refresh?: () => Promise<void>;
+}
+
+/** `ExecutedQuery` as the real client returns it (dist/index.d.ts). Only what this connector reads. */
+export type PlanetscaleExecutedQuery = {
+  rows: Array<Record<string, unknown>>;
+  fields?: Array<{ name: string; type?: string; columnType?: string | null; flags?: number | null; charset?: number | null; columnLength?: number | null }>;
+  rowsAffected?: number;
+  insertId?: string;
+};
+
+/** One table observed on the real database, already in this twin's storage shape. */
+export type PlanetscaleRealTable = {
+  name: string;
+  columns: ColumnDef[];
+  primaryKey: string[];
+  uniques: Array<{ name: string; columns: string[] }>;
+  autoIncrement: number;
+  rows: Array<{ rowid: number; cells: Record<string, Cell> }>;
+};
+
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// PURE MAPPERS
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+//
+// Both are PURE (they never touch a client), so the mutation harness's connector-seam sweep — which
+// sabotages exports matching /^(sync|push|pull|fullSync)/ — leaves them real. That is the pack
+// convention (qstash's `mapMessage`, upstash's `mapKey`).
+
+/**
+ * A `DESCRIBE <table>` row → a `ColumnDef`.
+ *
+ * MySQL's `DESCRIBE` output is the schema as the SERVER renders it: `Type` is the full column type
+ * (`varchar(255)`, `bigint unsigned`), `Null` is `YES`/`NO`, `Key` is `PRI`/`UNI`/`MUL`/``, `Default`
+ * is the literal or NULL, and `Extra` carries `auto_increment`. Every field of `ColumnDef` is
+ * derivable from those five, which is why the pull needs no information_schema query.
+ */
+export function mapDescribeRow(row: Record<string, unknown>): ColumnDef {
+  const name = String(row.Field ?? row.field ?? '');
+  const rendered = String(row.Type ?? row.type ?? 'varchar(255)');
+  const base = /^([a-zA-Z_]+)/.exec(rendered);
+  const lengthMatch = /\((\d+)/.exec(rendered);
+  const key = String(row.Key ?? row.key ?? '');
+  const extra = String(row.Extra ?? row.extra ?? '');
+  const rawDefault = row.Default ?? row.default ?? null;
+  const def: ColumnDef = {
+    name,
+    dataType: (base?.[1] ?? 'varchar').toUpperCase(),
+    columnType: rendered,
+    length: lengthMatch === null ? null : Number(lengthMatch[1]),
+    unsigned: /\bunsigned\b/i.test(rendered),
+    nullable: String(row.Null ?? row.null ?? 'YES').toUpperCase() !== 'NO',
+    autoIncrement: /auto_increment/i.test(extra),
+    primaryKey: key.toUpperCase() === 'PRI',
+    unique: key.toUpperCase() === 'UNI',
+  };
+  // A column with NO default and a column defaulting to NULL are DIFFERENT (errno 1364 vs. a
+  // silent NULL), so the absence is preserved rather than flattened to `null`.
+  if (rawDefault !== null && rawDefault !== undefined) return { ...def, defaultValue: String(rawDefault) };
+  if (def.nullable && key.toUpperCase() !== 'PRI' && !def.autoIncrement) return { ...def, defaultValue: null };
+  return def;
+}
+
+/** A real table → the kernel `table` resource. */
+export function mapTable(real: PlanetscaleRealTable): SyncResource {
+  return {
+    type: 'table',
+    id: `table:${tableKey(real.name)}`,
+    // The kernel MERGES fields (never a deep merge, never an omission-clear), so every field a
+    // later local write could overwrite is written explicitly — a pulled table can never inherit a
+    // stale `gone` flag or a previous incarnation's columns.
+    fields: {
+      name: real.name,
+      columns: real.columns as never,
+      primary_key: real.primaryKey as never,
+      uniques: real.uniques as never,
+      auto_increment: real.autoIncrement,
+      gone: false,
+    },
+  };
+}
+
+/** Vendor cells are nested to avoid reserved resource keys. Local write ordinals are
+ *  deliberately absent: observation must compare vendor facts, not local bookkeeping. */
+export function mapRow(table: string, rowid: number, cells: Record<string, Cell>): SyncResource {
+  return {
+    type: 'row',
+    id: `row:${tableKey(table)}:${rowid}`,
+    fields: { table_name: table, rowid, cells: cells as never, gone: false },
+  };
+}
+
+/** Normalize a value the real client handed back into this twin's text-cell encoding. */
+export function encodeCellValue(value: unknown): Cell {
+  if (value === null || value === undefined) return null;
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number' || typeof value === 'bigint' || typeof value === 'boolean') return String(value);
+  if (value instanceof Uint8Array) {
+    // A BLOB/BINARY column: `cast` returns bytes, and this twin stores bytes as one char per byte
+    // (planetscale-wire.ts packs them back out the same way).
+    let out = '';
+    for (const b of value) out += String.fromCharCode(b);
+    return out;
+  }
+  // A JSON column: `cast` already parsed it, so re-serialising is what puts it back on the wire the
+  // way the vendor sent it.
+  return JSON.stringify(value);
+}
+
+/**
+ * MySQL string-literal quoting, for the statements this connector BUILDS.
+ *
+ * Deliberately a local implementation rather than importing the SDK's `format`: this pack must not
+ * depend on the vendor SDK at runtime (it is a devDependency), and the escape set here is the same
+ * one `@planetscale/database`'s `dist/sanitization.js` uses — \0 \b \n \r \t \x1a \\ " '.
+ */
+
+/** MySQL identifier quoting — a backtick inside an identifier is doubled. */
+
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// PULL
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+
+export type PlanetscalePullOptions = {
+  /** Only these tables. Omit to discover them with `SHOW TABLES`. */
+  tables?: string[];
+  /** Maximum returned rows per page (1–10,000), default 500. Not a billed-rows guarantee. */
+  rowLimit?: number;
+  /** Maximum pages per table (1–100), default 10. A full last page remains partial. */
+  maxPages?: number;
+  /** Maximum missing-row point checks per refresh (1–1,000), default 100. */
+  maxMissingChecks?: number;
+} & PlanetscaleBudgetedOptions;
+
+const DEFAULT_ROW_LIMIT = 500;
+export type PlanetscalePullReport = {
+  resources: SyncResource[];
+  completeTables: string[];
+  partialTables: string[];
+};
+export type PlanetscaleRefreshReport = Omit<PlanetscalePullReport, 'resources'> & {
+  observed: number; deltasAppended: number; removed: number;
+};
+
+function bound(value: number | undefined, fallback: number, max: number, name: string): number {
+  const n = value === undefined ? fallback : value;
+  if (!Number.isSafeInteger(n) || n < 1 || n > max) throw new Error(`Invalid PlanetScale ${name}: expected 1..${max}`);
+  return n;
+}
+function queryRows(result: PlanetscaleExecutedQuery): Array<Record<string, unknown>> {
+  if (result?.fields !== undefined && (!Array.isArray(result.fields) || !result.fields.length || result.fields.some(f => !f || typeof f.name !== 'string' || !f.name))) throw new Error('PlanetScale read returned no valid field metadata');
+  if (!result || !Array.isArray(result.rows) || result.rows.some(r => !r || typeof r !== 'object' || Array.isArray(r))) throw new Error('Malformed PlanetScale rows');
+  return result.rows;
+}
+function tableNames(names: string[]): string[] {
+  if (!Array.isArray(names) || names.some(n => typeof n !== 'string' || !n) || new Set(names.map(tableKey)).size !== names.length) throw new Error('Invalid or colliding PlanetScale table names');
+  return names;
+}
+/** Use the column's own ordering. Numeric literals stay exact, including BIGINTs above 2^53. */
+function keyLiteral(column: ColumnDef, value: Cell): string {
+  if (typeof value !== 'string') throw new Error(`Missing PlanetScale key: ${column.name}`);
+  if (/^(?:TINYINT|SMALLINT|MEDIUMINT|INT|INTEGER|BIGINT|DECIMAL|NUMERIC)$/.test(column.dataType)) {
+    if (!/^[+-]?[0-9]+(?:\.[0-9]+)?$/.test(value)) throw new Error(`Invalid PlanetScale numeric key: ${column.name}`);
+    return value;
+  }
+  if (/^(?:VARBINARY|BINARY)$/.test(column.dataType)) return `X'${Buffer.from(value, 'latin1').toString('hex')}'`;
+  if (/^(?:VARCHAR|CHAR|TEXT|TINYTEXT|MEDIUMTEXT|LONGTEXT)$/.test(column.dataType)) return quoteSqlLiteral(value);
+  throw new Error(`Unsupported PlanetScale paging key: ${column.name} (${column.dataType})`);
+}
+function keyPredicate(columns: ColumnDef[], cells: Record<string, Cell>, after: boolean): string {
+  const parts = columns.map(c => ({ name: quoteIdent(c.name), literal: keyLiteral(c, cells[Object.keys(cells).find(k => k.toLowerCase() === c.name.toLowerCase()) ?? c.name]!) }));
+  const equal = (p: typeof parts[number]) => `${p.name} = ${p.literal}`;
+  if (!after) return parts.map(equal).join(' AND ');
+  return parts.map((p, i) => `(${[...parts.slice(0, i).map(equal), `${p.name} > ${p.literal}`].join(' AND ')})`).join(' OR ');
+}
+
+/** Discover the real database's table names. */
+export async function pullPlanetscaleTables(
+  rawClient: PlanetscaleLikeClient,
+  opts: PlanetscaleBudgetedOptions = {},
+): Promise<string[]> {
+  const client = guardPlanetscaleClient(rawClient, planetscaleBudgetOf(opts));
+  if (!client.execute) throw new Error('PlanetScale pull requires execute');
+  const res = await client.execute('SHOW TABLES');
+  // `SHOW TABLES` names its single column `Tables_in_<database>`, so the column NAME is not knowable
+  // in advance — the first value of each row is.
+  return tableNames(queryRows(res).map(r => {
+    const values = Object.values(r);
+    if (values.length !== 1 || typeof values[0] !== 'string') throw new Error('Malformed PlanetScale table listing');
+    return values[0];
+  }));
+}
+
+/** Compatibility resource-only pull. Use pullPlanetscaleSnapshot for completion metadata. */
+export async function pullPlanetscaleDatabase(rawClient: PlanetscaleLikeClient, opts: PlanetscalePullOptions = {}): Promise<SyncResource[]> {
+  const client = guardPlanetscaleClient(rawClient, planetscaleBudgetOf(opts));
+  return (await pullPlanetscaleSnapshot(client, opts)).resources;
+}
+
+/** Bounded scan. A short page proves that this traversal ended; it is not a global snapshot. */
+export async function pullPlanetscaleSnapshot(
+  rawClient: PlanetscaleLikeClient,
+  opts: PlanetscalePullOptions = {},
+): Promise<PlanetscalePullReport> {
+  const client = guardPlanetscaleClient(rawClient, planetscaleBudgetOf(opts));
+  if (!client.execute) throw new Error('PlanetScale pull requires execute');
+  const rowLimit = bound(opts.rowLimit, DEFAULT_ROW_LIMIT, 10_000, 'rowLimit');
+  const maxPages = bound(opts.maxPages, 10, 100, 'maxPages');
+  bound(opts.maxMissingChecks, 100, 1_000, 'maxMissingChecks');
+  const names = tableNames(opts.tables ?? (await pullPlanetscaleTables(client, planetscaleBudgetOf(opts))));
+  const out: SyncResource[] = [];
+  const completeTables: string[] = []; const partialTables: string[] = [];
+  for (const name of names) {
+    const described = await client.execute(`DESCRIBE ${quoteIdent(name)}`);
+    const rawColumns = queryRows(described);
+    if (!rawColumns.length || rawColumns.some(c => typeof (c.Field ?? c.field) !== 'string' || !(c.Field ?? c.field) || typeof (c.Type ?? c.type) !== 'string' || !(c.Type ?? c.type) || !['YES', 'NO'].includes(String(c.Null ?? c.null)) || !['', 'PRI', 'UNI', 'MUL'].includes(String(c.Key ?? c.key)) || typeof (c.Extra ?? c.extra) !== 'string')) throw new Error(`Malformed PlanetScale schema: ${name}`);
+    const columns = rawColumns.map(mapDescribeRow);
+    if (new Set(columns.map(c => c.name.toLowerCase())).size !== columns.length) throw new Error(`Duplicate PlanetScale columns: ${name}`);
+    const primaryKey = columns.filter(c => c.primaryKey).map(c => c.name);
+    const keyColumns = columns.filter(c => c.primaryKey);
+    const uniques = columns.filter(c => c.unique).map(c => ({ name: c.name, columns: [c.name] }));
+    const selected: Array<Record<string, unknown>> = [];
+    const order = primaryKey.length ? ` ORDER BY ${primaryKey.map(quoteIdent).join(', ')}` : '';
+    let cursor: Record<string, Cell> | undefined;
+    let complete = false;
+    for (let page = 0; page < maxPages; page++) {
+      const where = cursor ? ` WHERE ${keyPredicate(keyColumns, cursor, true)}` : '';
+      const rows = queryRows(await client.execute(`SELECT * FROM ${quoteIdent(name)}${where}${order} LIMIT ${rowLimit}`));
+      if (rows.length > rowLimit || rows.some(r => Object.keys(r).length !== columns.length || columns.some(c => !Object.hasOwn(r, c.name) || r[c.name] === undefined || (c.primaryKey && r[c.name] === null)))) throw new Error(`Malformed PlanetScale page: ${name}`);
+      selected.push(...rows);
+      if (rows.length < rowLimit) { complete = true; break; }
+      if (!primaryKey.length) break; // no unique key means no safe continuation
+      cursor = Object.fromEntries(columns.map(c => [c.name, encodeCellValue(rows.at(-1)![c.name])]));
+    }
+    (complete ? completeTables : partialTables).push(name);
+    // Identity: the PK's values, or every cell when the table has no PK. See `pulledRowId` for
+    // why this must not be the row's POSITION — and why identical identities still need an ordinal.
+    const seen = new Map<string, number>();
+    const rowIds = new Set<number>();
+    const rows = selected.map((raw) => {
+      const cells: Record<string, Cell> = {};
+      for (const col of columns) cells[col.name] = encodeCellValue(raw[col.name]);
+      const identityColumns = primaryKey.length > 0 ? primaryKey : columns.map((c) => c.name);
+      const identity = identityColumns.map((n) => `${n}=${cells[n] ?? '\u0000NULL'}`);
+      const key = identity.join('\u0000');
+      const ordinal = seen.get(key) ?? 0;
+      seen.set(key, ordinal + 1);
+      const rowid = primaryKey.length ? keyedRowId({ name, primaryKey }, cells) : pulledRowId(name, identity, ordinal);
+      if (rowIds.has(rowid)) throw new Error(`PlanetScale row identity hash collision in ${name}`);
+      rowIds.add(rowid);
+      return { rowid, cells };
+    });
+    // The AUTO_INCREMENT watermark is derived from the rows actually observed, pushed one past the
+    // largest id seen. That is deliberately CONSERVATIVE relative to the real server's counter: a
+    // twin that guessed lower would mint an id colliding with a pulled row, which is the exact
+    // "create after connector pull" collision class. `planetscale.connector.auto_increment_watermark`
+    // files the residual gap (rows beyond `rowLimit` are unobserved, so the watermark is a floor).
+    const autoColumn = columns.find((c) => c.autoIncrement);
+    let autoIncrement = 1;
+    if (autoColumn !== undefined) {
+      for (const r of rows) {
+        const n = Number(r.cells[autoColumn.name] ?? 0);
+        if (Number.isFinite(n) && n >= autoIncrement) autoIncrement = Math.floor(n) + 1;
+      }
+    }
+    out.push(mapTable({ name, columns, primaryKey, uniques, autoIncrement, rows }));
+    for (const r of rows) out.push(mapRow(name, r.rowid, r.cells));
+  }
+  return { resources: out, completeTables, partialTables };
+}
+
+/** Compare the incoming batch with BOTH views: a pending local edit/deletion cannot hide
+ *  an upstream identity that occupies the same hashed subject. The kernel owns both folds. */
+function assertObservationIdentities(resources: SyncResource[], root?: string): void {
+  const projected = twinResources(SERVICE, root).map(r => ({ type: r.type, id: r.id, fields: ownFields(r) }));
+  const upstream = [...readParentTreeMap(SERVICE, root).values()];
+  const incomingTables = new Map(resources.filter(r => r.type === 'table').map(r => [tableKey(String(r.fields.name)), r.fields]));
+  for (const view of [projected, upstream]) {
+    const held = new Map(view.filter(r => r.type === 'row' && r.fields.gone !== true).map(r => [r.id, r.fields]));
+    for (const r of resources) {
+      if (r.type !== 'row') continue;
+      const prior = held.get(r.id); if (!prior) continue;
+      const name = String(r.fields.table_name); const table = incomingTables.get(tableKey(name));
+      const primaryKey = (table?.primary_key ?? []) as string[];
+      const identity = (cells: unknown) => primaryKey.length
+        ? keyedRowIdentity({ name, primaryKey }, cells as Record<string, Cell>)
+        : Object.entries(cells as Record<string, Cell>).sort(([a], [b]) => a.localeCompare(b));
+      if (JSON.stringify(identity(prior.cells)) !== JSON.stringify(identity(r.fields.cells))) throw new Error(`PlanetScale row identity hash collision in ${name}`);
+    }
+  }
+}
+
+/**
+ * Pull the real database and fold it into the twin through the kernel observation path. Returns `{observed, deltasAppended}` — a re-pull of identical state appends ZERO deltas,
+ * which is what makes the pull idempotent.
+ */
+export async function syncPlanetscaleFromReal(
+  rawClient: PlanetscaleLikeClient,
+  opts: { root?: string; occurredAt?: string } & PlanetscalePullOptions = {},
+): Promise<PlanetscaleRefreshReport> {
+  // Guard ONCE here and hand the guarded client down: the per-table loop is unbounded in table
+  // count, so this is the entrypoint that must be unable to run unbudgeted.
+  const client = guardPlanetscaleClient(rawClient, planetscaleBudgetOf(opts));
+  // Distinct polling batches get distinct identities even when calls share a millisecond.
+  const occurredAt = opts.occurredAt ?? pollTimestamp();
+  const scan = await pullPlanetscaleSnapshot(client, opts);
+  const { resources } = scan;
+  const upstream = readParentTreeMap(SERVICE, opts.root);
+  const keysEqual = (keys: string[]) => JSON.stringify(keys.map(k => k.toLowerCase()).sort());
+  for (const table of resources.filter(r => r.type === 'table')) {
+    const prior = upstream.get(`table:${table.id}`);
+    if (prior && prior.fields.deleted !== true && scan.partialTables.includes(String(table.fields.name)) && keysEqual((prior.fields.primary_key ?? []) as string[]) !== keysEqual((table.fields.primary_key ?? []) as string[])) {
+      throw new Error(`Incomplete PlanetScale primary-key change: ${table.fields.name}; increase the bounded scan before refreshing`);
+    }
+  }
+  assertObservationIdentities(resources, opts.root);
+  const tables = new Map(resources.filter(r => r.type === 'table').map(r => [tableKey(String(r.fields.name)), r.fields]));
+  const complete = new Set(scan.completeTables.map(tableKey));
+  const seen = new Set(resources.filter(r => r.type === 'row').map(r => r.id));
+  const absent: ObservedResource[] = [];
+  let checks = 0;
+  const observedRows = new Map(resources.filter(r => r.type === 'row').map(r => [r.id, r]));
+  for (const prior of upstream.values()) {
+    if (prior.type !== 'row' || prior.fields.deleted === true || prior.fields.gone === true || seen.has(prior.id)) continue;
+    const name = String(prior.fields.table_name); const table = tables.get(tableKey(name));
+    if (!table) {
+      // Only an unfiltered, successful SHOW TABLES can establish a dropped table's absence.
+      if (opts.tables === undefined) absent.push({ type: 'row', id: prior.id, fields: {}, deleted: true });
+      continue;
+    }
+    if (!complete.has(tableKey(name))) continue;
+    const keyColumns = (table.columns as unknown as ColumnDef[]).filter(c => c.primaryKey);
+    const oldTable = upstream.get(`table:table:${tableKey(name)}`);
+    const oldKeys = (oldTable?.fields.primary_key ?? []) as string[];
+    const identityChanged = keysEqual(oldKeys) !== keysEqual(keyColumns.map(c => c.name));
+    // A changed key definition retires the old addressing scheme. Only a completed table
+    // can replace those subjects; old rows need not contain newly added key columns.
+    if (keyColumns.length && !identityChanged) {
+      if (++checks > bound(opts.maxMissingChecks, 100, 1_000, 'maxMissingChecks')) throw new Error('PlanetScale missing-row check limit exceeded');
+      const predicate = keyPredicate(keyColumns, prior.fields.cells as Record<string, Cell>, false);
+      const rows = queryRows(await client.execute!(`SELECT * FROM ${quoteIdent(name)} WHERE ${predicate} LIMIT 2`));
+      if (rows.length > 1) throw new Error(`Ambiguous PlanetScale primary key: ${name}`);
+      if (rows.length) {
+        const columns = table.columns as unknown as ColumnDef[];
+        const raw = rows[0]!;
+        if (Object.keys(raw).length !== columns.length || columns.some(c => !Object.hasOwn(raw, c.name) || raw[c.name] === undefined || (c.primaryKey && raw[c.name] === null))) throw new Error(`Malformed PlanetScale point read: ${name}`);
+        const cells = Object.fromEntries(columns.map(c => [c.name, encodeCellValue(raw[c.name])]));
+        const id = `row:${tableKey(name)}:${keyedRowId({ name, primaryKey: keyColumns.map(c => c.name) }, cells)}`;
+        const scanned = observedRows.get(id);
+        // Collation can resolve the old key spelling to an already-scanned new identity.
+        // Retire the old subject only when this point read agrees with that complete scan.
+        if (!scanned || id === prior.id || JSON.stringify(scanned.fields.cells) !== JSON.stringify(cells)) throw new Error(`PlanetScale rows changed during refresh: ${name}; retry the refresh`);
+      }
+    }
+    // Keyless tables only complete in one short page; no paged absence inference is made.
+    absent.push({ type: 'row', id: prior.id, fields: {}, deleted: true });
+  }
+  const result = observeResources(SERVICE, [...resources, ...absent], {
+    ...(opts.root !== undefined ? { root: opts.root } : {}), at: occurredAt, batch: `obs:${SERVICE}:${occurredAt}`,
+    ...(opts.tables === undefined ? { complete: ['table'] } : {}),
+  });
+  return { observed: resources.length, deltasAppended: result.appended + result.removed,
+    removed: result.removed, completeTables: scan.completeTables, partialTables: scan.partialTables };
+}
+
+let lastPollMs = 0;
+/** `now`, forced strictly increasing within this process — see `syncPlanetscaleFromReal`. */
+export function pollTimestamp(): string {
+  const now = Date.now();
+  lastPollMs = now > lastPollMs ? now : lastPollMs + 1;
+  return new Date(lastPollMs).toISOString();
+}
+
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// PUSH
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+
+/** Apply captured row changes as one guarded vendor transaction. The transaction reservation
+ *  covers BEGIN, its callback, COMMIT and rollback, so exhausted budget cannot strand an open
+ *  transaction halfway through cleanup. Known row plans reserve all row and lifecycle calls. */
+export async function applyPlanetscaleRows(rawClient: PlanetscaleLikeClient, plan: unknown, opts: PlanetscaleBudgetedOptions = {}): Promise<string[]> {
+  const statements = deploymentStatements(plan);
+  if (!statements.length) return statements;
+  const client = guardPlanetscaleClient(rawClient, planetscaleBudgetOf(opts));
+  if (!client.transaction) throw new Error('PlanetScale deployment requires a transactional client');
+  await runPlanetscaleTransaction(client, statements.length, async value => {
+    const tx = value as PlanetscaleLikeClient;
+    if (typeof tx?.execute !== 'function') throw new Error('PlanetScale transaction cannot execute');
+    for (const statement of statements) {
+      const result = await tx.execute(statement);
+      if (result.rowsAffected !== 1) throw new Error(`PlanetScale row conflict: expected one affected row, received ${result.rowsAffected ?? 'no count'}`);
+    }
+  }, opts);
+  return statements;
+}
+
+/** Compatibility entry point over the same captured plan as the head's performer. */
+export async function pushPlanetscaleAction(
+  rawClient: PlanetscaleLikeClient,
+  action: { id: string; operation?: string; subjectType?: string; subjectId?: string; fields?: Record<string, unknown>; input?: Record<string, unknown> },
+  opts: { root?: string; occurredAt?: string } & PlanetscaleBudgetedOptions = {},
+): Promise<{ pushed: boolean; statement: string }> {
+  const client = guardPlanetscaleClient(rawClient, planetscaleBudgetOf(opts));
+  if (!action.subjectType || !action.subjectId) throw new Error('PlanetScale action has no subject');
+  const statements = await applyPlanetscaleRows(client, action.input?.plan, opts);
+  confirmAction({ service: SERVICE, actionId: action.id,
+    subject: { type: action.subjectType, id: action.subjectId }, fields: action.fields as never ?? {},
+    occurredAt: opts.occurredAt ?? pollTimestamp(), ...(opts.root !== undefined ? { root: opts.root } : {}) });
+  return { pushed: true, statement: statements.join('\n') };
+}
+
+export async function pushPlanetscaleActions(rawClient: PlanetscaleLikeClient,
+  opts: { root?: string; occurredAt?: string } & PlanetscaleBudgetedOptions = {},
+): Promise<{ pushed: number }> {
+  const client = guardPlanetscaleClient(rawClient, planetscaleBudgetOf(opts));
+  let pushed = 0;
+  for (const action of deployableEntries(SERVICE, opts.root)) {
+    await pushPlanetscaleAction(client, { ...action, subjectType: action.subject.type, subjectId: action.subject.id }, opts);
+    pushed++;
+  }
+  return { pushed };
+}
+
+export type { TableDef };
+
+// ── PROTOCOL 2: the pack's half of the real state system ────────────────────────────────────
+
+/**
+ * A `PlanetscaleLikeClient` over the kernel's executor.
+ *
+ * PlanetScale's serverless driver speaks CONNECT RPC over unary JSON POSTs to
+ * `psdb.v1alpha1.Database` — `CreateSession` then `Execute` — so a session is established once and
+ * carried on every query after it, exactly as `@planetscale/database` does. At a REAL boundary the
+ * kernel sets the sealed credential over these headers (executor.ts); at the twin's own wire any
+ * credential is one.
+ */
+export function planetscaleClientOver(execute: RemoteExecute): PlanetscaleLikeClient {
+  // The session is the driver's own, established lazily and reused — a `CreateSession` per query
+  // would be a real round trip per statement against a vendor that bills by connection time.
+  let session: unknown = null;
+  const rpc = async (method: string, body: Record<string, unknown>): Promise<any> => {
+    const res = await execute({
+      method: 'POST', path: `/psdb.v1alpha1.Database/${method}`,
+      // A WELL-FORMED Basic header: base64('twin:twin'). The wire decodes it the way the real
+      // driver builds it (`btoa(user + ':' + pass)`) and answers anything else with the vendor's own
+      // 401 `unauthenticated` — a bare word where a base64 pair belongs is not a credential.
+      headers: { accept: 'application/json', 'content-type': 'application/json', authorization: 'Basic dHdpbjp0d2lu' },
+      body: JSON.stringify(body),
+    });
+    const failure = (message: string): Error => Object.assign(new Error(message), { status: res.status, headers: res.headers });
+    if (res.status < 200 || res.status >= 300) throw failure(`PlanetScale ${method} refused: HTTP ${res.status}`);
+    let parsed: any;
+    try { parsed = JSON.parse(res.body); } catch { throw failure(`PlanetScale ${method} returned malformed JSON`); }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw failure(`PlanetScale ${method} returned an invalid envelope`);
+    return parsed;
+  };
+  const client: PlanetscaleLikeClient = {
+    execute: async (query: string) => {
+      if (session === null) {
+        session = (await rpc('CreateSession', {})).session;
+        if (!session || typeof session !== 'object') throw new Error('PlanetScale CreateSession returned no session');
+      }
+      const answered = await rpc('Execute', { query, ...(session === null ? {} : { session }) });
+      if (answered?.session !== undefined) session = answered.session;
+      // A vendor ERROR arrives inside a 200 body — the SQL analogue of an error envelope — and must
+      // never be read as an empty result set, which would fold a table's rows away as if they had
+      // been deleted.
+      if (answered?.error !== undefined && answered.error !== null) {
+        throw new Error(`planetscale query refused: ${JSON.stringify(answered.error).slice(0, 200)}`);
+      }
+      if (!answered.result || typeof answered.result !== 'object' || Array.isArray(answered.result)) throw new Error('PlanetScale Execute returned no result');
+      const result = answered.result as Record<string, any>;
+      if ((result.fields !== undefined && !Array.isArray(result.fields)) || (result.rows !== undefined && !Array.isArray(result.rows))) throw new Error('PlanetScale returned malformed result arrays');
+      const fields = result.fields ?? [];
+      if (!fields.every((f: any) => f && typeof f.name === 'string' && f.name.length)) throw new Error('PlanetScale returned malformed field metadata');
+      const names = fields.map((f: any) => f.name);
+      // Protojson omits an empty values payload, including rows containing only NULLs.
+      const rows = (result.rows ?? []).map((r: any) => {
+        if (!r || !Array.isArray(r.lengths) || r.lengths.length !== fields.length || (r.values !== undefined && typeof r.values !== 'string')) throw new Error('PlanetScale returned a malformed packed row');
+        const decoded = Buffer.from(r.values ?? '', 'base64');
+        const out: Record<string, unknown> = {};
+        let offset = 0;
+        r.lengths.forEach((len: unknown, i: number) => {
+          const n = typeof len === 'string' && /^-?\d+$/.test(len) ? Number(len) : len;
+          if (typeof n !== 'number' || !Number.isSafeInteger(n) || n < -1 || offset + Math.max(n, 0) > decoded.length) throw new Error('PlanetScale returned invalid packed row lengths');
+          if (n === -1) { out[names[i]] = null; return; }
+          out[names[i]] = decoded.subarray(offset, offset + n).toString(Number(fields[i]?.charset) === 63 ? 'latin1' : 'utf8');
+          offset += n;
+        });
+        if (offset !== decoded.length) throw new Error('PlanetScale returned trailing packed row bytes');
+        return out;
+      });
+      if (!Number.isSafeInteger(Number(result.rowsAffected ?? 0)) || Number(result.rowsAffected ?? 0) < 0) throw new Error('PlanetScale returned invalid rowsAffected');
+      return { rows, fields, rowsAffected: Number(result.rowsAffected ?? 0), insertId: String(result.insertId ?? '0') };
+    },
+    transaction: async <T>(fn: (tx: unknown) => Promise<T>): Promise<T> => {
+      await client.execute!('BEGIN');
+      try {
+        const result = await fn(client);
+        await client.execute!('COMMIT');
+        return result;
+      } catch (error) {
+        try { await client.execute!('ROLLBACK'); }
+        catch (rollback) { throw new AggregateError([error, rollback], 'PlanetScale transaction failed and rollback could not be confirmed'); }
+        throw error;
+      }
+    },
+  };
+  return client;
+}
+
+/** The refresh adapter: PlanetScale enumerates through SQL itself (`SHOW TABLES`, then each table),
+ *  with explicit per-table completion from the bounded scan. */
+export async function syncPlanetscaleFromRemote(
+  execute: RemoteExecute,
+  opts: { root?: string; origin?: string; occurredAt?: string } & PlanetscalePullOptions = {},
+): Promise<PlanetscaleRefreshReport> {
+  // Guarded here as well as inside the sync: the guard is idempotent, and stating it at every
+  // entrypoint is what this pack's source tooth holds the connector to.
+  const client = guardPlanetscaleClient(planetscaleClientOver(execute), planetscaleBudgetOf(opts));
+  return syncPlanetscaleFromReal(client, {
+    ...opts,
+    ...(opts.root !== undefined ? { root: opts.root } : {}),
+    occurredAt: opts.occurredAt ?? pollTimestamp(),
+  });
+}
+
+/** The head performs the captured row plan; query results never become resource fields. */
+export async function performPlanetscaleAction(execute: RemoteExecute, action: TwinAction, _ctx: PerformContext,
+  opts: PlanetscaleBudgetedOptions = {},
+): Promise<PushOutcome> {
+  const client = guardPlanetscaleClient(planetscaleClientOver(execute), planetscaleBudgetOf(opts));
+  await applyPlanetscaleRows(client, action.input?.plan, opts);
+  return { externalId: action.subject.id };
+}