@pol-studios/powersync 1.0.24 → 1.0.30

package/dist/provider/index.d.ts

@@ -1,15 +1,15 @@
 import { SupabaseClient } from '@supabase/supabase-js';
 import { QueryClient } from '@tanstack/react-query';
-import { A as AbstractPowerSyncDatabase, a as SyncStatus, C as CrudEntry, S as SyncMode, F as FailedTransaction, h as CompletedTransaction, b as ConnectionHealth, e as SyncMetrics, D as DownloadProgress, E as EntitySyncState, f as SyncError } from '../types-CDqWh56B.js';
+import { A as AbstractPowerSyncDatabase, a as SyncStatus, C as CrudEntry, S as SyncMode, F as FailedTransaction, h as CompletedTransaction, b as ConnectionHealth, e as SyncMetrics, D as DownloadProgress, E as EntitySyncState, f as SyncError, U as UploadBlockReason } from '../types-Dv1uf0LZ.js';
 import { PlatformAdapter } from '../platform/index.js';
-import { a as ConnectorConfig, i as ConflictBus } from '../types-DiBvmGEi.js';
+import { a as ConnectorConfig, i as ConflictBus } from '../types-CpM2_LhU.js';
 import { f as AttachmentConfig, P as PolAttachmentQueue, A as AttachmentSourceConfig, F as AttachmentRecord, C as CompressionConfig, j as DownloadConfig } from '../pol-attachment-queue-BE2HU3Us.js';
-import { S as SupabaseConnector } from '../supabase-connector-D2oIl2t8.js';
+import { S as SupabaseConnector } from '../supabase-connector-C4YpH_l3.js';
 import * as react from 'react';
 import react__default, { ReactNode } from 'react';
 import { Schema } from '@powersync/react-native';
 import { a as StorageBackend } from '../types-D0WcHrq6.js';
-import { h as BackgroundSyncSystem, c as SyncControlActions } from '../background-sync-ChCXW-EV.js';
+import { h as BackgroundSyncSystem, c as SyncControlActions } from '../background-sync-CVR3PkFi.js';
 import '@powersync/attachments';
 import '@powersync/common';
 
