@spooky-sync/core 0.0.1-canary.84 → 0.0.1-canary.85

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { A as UpEvent, C as RunOptions, D as StoreType, E as Sp00kyQueryResultPromise, M as SyncEventSystem, N as EventDefinition, O as TimingPhase, P as EventSystem, S as RegistrationTimings, T as Sp00kyQueryResult, _ as QueryTimeToLive, a as MutationCallback, b as RecordVersionArray, c as PersistenceClient, d as QueryConfig, f as QueryConfigRecord, g as QueryStatusCallback, h as QueryStatus, i as MATERIALIZATION_SAMPLE_WINDOW, j as Logger$1, k as UpdateOptions, l as PhaseStat, m as QueryState, n as EventSubscriptionOptions, o as MutationEvent, p as QueryHash, r as Level, s as MutationEventType, t as DebounceOptions, u as PinoTransmit, v as QueryTimings, w as Sp00kyConfig, x as RecordVersionDiff, y as QueryUpdateCallback } from "./types.js";
+import { A as SyncHealthStatus, C as RunOptions, D as StoreType, E as Sp00kyQueryResultPromise, F as SyncEventSystem, I as EventDefinition, L as EventSystem, M as UpdateOptions, N as UpEvent, O as SyncHealth, P as Logger$1, S as RegistrationTimings, T as Sp00kyQueryResult, _ as QueryTimeToLive, a as MutationCallback, b as RecordVersionArray, c as PersistenceClient, d as QueryConfig, f as QueryConfigRecord, g as QueryStatusCallback, h as QueryStatus, i as MATERIALIZATION_SAMPLE_WINDOW, j as TimingPhase, k as SyncHealthConfig, l as PhaseStat, m as QueryState, n as EventSubscriptionOptions, o as MutationEvent, p as QueryHash, r as Level, s as MutationEventType, t as DebounceOptions, u as PinoTransmit, v as QueryTimings, w as Sp00kyConfig, x as RecordVersionDiff, y as QueryUpdateCallback } from "./types.js";
 import * as surrealdb0 from "surrealdb";
 import { Duration, RecordId, Surreal as Surreal$1, SurrealTransaction } from "surrealdb";
 import { AccessDefinition, BackendNames, BackendRoutes, BucketNames, ColumnSchema, GetTable, QueryBuilder, QueryOptions, RoutePayload, SchemaStructure, TableModel, TableNames, TypeNameToTypeMap } from "@spooky-sync/query-builder";
@@ -586,6 +586,12 @@ interface Sp00kySyncOptions {
    * Defaults to `false`.
    */
   anonymousLiveQueries?: boolean;
+  /**
+   * Consecutive failed sync rounds before sync health flips to `degraded`.
+   * `0` disables degraded reporting. See {@link Sp00kyConfig.syncHealth}.
+   * Defaults to `3`.
+   */
+  degradeAfterConsecutiveFailures?: number;
 }
 /**
  * The main synchronization engine for Sp00ky.
@@ -627,6 +633,28 @@ declare class Sp00kySync<S extends SchemaStructure> {
   get isSyncing(): boolean;
   get pendingMutationCount(): number;
   subscribeToPendingMutations(cb: (count: number) => void): () => void;
+  private readonly degradeAfterFailures;
+  private consecutiveSyncFailures;
+  private syncHealthStatus;
+  private lastSyncErrorKind;
+  private lastSyncErrorMessage;
+  /** Current sync-health snapshot. */
+  get syncHealth(): SyncHealth;
+  /**
+   * Observe sync health. The callback fires immediately with the current
+   * status and again on every healthy↔degraded transition. Returns an
+   * unsubscribe. Mirrors {@link subscribeToPendingMutations}.
+   */
+  subscribeToSyncHealth(cb: (health: SyncHealth) => void): () => void;
+  private emitSyncHealth;
+  /**
+   * Fed by the scheduler once per drained sync round. Individual failures are
+   * absorbed by the queue's retry; only a run of `degradeAfterFailures`
+   * consecutive failures flips the status to `degraded`, and the next clean
+   * round flips it back. No-op when reporting is disabled (`degradeAfterFailures`
+   * is 0).
+   */
+  private recordSyncOutcome;
   constructor(local: LocalDatabaseService, remote: RemoteDatabaseService, cache: CacheModule, dataModule: DataModule<S>, schema: S, logger: Logger$1, options?: Sp00kySyncOptions);
   /**
    * Initializes the synchronization system.
@@ -1043,6 +1071,13 @@ declare class Sp00kyClient<S extends SchemaStructure> {
    *  suite can guard the pre-emptive path against regression. */
   get liveRetryCount(): number;
   subscribeToPendingMutations(cb: (count: number) => void): () => void;
