@spooky-sync/core 0.0.1-canary.17 → 0.0.1-canary.170

package/src/services/database/remote.ts

@@ -1,20 +1,47 @@
+import type {
+  Diagnostic,
+  SurrealEvents} from 'surrealdb';
 import {
   applyDiagnostics,
   createRemoteEngines,
-  Diagnostic,
   Surreal,
-  SurrealTransaction,
 } from 'surrealdb';
-import { SpookyConfig } from '../../types';
-import { Logger } from '../logger/index';
+import type { ConnectionState, ReconnectConfig, Sp00kyConfig } from '../../types';
+import type { Logger } from '../logger/index';
 import { AbstractDatabaseService } from './database';
 import { createDatabaseEventSystem, DatabaseEventTypes } from './events/index';
 
+/** Defaults for {@link ReconnectConfig}. See that type for the rationale. */
+export const RECONNECT_DEFAULTS = {
+  attempts: -1,
+  retryDelayMax: 15_000,
+  heartbeatIntervalMs: 20_000,
+  heartbeatTimeoutMs: 10_000,
+  superviseRetryDelayMaxMs: 15_000,
+} as const;
+
+/** Fill in {@link RECONNECT_DEFAULTS} for every field the caller omitted. */
+export function resolveReconnectConfig(
+  input?: ReconnectConfig
+): Required<ReconnectConfig> {
+  return { ...RECONNECT_DEFAULTS, ...input };
+}
+
+/** Transport events the SDK publishes, mapped 1:1 to {@link ConnectionState}. */
+export type RemoteConnectionEvent = ConnectionState | 'error';
+
 export class RemoteDatabaseService extends AbstractDatabaseService {
-  private config: SpookyConfig<any>['database'];
+  private config: Sp00kyConfig<any>['database'];
   protected eventType = DatabaseEventTypes.RemoteQuery;
+  private readonly reconnectConfig: Required<ReconnectConfig>;
+  /**
+   * In-flight `connect()`, so concurrent callers (boot + supervisor revive +
+   * an `online` event landing at the same moment) share one attempt instead of
+   * racing two sockets. Cleared on settle, so a later call always reconnects.
+   */
+  private connecting: Promise<void> | null = null;
 
-  constructor(config: SpookyConfig<any>['database'], logger: Logger) {
+  constructor(config: Sp00kyConfig<any>['database'], logger: Logger) {
     const events = createDatabaseEventSystem();
     super(
       new Surreal({
@@ -29,7 +56,7 @@ export class RemoteDatabaseService extends AbstractDatabaseService {
                   type,
                   phase,
                   service: 'surrealdb:remote',
-                  Category: 'spooky-client::RemoteDatabaseService::diagnostics',
+                  Category: 'sp00ky-client::RemoteDatabaseService::diagnostics',
                 },
                 `Remote SurrealDB diagnostics captured ${type}:${phase}`
               );
@@ -41,13 +68,68 @@ export class RemoteDatabaseService extends AbstractDatabaseService {
       events
     );
     this.config = config;
+    this.reconnectConfig = resolveReconnectConfig(config.reconnect);
+    this.queryTimeoutMs = Math.max(0, config.queryTimeoutMs ?? 60_000);
   }
 
-  getConfig(): SpookyConfig<any>['database'] {
+  getConfig(): Sp00kyConfig<any>['database'] {
     return this.config;
   }
 
+  /** Resolved reconnect tunables; the supervisor reads its own knobs here. */
+  getReconnectConfig(): Required<ReconnectConfig> {
+    return this.reconnectConfig;
+  }
+
+  /** Current transport state as reported by the SDK. */
+  getStatus(): ConnectionState {
+    return this.client.status as ConnectionState;
+  }
+
+  /**
+   * Observe transport events. Thin passthrough so callers (the supervisor,
+   * sync, CRDT) don't have to reach through `getClient()`.
+   */
+  subscribeConnection<K extends RemoteConnectionEvent>(
+    event: K,
+    cb: (...payload: SurrealEvents[K]) => void
+  ): () => void {
+    return this.client.subscribe(event, cb);
+  }
+
+  /**
+   * Tear the socket down on purpose. Used by the heartbeat watchdog when a
+   * socket stops answering but never closes: `close()` makes the SDK publish
+   * `disconnected`, which is what drives the supervisor's revive loop.
+   */
+  async forceClose(): Promise<void> {
+    try {
+      await this.client.close();
+    } catch (err) {
+      this.logger.debug(
+        { err, Category: 'sp00ky-client::RemoteDatabaseService::forceClose' },
+        'forceClose failed; treating the socket as gone anyway'
+      );
+    }
+  }
+
+  /**
+   * Open (or re-open) the remote connection.
+   *
+   * Safe to call repeatedly: concurrent calls share the in-flight attempt, and
+   * a call after a `disconnected` builds a fresh socket. `use()` and
+   * `authenticate()` are re-applied here for the cold path; the SDK also
+   * replays them itself on its own internal reconnects.
+   */
   async connect(): Promise<void> {
+    if (this.connecting) return this.connecting;
+    this.connecting = this.doConnect().finally(() => {
+      this.connecting = null;
+    });
+    return this.connecting;
+  }
+
+  private async doConnect(): Promise<void> {
     const { endpoint, token, namespace, database } = this.getConfig();
     if (endpoint) {
       this.logger.info(
@@ -55,12 +137,26 @@ export class RemoteDatabaseService extends AbstractDatabaseService {
           endpoint,
           namespace,
           database,
-          Category: 'spooky-client::RemoteDatabaseService::connect',
+          Category: 'sp00ky-client::RemoteDatabaseService::connect',
         },
         'Connecting to remote database'
       );
       try {
-        await this.client.connect(endpoint);
+        // Without explicit options the SDK caps itself at 5 attempts (~62s of
+        // outage) and then gives up permanently — nothing would re-open the
+        // socket after that. `attempts: -1` keeps it trying; the supervisor
+        // still covers the case where the SDK terminates the engine because its
+        // post-reconnect handshake threw.
+        await this.client.connect(endpoint, {
+          reconnect: {
+            enabled: true,
+            attempts: this.reconnectConfig.attempts,
+            retryDelay: 1_000,
+            retryDelayMax: this.reconnectConfig.retryDelayMax,
+            retryDelayMultiplier: 2,
+            retryDelayJitter: 0.1,
+          },
+        });
         await this.client.use({
           namespace,
           database,
@@ -68,25 +164,25 @@ export class RemoteDatabaseService extends AbstractDatabaseService {
 
         if (token) {
           this.logger.debug(
-            { Category: 'spooky-client::RemoteDatabaseService::connect' },
+            { Category: 'sp00ky-client::RemoteDatabaseService::connect' },
             'Authenticating with token'
           );
           await this.client.authenticate(token);
         }
         this.logger.info(
-          { Category: 'spooky-client::RemoteDatabaseService::connect' },
+          { Category: 'sp00ky-client::RemoteDatabaseService::connect' },
           'Connected to remote database'
         );
       } catch (err) {
         this.logger.error(
-          { err, Category: 'spooky-client::RemoteDatabaseService::connect' },
+          { err, Category: 'sp00ky-client::RemoteDatabaseService::connect' },
           'Failed to connect to remote database'
         );
         throw err;
       }
     } else {
       this.logger.warn(
-        { Category: 'spooky-client::RemoteDatabaseService::connect' },
+        { Category: 'sp00ky-client::RemoteDatabaseService::connect' },
         'No endpoint configured for remote database'
       );
     }

package/src/services/database/sqlite-cache-engine.test.ts

@@ -0,0 +1,464 @@
+import { describe, it, expect } from 'vitest';
+import { RecordId } from 'surrealdb';
+import { pureWriteOpResult, SqliteCacheEngine } from './sqlite-cache-engine';
+import { stubTransport } from './sqlite-transport.fixture';
+import { translateSurql } from './surql-translate';
+import type { SqlOp } from './surql-translate';
+import { surql } from '../../utils/surql';
+
+function makeLogger(): any {
+  const noop = () => {};
+  const l: any = { debug: noop, info: noop, warn: noop, error: noop, trace: noop };
+  l.child = () => l;
+  return l;
+}
+
+/**
+ * A fake transport handler that models the real SQLite worker's open/closed
+ * lifecycle: `open` opens the DB, `close` closes it, and `exec`/`run` REJECT
+ * with "sqlite: DB not open" when the DB isn't currently open — exactly the
+ * failure the fix targets. Records every message `type` (across transport
+ * generations) so tests can also inspect dispatch order.
+ */
+function lifecycleHandler(log: string[]) {
+  let dbOpen = false;
+  return (type: string) => {
+    log.push(type);
+    if (type === 'open') {
+      dbOpen = true;
+      return { persisted: true };
+    }
+    if (type === 'close') {
+      dbOpen = false;
+      return {};
+    }
+    if (type === 'exec' || type === 'select' || type === 'run' || type === 'batch') {
+      if (!dbOpen) throw new Error('sqlite: DB not open');
+      if (type === 'exec') return { rows: [] };
+      if (type === 'select') return { rows: [], relationFetches: 0 };
+    }
+    return {};
+  };
+}
+
+// Regression: switchBucket must run close → reopen as a single serialized
+// opQueue entry. Otherwise a read/write enqueued during an auth/bucket change
+// dispatches to the just-closed worker → "sqlite: DB not open" (the crash on
+// sign-in). The invariant: no `exec` may appear between a `close` and the next
+// `open` in the message stream.
+describe('SqliteCacheEngine.switchBucket serialization', () => {
+  it('never dispatches an op to a closed DB during a bucket switch', async () => {
+    const log: string[] = [];
+    const engine = new SqliteCacheEngine({ namespace: 'n', database: 'd' } as any, makeLogger());
+    stubTransport(engine, lifecycleHandler(log));
+
+    await engine.connect('anon');
+    expect(log).toContain('open');
+
+    // Fire a switch and a concurrent read (exactly what the sign-in query
+    // re-registration does). With the old non-atomic switch the read's `exec`
+    // dispatched to the closed/terminated worker and REJECTED ("sqlite: DB not
+    // open" / "not connected") — the uncaught crash. The atomic switch makes the
+    // read wait for the reopen and resolve against the new bucket.
+    const switching = engine.switchBucket('user:abc');
+    const reading = engine.getById('_00_query', 'h1');
+    await expect(Promise.all([switching, reading])).resolves.toBeDefined();
+    await expect(reading).resolves.toBeNull(); // missing row → null, not a throw
+
+    // And the close→reopen ran with no op wedged between them.
+    const closeIdx = log.indexOf('close');
+    const openAfter = log.indexOf('open', closeIdx + 1);
+    expect(openAfter).toBeGreaterThan(closeIdx);
+    expect(log.slice(closeIdx + 1, openAfter)).not.toContain('exec');
+    expect(engine.currentBucketId).toBe('user:abc');
+  });
+});
+
+// Regression: DEFINE is a noop on this engine, so the `_00_*` internal tables
+// the migrator DEFINEs are never physically created — a fresh bucket that READS
+// one before any write (the sync layer selects `_00_query` at startup) threw
+// "no such table: _00_query" and wedged the client on "Loading database". The
+// fix seeds them inside `open`; assert the open message carries them.
+describe('SqliteCacheEngine system-table seeding', () => {
+  it('passes the _00_* system tables to the worker open (fresh-bucket safe)', async () => {
+    const msgs: any[] = [];
+    const engine = new SqliteCacheEngine({ namespace: 'n', database: 'd' } as any, makeLogger());
+    stubTransport(engine, (type, payload) => {
+      msgs.push({ type, payload });
+      return type === 'open' ? { persisted: true } : {};
+    });
+
+    await engine.connect('user:fresh');
+    const open = msgs.find((m) => m.type === 'open');
+    expect(open?.payload?.systemTables).toContain('_00_query');
+    expect(open?.payload?.systemTables).toContain('_00_pending_mutations');
+  });
+});
+
+// The worker's `persisted`/`opfsError` reply used to die in a `logger.info`
+// line, so a host app running pino at `fatal` (whitepawn does) could not tell a
+// disk-backed store from a full-RAM one. It now lands on the engine as
+// observable state the app can render.
+describe('SqliteCacheEngine storage health', () => {
+  /** Engine wired to a worker whose `open` replies with `openReply`. */
+  function makeEngine(openReply: Record<string, unknown>, opts?: { useOpfs?: boolean }) {
+    const logs: { level: string; msg: string; meta: any }[] = [];
+    const logger: any = {};
+    for (const level of ['debug', 'info', 'warn', 'error', 'trace']) {
+      logger[level] = (meta: any, msg: string) => logs.push({ level, msg, meta });
+    }
+    logger.child = () => logger;
+
+    const engine = new SqliteCacheEngine(
+      { namespace: 'n', database: 'd' } as any,
+      logger,
+      opts ?? {}
+    );
+    stubTransport(engine, (type) => (type === 'open' ? openReply : {}));
+    return { engine, logs };
+  }
+
+  it('publishes a persistent store and logs no error', async () => {
+    const { engine, logs } = makeEngine({ persisted: true });
+    await engine.connect('user:abc');
+
+    expect(engine.storageHealth).toEqual({
+      status: 'persistent',
+      fallback: false,
+      error: undefined,
+    });
+    expect(logs.some((l) => l.level === 'error')).toBe(false);
+  });
+
+  it('publishes the fallback, its reason, and an error log when OPFS is lost', async () => {
+    const { engine, logs } = makeEngine({
+      persisted: false,
+      opfsError: 'NoModificationAllowedError: locked',
+    });
+    await engine.connect('user:abc');
+
+    expect(engine.storageHealth).toEqual({
+      status: 'memory',
+      fallback: true,
+      error: 'NoModificationAllowedError: locked',
+    });
+    const err = logs.find((l) => l.level === 'error');
+    expect(err?.msg).toContain('IN MEMORY');
+    expect(err?.meta.opfsError).toBe('NoModificationAllowedError: locked');
+    // Inspectable from the console without any logging configured.
+    expect((globalThis as any).__sqliteStats.persisted).toBe(false);
+  });
+
+  // A subscriber almost always attaches AFTER connect() (components mount
+  // later), so an immediate fire is the only way it learns about a fallback.
+  it('fires a late subscriber with the current snapshot', async () => {
+    const { engine } = makeEngine({ persisted: false, opfsError: 'boom' });
+    await engine.connect('user:abc');
+
+    const seen: any[] = [];
+    const unsub = engine.subscribeToStorageHealth((h) => seen.push(h));
+    expect(seen).toEqual([{ status: 'memory', fallback: true, error: 'boom' }]);
+    unsub();
+  });
+
+  // `store: 'memory'` asked for RAM, so it is not a fallback and must not warn.
+  it('does not flag a configured in-memory store as a fallback', async () => {
+    const { engine, logs } = makeEngine({ persisted: false }, { useOpfs: false });
+    await engine.connect('user:abc');
+
+    expect(engine.storageHealth).toEqual({ status: 'memory', fallback: false, error: undefined });
+    expect(logs.some((l) => l.level === 'error')).toBe(false);
+  });
+});
+
+// Storage numbers for the DevTools Storage tab: DB size via the pragmas, row
+// counts on demand, and the configured-vs-effective workerSelect split. Errors
+// must land in `error` (the worker may be mid bucket-switch), never throw.
+describe('SqliteCacheEngine.getStorageDiagnostics', () => {
+  function makeEngine(execRows: (sql: string) => unknown[]) {
+    const noop = () => {};
+    const logger: any = { debug: noop, info: noop, warn: noop, error: noop, trace: noop };
+    logger.child = () => logger;
+    const engine = new SqliteCacheEngine({ namespace: 'n', database: 'd' } as any, logger);
+    stubTransport(engine, (type, payload) =>
+      type === 'open' ? { persisted: true } : type === 'exec' ? { rows: execRows(payload.sql) } : {}
+    );
+    return engine;
+  }
+
+  it('reports size, freelist, and per-table counts', async () => {
+    const engine = makeEngine((sql) => {
+      if (sql.includes('pragma_page_count')) return [{ bytes: 40960, freelist: 4096 }];
+      if (sql.includes('sqlite_master')) return [{ name: '_00_query' }, { name: 'game' }];
+      if (sql.includes('COUNT(*)'))
+        return [
+          { t: '_00_query', n: 3 },
+          { t: 'game', n: 12 },
+        ];
+      return [];
+    });
+    await engine.connect('user:abc');
+
+    const diag = await engine.getStorageDiagnostics({ tableCounts: true });
+    expect(diag.engine).toBe('sqlite');
+    expect(diag.bucketId).toBe('user:abc');
+    expect(diag.dbSizeBytes).toBe(40960);
+    expect(diag.freelistBytes).toBe(4096);
+    expect(diag.tableCounts).toEqual([
+      { table: '_00_query', rows: 3 },
+      { table: 'game', rows: 12 },
+    ]);
+    // Default config: workerSelect on, never downgraded.
+    expect(diag.workerSelectConfigured).toBe(true);
+    expect(diag.workerSelectEffective).toBe(true);
+  });
+
+  it('skips table counts unless asked and never throws on a dead worker', async () => {
+    const engine = makeEngine(() => [{ bytes: 8192, freelist: 0 }]);
+    await engine.connect('anon');
+
+    const diag = await engine.getStorageDiagnostics();
+    expect(diag.tableCounts).toBeUndefined();
+
+    // No worker at all → the failure lands in `error`, not as a throw.
+    const cold = makeEngine(() => []);
+    const coldDiag = await cold.getStorageDiagnostics();
+    expect(coldDiag.error).toContain('not connected');
+    expect(coldDiag.bucketId).toBe('anon');
+  });
+});
+
+// Shared-tabs engine role modes: the engine object survives every role change
+// (one monotonic epoch per tab), followers speak the same protocol over a
+// MessagePort, and the leaderless window parks ops instead of failing the UI.
+describe('SqliteCacheEngine role modes', () => {
+  function makeSharedEngine() {
+    const log: string[] = [];
+    const engine = new SqliteCacheEngine({ namespace: 'n', database: 'd' } as any, makeLogger(), {
+      shared: true,
+      useOpfs: true,
+    });
+    stubTransport(engine, lifecycleHandler(log));
+    return { engine, log };
+  }
+
+  /** A fake follower dbPort: replies like the worker over postMessage. */
+  function fakeLeaderPort() {
+    const port: any = {
+      onmessage: null as null | ((ev: { data: any }) => void),
+      onmessageerror: null,
+      started: false,
+      closed: false,
+      start() {
+        this.started = true;
+      },
+      close() {
+        this.closed = true;
+      },
+      postMessage(msg: any) {
+        queueMicrotask(() => {
+          const rest =
+            msg.type === 'exec'
+              ? { rows: [] }
+              : msg.type === 'select'
+                ? { rows: [], relationFetches: 0 }
+                : {};
+          port.onmessage?.({ data: { id: msg.id, ok: true, wt: 0, ...rest } });
+        });
+      },
+    };
+    return port;
+  }
+
+  it('adoptOwner opens under the worker lock and wipes stale _00_query rows', async () => {
+    const { engine, log } = makeSharedEngine();
+    const health = await engine.adoptOwner('anon', {
+      workerLockName: 'sp00ky-tabs:fp:anon:worker:1',
+      allowMemoryFallback: false,
+      resumeHeld: false,
+    });
+    expect(health.status).toBe('persistent');
+    expect(engine.storageHealth.role).toBe('leader');
+    expect(log[0]).toBe('open');
+    expect(log).toContain('run'); // the DELETE _00_query wipe
+    expect(engine.currentBucketId).toBe('anon');
+  });
+
+  it('adoptAttached serves reads over the leader port and reports follower role', async () => {
+    const engine = new SqliteCacheEngine({ namespace: 'n', database: 'd' } as any, makeLogger(), {
+      shared: true,
+    });
+    const port = fakeLeaderPort();
+    await engine.adoptAttached(
+      port,
+      { bucketId: 'anon', storageHealth: { status: 'persistent', fallback: false } },
+      () => {}
+    );
+    expect(port.started).toBe(true);
+    expect(engine.storageHealth).toMatchObject({ status: 'persistent', role: 'follower' });
+    await expect(engine.getById('game', 'game:1')).resolves.toBeNull();
+    expect((globalThis as any).__sqliteStats.proxiedOps).toBeGreaterThan(0);
+  });
+
+  it('parks ops through a leader loss and releases them on promotion', async () => {
+    const { engine } = makeSharedEngine();
+    const port = fakeLeaderPort();
+    await engine.adoptAttached(
+      port,
+      { bucketId: 'anon', storageHealth: { status: 'persistent', fallback: false } },
+      () => {}
+    );
+    const epochBefore = engine.epoch;
+    engine.onLeaderLost('leader tab closed');
+    expect(engine.epoch).toBe(epochBefore + 1);
+
+    // Issued during the leaderless window: must not reject immediately.
+    const read = engine.getById('_00_query', 'h1');
+    let settled = false;
+    void read.finally(() => {
+      settled = true;
+    });
+    await new Promise((r) => setTimeout(r, 10));
+    expect(settled).toBe(false);
+
+    await engine.adoptOwner('anon', {
+      workerLockName: 'sp00ky-tabs:fp:anon:worker:2',
+      allowMemoryFallback: false,
+      resumeHeld: false,
+    });
+    await expect(read).resolves.toBeNull();
+    expect(engine.storageHealth.role).toBe('leader');
+  });
+
+  it('bumps the epoch on promotion after having had a store (fences in-flight chains)', async () => {
+    const { engine } = makeSharedEngine();
+    await engine.adoptOwner('anon', {
+      workerLockName: 'sp00ky-tabs:fp:anon:worker:1',
+      allowMemoryFallback: false,
+      resumeHeld: false,
+    });
+    const before = engine.epoch;
+    await engine.adoptOwner('anon', {
+      workerLockName: 'sp00ky-tabs:fp:anon:worker:3',
+      allowMemoryFallback: false,
+      resumeHeld: false,
+    });
+    expect(engine.epoch).toBeGreaterThan(before);
+  });
+});
+
+// `pureWriteOpResult` is the single source of truth for what a pure-write op
+// contributes to a query's per-statement results. The batched fast path in
+// `query()` and the per-op `execOp` path BOTH route through it, so a caller that
+// reads a statement's output (e.g. `create()` reads `resultIndex:0` for the new
+// row + its id) sees the same shape either way.
+describe('pureWriteOpResult', () => {
+  it('echoes the written row (with id) for an upsert — no read-back', () => {
+    const op: SqlOp = {
+      kind: 'upsert',
+      id: 'connection:CONN_abc',
+      data: { provider: 'chesscom', username: 'hikaru' },
+      mode: 'replace',
+    };
+    expect(pureWriteOpResult(op)).toEqual({
+      provider: 'chesscom',
+      username: 'hikaru',
+      id: 'connection:CONN_abc',
+    });
+  });
+
+  it('stringifies a RecordId id via stableKey', () => {
+    const op: SqlOp = {
+      kind: 'upsert',
+      id: new RecordId('connection', 'CONN_abc'),
+      data: { provider: 'lichess' },
+      mode: 'replace',
+    };
+    expect(pureWriteOpResult(op)).toEqual({ provider: 'lichess', id: 'connection:CONN_abc' });
+  });
+
+  it('yields [] for delete / deleteAll and null for noop', () => {
+    expect(pureWriteOpResult({ kind: 'delete', id: 'game:1' })).toEqual([]);
+    expect(pureWriteOpResult({ kind: 'deleteAll', table: 'game' })).toEqual([]);
+    expect(pureWriteOpResult({ kind: 'noop' })).toBeNull();
+  });
+});
+
+// Regression: a single `create()` compiles to an all-upsert transaction
+// (createSet for the row + createMutation for the pending-mutation log) and
+// extracts `resultIndex:0` for the created row. The SQLite fast path must return
+// that row (with its id) at that index — returning `[]` there dropped the id and
+// crashed the reconcile in `encodeRecordId` ("reading 'table'").
+describe('create() tx result shaping (fast path parity)', () => {
+  it('resultIndex:0 carries the created row with its id', () => {
+    const rid = new RecordId('connection', 'CONN_abc');
+    const mid = new RecordId('_00_pending_mutations', '1');
+    const vars = {
+      id: rid,
+      mid,
+      data_provider: 'chesscom',
+      data_username: 'hikaru',
+    };
+
+    // Same statement pair DataModule.create emits.
+    const sealed = surql.seal(
+      surql.tx([
+        surql.createSet('id', [
+          { key: 'provider', variable: 'data_provider' },
+          { key: 'username', variable: 'data_username' },
+        ]),
+        surql.createMutation('create', 'mid', 'id', 'data'),
+      ]),
+      { resultIndex: 0 }
+    );
+
+    const { transaction, ops } = translateSurql(sealed.sql, vars);
+    expect(transaction).toBe(true);
+    // Both statements are upserts → the engine takes the all-write fast path.
+    expect(ops.every((o) => o.kind === 'upsert')).toBe(true);
+
+    // Fast-path shaping: [null (BEGIN), ...one result per statement].
+    const shaped = [null, ...ops.map(pureWriteOpResult)];
+    const created = sealed.extract(shaped) as unknown as { id: unknown; provider: string };
+
+    expect(created.id).toBe('connection:CONN_abc');
+    expect(created.provider).toBe('chesscom');
+  });
+
+  // The outbox row is the ONLY copy of a pending create once the in-memory
+  // UpEvent is gone (reload, or a shared-tabs follower whose row the leader
+  // replays). It must carry the payload: `processUpEvent` does
+  // `Object.keys(event.data)`, so a row written with `data` unbound produces a
+  // create that can never be sent AND blocks every later mutation behind it.
+  //
+  // Note the vars: the RECORD is written from per-key `data_<field>` vars, so
+  // it is easy to emit `data = $data` and never bind `data` at the call site.
+  // That is exactly the bug this asserts against.
+  it('the outbox row carries the whole payload, not just the record id', () => {
+    const payload = { provider: 'chesscom', username: 'hikaru' };
+    const vars = {
+      id: new RecordId('connection', 'CONN_abc'),
+      mid: new RecordId('_00_pending_mutations', '1'),
+      data: payload,
+      data_provider: 'chesscom',
+      data_username: 'hikaru',
+    };
+
+    const sealed = surql.seal(
+      surql.tx([
+        surql.createSet('id', [
+          { key: 'provider', variable: 'data_provider' },
+          { key: 'username', variable: 'data_username' },
+        ]),
+        surql.createMutation('create', 'mid', 'id', 'data'),
+      ]),
+      { resultIndex: 0 }
+    );
+
+    const { ops } = translateSurql(sealed.sql, vars);
+    const outboxRow = pureWriteOpResult(ops[1]) as Record<string, unknown>;
+
+    expect(outboxRow.mutationType).toBe('create');
+    expect(outboxRow.data).toEqual(payload);
+  });
+});