@@ -232,10 +232,6 @@ interface SyncStatusContextValue {
      * Clear a specific failure by its ID.
      */
     clearFailure: (failureId: string) => void;
-    /**
-     * Clear all failures.
-     */
-    clearAllFailures: () => void;
     /**
      * Completed transactions history.
      */
@@ -261,20 +257,31 @@ interface SyncStatusContextValue {
      */
     discardPendingMutation: (clientId: number) => Promise<void>;
     /**
-     * Discard all pending mutations.
-     * Uses safe disconnect/reconnect pattern to avoid transaction conflicts.
-     * @throws Error if upload is in progress
+     * Whether we're currently waiting for a retry after upload failure.
+     */
+    isWaitingForUploadRetry: boolean;
+    /**
+     * When the next retry will occur (null if not waiting).
+     */
+    nextUploadRetryAt: Date | null;
+    /**
+     * Whether the maximum retry attempts have been reached.
+     */
+    maxUploadRetriesReached: boolean;
+    /**
+     * Current retry attempt count.
      */
-    discardAllPendingMutations: () => Promise<void>;
+    uploadRetryCount: number;
     /**
-     * Pause automatic retry of failed uploads.
-     * Useful when user is actively resolving conflicts.
+     * Force a manual retry after max retries reached.
      */
-    pauseAutoRetry: () => void;
+    manualUploadRetry: () => Promise<void>;
     /**
-     * Resume automatic retry of failed uploads.
+     * Discard a specific failed entry by its ps_crud ID and reconnect.
+     * Use this when a single entry is causing upload failures.
+     * @param entryId - The ps_crud entry ID (clientId) to discard
      */
-    resumeAutoRetry: () => void;
+    discardFailedEntryAndReconnect: (entryId: number) => Promise<void>;
 }
 /**
  * Connection state - changes rarely (on connect/disconnect).
@@ -315,8 +322,6 @@ interface PendingMutationsContextValue {
     pendingCount: number;
     /** Discard a specific pending mutation by its client ID */
     discardPendingMutation: (clientId: number) => Promise<void>;
-    /** Discard all pending mutations */
-    discardAllPendingMutations: () => Promise<void>;
     /**
      * Add a pending mutation to the list.
      * Called by mutation hooks (useDbInsert, useDbUpdate, useDbDelete, useDbUpsert)
@@ -342,12 +347,6 @@ interface FailedTransactionsContextValue {
     permanentErrorCount: number;
     /** Clear a specific failure by its ID */
     clearFailure: (failureId: string) => void;
-    /** Clear all failures */
-    clearAllFailures: () => void;
-    /** Pause automatic retry of failed uploads */
-    pauseAutoRetry: () => void;
-    /** Resume automatic retry of failed uploads */
-    resumeAutoRetry: () => void;
     /**
      * Retry a specific failed transaction.
      *
@@ -405,6 +404,36 @@ interface SyncModeContextValue {
     setSyncMode: (mode: SyncMode) => Promise<void>;
     /** Set the force next upload flag */
     setForceNextUpload: (force: boolean) => void;
+    /**
+     * Whether we're currently waiting for a retry after upload failure.
+     * When true, PowerSync is disconnected and waiting for the backoff timer.
+     */
+    isWaitingForUploadRetry: boolean;
+    /**
+     * When the next retry will occur (null if not waiting).
+     * Use this to display a countdown to the user.
+     */
+    nextUploadRetryAt: Date | null;
+    /**
+     * Whether the maximum retry attempts have been reached.
+     * When true, the system won't automatically retry - user must intervene.
+     */
+    maxUploadRetriesReached: boolean;
+    /**
+     * Current retry attempt count (0 when no retries have occurred).
+     */
+    uploadRetryCount: number;
+    /**
+     * Force a manual retry after max retries reached.
+     * Resets retry state and attempts to reconnect.
+     */
+    manualUploadRetry: () => Promise<void>;
+    /**
+     * Discard a specific failed entry by its ps_crud ID and reconnect.
+     * Use this when a single entry is causing upload failures.
+     * @param entryId - The ps_crud entry ID (clientId) to discard
+     */
+    discardFailedEntryAndReconnect: (entryId: number) => Promise<void>;
 }
 /**
  * Value provided by ConnectionHealthContext.
@@ -1164,6 +1193,58 @@ declare function useSyncMode(): {
     canDownload: boolean;
     networkReachable: boolean;
 };
+/**
+ * Hook to access upload retry state for exponential backoff handling.
+ *
+ * When an upload fails, the provider disconnects and waits with exponential backoff
+ * before reconnecting. After 7 failed attempts (256s backoff), it stays disconnected
+ * and lets the user decide.
+ *
+ * @returns Upload retry state and control functions
+ * @throws Error if used outside of PowerSyncProvider
+ *
+ * @example
+ * ```typescript
+ * function UploadRetryBanner() {
+ *   const {
+ *     isWaiting,
+ *     nextRetryAt,
+ *     maxRetriesReached,
+ *     retryCount,
+ *     manualRetry,
+ *     discardAndReconnect,
+ *   } = useUploadRetry();
+ *
+ *   if (maxRetriesReached) {
+ *     return (
+ *       <View>
+ *         <Text>Upload failed after {retryCount} attempts</Text>
+ *         <Button onPress={manualRetry}>Try Again</Button>
+ *         <Button onPress={discardAndReconnect}>Discard Changes</Button>
+ *       </View>
+ *     );
+ *   }
+ *
+ *   if (isWaiting && nextRetryAt) {
+ *     return (
+ *       <View>
+ *         <Text>Retrying in {Math.ceil((nextRetryAt.getTime() - Date.now()) / 1000)}s</Text>
+ *       </View>
+ *     );
+ *   }
+ *
+ *   return null;
+ * }
+ * ```
+ */
+declare function useUploadRetry(): {
+    isWaiting: boolean;
+    nextRetryAt: Date | null;
+    maxRetriesReached: boolean;
+    retryCount: number;
+    manualRetry: () => Promise<void>;
+    discardEntryAndReconnect: (entryId: number) => Promise<void>;
+};
 /**
  * Hook to access connection health status.
  *
@@ -1469,8 +1550,8 @@ interface UploadStatusResult {
     failedTransactions: FailedTransaction[];
     /** Trigger sync retry (reconnect) */
     retryAll: () => Promise<void>;
