@syncular/client 0.26.6 → 0.28.0

package/dist/client.js

@@ -176,6 +176,7 @@ export class SyncClient {
     #localResetEpoch = 0;
     /** Retry policy belongs to the operation that classified the failure. */
     #retryDelayMs = 250;
+    #roundRetryDelayMs;
     #hasBlobs;
     /** §8.6 presence: scopeKey → (peerKey `actorId clientId` → peer). */
     #presence = new Map();
@@ -2334,6 +2335,9 @@ export class SyncClient {
                 errorCode: typeof code === 'string'
                     ? this.#diagnosticCode(code)
                     : 'client.unknown_failure',
+                ...(this.#roundRetryDelayMs !== undefined
+                    ? { retryDelayMs: this.#roundRetryDelayMs }
+                    : {}),
             });
             this.#lastRound = {
                 status: 'failed',
@@ -2381,6 +2385,7 @@ export class SyncClient {
             : 'client.unknown_failure';
     }
     async #runSync() {
+        this.#roundRetryDelayMs = undefined;
         this.#progress.emit({
             attempt: ++this.#progressAttempt,
             state: 'running',
@@ -2508,6 +2513,7 @@ export class SyncClient {
                     delayMs: delay,
                 };
                 this.#retryDelayMs = Math.min(this.#retryDelayMs * 2, 30_000);
+                this.#roundRetryDelayMs = delay;
                 this.#emitSyncIntent(intent);
             }
             throw error;

package/dist/errors.d.ts

@@ -22,6 +22,21 @@ export declare class ClientSyncError extends Error {
     readonly retryable: boolean;
     constructor(code: string, message: string, retryable?: boolean);
 }
+/**
+ * SPEC §7.5: the latest sync attempt failed while a live query still waited
+ * for its required coverage. `code` is the attempt's static progress error
+ * code; `attempt` is the progress attempt that failed. `retryable` is true when
+ * the client scheduled a background retry for the attempt, and `retryDelayMs`
+ * is that retry's delay from the failure; a non-retryable failure has no
+ * delay and no automatic next attempt. The query returns to waiting when the
+ * next attempt starts.
+ */
+export declare class SyncRoundFailedError extends ClientSyncError {
+    readonly name = "SyncRoundFailedError";
+    readonly attempt: number;
+    readonly retryDelayMs: number | undefined;
+    constructor(code: string, attempt: number, retryDelayMs: number | undefined);
+}
 /**
  * SPEC §8.8: the `required` realtime policy refused a round because the
  * socket is not connected. `state` is the availability state that refused

package/dist/errors.js

@@ -25,6 +25,25 @@ export class ClientSyncError extends Error {
         this.retryable = retryable;
     }
 }
+/**
+ * SPEC §7.5: the latest sync attempt failed while a live query still waited
+ * for its required coverage. `code` is the attempt's static progress error
+ * code; `attempt` is the progress attempt that failed. `retryable` is true when
+ * the client scheduled a background retry for the attempt, and `retryDelayMs`
+ * is that retry's delay from the failure; a non-retryable failure has no
+ * delay and no automatic next attempt. The query returns to waiting when the
+ * next attempt starts.
+ */
+export class SyncRoundFailedError extends ClientSyncError {
+    name = 'SyncRoundFailedError';
+    attempt;
+    retryDelayMs;
+    constructor(code, attempt, retryDelayMs) {
+        super(code, 'the sync round failed before the query coverage completed', retryDelayMs !== undefined);
+        this.attempt = attempt;
+        this.retryDelayMs = retryDelayMs;
+    }
+}
 /**
  * SPEC §8.8: the `required` realtime policy refused a round because the
  * socket is not connected. `state` is the availability state that refused

package/dist/progress.d.ts

@@ -11,6 +11,8 @@ export interface SyncProgress {
     readonly rowsProcessed: number;
     readonly rowsTotal?: number;
     readonly errorCode?: string;
+    /** Present on `failed` when the core scheduled a background retry. */
+    readonly retryDelayMs?: number;
 }
 export type SyncProgressListener = (progress: SyncProgress) => void;
 /** Shared by the direct client and event-forwarding handles. */

package/dist/reactive-store.d.ts

@@ -1,8 +1,10 @@
 import { type SyncAvailability } from './availability.js';
 import type { CommitOutcome, ClientSnapshotReader, QueryReadSpec, QuerySnapshot, WindowCoverage, WindowState } from './client.js';
 import type { SqlValue } from './database.js';