+  /** Current sync-health snapshot. See {@link Sp00kyConfig.syncHealth}. */
+  get syncHealth(): SyncHealth;
+  /**
+   * Observe sync health. Fires immediately with the current status and again
+   * on every healthy↔degraded transition. Returns an unsubscribe.
+   */
+  subscribeToSyncHealth(cb: (health: SyncHealth) => void): () => void;
   constructor(config: Sp00kyConfig<S>);
   /**
    * Setup direct callbacks instead of event subscriptions
@@ -1130,4 +1165,4 @@ declare function textToHtml(text: string): string;
  */
 
 //#endregion
-export { AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, BucketHandle, CURSOR_COLORS, CrdtField, CrdtManager, DebounceOptions, EventSubscriptionOptions, FeatureFlagHandle, FeatureFlagModule, type FeatureFlagOptions, type FeatureFlagSnapshot, Level, MATERIALIZATION_SAMPLE_WINDOW, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, PhaseStat, PinoTransmit, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryStatus, QueryStatusCallback, QueryTimeToLive, QueryTimings, QueryUpdateCallback, RecordVersionArray, RecordVersionDiff, RegistrationTimings, RunOptions, Sp00kyClient, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StoreType, TimingPhase, UpdateOptions, createAuthEventSystem, cursorColorFromName, fileToUint8Array, textToHtml };
+export { AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, BucketHandle, CURSOR_COLORS, CrdtField, CrdtManager, DebounceOptions, EventSubscriptionOptions, FeatureFlagHandle, FeatureFlagModule, type FeatureFlagOptions, type FeatureFlagSnapshot, Level, MATERIALIZATION_SAMPLE_WINDOW, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, PhaseStat, PinoTransmit, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryStatus, QueryStatusCallback, QueryTimeToLive, QueryTimings, QueryUpdateCallback, RecordVersionArray, RecordVersionDiff, RegistrationTimings, RunOptions, Sp00kyClient, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StoreType, SyncHealth, SyncHealthConfig, SyncHealthStatus, TimingPhase, UpdateOptions, createAuthEventSystem, cursorColorFromName, fileToUint8Array, textToHtml };

package/dist/index.js