-    /** Dismiss all failures */
-    dismissAll: () => void;
+    /** Dismiss a specific failure by its ID */
+    dismissFailure: (failureId: string) => void;
 }
 /**
  * Hook to get overall upload status across all entities.
@@ -1559,5 +1640,84 @@ declare const useFailedTransactions: typeof useFailedTransactionsContext;
  * Alias for useCompletedTransactionsContext.
  */
 declare const useCompletedTransactions: typeof useCompletedTransactionsContext;
+/**
+ * Return type for useUploadBlockedReason hook.
+ */
+interface UploadBlockedReasonResult {
+    /** Whether uploads are currently blocked */
+    isBlocked: boolean;
+    /** The reason uploads are blocked */
+    reason: UploadBlockReason;
+    /** Human-readable description of why uploads are blocked */
+    description: string | null;
+    /** Whether an upload is actively in progress */
+    isUploading: boolean;
+}
+/**
+ * Hook to get why uploads are blocked.
+ * Derives block reason from existing sync mode, network, and connection state.
+ *
+ * @returns Upload blocked status with reason and description
+ *
+ * @example
+ * ```typescript
+ * function UploadBlockedBanner() {
+ *   const { isBlocked, reason, description } = useUploadBlockedReason();
+ *
+ *   if (!isBlocked) return null;
+ *
+ *   return <Banner>{description}</Banner>;
+ * }
+ * ```
+ */
+declare function useUploadBlockedReason(): UploadBlockedReasonResult;
+/**
+ * Return type for useRetryCountdown hook.
+ */
+interface RetryCountdownResult {
+    /** The soonest next retry time from all failed transactions */
+    nextRetryAt: Date | null;
+    /** Milliseconds until the next retry (0 if already past) */
+    timeUntilRetryMs: number;
+    /** Formatted countdown string (e.g., "5s", "1m 30s", "2m") or null if no retry scheduled */
+    formattedCountdown: string | null;
+}
+/**
+ * Hook for retry countdown display.
+ * Returns the soonest nextRetryAt from all failed transactions.
+ * Re-renders every second when countdown is active.
+ *
+ * @returns Retry countdown information
+ *
+ * @example
+ * ```typescript
+ * function RetryTimer() {
+ *   const { nextRetryAt, formattedCountdown } = useRetryCountdown();
+ *
+ *   if (!nextRetryAt) return null;
+ *
+ *   return <Text>Retrying in {formattedCountdown}</Text>;
+ * }
+ * ```
+ */
+declare function useRetryCountdown(): RetryCountdownResult;
+
+/**
+ * Provider Constants for @pol-studios/powersync
+ *
+ * Exports constants used in the provider that may need to be accessed by UI components.
+ */
+/**
+ * Maximum number of upload retry attempts before stopping automatic retries.
+ * After this many attempts, the user must manually retry or discard the failed entries.
+ *
+ * Backoff delays: 4s, 8s, 16s, 32s, 64s, 128s, 256s (total: ~8.5 minutes)
+ */
+declare const UPLOAD_MAX_RETRIES = 7;
+/**
+ * Backoff delays in seconds for each retry attempt.
+ * Uses exponential backoff: 4s, 8s, 16s, 32s, 64s, 128s, 256s
+ */
+declare const UPLOAD_BACKOFF_DELAYS: readonly [4, 8, 16, 32, 64, 128, 256];
 
