@syncular/client 0.27.0 → 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

@@ -25,13 +25,17 @@ export declare 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. The query returns to
- * waiting when the next attempt starts.
+ * 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;
-    constructor(code: string, 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

package/dist/errors.js

@@ -28,15 +28,20 @@ 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. The query returns to
- * waiting when the next attempt starts.
+ * 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;
-    constructor(code, attempt) {
-        super(code, 'the sync round failed before the query coverage completed');
+    retryDelayMs;
+    constructor(code, attempt, retryDelayMs) {
+        super(code, 'the sync round failed before the query coverage completed', retryDelayMs !== undefined);
         this.attempt = attempt;
+        this.retryDelayMs = retryDelayMs;
     }
 }
 /**

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.js

@@ -976,7 +976,7 @@ export class ReactiveClientStore {
         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));
+                roundFailure.set(new SyncRoundFailedError(progress.errorCode ?? 'client.unknown_failure', progress.attempt, progress.retryDelayMs));
             else if (progress.state !== 'failed' &&
                 current !== undefined &&
                 progress.attempt !== current.attempt)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.27.0",
+  "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.27.0"
+    "@syncular/core": "0.28.0"
   },
   "devDependencies": {
-    "@syncular/server": "0.27.0",
+    "@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

@@ -38,16 +38,25 @@ 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. The query returns to
- * waiting when the next attempt starts.
+ * 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) {
-    super(code, 'the sync round failed before the query coverage completed');
+  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;
   }
 }
 

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

@@ -1156,6 +1156,7 @@ export class ReactiveClientStore {
           new SyncRoundFailedError(
             progress.errorCode ?? 'client.unknown_failure',
             progress.attempt,
+            progress.retryDelayMs,
           ),
         );
       else if (