@@ -1948,13 +1948,15 @@ function createSyncQueueEventSystem() {
 const SyncEventTypes = {
 	QueryUpdated: "SYNC_QUERY_UPDATED",
 	RemoteDataIngested: "SYNC_REMOTE_DATA_INGESTED",
-	MutationRolledBack: "SYNC_MUTATION_ROLLED_BACK"
+	MutationRolledBack: "SYNC_MUTATION_ROLLED_BACK",
+	SyncHealthChanged: "SYNC_HEALTH_CHANGED"
 };
 function createSyncEventSystem() {
 	return createEventSystem([
 		SyncEventTypes.QueryUpdated,
 		SyncEventTypes.RemoteDataIngested,
-		SyncEventTypes.MutationRolledBack
+		SyncEventTypes.MutationRolledBack,
+		SyncEventTypes.SyncHealthChanged
 	]);
 }
 
@@ -2489,13 +2491,14 @@ var SyncEngine = class {
 var SyncScheduler = class {
 	isSyncingUp = false;
 	isSyncingDown = false;
-	constructor(upQueue, downQueue, onProcessUp, onProcessDown, logger, onRollback) {
+	constructor(upQueue, downQueue, onProcessUp, onProcessDown, logger, onRollback, onSyncOutcome) {
 		this.upQueue = upQueue;
 		this.downQueue = downQueue;
 		this.onProcessUp = onProcessUp;
 		this.onProcessDown = onProcessDown;
 		this.logger = logger;
 		this.onRollback = onRollback;
+		this.onSyncOutcome = onSyncOutcome;
 	}
 	async init() {
 		await this.upQueue.loadFromDatabase();
@@ -2520,8 +2523,19 @@ var SyncScheduler = class {
 	async syncUp() {
 		if (this.isSyncingUp) return;
 		this.isSyncingUp = true;
+		let processedAny = false;
 		try {
-			while (this.upQueue.size > 0) await this.upQueue.next(this.onProcessUp, this.onRollback);
+			while (this.upQueue.size > 0) {
+				await this.upQueue.next(this.onProcessUp, this.onRollback);
+				processedAny = true;
+			}
+			if (processedAny) this.onSyncOutcome?.(true);
+		} catch (error) {
+			this.onSyncOutcome?.(false, error);
+			this.logger.debug({
+				error,
+				Category: "sp00ky-client::SyncScheduler::syncUp"
+			}, "syncUp halted on a queue error; item re-queued, will retry on next trigger");
 		} finally {
 			this.isSyncingUp = false;
 			this.syncDown();
@@ -2534,11 +2548,20 @@ var SyncScheduler = class {
 		if (this.isSyncingDown) return;
 		if (this.upQueue.size > 0) return;
 		this.isSyncingDown = true;
+		let processedAny = false;
 		try {
 			while (this.downQueue.size > 0) {
 				if (this.upQueue.size > 0) break;
 				await this.downQueue.next(this.onProcessDown);
+				processedAny = true;
 			}
+			if (processedAny) this.onSyncOutcome?.(true);
+		} catch (error) {
+			this.onSyncOutcome?.(false, error);
+			this.logger.debug({
+				error,
+				Category: "sp00ky-client::SyncScheduler::syncDown"
+			}, "syncDown halted on a queue error; item re-queued, will retry on next trigger");
 		} finally {
 			this.isSyncingDown = false;
 		}
@@ -2647,6 +2670,68 @@ var Sp00kySync = class {
 			this.upQueue.events.unsubscribe(id2);
 		};
 	}
+	degradeAfterFailures;
+	consecutiveSyncFailures = 0;
+	syncHealthStatus = "healthy";
+	lastSyncErrorKind;
+	lastSyncErrorMessage;
+	/** Current sync-health snapshot. */
+	get syncHealth() {
+		return {
+			status: this.syncHealthStatus,
+			consecutiveFailures: this.consecutiveSyncFailures,
+			kind: this.syncHealthStatus === "degraded" ? this.lastSyncErrorKind : void 0,
+			error: this.syncHealthStatus === "degraded" ? this.lastSyncErrorMessage : void 0
+		};
+	}
+	/**
+	* Observe sync health. The callback fires immediately with the current
+	* status and again on every healthy↔degraded transition. Returns an
+	* unsubscribe. Mirrors {@link subscribeToPendingMutations}.
+	*/
+	subscribeToSyncHealth(cb) {
+		cb(this.syncHealth);
+		const id = this.events.subscribe(SyncEventTypes.SyncHealthChanged, (event) => cb(event.payload));
+		return () => this.events.unsubscribe(id);
+	}
+	emitSyncHealth() {
+		this.events.emit(SyncEventTypes.SyncHealthChanged, this.syncHealth);
+	}
+	/**
+	* Fed by the scheduler once per drained sync round. Individual failures are
+	* absorbed by the queue's retry; only a run of `degradeAfterFailures`
+	* consecutive failures flips the status to `degraded`, and the next clean
+	* round flips it back. No-op when reporting is disabled (`degradeAfterFailures`
+	* is 0).
+	*/
+	recordSyncOutcome(ok, error) {
+		if (this.degradeAfterFailures <= 0) return;
+		if (ok) {
+			if (this.consecutiveSyncFailures === 0) return;
+			this.consecutiveSyncFailures = 0;
+			if (this.syncHealthStatus !== "healthy") {
+				this.syncHealthStatus = "healthy";
+				this.lastSyncErrorKind = void 0;
+				this.lastSyncErrorMessage = void 0;
+				this.logger.info({ Category: "sp00ky-client::Sp00kySync::syncHealth" }, "Sync recovered; health back to healthy");
+				this.emitSyncHealth();
+			}
+			return;
+		}
+		this.consecutiveSyncFailures++;
+		this.lastSyncErrorKind = classifySyncError(error);
+		this.lastSyncErrorMessage = error instanceof Error ? error.message : String(error);
+		if (this.syncHealthStatus !== "degraded" && this.consecutiveSyncFailures >= this.degradeAfterFailures) {
+			this.syncHealthStatus = "degraded";
+			this.logger.warn({
+				consecutiveFailures: this.consecutiveSyncFailures,
+				kind: this.lastSyncErrorKind,
+				error,
+				Category: "sp00ky-client::Sp00kySync::syncHealth"
+			}, "Sync degraded after sustained failures");
+			this.emitSyncHealth();
+		}
+	}
 	constructor(local, remote, cache, dataModule, schema, logger, options) {
 		this.local = local;
 		this.remote = remote;
@@ -2657,9 +2742,10 @@ var Sp00kySync = class {
 		this.upQueue = new UpQueue(this.local, this.logger);
 		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.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);
 	}
 	/**
 	* Initializes the synchronization system.
@@ -3343,8 +3429,8 @@ function parseBackendInfo(raw) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.84";
-const WASM_VERSION = "0.0.1-canary.84";
+const CORE_VERSION = "0.0.1-canary.85";
+const WASM_VERSION = "0.0.1-canary.85";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class {
 	eventsHistory = [];
@@ -5170,6 +5256,17 @@ var Sp00kyClient = class {
 	subscribeToPendingMutations(cb) {
 		return this.sync.subscribeToPendingMutations(cb);
 	}
+	/** Current sync-health snapshot. See {@link Sp00kyConfig.syncHealth}. */
+	get syncHealth() {
+		return this.sync.syncHealth;
+	}
+	/**
+	* Observe sync health. Fires immediately with the current status and again
+	* on every healthy↔degraded transition. Returns an unsubscribe.
+	*/
+	subscribeToSyncHealth(cb) {
+		return this.sync.subscribeToSyncHealth(cb);
+	}
 	constructor(config) {
 		this.config = config;
 		const logger = createLogger(config.logLevel ?? "info", config.otelTransmit);
@@ -5197,7 +5294,8 @@ var Sp00kyClient = class {
 		this.auth = new AuthService(this.config.schema, this.remote, this.persistenceClient, logger);
 		this.sync = new Sp00kySync(this.local, this.remote, this.cache, this.dataModule, this.config.schema, this.logger, {
 			refSyncIntervalMs: this.config.refSyncIntervalMs,
-			anonymousLiveQueries: this.config.enableAnonymousLiveQueries
+			anonymousLiveQueries: this.config.enableAnonymousLiveQueries,
+			degradeAfterConsecutiveFailures: this.config.syncHealth === false ? 0 : this.config.syncHealth?.degradeAfterConsecutiveFailures ?? 3
 		});
 		this.featureFlags = new FeatureFlagModule({
 			dataModule: this.dataModule,

package/dist/types.d.ts

@@ -128,6 +128,7 @@ declare const SyncEventTypes: {
   readonly QueryUpdated: "SYNC_QUERY_UPDATED";
   readonly RemoteDataIngested: "SYNC_REMOTE_DATA_INGESTED";
   readonly MutationRolledBack: "SYNC_MUTATION_ROLLED_BACK";
+  readonly SyncHealthChanged: "SYNC_HEALTH_CHANGED";
 };
 type SyncEventTypeMap = {
   [SyncEventTypes.QueryUpdated]: EventDefinition<typeof SyncEventTypes.QueryUpdated, {
@@ -146,6 +147,7 @@ type SyncEventTypeMap = {
     recordId: string;
     error: string;
   }>;
+  [SyncEventTypes.SyncHealthChanged]: EventDefinition<typeof SyncEventTypes.SyncHealthChanged, SyncHealth>;
 };
 type SyncEventSystem = EventSystem<SyncEventTypeMap>;
 //#endregion
@@ -301,6 +303,41 @@ interface Sp00kyConfig<S extends SchemaStructure> {
    * one-shot but never sync live.
    */
   enableAnonymousLiveQueries?: boolean;
+  /**
+   * Surface sustained sync failures as a "degraded" health status that the app
+   * can observe via `subscribeToSyncHealth` (or the client-solid
+   * `useSyncStatus` hook) to render a "can't reach the server" banner.
+   *
+   * Individual failures — a transient remote 500 on query registration, a
+   * dropped WebSocket, etc. — are always swallowed and retried; they never
+   * throw at the app. This only controls when a *run* of consecutive failures
+   * is reported. Status flips back to `healthy` on the next successful sync
+   * round. Defaults to `{ degradeAfterConsecutiveFailures: 3 }`; pass `false`
+   * (or `degradeAfterConsecutiveFailures: 0`) to never report degraded.
+   */
+  syncHealth?: SyncHealthConfig | false;
+}
+/** Tunables for sync-health reporting. See {@link Sp00kyConfig.syncHealth}. */
+interface SyncHealthConfig {
+  /**
+   * Number of consecutive failed sync rounds (up or down) before the status
+   * flips from `healthy` to `degraded`. A single transient failure is absorbed
+   * by the retry; only a sustained run trips the banner. Defaults to `3`. `0`
+   * disables degraded reporting entirely.
+   */
+  degradeAfterConsecutiveFailures?: number;
+}
+type SyncHealthStatus = 'healthy' | 'degraded';
+/** Snapshot of sync health delivered to `subscribeToSyncHealth` subscribers. */
+interface SyncHealth {
+  /** `'degraded'` once consecutive failures cross the configured threshold. */
+  status: SyncHealthStatus;
+  /** Consecutive failed sync rounds at the moment of this report. */
+  consecutiveFailures: number;
+  /** Classification of the most recent failure (only set while `degraded`). */
+  kind?: 'network' | 'application';
+  /** Message of the most recent failure (only set while `degraded`). */
+  error?: string;
 }
 type QueryHash = string;
 type RecordVersionArray = Array<[string, number]>;
@@ -501,4 +538,4 @@ interface DebounceOptions {
   delay?: number;
 }
 //#endregion
-export { UpEvent as A, RunOptions as C, StoreType as D, Sp00kyQueryResultPromise as E, SyncEventSystem as M, EventDefinition as N, TimingPhase as O, EventSystem as P, RegistrationTimings as S, Sp00kyQueryResult as T, QueryTimeToLive as _, MutationCallback as a, RecordVersionArray as b, PersistenceClient as c, QueryConfig as d, QueryConfigRecord as f, QueryStatusCallback as g, QueryStatus as h, MATERIALIZATION_SAMPLE_WINDOW as i, Logger$1 as j, UpdateOptions as k, PhaseStat as l, QueryState as m, EventSubscriptionOptions as n, MutationEvent as o, QueryHash as p, Level$1 as r, MutationEventType as s, DebounceOptions as t, PinoTransmit as u, QueryTimings as v, Sp00kyConfig as w, RecordVersionDiff as x, QueryUpdateCallback as y };
+export { SyncHealthStatus as A, RunOptions as C, StoreType as D, Sp00kyQueryResultPromise as E, SyncEventSystem as F, EventDefinition as I, EventSystem as L, UpdateOptions as M, UpEvent as N, SyncHealth as O, Logger$1 as P, RegistrationTimings as S, Sp00kyQueryResult as T, QueryTimeToLive as _, MutationCallback as a, RecordVersionArray as b, PersistenceClient as c, QueryConfig as d, QueryConfigRecord as f, QueryStatusCallback as g, QueryStatus as h, MATERIALIZATION_SAMPLE_WINDOW as i, TimingPhase as j, SyncHealthConfig as k, PhaseStat as l, QueryState as m, EventSubscriptionOptions as n, MutationEvent as o, QueryHash as p, Level$1 as r, MutationEventType as s, DebounceOptions as t, PinoTransmit as u, QueryTimings as v, Sp00kyConfig as w, RecordVersionDiff as x, QueryUpdateCallback as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.84",
+  "version": "0.0.1-canary.85",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -59,8 +59,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.84",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.84",
+    "@spooky-sync/query-builder": "0.0.1-canary.85",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.85",
     "@surrealdb/wasm": "^3.0.3",
     "fast-json-patch": "^3.1.1",
     "loro-crdt": "^1.5.6",

package/src/modules/sync/events/index.ts

@@ -1,6 +1,6 @@
 import type { EventDefinition, EventSystem } from '../../../events/index';
 import { createEventSystem } from '../../../events/index';
-import type { RecordVersionArray } from '../../../types';
+import type { RecordVersionArray, SyncHealth } from '../../../types';
 
 export const SyncQueueEventTypes = {
   MutationEnqueued: 'MUTATION_ENQUEUED',
@@ -37,6 +37,7 @@ export const SyncEventTypes = {
   QueryUpdated: 'SYNC_QUERY_UPDATED',
   RemoteDataIngested: 'SYNC_REMOTE_DATA_INGESTED',
   MutationRolledBack: 'SYNC_MUTATION_ROLLED_BACK',
+  SyncHealthChanged: 'SYNC_HEALTH_CHANGED',
 } as const;
 
 export type SyncEventTypeMap = {
@@ -65,6 +66,10 @@ export type SyncEventTypeMap = {
       error: string;
     }
   >;
+  [SyncEventTypes.SyncHealthChanged]: EventDefinition<
+    typeof SyncEventTypes.SyncHealthChanged,
+    SyncHealth
+  >;
 };
 
 export type SyncEventSystem = EventSystem<SyncEventTypeMap>;
@@ -74,5 +79,6 @@ export function createSyncEventSystem(): SyncEventSystem {
     SyncEventTypes.QueryUpdated,
     SyncEventTypes.RemoteDataIngested,
     SyncEventTypes.MutationRolledBack,
+    SyncEventTypes.SyncHealthChanged,
   ]);
 }

package/src/modules/sync/scheduler.ts

@@ -16,7 +16,12 @@ export class SyncScheduler {
     private onProcessUp: (event: UpEvent) => Promise<void>,
     private onProcessDown: (event: DownEvent) => Promise<void>,
     private logger: Logger,
-    private onRollback?: RollbackCallback
+    private onRollback?: RollbackCallback,
+    // Reports the outcome of each drained sync round (one syncUp/syncDown pass
+    // that actually processed ≥1 item): `ok=true` on a clean drain, `ok=false`
+    // with the error when the round halted on a failure. Drives the consumer's
+    // sync-health tracking; empty/no-op rounds report nothing.
+    private onSyncOutcome?: (ok: boolean, error?: unknown) => void
   ) {}
 
   async init() {
@@ -50,10 +55,26 @@ export class SyncScheduler {
   async syncUp() {
     if (this.isSyncingUp) return;
     this.isSyncingUp = true;
+    let processedAny = false;
     try {
       while (this.upQueue.size > 0) {
         await this.upQueue.next(this.onProcessUp, this.onRollback);
+        processedAny = true;
       }
+      if (processedAny) this.onSyncOutcome?.(true);
+    } catch (error) {
+      this.onSyncOutcome?.(false, error);
+      // syncUp runs fire-and-forget — it's wired to the MutationEnqueued event
+      // (broadcast synchronously, return value dropped) and is also kicked off
+      // via `void this.syncDown()` below. A rejection escaping here therefore
+      // surfaces as an *unhandled promise rejection* in the console rather than
+      // anything a caller can catch. UpQueue.next already logs the failing item
+      // (and re-queues it for retry on the next trigger), so swallow here to
+      // keep the failure contained instead of leaking it globally.
+      this.logger.debug(
+        { error, Category: 'sp00ky-client::SyncScheduler::syncUp' },
+        'syncUp halted on a queue error; item re-queued, will retry on next trigger'
+      );
     } finally {
       this.isSyncingUp = false;
       void this.syncDown();
@@ -68,11 +89,27 @@ export class SyncScheduler {
     if (this.upQueue.size > 0) return;
 
     this.isSyncingDown = true;
+    let processedAny = false;
     try {
       while (this.downQueue.size > 0) {
         if (this.upQueue.size > 0) break;
         await this.downQueue.next(this.onProcessDown);
+        processedAny = true;
       }
+      if (processedAny) this.onSyncOutcome?.(true);
+    } catch (error) {
+      this.onSyncOutcome?.(false, error);
+      // Same fire-and-forget story as syncUp: this is the QueryItemEnqueued
+      // subscriber (and is also called via `void this.syncDown()`), so a thrown
+      // error here becomes an unhandled rejection. The canonical case is a
+      // transient remote 500 on `fn::query::register` — DownQueue.next logs it
+      // and re-queues the event at the head; we just stop draining this pass and
+      // let the next enqueue retry, without spamming the console with an
+      // "Uncaught (in promise) ... 500 Internal Server Error".
+      this.logger.debug(
+        { error, Category: 'sp00ky-client::SyncScheduler::syncDown' },
+        'syncDown halted on a queue error; item re-queued, will retry on next trigger'
+      );
     } finally {
       this.isSyncingDown = false;
     }

package/src/modules/sync/sync.ts

@@ -1,5 +1,5 @@
 import type { LocalDatabaseService, RemoteDatabaseService } from '../../services/database/index';
-import type { RecordVersionArray, RecordVersionDiff } 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';
@@ -20,7 +20,7 @@ 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 { 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';
 
 /**
@@ -40,6 +40,12 @@ export interface Sp00kySyncOptions {
    * Defaults to `false`.
    */
   anonymousLiveQueries?: boolean;
+  /**
+   * Consecutive failed sync rounds before sync health flips to `degraded`.
+   * `0` disables degraded reporting. See {@link Sp00kyConfig.syncHealth}.
+   * Defaults to `3`.
+   */
+  degradeAfterConsecutiveFailures?: number;
 }
 
 /**
@@ -154,6 +160,87 @@ export class Sp00kySync<S extends SchemaStructure> {
     };
   }
 
+  // ---- Sync health -------------------------------------------------------
+  // `0` disables degraded reporting (config `syncHealth: false`). Resolved
+  // from config in Sp00kyClient and passed through the constructor options.
+  private readonly degradeAfterFailures: number;
+  private consecutiveSyncFailures = 0;
+  private syncHealthStatus: SyncHealthStatus = 'healthy';
+  private lastSyncErrorKind: 'network' | 'application' | undefined;
+  private lastSyncErrorMessage: string | undefined;
+
+  /** Current sync-health snapshot. */
+  get syncHealth(): SyncHealth {
+    return {
+      status: this.syncHealthStatus,
+      consecutiveFailures: this.consecutiveSyncFailures,
+      kind: this.syncHealthStatus === 'degraded' ? this.lastSyncErrorKind : undefined,
+      error: this.syncHealthStatus === 'degraded' ? this.lastSyncErrorMessage : undefined,
+    };
+  }
+
+  /**
+   * Observe sync health. The callback fires immediately with the current
+   * status and again on every healthy↔degraded transition. Returns an
+   * unsubscribe. Mirrors {@link subscribeToPendingMutations}.
+   */
+  subscribeToSyncHealth(cb: (health: SyncHealth) => void): () => void {
+    cb(this.syncHealth);
+    const id = this.events.subscribe(SyncEventTypes.SyncHealthChanged, (event) =>
+      cb(event.payload)
+    );
+    return () => this.events.unsubscribe(id);
+  }
+
+  private emitSyncHealth(): void {
+    this.events.emit(SyncEventTypes.SyncHealthChanged, this.syncHealth);
+  }
+
+  /**
+   * Fed by the scheduler once per drained sync round. Individual failures are
+   * absorbed by the queue's retry; only a run of `degradeAfterFailures`
+   * consecutive failures flips the status to `degraded`, and the next clean
+   * round flips it back. No-op when reporting is disabled (`degradeAfterFailures`
+   * is 0).
+   */
+  private recordSyncOutcome(ok: boolean, error?: unknown): void {
+    if (this.degradeAfterFailures <= 0) return;
+    if (ok) {
+      if (this.consecutiveSyncFailures === 0) return;
+      this.consecutiveSyncFailures = 0;
+      if (this.syncHealthStatus !== 'healthy') {
+        this.syncHealthStatus = 'healthy';
+        this.lastSyncErrorKind = undefined;
+        this.lastSyncErrorMessage = undefined;
+        this.logger.info(
+          { Category: 'sp00ky-client::Sp00kySync::syncHealth' },
+          'Sync recovered; health back to healthy'
+        );
+        this.emitSyncHealth();
+      }
+      return;
+    }
+    this.consecutiveSyncFailures++;
+    this.lastSyncErrorKind = classifySyncError(error);
+    this.lastSyncErrorMessage = error instanceof Error ? error.message : String(error);
+    if (
+      this.syncHealthStatus !== 'degraded' &&
+      this.consecutiveSyncFailures >= this.degradeAfterFailures
+    ) {
+      this.syncHealthStatus = 'degraded';
+      this.logger.warn(
+        {
+          consecutiveFailures: this.consecutiveSyncFailures,
+          kind: this.lastSyncErrorKind,
+          error,
+          Category: 'sp00ky-client::Sp00kySync::syncHealth',
+        },
+        'Sync degraded after sustained failures'
+      );
+      this.emitSyncHealth();
+    }
+  }
+
   constructor(
     private local: LocalDatabaseService,
     private remote: RemoteDatabaseService,
@@ -173,10 +260,12 @@ export class Sp00kySync<S extends SchemaStructure> {
       this.processUpEvent.bind(this),
       this.processDownEvent.bind(this),
       this.logger,
-      this.handleRollback.bind(this)
+      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);
   }
 
   /**

package/src/sp00ky.ts

@@ -6,7 +6,8 @@ import type {
   Sp00kyQueryResultPromise,
   PersistenceClient,
   UpdateOptions,
-  RunOptions} from './types';
+  RunOptions,
+  SyncHealth} from './types';
 import {
   LocalDatabaseService,
   LocalMigrator,
@@ -128,6 +129,19 @@ export class Sp00kyClient<S extends SchemaStructure> {
     return this.sync.subscribeToPendingMutations(cb);
   }
 
+  /** Current sync-health snapshot. See {@link Sp00kyConfig.syncHealth}. */
+  get syncHealth(): SyncHealth {
+    return this.sync.syncHealth;
+  }
+
+  /**
+   * Observe sync health. Fires immediately with the current status and again
+   * on every healthy↔degraded transition. Returns an unsubscribe.
+   */
+  subscribeToSyncHealth(cb: (health: SyncHealth) => void): () => void {
+    return this.sync.subscribeToSyncHealth(cb);
+  }
+
   constructor(private config: Sp00kyConfig<S>) {
     const logger = createLogger(config.logLevel ?? 'info', config.otelTransmit);
     this.logger = logger.child({ service: 'Sp00kyClient' });
@@ -206,6 +220,12 @@ export class Sp00kyClient<S extends SchemaStructure> {
       {
         refSyncIntervalMs: this.config.refSyncIntervalMs,
         anonymousLiveQueries: this.config.enableAnonymousLiveQueries,
+        // `syncHealth: false` (or `{ degradeAfterConsecutiveFailures: 0 }`)
+        // disables degraded reporting; otherwise default to 3.
+        degradeAfterConsecutiveFailures:
+          this.config.syncHealth === false
+            ? 0
+            : this.config.syncHealth?.degradeAfterConsecutiveFailures ?? 3,
       }
     );
 

package/src/types.ts

@@ -153,6 +153,44 @@ export interface Sp00kyConfig<S extends SchemaStructure> {
    * one-shot but never sync live.
    */
   enableAnonymousLiveQueries?: boolean;
+  /**
+   * Surface sustained sync failures as a "degraded" health status that the app
+   * can observe via `subscribeToSyncHealth` (or the client-solid
+   * `useSyncStatus` hook) to render a "can't reach the server" banner.
+   *
+   * Individual failures — a transient remote 500 on query registration, a
+   * dropped WebSocket, etc. — are always swallowed and retried; they never
+   * throw at the app. This only controls when a *run* of consecutive failures
+   * is reported. Status flips back to `healthy` on the next successful sync
+   * round. Defaults to `{ degradeAfterConsecutiveFailures: 3 }`; pass `false`
+   * (or `degradeAfterConsecutiveFailures: 0`) to never report degraded.
+   */
+  syncHealth?: SyncHealthConfig | false;
+}
+
+/** Tunables for sync-health reporting. See {@link Sp00kyConfig.syncHealth}. */
+export interface SyncHealthConfig {
+  /**
+   * Number of consecutive failed sync rounds (up or down) before the status
+   * flips from `healthy` to `degraded`. A single transient failure is absorbed
+   * by the retry; only a sustained run trips the banner. Defaults to `3`. `0`
+   * disables degraded reporting entirely.
+   */
+  degradeAfterConsecutiveFailures?: number;
+}
+
+export type SyncHealthStatus = 'healthy' | 'degraded';
+
+/** Snapshot of sync health delivered to `subscribeToSyncHealth` subscribers. */
+export interface SyncHealth {
+  /** `'degraded'` once consecutive failures cross the configured threshold. */
+  status: SyncHealthStatus;
+  /** Consecutive failed sync rounds at the moment of this report. */
+  consecutiveFailures: number;
+  /** Classification of the most recent failure (only set while `degraded`). */
+  kind?: 'network' | 'application';
+  /** Message of the most recent failure (only set while `degraded`). */
+  error?: string;
 }
 
 export type QueryHash = string;