-export { AttachmentQueueContext, type BackgroundSyncCallbacks, type BackgroundSyncConfig, type BackgroundSyncStatus, CompletedTransactionsContext, type CompletedTransactionsContextValue, ConnectionHealthContext, type ConnectionHealthContextValue, ConnectionStatusContext, type ConnectionStatusContextValue, DEFAULT_CONNECTION_HEALTH, DEFAULT_SYNC_CONFIG, DEFAULT_SYNC_METRICS, DEFAULT_SYNC_STATUS, type DataLayerConfig, type DataLayerIntegration, type EntitySyncStatusResult, FailedTransactionsContext, type FailedTransactionsContextValue, type OfflineDataAttachmentConfig, OfflineDataProvider, type OfflineDataProviderConfig, type OfflineDataProviderProps, PendingMutationsContext, type PendingMutationsContextValue, type PowerSyncConfig, PowerSyncContext, type PowerSyncContextValue, PowerSyncProvider, type PowerSyncProviderProps, type PowerSyncSyncStatusSnapshot, ProviderBridge, type ProviderBridgeProps, SyncActivityContext, type SyncActivityContextValue, type SyncActivityResult, type SyncConfig, SyncMetricsContext, type SyncMetricsContextValue, SyncModeContext, type SyncModeContextValue, SyncStatusContext, type SyncStatusContextValue, type UploadStatusResult, useAttachmentQueue, useAttachmentQueueReady, useCompletedTransactions, useCompletedTransactionsContext, useConnectionHealth, useConnectionStatus, useDatabase, useDownloadProgress, useEntitySyncStatus, useFailedTransactions, useFailedTransactionsContext, useIsSyncing, useOnlineStatus, usePendingMutations, usePendingMutationsContext, usePlatform, usePowerSync, useSyncActivity, useSyncActivityContext, useSyncControl, useSyncMetrics, useSyncMode, useSyncModeContext, useSyncStatus, useUploadStatus };
+export { AttachmentQueueContext, type BackgroundSyncCallbacks, type BackgroundSyncConfig, type BackgroundSyncStatus, CompletedTransactionsContext, type CompletedTransactionsContextValue, ConnectionHealthContext, type ConnectionHealthContextValue, ConnectionStatusContext, type ConnectionStatusContextValue, DEFAULT_CONNECTION_HEALTH, DEFAULT_SYNC_CONFIG, DEFAULT_SYNC_METRICS, DEFAULT_SYNC_STATUS, type DataLayerConfig, type DataLayerIntegration, type EntitySyncStatusResult, FailedTransactionsContext, type FailedTransactionsContextValue, type OfflineDataAttachmentConfig, OfflineDataProvider, type OfflineDataProviderConfig, type OfflineDataProviderProps, PendingMutationsContext, type PendingMutationsContextValue, type PowerSyncConfig, PowerSyncContext, type PowerSyncContextValue, PowerSyncProvider, type PowerSyncProviderProps, type PowerSyncSyncStatusSnapshot, ProviderBridge, type ProviderBridgeProps, type RetryCountdownResult, SyncActivityContext, type SyncActivityContextValue, type SyncActivityResult, type SyncConfig, SyncMetricsContext, type SyncMetricsContextValue, SyncModeContext, type SyncModeContextValue, SyncStatusContext, type SyncStatusContextValue, UPLOAD_BACKOFF_DELAYS, UPLOAD_MAX_RETRIES, type UploadBlockedReasonResult, type UploadStatusResult, useAttachmentQueue, useAttachmentQueueReady, useCompletedTransactions, useCompletedTransactionsContext, useConnectionHealth, useConnectionStatus, useDatabase, useDownloadProgress, useEntitySyncStatus, useFailedTransactions, useFailedTransactionsContext, useIsSyncing, useOnlineStatus, usePendingMutations, usePendingMutationsContext, usePlatform, usePowerSync, useRetryCountdown, useSyncActivity, useSyncActivityContext, useSyncControl, useSyncMetrics, useSyncMode, useSyncModeContext, useSyncStatus, useUploadBlockedReason, useUploadRetry, useUploadStatus };

