@spooky-sync/core 0.0.1-canary.158 → 0.0.1-canary.159

package/dist/index.d.ts

@@ -802,6 +802,12 @@ interface Sp00kySyncOptions {
    * Defaults to `3`.
    */
   degradeAfterConsecutiveFailures?: number;
+  /**
+   * Max time a single mutation push may take before it is treated as a network
+   * failure and retried. Guards against an RPC that never settles wedging the
+   * up-queue for the session. Defaults to 30000; `0` disables the timeout.
+   */
+  pushTimeoutMs?: number;
 }
 /**
  * The main synchronization engine for Sp00ky.
@@ -849,6 +855,8 @@ declare class Sp00kySync<S extends SchemaStructure> {
   get pendingMutationCount(): number;
   subscribeToPendingMutations(cb: (count: number) => void): () => void;
   private readonly degradeAfterFailures;
+  /** Per-push RPC deadline; see {@link withPushTimeout}. */
+  private readonly pushTimeoutMs;
   private consecutiveSyncFailures;
   private syncHealthStatus;
   private lastSyncErrorKind;
@@ -901,6 +909,16 @@ declare class Sp00kySync<S extends SchemaStructure> {
    *  leader; everything else (registration, per-query sync, poll) runs
    *  against this tab's own remote session as usual. */
   demoteToFollower(forwarder: SyncForwarder): void;
+  /**
+   * A pending mutation was discarded because it can never be sent.
+   *
+   * This is a lost write, so it must not stay invisible. Every failure in this
+   * chain used to be a `logger.error` an app running `logLevel: 'fatal'` never
+   * shows, which is how an outbox could sit undrained for hours with the UI
+   * reporting nothing. Surfaces as a rollback event (the mutation will never
+   * apply, which is what a subscriber needs to know) and degrades sync health.
+   */
+  private onMutationDropped;
   /** A forwarded outbox row from a follower: load + drain it. Idempotent. */
   enqueueForwardedMutation(mutationId: string): Promise<void>;
   /** A relayed `_00_list_ref` LIVE event: resolve against THIS tab's queries
@@ -1002,6 +1020,19 @@ declare class Sp00kySync<S extends SchemaStructure> {
    * @param event The DownEvent to enqueue.
    */
   enqueueDownEvent(event: DownEvent): void;
+  /**
+   * Bound a mutation push so it always settles.
+   *
+   * `SyncScheduler.syncUp` early-returns while `isSyncingUp` is true, and that
+   * flag only clears in the `finally` of the drain loop. A push whose RPC never
+   * settles (socket dropped mid-flight, response lost) therefore wedges the
+   * up-queue for the rest of the session: no retry, no error, no further
+   * mutation ever sent. A timeout turns that into an ordinary network failure,
+   * which `UpQueue.next` re-queues for the next trigger. The message deliberately
+   * contains "timed out" so `classifySyncError` treats it as `network` and
+   * retries rather than rolling the mutation back.
+   */
+  private withPushTimeout;
   private processUpEvent;
   private handleRollback;
   private processDownEvent;

package/dist/index.js

@@ -297,7 +297,7 @@ const surql = {
 	},
 	createMutation(t, mutationIdVar, recordIdVar, dataVar, beforeRecordVar) {
 		switch (t) {
-			case "create": return `CREATE ONLY $${mutationIdVar} SET mutationType = 'create', recordId = $${recordIdVar}`;
+			case "create": return dataVar ? `CREATE ONLY $${mutationIdVar} SET mutationType = 'create', recordId = $${recordIdVar}, data = $${dataVar}` : `CREATE ONLY $${mutationIdVar} SET mutationType = 'create', recordId = $${recordIdVar}`;
 			case "update": {
 				let stmt = `CREATE ONLY $${mutationIdVar} SET mutationType = 'update', recordId = $${recordIdVar}, data = $${dataVar}`;
 				if (beforeRecordVar) stmt += `, beforeRecord = $${beforeRecordVar}`;
@@ -3886,12 +3886,46 @@ var UpQueue = class {
 	get events() {
 		return this._events;
 	}
-	constructor(local, logger) {
+	constructor(local, logger, onDropped) {
 		this.local = local;
+		this.onDropped = onDropped;
 		this._events = createSyncQueueEventSystem();
 		this.logger = logger.child({ service: "UpQueue" });
 		this.debouncedMutations = /* @__PURE__ */ new Map();
 	}
+	/**
+	* Discard an outbox row that can never be replayed and report it.
+	*
+	* Silently skipping such a row leaves it in the store to be re-read on every
+	* boot; leaving it QUEUED is worse, since `next()` re-queues it on failure and
+	* one unsendable row then blocks every later mutation for the whole app. A
+	* lost write must also be loud: this is the only signal a caller gets.
+	*/
+	async discardUnreplayable(row, reason) {
+		const mutationId = typeof row?.id === "string" ? row.id : encodeRecordId(row?.id);
+		this.logger.error({
+			mutationId,
+			recordId: row?.recordId,
+			mutationType: row?.mutationType,
+			reason,
+			Category: "sp00ky-client::UpQueue::discardUnreplayable"
+		}, "Discarding an unsendable pending mutation");
+		try {
+			await this.local.query(`DELETE $mutation_id`, { mutation_id: parseRecordIdString(mutationId) });
+		} catch (error) {
+			this.logger.error({
+				error,
+				mutationId,
+				Category: "sp00ky-client::UpQueue::discardUnreplayable"
+			}, "Failed to delete an unsendable pending mutation");
+		}
+		this.onDropped?.({
+			mutationId,
+			recordId: row?.recordId,
+			mutationType: row?.mutationType,
+			reason
+		});
+	}
 	get size() {
 		return this.queue.length;
 	}
@@ -4011,20 +4045,38 @@ var UpQueue = class {
 		if (this.queue.some((e) => encodeUpEventId(e) === mutationId)) return;
 		try {
 			const [records] = await this.local.query(`SELECT * FROM $mutation_ids`, { mutation_ids: [parseRecordIdString(mutationId)] });
-			const event = Array.isArray(records) && records[0] ? rowToUpEvent(records[0], this.logger) : null;
-			if (event) this.addToQueue(event);
+			const row = Array.isArray(records) ? records[0] : void 0;
+			if (!row) return;
+			const event = rowToUpEvent(row, this.logger);
+			if (event) {
+				this.addToQueue(event);
+				return;
+			}
+			await this.discardUnreplayable(row, "forwarded mutation is not replayable");
 		} catch (error) {
 			this.logger.error({
 				error,
 				mutationId,
 				Category: "sp00ky-client::UpQueue::enqueueFromDatabase"
 			}, "Failed to load a forwarded mutation");
+			this.onDropped?.({
+				mutationId,
+				reason: error instanceof Error ? error.message : String(error)
+			});
 		}
 	}
 	async loadFromDatabase() {
 		try {
 			const [records] = await this.local.query(`SELECT * FROM _00_pending_mutations ORDER BY id ASC`);
-			this.queue = records.map((r) => rowToUpEvent(r, this.logger)).filter((e) => e !== null);
+			const loaded = [];
+			const unreplayable = [];
+			for (const row of records) {
+				const event = rowToUpEvent(row, this.logger);
+				if (event) loaded.push(event);
+				else unreplayable.push(row);
+			}
+			this.queue = loaded;
+			for (const row of unreplayable) await this.discardUnreplayable(row, "pending mutation is not replayable");
 		} catch (error) {
 			this.logger.error({
 				error,
@@ -4040,13 +4092,15 @@ function encodeUpEventId(event) {
 /** Materialize one `_00_pending_mutations` row into an UpEvent. */
 function rowToUpEvent(r, logger) {
 	switch (r.mutationType) {
-		case "create": return {
-			type: "create",
-			mutation_id: parseRecordIdString(r.id),
-			record_id: parseRecordIdString(r.recordId),
-			data: r.data,
-			tableName: extractTablePart(r.recordId)
-		};
+		case "create":
+			if (r.data === void 0 || r.data === null) return null;
+			return {
+				type: "create",
+				mutation_id: parseRecordIdString(r.id),
+				record_id: parseRecordIdString(r.recordId),
+				data: r.data,
+				tableName: extractTablePart(r.recordId)
+			};
 		case "update": return {
 			type: "update",
 			mutation_id: parseRecordIdString(r.id),
@@ -4614,6 +4668,8 @@ var Sp00kySync = class Sp00kySync {
 		};
 	}
 	degradeAfterFailures;
+	/** Per-push RPC deadline; see {@link withPushTimeout}. */
+	pushTimeoutMs;
 	consecutiveSyncFailures = 0;
 	syncHealthStatus = "healthy";
 	lastSyncErrorKind;
@@ -4740,13 +4796,14 @@ var Sp00kySync = class Sp00kySync {
 		this.dataModule = dataModule;
 		this.schema = schema;
 		this.logger = logger.child({ service: "Sp00kySync" });
-		this.upQueue = new UpQueue(this.local, this.logger);
+		this.upQueue = new UpQueue(this.local, this.logger, (dropped) => this.onMutationDropped(dropped));
 		this.downQueue = new DownQueue(this.local, this.logger);
 		this.syncEngine = new SyncEngine(this.remote, this.cache, this.schema, this.logger);
 		this.scheduler = new SyncScheduler(this.upQueue, this.downQueue, this.processUpEvent.bind(this), this.processDownEvent.bind(this), this.logger, this.handleRollback.bind(this), this.recordSyncOutcome.bind(this));
 		this.refSyncIntervalMs = resolveListRefPollInterval(options?.refSyncIntervalMs);
 		this.anonLiveEnabled = options?.anonymousLiveQueries ?? false;
 		this.degradeAfterFailures = Math.max(0, options?.degradeAfterConsecutiveFailures ?? 3);
+		this.pushTimeoutMs = Math.max(0, options?.pushTimeoutMs ?? 3e4);
 	}
 	/**
 	* Initializes the synchronization system.
@@ -4838,6 +4895,27 @@ var Sp00kySync = class Sp00kySync {
 			}
 		};
 	}
+	/**
+	* A pending mutation was discarded because it can never be sent.
+	*
+	* This is a lost write, so it must not stay invisible. Every failure in this
+	* chain used to be a `logger.error` an app running `logLevel: 'fatal'` never
+	* shows, which is how an outbox could sit undrained for hours with the UI
+	* reporting nothing. Surfaces as a rollback event (the mutation will never
+	* apply, which is what a subscriber needs to know) and degrades sync health.
+	*/
+	onMutationDropped(dropped) {
+		this.logger.error({
+			...dropped,
+			Category: "sp00ky-client::Sp00kySync::onMutationDropped"
+		}, "Dropped a pending mutation that can never be sent");
+		this.recordSyncOutcome(false, /* @__PURE__ */ new Error(`dropped mutation: ${dropped.reason}`));
+		this.events.emit(SyncEventTypes.MutationRolledBack, {
+			eventType: dropped.mutationType ?? "update",
+			recordId: dropped.recordId ?? dropped.mutationId,
+			error: `dropped: ${dropped.reason}`
+		});
+	}
 	/** A forwarded outbox row from a follower: load + drain it. Idempotent. */
 	async enqueueForwardedMutation(mutationId) {
 		if (this.tabRole !== "leader") return;
@@ -5250,6 +5328,33 @@ var Sp00kySync = class Sp00kySync {
 	enqueueDownEvent(event) {
 		this.scheduler.enqueueDownEvent(event);
 	}
+	/**
+	* Bound a mutation push so it always settles.
+	*
+	* `SyncScheduler.syncUp` early-returns while `isSyncingUp` is true, and that
+	* flag only clears in the `finally` of the drain loop. A push whose RPC never
+	* settles (socket dropped mid-flight, response lost) therefore wedges the
+	* up-queue for the rest of the session: no retry, no error, no further
+	* mutation ever sent. A timeout turns that into an ordinary network failure,
+	* which `UpQueue.next` re-queues for the next trigger. The message deliberately
+	* contains "timed out" so `classifySyncError` treats it as `network` and
+	* retries rather than rolling the mutation back.
+	*/
+	withPushTimeout(promise, label) {
+		if (!(this.pushTimeoutMs > 0)) return promise;
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				reject(/* @__PURE__ */ new Error(`Mutation push timed out after ${this.pushTimeoutMs}ms (${label})`));
+			}, this.pushTimeoutMs);
+			promise.then((value) => {
+				clearTimeout(timer);
+				resolve(value);
+			}, (err) => {
+				clearTimeout(timer);
+				reject(err);
+			});
+		});
+	}
 	async processUpEvent(event) {
 		this.logger.debug({
 			event,
@@ -5263,20 +5368,20 @@ var Sp00kySync = class Sp00kySync {
 				}));
 				const prefixedParams = Object.fromEntries(dataKeys.map(({ key, variable }) => [variable, event.data[key]]));
 				const query = surql.seal(surql.createSet("id", dataKeys));
-				await this.remote.query(query, {
+				await this.withPushTimeout(this.remote.query(query, {
 					id: event.record_id,
 					...prefixedParams
-				});
+				}), "create");
 				break;
 			}
 			case "update":
-				await this.remote.query(`UPDATE $id MERGE $data`, {
+				await this.withPushTimeout(this.remote.query(`UPDATE $id MERGE $data`, {
 					id: event.record_id,
 					data: event.data
-				});
+				}), "update");
 				break;
 			case "delete":
-				await this.remote.query(`DELETE $id`, { id: event.record_id });
+				await this.withPushTimeout(this.remote.query(`DELETE $id`, { id: event.record_id }), "delete");
 				break;
 			default:
 				this.logger.error({
@@ -5694,8 +5799,8 @@ async function walkOpfs(maxEntries = 2e3, maxDepth = 8) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.158";
-const WASM_VERSION = "0.0.1-canary.158";
+const CORE_VERSION = "0.0.1-canary.159";
+const WASM_VERSION = "0.0.1-canary.159";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class DevToolsService {
 	eventsHistory = [];
@@ -8939,7 +9044,7 @@ var Sp00kyClient = class {
 		return new TabsCoordinator({
 			tabId,
 			fingerprint: computeTabsFingerprint({
-				coreVersion: "0.0.1-canary.158",
+				coreVersion: "0.0.1-canary.159",
 				schemaHash: hash53(this.config.schemaSurql),
 				endpoint: this.config.database.endpoint ?? "",
 				namespace: this.config.database.namespace,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.158",
+  "version": "0.0.1-canary.159",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -60,8 +60,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.158",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.158",
+    "@spooky-sync/query-builder": "0.0.1-canary.159",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.159",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@surrealdb/wasm": "^3.0.3",
     "fast-json-patch": "^3.1.1",

package/src/modules/sync/queue/queue-up.forwarded.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect, vi } from 'vitest';
 import { UpQueue } from './queue-up';
 import { translateSurql } from '../../../services/database/surql-translate';
+import { surql, classifySyncError } from '../../../utils/index';
 
 function makeLogger(): any {
   const noop = () => {};
@@ -57,6 +58,67 @@ describe('UpQueue.enqueueFromDatabase', () => {
   // single RecordId where the engine's `selectByIds` lowering expects an array,
   // so it threw, the surrounding catch swallowed it at `error` level, and every
   // follower mutation was silently never pushed. Drive the real translator.
+  it('discards a create with no payload instead of queueing a guaranteed failure', async () => {
+    // `processUpEvent` does `Object.keys(event.data)`, so this row can never be
+    // sent. Queued, it sat at the HEAD and blocked every later mutation for the
+    // whole app: `next()` re-queues on failure, so the backlog never drained.
+    const dropped: any[] = [];
+    const rows: Record<string, unknown[]> = {
+      [ROW.id]: [{ id: ROW.id, mutationType: 'create', recordId: 'comment:c1' }],
+    };
+    const query = vi.fn(async (sql: string, vars?: Record<string, unknown>) => {
+      if (sql.startsWith('DELETE')) return [[]];
+      const ids = (vars?.mutation_ids as unknown[]) ?? [];
+      return [rows[String(ids[0] ?? '')] ?? []];
+    });
+    const queue = new UpQueue({ query } as any, makeLogger(), (d) => dropped.push(d));
+
+    await queue.enqueueFromDatabase(ROW.id);
+
+    expect(queue.size).toBe(0);
+    expect(dropped).toHaveLength(1);
+    // And the row is deleted, so it cannot re-poison the next boot.
+    expect(query.mock.calls.some(([sql]) => String(sql).startsWith('DELETE'))).toBe(true);
+  });
+
+  it('loadFromDatabase drains the replayable rows even when one is unsendable', async () => {
+    const dropped: any[] = [];
+    const query = vi.fn(async (sql: string) => {
+      if (sql.startsWith('DELETE')) return [[]];
+      return [
+        [
+          { id: '_00_pending_mutations:a', mutationType: 'create', recordId: 'comment:c1' },
+          {
+            id: '_00_pending_mutations:b',
+            mutationType: 'update',
+            recordId: 'game:g1',
+            data: { title: 'x' },
+          },
+        ],
+      ];
+    });
+    const queue = new UpQueue({ query } as any, makeLogger(), (d) => dropped.push(d));
+
+    await queue.loadFromDatabase();
+
+    // The good row still loads; the poison one is dropped and reported.
+    expect(queue.size).toBe(1);
+    expect(dropped).toHaveLength(1);
+    expect(dropped[0].mutationId).toBe('_00_pending_mutations:a');
+  });
+
+  it('persists the payload for a create, so it can be replayed at all', () => {
+    // The create branch used to accept `dataVar` and ignore it, so the outbox
+    // row was the ONLY copy of a pending create and it carried no data.
+    const stmt = surql.createMutation('create', 'mid', 'id', 'data');
+    expect(stmt).toContain('data = $data');
+  });
+
+  it('a push timeout classifies as network, so it retries instead of rolling back', () => {
+    const err = new Error('Mutation push timed out after 30000ms (create)');
+    expect(classifySyncError(err)).toBe('network');
+  });
+
   it('emits a statement the SQLite engine can actually translate', async () => {
     const { queue, query } = makeQueue({ [ROW.id]: [ROW] });
     await queue.enqueueFromDatabase(ROW.id);

package/src/modules/sync/queue/queue-up.ts

@@ -42,6 +42,19 @@ export type UpEvent = CreateEvent | UpdateEvent | DeleteEvent;
 
 export type RollbackCallback = (event: UpEvent, error: Error) => Promise<void>;
 
+/**
+ * A pending mutation that can never be sent, so it was discarded instead of
+ * being retried forever at the head of the queue.
+ */
+export type DroppedMutation = {
+  mutationId: string;
+  recordId?: string;
+  mutationType?: string;
+  reason: string;
+};
+
+export type DroppedCallback = (dropped: DroppedMutation) => void;
+
 export class UpQueue {
   private queue: UpEvent[] = [];
   private _events: SyncQueueEventSystem;
@@ -57,13 +70,52 @@ export class UpQueue {
 
   constructor(
     private local: LocalStore,
-    logger: Logger
+    logger: Logger,
+    private onDropped?: DroppedCallback
   ) {
     this._events = createSyncQueueEventSystem();
     this.logger = logger.child({ service: 'UpQueue' });
     this.debouncedMutations = new Map();
   }
 
+  /**
+   * Discard an outbox row that can never be replayed and report it.
+   *
+   * Silently skipping such a row leaves it in the store to be re-read on every
+   * boot; leaving it QUEUED is worse, since `next()` re-queues it on failure and
+   * one unsendable row then blocks every later mutation for the whole app. A
+   * lost write must also be loud: this is the only signal a caller gets.
+   */
+  private async discardUnreplayable(row: any, reason: string): Promise<void> {
+    const mutationId = typeof row?.id === 'string' ? row.id : encodeRecordId(row?.id);
+    this.logger.error(
+      {
+        mutationId,
+        recordId: row?.recordId,
+        mutationType: row?.mutationType,
+        reason,
+        Category: 'sp00ky-client::UpQueue::discardUnreplayable',
+      },
+      'Discarding an unsendable pending mutation'
+    );
+    try {
+      await this.local.query(`DELETE $mutation_id`, {
+        mutation_id: parseRecordIdString(mutationId),
+      });
+    } catch (error) {
+      this.logger.error(
+        { error, mutationId, Category: 'sp00ky-client::UpQueue::discardUnreplayable' },
+        'Failed to delete an unsendable pending mutation'
+      );
+    }
+    this.onDropped?.({
+      mutationId,
+      recordId: row?.recordId,
+      mutationType: row?.mutationType,
+      reason,
+    });
+  }
+
   get size(): number {
     return this.queue.length;
   }
@@ -209,14 +261,23 @@ export class UpQueue {
       const [records] = await this.local.query<any>(`SELECT * FROM $mutation_ids`, {
         mutation_ids: [parseRecordIdString(mutationId)],
       });
-      const event =
-        Array.isArray(records) && records[0] ? rowToUpEvent(records[0], this.logger) : null;
-      if (event) this.addToQueue(event);
+      const row = Array.isArray(records) ? records[0] : undefined;
+      if (!row) return;
+      const event = rowToUpEvent(row, this.logger);
+      if (event) {
+        this.addToQueue(event);
+        return;
+      }
+      await this.discardUnreplayable(row, 'forwarded mutation is not replayable');
     } catch (error) {
       this.logger.error(
         { error, mutationId, Category: 'sp00ky-client::UpQueue::enqueueFromDatabase' },
         'Failed to load a forwarded mutation'
       );
+      this.onDropped?.({
+        mutationId,
+        reason: error instanceof Error ? error.message : String(error),
+      });
     }
   }
 
@@ -230,9 +291,20 @@ export class UpQueue {
         `SELECT * FROM _00_pending_mutations ORDER BY id ASC`
       );
 
-      this.queue = records
-        .map((r: any): UpEvent | null => rowToUpEvent(r, this.logger))
-        .filter((e: UpEvent | null): e is UpEvent => e !== null);
+      const loaded: UpEvent[] = [];
+      const unreplayable: any[] = [];
+      for (const row of records as any[]) {
+        const event = rowToUpEvent(row, this.logger);
+        if (event) loaded.push(event);
+        else unreplayable.push(row);
+      }
+      this.queue = loaded;
+      // Drop them AFTER the queue is populated: one unsendable row must not
+      // stop the rest of the backlog from draining, and leaving it in the store
+      // would just re-poison the next boot.
+      for (const row of unreplayable) {
+        await this.discardUnreplayable(row, 'pending mutation is not replayable');
+      }
     } catch (error) {
       this.logger.error(
         { error, Category: 'sp00ky-client::UpQueue::loadFromDatabase' },
@@ -251,6 +323,12 @@ function encodeUpEventId(event: UpEvent): string {
 function rowToUpEvent(r: any, logger: Logger): UpEvent | null {
   switch (r.mutationType) {
     case 'create':
+      // `processUpEvent` does `Object.keys(event.data)`, so a create with no
+      // payload throws before it reaches the network and can never succeed.
+      // Rows written before the create branch of `surql.createMutation`
+      // persisted `data` are exactly that, so refuse them here instead of
+      // queueing a guaranteed failure.
+      if (r.data === undefined || r.data === null) return null;
       return {
         type: 'create',
         mutation_id: parseRecordIdString(r.id),

package/src/modules/sync/sync.ts

@@ -1,8 +1,13 @@
 import type { LocalStore, RemoteDatabaseService } from '../../services/database/index';
-import type { RecordVersionArray, RecordVersionDiff, SyncHealth, SyncHealthStatus } from '../../types';
+import type {
+  RecordVersionArray,
+  RecordVersionDiff,
+  SyncHealth,
+  SyncHealthStatus,
+} from '../../types';
 import { createSyncEventSystem, SyncEventTypes, SyncQueueEventTypes } from './events/index';
 import type { Logger } from '../../services/logger/index';
-import type { DownEvent, UpEvent} from './queue/index';
+import type { DownEvent, UpEvent } from './queue/index';
 import { DownQueue, UpQueue } from './queue/index';
 import type { RecordId, Uuid } from 'surrealdb';
 import {
@@ -20,7 +25,13 @@ import { SyncScheduler } from './scheduler';
 import type { SchemaStructure } from '@spooky-sync/query-builder';
 import type { CacheModule } from '../cache/index';
 import type { DataModule } from '../data/index';
-import { classifySyncError, encodeRecordId, extractIdPart, extractTablePart, surql } from '../../utils/index';
+import {
+  classifySyncError,
+  encodeRecordId,
+  extractIdPart,
+  extractTablePart,
+  surql,
+} from '../../utils/index';
 import { ANON_USER_ID, DEFAULT_REF_MODE, listRefTableFor, RefMode } from '../ref-tables';
 import { mutationOwnerTabId } from '../data/mutation-id';
 import type { LeaderSyncHub, SyncForwarder } from '../../services/tabs/coordinator';
@@ -49,6 +60,12 @@ export interface Sp00kySyncOptions {
    * Defaults to `3`.
    */
   degradeAfterConsecutiveFailures?: number;
+  /**
+   * Max time a single mutation push may take before it is treated as a network
+   * failure and retried. Guards against an RPC that never settles wedging the
+   * up-queue for the session. Defaults to 30000; `0` disables the timeout.
+   */
+  pushTimeoutMs?: number;
 }
 
 /**
@@ -162,13 +179,11 @@ export class Sp00kySync<S extends SchemaStructure> {
   }
 
   subscribeToPendingMutations(cb: (count: number) => void): () => void {
-    const id1 = this.upQueue.events.subscribe(
-      SyncQueueEventTypes.MutationEnqueued,
-      (event) => cb(event.payload.queueSize)
+    const id1 = this.upQueue.events.subscribe(SyncQueueEventTypes.MutationEnqueued, (event) =>
+      cb(event.payload.queueSize)
     );
-    const id2 = this.upQueue.events.subscribe(
-      SyncQueueEventTypes.MutationDequeued,
-      (event) => cb(event.payload.queueSize)
+    const id2 = this.upQueue.events.subscribe(SyncQueueEventTypes.MutationDequeued, (event) =>
+      cb(event.payload.queueSize)
     );
     return () => {
       this.upQueue.events.unsubscribe(id1);
@@ -180,6 +195,8 @@ export class Sp00kySync<S extends SchemaStructure> {
   // `0` disables degraded reporting (config `syncHealth: false`). Resolved
   // from config in Sp00kyClient and passed through the constructor options.
   private readonly degradeAfterFailures: number;
+  /** Per-push RPC deadline; see {@link withPushTimeout}. */
+  private readonly pushTimeoutMs: number;
   private consecutiveSyncFailures = 0;
   private syncHealthStatus: SyncHealthStatus = 'healthy';
   private lastSyncErrorKind: 'network' | 'application' | undefined;
@@ -297,7 +314,11 @@ export class Sp00kySync<S extends SchemaStructure> {
       if (this.syncHealthStatus !== 'degraded') return;
       this.selfHealAttempts++;
       this.logger.debug(
-        { attempt: this.selfHealAttempts, delayMs: delay, Category: 'sp00ky-client::Sp00kySync::selfHeal' },
+        {
+          attempt: this.selfHealAttempts,
+          delayMs: delay,
+          Category: 'sp00ky-client::Sp00kySync::selfHeal',
+        },
         'Self-heal: re-driving sync while degraded'
       );
       try {
@@ -353,7 +374,9 @@ export class Sp00kySync<S extends SchemaStructure> {
     options?: Sp00kySyncOptions
   ) {
     this.logger = logger.child({ service: 'Sp00kySync' });
-    this.upQueue = new UpQueue(this.local, this.logger);
+    this.upQueue = new UpQueue(this.local, this.logger, (dropped) =>
+      this.onMutationDropped(dropped)
+    );
     this.downQueue = new DownQueue(this.local, this.logger);
     this.syncEngine = new SyncEngine(this.remote, this.cache, this.schema, this.logger);
     this.scheduler = new SyncScheduler(
@@ -368,6 +391,7 @@ export class Sp00kySync<S extends SchemaStructure> {
     this.refSyncIntervalMs = resolveListRefPollInterval(options?.refSyncIntervalMs);
     this.anonLiveEnabled = options?.anonymousLiveQueries ?? false;
     this.degradeAfterFailures = Math.max(0, options?.degradeAfterConsecutiveFailures ?? 3);
+    this.pushTimeoutMs = Math.max(0, options?.pushTimeoutMs ?? 30_000);
   }
 
   /**
@@ -483,6 +507,33 @@ export class Sp00kySync<S extends SchemaStructure> {
     };
   }
 
+  /**
+   * A pending mutation was discarded because it can never be sent.
+   *
+   * This is a lost write, so it must not stay invisible. Every failure in this
+   * chain used to be a `logger.error` an app running `logLevel: 'fatal'` never
+   * shows, which is how an outbox could sit undrained for hours with the UI
+   * reporting nothing. Surfaces as a rollback event (the mutation will never
+   * apply, which is what a subscriber needs to know) and degrades sync health.
+   */
+  private onMutationDropped(dropped: {
+    mutationId: string;
+    recordId?: string;
+    mutationType?: string;
+    reason: string;
+  }): void {
+    this.logger.error(
+      { ...dropped, Category: 'sp00ky-client::Sp00kySync::onMutationDropped' },
+      'Dropped a pending mutation that can never be sent'
+    );
+    this.recordSyncOutcome(false, new Error(`dropped mutation: ${dropped.reason}`));
+    this.events.emit(SyncEventTypes.MutationRolledBack, {
+      eventType: (dropped.mutationType as 'create' | 'update' | 'delete') ?? 'update',
+      recordId: dropped.recordId ?? dropped.mutationId,
+      error: `dropped: ${dropped.reason}`,
+    });
+  }
+
   /** A forwarded outbox row from a follower: load + drain it. Idempotent. */
   public async enqueueForwardedMutation(mutationId: string): Promise<void> {
     if (this.tabRole !== 'leader') return;
@@ -709,7 +760,11 @@ export class Sp00kySync<S extends SchemaStructure> {
           reached = true;
         }
         this.logger.debug(
-          { err: (err as Error)?.message ?? err, hash, Category: 'sp00ky-client::Sp00kySync::pollListRefForActiveQueries' },
+          {
+            err: (err as Error)?.message ?? err,
+            hash,
+            Category: 'sp00ky-client::Sp00kySync::pollListRefForActiveQueries',
+          },
           'Per-query list_ref poll failed'
         );
       }
@@ -742,10 +797,7 @@ export class Sp00kySync<S extends SchemaStructure> {
       { in: queryState.config.id }
     );
     if (!Array.isArray(items)) return false;
-    const fresh: RecordVersionArray = items.map((item) => [
-      encodeRecordId(item.out),
-      item.version,
-    ]);
+    const fresh: RecordVersionArray = items.map((item) => [encodeRecordId(item.out), item.version]);
     // Capture which ids LEFT the query's window (present in the cached
     // remoteArray, absent from `fresh`) BEFORE we overwrite remoteArray — these
     // are cross-window deletes (or rows that scrolled out). They drive the
@@ -780,7 +832,11 @@ export class Sp00kySync<S extends SchemaStructure> {
       await this.syncQuery(queryHash);
     } catch (err) {
       this.logger.info(
-        { err: (err as Error)?.message ?? err, queryHash, Category: 'sp00ky-client::Sp00kySync::refetchListRefForQuery' },
+        {
+          err: (err as Error)?.message ?? err,
+          queryHash,
+          Category: 'sp00ky-client::Sp00kySync::refetchListRefForQuery',
+        },
         'syncQuery failed during poll'
       );
     }
@@ -789,7 +845,11 @@ export class Sp00kySync<S extends SchemaStructure> {
     // poll too (idempotent — no-op when nothing changed).
     await this.syncSubqueryChildren(queryHash).catch((err) => {
       this.logger.info(
-        { err: (err as Error)?.message ?? err, queryHash, Category: 'sp00ky-client::Sp00kySync::refetchListRefForQuery' },
+        {
+          err: (err as Error)?.message ?? err,
+          queryHash,
+          Category: 'sp00ky-client::Sp00kySync::refetchListRefForQuery',
+        },
         'Subquery child sync failed during poll'
       );
     });
@@ -803,7 +863,11 @@ export class Sp00kySync<S extends SchemaStructure> {
         await this.dataModule.notifyQuerySynced(queryHash);
       } catch (err) {
         this.logger.info(
-          { err: (err as Error)?.message ?? err, queryHash, Category: 'sp00ky-client::Sp00kySync::refetchListRefForQuery' },
+          {
+            err: (err as Error)?.message ?? err,
+            queryHash,
+            Category: 'sp00ky-client::Sp00kySync::refetchListRefForQuery',
+          },
           'notifyQuerySynced failed during poll-removal re-render'
         );
       }
@@ -833,7 +897,11 @@ export class Sp00kySync<S extends SchemaStructure> {
 
   private async killRefLiveQuery(): Promise<void> {
     if (this.liveQueryUnsubscribe) {
-      try { this.liveQueryUnsubscribe(); } catch { /* ignore */ }
+      try {
+        this.liveQueryUnsubscribe();
+      } catch {
+        /* ignore */
+      }
       this.liveQueryUnsubscribe = null;
     }
     if (this.currentLiveQueryUuid !== null) {
@@ -903,9 +971,7 @@ export class Sp00kySync<S extends SchemaStructure> {
       'Starting ref live queries'
     );
 
-    const [queryUuid] = await this.remote.query<[Uuid]>(
-      `LIVE SELECT * FROM ${tableName}`
-    );
+    const [queryUuid] = await this.remote.query<[Uuid]>(`LIVE SELECT * FROM ${tableName}`);
     this.currentLiveQueryUuid = queryUuid;
 
     const live = await this.remote.getClient().liveOf(queryUuid);
@@ -1077,6 +1143,37 @@ export class Sp00kySync<S extends SchemaStructure> {
     this.scheduler.enqueueDownEvent(event);
   }
 
+  /**
+   * Bound a mutation push so it always settles.
+   *
+   * `SyncScheduler.syncUp` early-returns while `isSyncingUp` is true, and that
+   * flag only clears in the `finally` of the drain loop. A push whose RPC never
+   * settles (socket dropped mid-flight, response lost) therefore wedges the
+   * up-queue for the rest of the session: no retry, no error, no further
+   * mutation ever sent. A timeout turns that into an ordinary network failure,
+   * which `UpQueue.next` re-queues for the next trigger. The message deliberately
+   * contains "timed out" so `classifySyncError` treats it as `network` and
+   * retries rather than rolling the mutation back.
+   */
+  private withPushTimeout<T>(promise: Promise<T>, label: string): Promise<T> {
+    if (!(this.pushTimeoutMs > 0)) return promise;
+    return new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        reject(new Error(`Mutation push timed out after ${this.pushTimeoutMs}ms (${label})`));
+      }, this.pushTimeoutMs);
+      promise.then(
+        (value) => {
+          clearTimeout(timer);
+          resolve(value);
+        },
+        (err) => {
+          clearTimeout(timer);
+          reject(err);
+        }
+      );
+    });
+  }
+
   private async processUpEvent(event: UpEvent) {
     this.logger.debug(
       { event, Category: 'sp00ky-client::Sp00kySync::processUpEvent' },
@@ -1089,22 +1186,31 @@ export class Sp00kySync<S extends SchemaStructure> {
           dataKeys.map(({ key, variable }) => [variable, event.data[key]])
         );
         const query = surql.seal(surql.createSet('id', dataKeys));
-        await this.remote.query(query, {
-          id: event.record_id,
-          ...prefixedParams,
-        });
+        await this.withPushTimeout(
+          this.remote.query(query, {
+            id: event.record_id,
+            ...prefixedParams,
+          }),
+          'create'
+        );
         break;
       }
       case 'update':
-        await this.remote.query(`UPDATE $id MERGE $data`, {
-          id: event.record_id,
-          data: event.data,
-        });
+        await this.withPushTimeout(
+          this.remote.query(`UPDATE $id MERGE $data`, {
+            id: event.record_id,
+            data: event.data,
+          }),
+          'update'
+        );
         break;
       case 'delete':
-        await this.remote.query(`DELETE $id`, {
-          id: event.record_id,
-        });
+        await this.withPushTimeout(
+          this.remote.query(`DELETE $id`, {
+            id: event.record_id,
+          }),
+          'delete'
+        );
         break;
       default:
         this.logger.error(
@@ -1118,9 +1224,7 @@ export class Sp00kySync<S extends SchemaStructure> {
   private async handleRollback(event: UpEvent, error: Error): Promise<void> {
     const recordId = encodeRecordId(event.record_id);
     const tableName =
-      event.type === 'create' && event.tableName
-        ? event.tableName
-        : extractTablePart(recordId);
+      event.type === 'create' && event.tableName ? event.tableName : extractTablePart(recordId);
 
     this.logger.warn(
       {
@@ -1448,7 +1552,11 @@ export class Sp00kySync<S extends SchemaStructure> {
     // empty. Best-effort: never fail registration over it.
     await this.syncSubqueryChildren(queryHash).catch((err) => {
       this.logger.info(
-        { err: (err as Error)?.message ?? err, queryHash, Category: 'sp00ky-client::Sp00kySync::createRemoteQuery' },
+        {
+          err: (err as Error)?.message ?? err,
+          queryHash,
+          Category: 'sp00ky-client::Sp00kySync::createRemoteQuery',
+        },
         'Subquery child sync failed during registration; poll will retry'
       );
     });

package/src/utils/surql.ts

@@ -91,17 +91,9 @@ export const surql: SurqlHelper = {
     returnValues: ({ field: string; alias: string } | string)[]
   ) {
     return `SELECT ${returnValues
-      .map((rv) =>
-        typeof rv === 'string'
-          ? rv
-          : `${rv.field} as ${rv.alias}`
-      )
+      .map((rv) => (typeof rv === 'string' ? rv : `${rv.field} as ${rv.alias}`))
       .join(',')} FROM ${table} WHERE ${whereVar
-      .map((wv) =>
-        typeof wv === 'string'
-          ? `${wv} = $${wv}`
-          : `${wv.field} = $${wv.variable}`
-      )
+      .map((wv) => (typeof wv === 'string' ? `${wv} = $${wv}` : `${wv.field} = $${wv.variable}`))
       .join(' AND ')}`;
   },
 
@@ -172,7 +164,18 @@ export const surql: SurqlHelper = {
   ) {
     switch (t) {
       case 'create':
-        return `CREATE ONLY $${mutationIdVar} SET mutationType = 'create', recordId = $${recordIdVar}`;
+        // `data` is REQUIRED here, not decorative. 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 is replayed by the leader). This
+        // used to drop `dataVar` on the floor, so every replayed create arrived
+        // with `data: undefined` and `processUpEvent` threw on
+        // `Object.keys(event.data)` before it ever reached the network: the
+        // create was unsendable AND it sat at the head of the queue blocking
+        // every later mutation. The payload was simply never persisted, so
+        // those creates were unrecoverable.
+        return dataVar
+          ? `CREATE ONLY $${mutationIdVar} SET mutationType = 'create', recordId = $${recordIdVar}, data = $${dataVar}`
+          : `CREATE ONLY $${mutationIdVar} SET mutationType = 'create', recordId = $${recordIdVar}`;
       case 'update': {
         let stmt = `CREATE ONLY $${mutationIdVar} SET mutationType = 'update', recordId = $${recordIdVar}, data = $${dataVar}`;
         if (beforeRecordVar) {