+import { SyncRoundFailedError } from './errors.js';
 import type { ClientChangeListener, SyncStatusSnapshot } from './invalidation.js';
 import type { LeadershipState } from './multi-tab.js';
+import type { SyncProgressListener } from './progress.js';
 import { type WindowBase } from './window.js';
 export interface QueryDependency {
     readonly table: string;
@@ -33,6 +35,7 @@ export interface ReactiveQueryClient extends Pick<ClientSnapshotReader, 'statusS
     querySnapshot<Row = Record<string, SqlValue>>(spec: QueryReadSpec): QuerySnapshot<Row> | Promise<QuerySnapshot<Row>>;
     leadershipSnapshot?(): LeadershipState | undefined;
     onLeadershipChange?(listener: (state: LeadershipState) => void): () => void;
+    onProgress(listener: SyncProgressListener): () => void;
     conflicts(): readonly unknown[] | Promise<readonly unknown[]>;
     rejections(): readonly unknown[] | Promise<readonly unknown[]>;
     setWindow(base: WindowBase, units: readonly string[]): void | Promise<void>;
@@ -74,6 +77,8 @@ export declare class ReactiveClientStore {
     readonly status: ExternalStoreEntry<StatusStoreSnapshot>;
     readonly conflicts: ExternalStoreEntry<ConflictStoreSnapshot>;
     readonly outcomes: ExternalStoreEntry<OutcomeStoreSnapshot>;
+    /** The latest sync attempt's failure until the next attempt starts. */
+    readonly roundFailure: ExternalStoreEntry<SyncRoundFailedError | undefined>;
     constructor(client: ReactiveQueryClient);
     query<Row>(spec: ReactiveQuerySpec<Row>): ExternalStoreEntry<LiveQueryResult<Row>>;
     availabilitySnapshot(): SyncAvailability;

package/dist/reactive-store.js

@@ -1,5 +1,5 @@
 import { classifySyncAvailability, } from './availability.js';
-import { ClientSyncError } from './errors.js';
+import { ClientSyncError, SyncRoundFailedError } from './errors.js';
 import { windowBaseKey } from './window.js';
 function errorOf(value) {
     return value instanceof Error ? value : new Error(String(value));
@@ -280,6 +280,7 @@ class QueryEntry {
     #claimError;
     #claimPending = false;
     #offStatus;
+    #offRound;
     constructor(store, spec, key, cache) {
         this.store = store;
         this.spec = spec;
@@ -298,6 +299,7 @@ class QueryEntry {
         this.#listeners.add(notify);
         if (this.#listeners.size === 1) {
             this.#offStatus = this.store.status.subscribe(() => this.#onAvailabilityChange());
+            this.#offRound = this.store.roundFailure.subscribe(() => this.#onRoundFailureChange());
             this.#onAvailabilityChange();
             if (this.spec.claimCoverage !== false) {
                 const claims = [];
@@ -349,6 +351,8 @@ class QueryEntry {
                 this.cache.deactivate(this.key, this);
                 this.#offStatus?.();
                 this.#offStatus = undefined;
+                this.#offRound?.();
+                this.#offRound = undefined;
                 this.store.releaseWindowClaims(this.#owner);
             }
         };
@@ -373,6 +377,8 @@ class QueryEntry {
         this.#listeners.clear();
         this.#offStatus?.();
         this.#offStatus = undefined;
+        this.#offRound?.();
+        this.#offRound = undefined;
         this.store.releaseWindowClaims(this.#owner);
         this.reset();
     }
@@ -448,6 +454,30 @@ class QueryEntry {
         if (wasBlocked)
             this.#requestRead();
     }
+    /** SPEC §7.5 failed transfer: incomplete coverage stops waiting on a failed
+     * sync attempt and resumes waiting when the next attempt starts. */
+    #onRoundFailureChange() {
+        const failure = this.store.roundFailure.getSnapshot();
+        if (failure !== undefined) {
+            if (this.#state.phase === 'loading' || this.#state.phase === 'partial')
+                this.#publish({
+                    ...this.#state,
+                    phase: 'error',
+                    error: failure,
+                    isRefreshing: false,
+                });
+            return;
+        }
+        if (this.#state.phase === 'error' &&
+            this.#state.error instanceof SyncRoundFailedError) {
+            this.#publish({
+                ...this.#state,
+                phase: this.#state.rows.length > 0 ? 'partial' : 'loading',
+                error: undefined,
+            });
+            this.#requestRead();
+        }
+    }
     async #readLoop() {
         if (this.#running || this.#listeners.size === 0)
             return;
@@ -502,16 +532,21 @@ class QueryEntry {
                     ? snapshot.rows
                     : snapshot.rows.map(this.spec.mapRow);
                 const rows = reconcileRows(this.#state.rows, mappedRows, this.spec.rowKey);
+                const roundFailure = snapshot.coverage.complete
+                    ? undefined
+                    : this.store.roundFailure.getSnapshot();
                 const phase = snapshot.coverage.complete
                     ? 'ready'
-                    : rows.length > 0
-                        ? 'partial'
-                        : 'loading';
+                    : roundFailure !== undefined
+                        ? 'error'
+                        : rows.length > 0
+                            ? 'partial'
+                            : 'loading';
                 this.#publish({
                     rows,
                     phase,
                     revision: snapshot.revision,
-                    error: undefined,
+                    error: roundFailure,
                     isRefreshing: false,
                     availability,
                 });
@@ -675,6 +710,9 @@ export class ReactiveClientStore {
     status;
     conflicts;
     outcomes;
+    /** The latest sync attempt's failure until the next attempt starts. */
+    roundFailure;
+    #offProgress;
     constructor(client) {
         this.client = client;
         const status = new ValueEntry({
@@ -737,6 +775,8 @@ export class ReactiveClientStore {
         this.status = status;
         this.conflicts = conflicts;
         this.outcomes = outcomes;
+        const roundFailure = new ValueEntry(undefined, async () => roundFailure.getSnapshot());
+        this.roundFailure = roundFailure;
         this.start();
     }
     query(spec) {
@@ -932,6 +972,16 @@ export class ReactiveClientStore {
             if (batch.outcomesChanged)
                 this.outcomes.refresh();
         });
+        const roundFailure = this.roundFailure;
+        this.#offProgress = this.client.onProgress((progress) => {
+            const current = roundFailure.getSnapshot();
+            if (progress.state === 'failed' && current?.attempt !== progress.attempt)
+                roundFailure.set(new SyncRoundFailedError(progress.errorCode ?? 'client.unknown_failure', progress.attempt, progress.retryDelayMs));
+            else if (progress.state !== 'failed' &&
+                current !== undefined &&
+                progress.attempt !== current.attempt)
+                roundFailure.set(undefined);
+        });
         this.#offLeadership = this.client.onLeadershipChange?.((leadership) => {
             const previous = this.status.getSnapshot();
             this.status.set({
@@ -955,6 +1005,9 @@ export class ReactiveClientStore {
         this.#offChange = undefined;
         this.#offLeadership?.();
         this.#offLeadership = undefined;
+        this.#offProgress?.();
+        this.#offProgress = undefined;
+        this.roundFailure.set(undefined);
         for (const group of this.#windowClaims.values()) {
             for (const waiter of group.waiters.splice(0)) {
                 waiter.reject(new ClientSyncError('client.reactive_store_disposed', 'reactive store disposed'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.26.6",
+  "version": "0.28.0",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -89,10 +89,10 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.26.6"
+    "@syncular/core": "0.28.0"
   },
   "devDependencies": {
-    "@syncular/server": "0.26.6",
+    "@syncular/server": "0.28.0",
     "playwright": "1.63.0"
   }
 }

package/src/client.ts

@@ -779,6 +779,7 @@ export class SyncClient {
   #localResetEpoch = 0;
   /** Retry policy belongs to the operation that classified the failure. */
   #retryDelayMs = 250;
+  #roundRetryDelayMs: number | undefined;
   readonly #hasBlobs: boolean;
   /** §8.6 presence: scopeKey → (peerKey `actorId clientId` → peer). */
   readonly #presence = new Map<string, Map<string, PresencePeer>>();
@@ -3399,6 +3400,9 @@ export class SyncClient {
               typeof code === 'string'
                 ? this.#diagnosticCode(code)
                 : 'client.unknown_failure',
+            ...(this.#roundRetryDelayMs !== undefined
+              ? { retryDelayMs: this.#roundRetryDelayMs }
+              : {}),
           });
           this.#lastRound = {
             status: 'failed',
@@ -3454,6 +3458,7 @@ export class SyncClient {
   }
 
   async #runSync(): Promise<SyncSummary> {
+    this.#roundRetryDelayMs = undefined;
     this.#progress.emit({
       attempt: ++this.#progressAttempt,
       state: 'running',
@@ -3601,6 +3606,7 @@ export class SyncClient {
           delayMs: delay,
         };
         this.#retryDelayMs = Math.min(this.#retryDelayMs * 2, 30_000);
+        this.#roundRetryDelayMs = delay;
         this.#emitSyncIntent(intent);
       }
       throw error;

package/src/errors.ts

@@ -35,6 +35,31 @@ export class ClientSyncError extends Error {
   }
 }
 
+/**
+ * SPEC §7.5: the latest sync attempt failed while a live query still waited
+ * for its required coverage. `code` is the attempt's static progress error
+ * code; `attempt` is the progress attempt that failed. `retryable` is true when
+ * the client scheduled a background retry for the attempt, and `retryDelayMs`
+ * is that retry's delay from the failure; a non-retryable failure has no
+ * delay and no automatic next attempt. The query returns to waiting when the
+ * next attempt starts.
+ */
+export class SyncRoundFailedError extends ClientSyncError {
+  override readonly name = 'SyncRoundFailedError';
+  readonly attempt: number;
+  readonly retryDelayMs: number | undefined;
+
+  constructor(code: string, attempt: number, retryDelayMs: number | undefined) {
+    super(
+      code,
+      'the sync round failed before the query coverage completed',
+      retryDelayMs !== undefined,
+    );
+    this.attempt = attempt;
+    this.retryDelayMs = retryDelayMs;
+  }
+}
+
 /**
  * SPEC §8.8: the `required` realtime policy refused a round because the
  * socket is not connected. `state` is the availability state that refused

package/src/progress.ts

@@ -11,6 +11,8 @@ export interface SyncProgress {
   readonly rowsProcessed: number;
   readonly rowsTotal?: number;
   readonly errorCode?: string;
+  /** Present on `failed` when the core scheduled a background retry. */
+  readonly retryDelayMs?: number;
 }
 
 export type SyncProgressListener = (progress: SyncProgress) => void;

package/src/reactive-store.ts

@@ -11,13 +11,14 @@ import type {
   WindowState,
 } from './client';
 import type { SqlValue } from './database';
-import { ClientSyncError } from './errors';
+import { ClientSyncError, SyncRoundFailedError } from './errors';
 import type {
   ClientChangeBatch,
   ClientChangeListener,
   SyncStatusSnapshot,
 } from './invalidation';
 import type { LeadershipState } from './multi-tab';
+import type { SyncProgressListener } from './progress';
 import { type WindowBase, windowBaseKey } from './window';
 
 export interface QueryDependency {
@@ -63,6 +64,7 @@ export interface ReactiveQueryClient extends Pick<
   ): QuerySnapshot<Row> | Promise<QuerySnapshot<Row>>;
   leadershipSnapshot?(): LeadershipState | undefined;
   onLeadershipChange?(listener: (state: LeadershipState) => void): () => void;
+  onProgress(listener: SyncProgressListener): () => void;
   conflicts(): readonly unknown[] | Promise<readonly unknown[]>;
   rejections(): readonly unknown[] | Promise<readonly unknown[]>;
   setWindow(base: WindowBase, units: readonly string[]): void | Promise<void>;
@@ -401,6 +403,7 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
   #claimError: Error | undefined;
   #claimPending = false;
   #offStatus: (() => void) | undefined;
+  #offRound: (() => void) | undefined;
 
   constructor(
     readonly store: ReactiveClientStore,
@@ -425,6 +428,9 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
       this.#offStatus = this.store.status.subscribe(() =>
         this.#onAvailabilityChange(),
       );
+      this.#offRound = this.store.roundFailure.subscribe(() =>
+        this.#onRoundFailureChange(),
+      );
       this.#onAvailabilityChange();
       if (this.spec.claimCoverage !== false) {
         const claims: Promise<void>[] = [];
@@ -479,6 +485,8 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
         this.cache.deactivate(this.key, this);
         this.#offStatus?.();
         this.#offStatus = undefined;
+        this.#offRound?.();
+        this.#offRound = undefined;
         this.store.releaseWindowClaims(this.#owner);
       }
     };
@@ -504,6 +512,8 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
     this.#listeners.clear();
     this.#offStatus?.();
     this.#offStatus = undefined;
+    this.#offRound?.();
+    this.#offRound = undefined;
     this.store.releaseWindowClaims(this.#owner);
     this.reset();
   }
@@ -581,6 +591,33 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
     if (wasBlocked) this.#requestRead();
   }
 
+  /** SPEC §7.5 failed transfer: incomplete coverage stops waiting on a failed
+   * sync attempt and resumes waiting when the next attempt starts. */
+  #onRoundFailureChange(): void {
+    const failure = this.store.roundFailure.getSnapshot();
+    if (failure !== undefined) {
+      if (this.#state.phase === 'loading' || this.#state.phase === 'partial')
+        this.#publish({
+          ...this.#state,
+          phase: 'error',
+          error: failure,
+          isRefreshing: false,
+        });
+      return;
+    }
+    if (
+      this.#state.phase === 'error' &&
+      this.#state.error instanceof SyncRoundFailedError
+    ) {
+      this.#publish({
+        ...this.#state,
+        phase: this.#state.rows.length > 0 ? 'partial' : 'loading',
+        error: undefined,
+      });
+      this.#requestRead();
+    }
+  }
+
   async #readLoop(): Promise<void> {
     if (this.#running || this.#listeners.size === 0) return;
     const generation = this.#generation;
@@ -643,16 +680,21 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
           mappedRows,
           this.spec.rowKey,
         );
+        const roundFailure = snapshot.coverage.complete
+          ? undefined
+          : this.store.roundFailure.getSnapshot();
         const phase: LiveQueryPhase = snapshot.coverage.complete
           ? 'ready'
-          : rows.length > 0
-            ? 'partial'
-            : 'loading';
+          : roundFailure !== undefined
+            ? 'error'
+            : rows.length > 0
+              ? 'partial'
+              : 'loading';
         this.#publish({
           rows,
           phase,
           revision: snapshot.revision,
-          error: undefined,
+          error: roundFailure,
           isRefreshing: false,
           availability,
         });
@@ -819,6 +861,9 @@ export class ReactiveClientStore {
   readonly status: ExternalStoreEntry<StatusStoreSnapshot>;
   readonly conflicts: ExternalStoreEntry<ConflictStoreSnapshot>;
   readonly outcomes: ExternalStoreEntry<OutcomeStoreSnapshot>;
+  /** The latest sync attempt's failure until the next attempt starts. */
+  readonly roundFailure: ExternalStoreEntry<SyncRoundFailedError | undefined>;
+  #offProgress: (() => void) | undefined;
 
   constructor(readonly client: ReactiveQueryClient) {
     const status = new ValueEntry<StatusStoreSnapshot>(
@@ -887,6 +932,13 @@ export class ReactiveClientStore {
     this.status = status;
     this.conflicts = conflicts;
     this.outcomes = outcomes;
+    const roundFailure: ValueEntry<SyncRoundFailedError | undefined> =
+      new ValueEntry<SyncRoundFailedError | undefined>(
+        undefined,
+        async (): Promise<SyncRoundFailedError | undefined> =>
+          roundFailure.getSnapshot(),
+      );
+    this.roundFailure = roundFailure;
     this.start();
   }
 
@@ -1094,6 +1146,26 @@ export class ReactiveClientStore {
       }
       if (batch.outcomesChanged) this.outcomes.refresh();
     });
+    const roundFailure = this.roundFailure as ValueEntry<
+      SyncRoundFailedError | undefined
+    >;
+    this.#offProgress = this.client.onProgress((progress) => {
+      const current = roundFailure.getSnapshot();
+      if (progress.state === 'failed' && current?.attempt !== progress.attempt)
+        roundFailure.set(
+          new SyncRoundFailedError(
+            progress.errorCode ?? 'client.unknown_failure',
+            progress.attempt,
+            progress.retryDelayMs,
+          ),
+        );
+      else if (
+        progress.state !== 'failed' &&
+        current !== undefined &&
+        progress.attempt !== current.attempt
+      )
+        roundFailure.set(undefined);
+    });
     this.#offLeadership = this.client.onLeadershipChange?.((leadership) => {
       const previous = this.status.getSnapshot();
       (this.status as ValueEntry<StatusStoreSnapshot>).set({
@@ -1117,6 +1189,11 @@ export class ReactiveClientStore {
     this.#offChange = undefined;
     this.#offLeadership?.();
     this.#offLeadership = undefined;
+    this.#offProgress?.();
+    this.#offProgress = undefined;
+    (this.roundFailure as ValueEntry<SyncRoundFailedError | undefined>).set(
+      undefined,
+    );
     for (const group of this.#windowClaims.values()) {
       for (const waiter of group.waiters.splice(0)) {
         waiter.reject(