package/dist/provider/index.js

@@ -1,18 +1,20 @@
 import {
   OfflineDataProvider,
   PowerSyncProvider,
-  ProviderBridge
-} from "../chunk-YVX3A36I.js";
+  ProviderBridge,
+  UPLOAD_BACKOFF_DELAYS,
+  UPLOAD_MAX_RETRIES
+} from "../chunk-JCGOZVWL.js";
 import "../chunk-YHTZ7VMV.js";
 import "../chunk-P6WOZO7H.js";
 import "../chunk-CACKC6XG.js";
-import "../chunk-55DKCJV4.js";
+import "../chunk-RE5HWLCB.js";
 import {
   DEFAULT_CONNECTION_HEALTH,
   DEFAULT_SYNC_CONFIG,
   DEFAULT_SYNC_METRICS,
   DEFAULT_SYNC_STATUS
-} from "../chunk-24RDMMCL.js";
+} from "../chunk-FNYQFILT.js";
 import {
   AttachmentQueueContext,
   CompletedTransactionsContext,
@@ -42,6 +44,7 @@ import {
   usePendingMutationsContext,
   usePlatform,
   usePowerSync,
+  useRetryCountdown,
   useSyncActivity,
   useSyncActivityContext,
   useSyncControl,
@@ -49,15 +52,17 @@ import {
   useSyncMode,
   useSyncModeContext,
   useSyncStatus,
+  useUploadBlockedReason,
+  useUploadRetry,
   useUploadStatus
-} from "../chunk-YSTEESEG.js";
+} from "../chunk-C2ACBYBZ.js";
 import "../chunk-CAB26E6F.js";
 import "../chunk-XAEII4ZX.js";
 import "../chunk-Z6VOBGTU.js";
+import "../chunk-FV2HXEIY.js";
 import "../chunk-CGL33PL4.js";
 import "../chunk-WN5ZJ3E2.js";
-import "../chunk-BGBQYQV3.js";
-import "../chunk-FV2HXEIY.js";
+import "../chunk-BC2SRII2.js";
 import "../chunk-I2AYMY5O.js";
 export {
   AttachmentQueueContext,
@@ -78,6 +83,8 @@ export {
   SyncMetricsContext,
   SyncModeContext,
   SyncStatusContext,
+  UPLOAD_BACKOFF_DELAYS,
+  UPLOAD_MAX_RETRIES,
   useAttachmentQueue,
   useAttachmentQueueReady,
   useCompletedTransactions,
@@ -95,6 +102,7 @@ export {
   usePendingMutationsContext,
   usePlatform,
   usePowerSync,
+  useRetryCountdown,
   useSyncActivity,
   useSyncActivityContext,
   useSyncControl,
@@ -102,6 +110,8 @@ export {
   useSyncMode,
   useSyncModeContext,
   useSyncStatus,
+  useUploadBlockedReason,
+  useUploadRetry,
   useUploadStatus
 };
 //# sourceMappingURL=index.js.map

package/dist/react/index.d.ts

@@ -1,11 +1,11 @@
 import * as react from 'react';
 import react__default, { ReactNode } from 'react';
 import { Schema } from '@powersync/react-native';
-import { A as AuthProvider } from '../types-DiBvmGEi.js';
+import { A as AuthProvider } from '../types-CpM2_LhU.js';
 import { a as StorageBackend } from '../types-D0WcHrq6.js';
 import { f as AttachmentConfig, P as PolAttachmentQueue } from '../pol-attachment-queue-BE2HU3Us.js';
 import { PlatformAdapter } from '../platform/index.js';
-import { f as SyncError, a as SyncStatus, A as AbstractPowerSyncDatabase } from '../types-CDqWh56B.js';
+import { f as SyncError, a as SyncStatus, A as AbstractPowerSyncDatabase } from '../types-Dv1uf0LZ.js';
 import '@supabase/supabase-js';
 import '@powersync/attachments';
 import '@powersync/common';

package/dist/react/index.js

@@ -6,11 +6,11 @@ import {
   useAttachmentQueueContext,
   usePowerSyncContext,
   useSyncStatusContext
-} from "../chunk-TIFL2KWE.js";
+} from "../chunk-RBPWEOIV.js";
 import "../chunk-CACKC6XG.js";
-import "../chunk-24RDMMCL.js";
-import "../chunk-BGBQYQV3.js";
+import "../chunk-FNYQFILT.js";
 import "../chunk-FV2HXEIY.js";
+import "../chunk-BC2SRII2.js";
 import "../chunk-I2AYMY5O.js";
 export {
   AttachmentQueueContext,

package/dist/storage/index.d.ts

@@ -3,4 +3,4 @@ export { f as CacheSettings, C as CacheSettingsManager, h as CacheSettingsManage
 export { D as DEFAULT_UPLOAD_NOTIFICATION, S as SupabaseUploadHandlerOptions, U as UploadEventHandlers, a as UploadNotificationConfig } from '../types-CyvBaAl8.js';
 export { SupabaseUploadHandler, createSupabaseUploadHandler } from './upload/index.js';
 import '../platform/index.js';
-import '../types-CDqWh56B.js';
+import '../types-Dv1uf0LZ.js';

package/dist/storage/index.native.d.ts

@@ -3,4 +3,4 @@ export { f as CacheSettings, C as CacheSettingsManager, h as CacheSettingsManage
 export { D as DEFAULT_UPLOAD_NOTIFICATION, S as SupabaseUploadHandlerOptions, U as UploadEventHandlers, a as UploadNotificationConfig } from '../types-CyvBaAl8.js';
 export { SupabaseUploadHandler, createSupabaseUploadHandler } from './upload/index.native.js';
 import '../platform/index.js';
-import '../types-CDqWh56B.js';
+import '../types-Dv1uf0LZ.js';

package/dist/storage/index.web.d.ts

@@ -3,4 +3,4 @@ export { f as CacheSettings, C as CacheSettingsManager, h as CacheSettingsManage
 export { D as DEFAULT_UPLOAD_NOTIFICATION, S as SupabaseUploadHandlerOptions, U as UploadEventHandlers, a as UploadNotificationConfig } from '../types-CyvBaAl8.js';
 export { SupabaseUploadHandler, createSupabaseUploadHandler } from './upload/index.js';
 import '../platform/index.js';
-import '../types-CDqWh56B.js';
+import '../types-Dv1uf0LZ.js';

package/dist/{supabase-connector-D2oIl2t8.d.ts → supabase-connector-C4YpH_l3.d.ts}

@@ -1,5 +1,5 @@
-import { P as PowerSyncBackendConnector, A as AbstractPowerSyncDatabase } from './types-CDqWh56B.js';
-import { S as SupabaseConnectorOptions, P as PowerSyncCredentials } from './types-DiBvmGEi.js';
+import { P as PowerSyncBackendConnector, A as AbstractPowerSyncDatabase } from './types-Dv1uf0LZ.js';
+import { S as SupabaseConnectorOptions, P as PowerSyncCredentials } from './types-CpM2_LhU.js';
 
 /**
  * Supabase Connector for PowerSync
@@ -10,6 +10,12 @@ import { S as SupabaseConnectorOptions, P as PowerSyncCredentials } from './type
  * - Schema routing for multi-schema databases
  * - Custom CRUD handling for complex operations
  * - Version-based conflict detection (when enabled)
+ *
+ * Error Handling Architecture (Simplified):
+ * - NO internal retry loops - PowerSync SDK handles all retries naturally
+ * - Middleware decides once: success/discard/retry/fail_transaction
+ * - ALL errors throw to let PowerSync retry naturally
+ * - ALL errors call onTransactionFailure (at outer level) for UI visibility
  */
 
 /**
@@ -78,15 +84,10 @@ declare class SupabaseConnector implements PowerSyncBackendConnector {
     private unsubscribeResolution?;
     private versionColumnPromises;
     private isDestroyed;
-    private retryConfig;
     private completionFailures;
     private static readonly COMPLETION_MAX_FAILURES;
     private static readonly COMPLETION_EXTENDED_TIMEOUT_MS;
     private static readonly MAX_STORED_RESOLUTIONS;
-    private autoRetryPaused;
-    private entryCooldowns;
-    private static readonly COOLDOWN_DURATION_MS;
-    private static readonly MAX_ENTRY_COOLDOWNS;
     private readonly uploadErrorMiddleware;
     constructor(options: SupabaseConnectorOptions);
     /**
@@ -100,28 +101,25 @@ declare class SupabaseConnector implements PowerSyncBackendConnector {
      */
     private generateTransactionFingerprint;
     /**
-     * Pause automatic retry of failed uploads.
-     * Use this when the user goes offline intentionally or wants manual control.
-     */
-    pauseAutoRetry(): void;
-    /**
-     * Resume automatic retry of failed uploads.
-     */
-    resumeAutoRetry(): void;
-    /**
-     * Process a single CRUD entry with exponential backoff retry.
-     *
-     * This method uses a two-phase approach:
-     * 1. First attempt - try the operation to classify the error type
-     * 2. Retry phase - use the appropriate config (transient vs permanent) based on classification
+     * Process a single CRUD entry once (no internal retries).
      *
-     * This fixes the issue where reassigning selectedConfig inside withExponentialBackoff's
-     * callback had no effect because the config was already destructured at call time.
+     * On failure, middleware classifies the error:
+     * - 'success': Treat as completed (e.g., idempotent duplicate)
+     * - 'discard': Remove from queue silently
+     * - 'retry': Throw to let PowerSync retry on next sync cycle
+     * - 'fail_transaction': Throw TransactionAbortError immediately
+     * - 'continue': Throw original error (PowerSync will retry)
      *
      * @param entry - The CRUD entry to process
-     * @throws Error if all retries exhausted (for critical failures)
+     * @throws Error for all errors (PowerSync will retry)
+     * @throws TransactionAbortError when middleware returns 'fail_transaction'
+     * @throws DiscardEntryError for discarded entries
+     */
+    private processEntryOnce;
+    /**
+     * Handle an entry error by running middleware and deciding what to do.
      */
-    private processWithRetry;
+    private handleEntryError;
     /**
      * Set the active project IDs for scoped sync.
      * Call this when user selects/opens projects.

package/dist/sync/index.d.ts

@@ -1,6 +1,6 @@
-import { b as SyncStatusTrackerOptions, P as PowerSyncRawStatus, U as Unsubscribe, M as MetricsCollectorOptions, d as SyncOperationData, H as HealthMonitorOptions, e as HealthCheckResult } from '../background-sync-ChCXW-EV.js';
-export { B as BackgroundSyncOptions, h as BackgroundSyncSystem, c as SyncControlActions, f as SyncEvent, g as SyncEventListener, S as SyncScope, a as SyncStatusState, i as defineBackgroundSyncTask, j as initializeBackgroundSync, k as isBackgroundSyncRegistered, r as registerBackgroundSync, u as unregisterBackgroundSync } from '../background-sync-ChCXW-EV.js';
-import { a as SyncStatus, S as SyncMode, C as CrudEntry, f as SyncError, F as FailedTransaction, h as CompletedTransaction, e as SyncMetrics, A as AbstractPowerSyncDatabase, b as ConnectionHealth } from '../types-CDqWh56B.js';
+import { b as SyncStatusTrackerOptions, P as PowerSyncRawStatus, U as Unsubscribe, M as MetricsCollectorOptions, d as SyncOperationData, H as HealthMonitorOptions, e as HealthCheckResult } from '../background-sync-CVR3PkFi.js';
+export { B as BackgroundSyncOptions, h as BackgroundSyncSystem, c as SyncControlActions, f as SyncEvent, g as SyncEventListener, S as SyncScope, a as SyncStatusState, i as defineBackgroundSyncTask, j as initializeBackgroundSync, k as isBackgroundSyncRegistered, r as registerBackgroundSync, u as unregisterBackgroundSync } from '../background-sync-CVR3PkFi.js';
+import { a as SyncStatus, S as SyncMode, U as UploadBlockReason, C as CrudEntry, f as SyncError, F as FailedTransaction, h as CompletedTransaction, e as SyncMetrics, A as AbstractPowerSyncDatabase, b as ConnectionHealth } from '../types-Dv1uf0LZ.js';
 import { AsyncStorageAdapter, LoggerAdapter } from '../platform/index.js';
 
 /**
@@ -53,6 +53,9 @@ declare class SyncStatusTracker {
     private readonly _networkRestoreDelayMs;
     private _persistDebounceTimer;
     private _lastProgress;
+    private readonly _backoffBaseMs;
+    private readonly _backoffMaxMs;
+    private readonly _backoffMultiplier;
     private _failedTransactions;
     private readonly _maxStoredFailures;
     private readonly _failureTTLMs;
@@ -79,6 +82,26 @@ declare class SyncStatusTracker {
      * Get the current sync mode.
      */
     getSyncMode(): SyncMode;
+    /**
+     * Get the reason why uploads are currently blocked.
+     * Returns 'none' if uploads are ready to proceed.
+     *
+     * Priority order (first match wins):
+     * 1. offline_mode - User explicitly chose offline mode
+     * 2. auto_offline - System went offline automatically (network loss with auto-offline flag)
+     * 3. pull_only_mode - Pull-only mode active
+     * 4. network_unreachable - No internet connection
+     * 5. disconnected - PowerSync not connected
+     * 6. connecting - PowerSync is connecting
+     * 7. uploading - Actively uploading
+     * 8. none - Ready to sync
+     */
+    getUploadBlockReason(): UploadBlockReason;
+    /**
+     * Get a human-readable description of why uploads are blocked.
+     * Returns null if uploads are not blocked.
+     */
+    getUploadBlockDescription(): string | null;
     /**
      * Check if uploads are allowed based on current sync mode and network reachability.
      */
@@ -157,6 +180,14 @@ declare class SyncStatusTracker {
      * @returns Unsubscribe function
      */
     onSyncModeChange(listener: (mode: SyncMode) => void): Unsubscribe;
+    /**
+     * Compute exponential backoff delay for a given retry count.
+     * Uses base 1s, max 60s, multiplier 2.
+     *
+     * @param retryCount - Number of retries (1-based)
+     * @returns Backoff delay in milliseconds
+     */
+    private _computeBackoffMs;
     /**
      * Record a transaction failure.
      * If a failure for the same entries already exists, updates the retry count.
@@ -173,9 +204,15 @@ declare class SyncStatusTracker {
      */
     clearFailure(failureId: string): void;
     /**
-     * Clear all failures.
+     * Clear failures for successfully synced entries.
+     * Removes any failed transaction that contains entries with the given IDs.
+     *
+     * This is called when `onTransactionSuccess` fires - if any entry in a failed
+     * transaction has now succeeded, we remove that entire failure record.
+     *
+     * @param entryIds - Array of CrudEntry.id values that succeeded
      */
-    clearAllFailures(): void;
+    clearSuccessfulEntries(entryIds: string[]): void;
     /**
      * Remove a failed transaction from tracking and return its entries.
      * This is a "pop" operation - the failure is removed from the list.

package/dist/sync/index.js

@@ -12,8 +12,8 @@ import {
   HealthMonitor,
   MetricsCollector,
   SyncStatusTracker
-} from "../chunk-55DKCJV4.js";
-import "../chunk-24RDMMCL.js";
+} from "../chunk-RE5HWLCB.js";
+import "../chunk-FNYQFILT.js";
 import "../chunk-CGL33PL4.js";
 import "../chunk-I2AYMY5O.js";
 export {