@tanstack/offline-transactions 1.0.58 → 1.0.61

package/dist/esm/types.d.ts

@@ -31,6 +31,8 @@ export interface OfflineTransaction {
     createdAt: Date;
     retryCount: number;
     nextAttemptAt: number;
+    /** Provider work has settled; only durable outbox deletion remains. */
+    outboxPhase?: `deletion-pending` | `rejection-pending`;
     lastError?: SerializedError;
     metadata?: Record<string, any>;
     spanContext?: SerializedSpanContext;
@@ -47,6 +49,8 @@ export interface SerializedOfflineTransaction {
     createdAt: string;
     retryCount: number;
     nextAttemptAt: number;
+    /** Absent in older records and while mutationFn may still need to run. */
+    outboxPhase?: `deletion-pending` | `rejection-pending`;
     lastError?: SerializedError;
     metadata?: Record<string, any>;
     spanContext?: SerializedSpanContext;

package/dist/esm/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sources":["../../src/types.ts"],"sourcesContent":["import type {\n  Collection,\n  MutationFnParams,\n  PendingMutation,\n  Transaction,\n} from '@tanstack/db'\n\n// Extended mutation function that includes idempotency key\nexport type OfflineMutationFnParams<\n  T extends object = Record<string, unknown>,\n> = MutationFnParams<T> & {\n  idempotencyKey: string\n}\n\nexport type OfflineMutationFn<T extends object = Record<string, unknown>> = (\n  params: OfflineMutationFnParams<T>,\n) => Promise<any>\n\n// Simplified mutation structure for serialization\nexport interface SerializedMutation {\n  globalKey: string\n  type: string\n  modified: any\n  original: any\n  changes: any\n  collectionId: string\n}\n\nexport interface SerializedError {\n  name: string\n  message: string\n  stack?: string\n}\n\nexport interface SerializedSpanContext {\n  traceId: string\n  spanId: string\n  traceFlags: number\n  traceState?: string\n}\n\n// In-memory representation with full PendingMutation objects\nexport interface OfflineTransaction {\n  id: string\n  mutationFnName: string\n  mutations: Array<PendingMutation>\n  keys: Array<string>\n  idempotencyKey: string\n  createdAt: Date\n  retryCount: number\n  nextAttemptAt: number\n  lastError?: SerializedError\n  metadata?: Record<string, any>\n  spanContext?: SerializedSpanContext\n  version: 1\n}\n\n// Serialized representation for storage\nexport interface SerializedOfflineTransaction {\n  /** Absent for the original Date-marker format. */\n  valueEncoding?: 2 | 3\n  id: string\n  mutationFnName: string\n  mutations: Array<SerializedMutation>\n  keys: Array<string>\n  idempotencyKey: string\n  createdAt: string\n  retryCount: number\n  nextAttemptAt: number\n  lastError?: SerializedError\n  metadata?: Record<string, any>\n  spanContext?: SerializedSpanContext\n  version: 1\n}\n\n// Storage diagnostics and mode\nexport type OfflineMode = `offline` | `online-only`\n\nexport type StorageDiagnosticCode =\n  | `STORAGE_AVAILABLE`\n  | `INDEXEDDB_UNAVAILABLE`\n  | `LOCALSTORAGE_UNAVAILABLE`\n  | `STORAGE_BLOCKED`\n  | `QUOTA_EXCEEDED`\n  | `UNKNOWN_ERROR`\n\nexport interface StorageDiagnostic {\n  code: StorageDiagnosticCode\n  mode: OfflineMode\n  message: string\n  error?: Error\n}\n\nexport interface OfflineConfig {\n  collections: Record<string, Collection<any, any, any, any, any>>\n  mutationFns: Record<string, OfflineMutationFn>\n  storage?: StorageAdapter\n  maxConcurrency?: number\n  jitter?: boolean\n  beforeRetry?: (\n    transactions: Array<OfflineTransaction>,\n  ) => Array<OfflineTransaction>\n  onUnknownMutationFn?: (name: string, tx: OfflineTransaction) => void\n  onLeadershipChange?: (isLeader: boolean) => void\n  onStorageFailure?: (diagnostic: StorageDiagnostic) => void\n  leaderElection?: LeaderElection\n  /**\n   * Custom online detector implementation.\n   * Defaults to WebOnlineDetector for browser environments.\n   * The '@tanstack/offline-transactions/react-native' entry point uses ReactNativeOnlineDetector automatically.\n   */\n  onlineDetector?: OnlineDetector\n}\n\nexport interface StorageAdapter {\n  get: (key: string) => Promise<string | null>\n  set: (key: string, value: string) => Promise<void>\n  delete: (key: string) => Promise<void>\n  keys: () => Promise<Array<string>>\n  clear: () => Promise<void>\n}\n\nexport interface RetryPolicy {\n  calculateDelay: (retryCount: number) => number\n  shouldRetry: (error: Error, retryCount: number) => boolean\n}\n\nexport interface LeaderElection {\n  requestLeadership: () => Promise<boolean>\n  releaseLeadership: () => void\n  isLeader: () => boolean\n  onLeadershipChange: (callback: (isLeader: boolean) => void) => () => void\n}\n\nexport interface TransactionSignaler {\n  readonly isOfflineEnabled: boolean\n  resolveTransaction: (transactionId: string, result: any) => void\n  rejectTransaction: (transactionId: string, error: Error) => void\n  registerRestorationTransaction: (\n    offlineTransactionId: string,\n    restorationTransaction: Transaction,\n  ) => void\n  isOnline: () => boolean\n}\n\nexport interface OnlineDetector {\n  subscribe: (callback: () => void) => () => void\n  notifyOnline: () => void\n  isOnline: () => boolean\n  dispose: () => void\n}\n\nexport interface CreateOfflineTransactionOptions {\n  id?: string\n  mutationFnName: string\n  autoCommit?: boolean\n  idempotencyKey?: string\n  metadata?: Record<string, any>\n}\n\nexport interface CreateOfflineActionOptions<T> {\n  mutationFnName: string\n  onMutate: (variables: T) => void\n}\n\nexport class NonRetriableError extends Error {\n  constructor(message: string) {\n    super(message)\n    this.name = `NonRetriableError`\n  }\n}\n"],"names":[],"mappings":"AAqKO,MAAM,0BAA0B,MAAM;AAAA,EAC3C,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;"}
+{"version":3,"file":"types.js","sources":["../../src/types.ts"],"sourcesContent":["import type {\n  Collection,\n  MutationFnParams,\n  PendingMutation,\n  Transaction,\n} from '@tanstack/db'\n\n// Extended mutation function that includes idempotency key\nexport type OfflineMutationFnParams<\n  T extends object = Record<string, unknown>,\n> = MutationFnParams<T> & {\n  idempotencyKey: string\n}\n\nexport type OfflineMutationFn<T extends object = Record<string, unknown>> = (\n  params: OfflineMutationFnParams<T>,\n) => Promise<any>\n\n// Simplified mutation structure for serialization\nexport interface SerializedMutation {\n  globalKey: string\n  type: string\n  modified: any\n  original: any\n  changes: any\n  collectionId: string\n}\n\nexport interface SerializedError {\n  name: string\n  message: string\n  stack?: string\n}\n\nexport interface SerializedSpanContext {\n  traceId: string\n  spanId: string\n  traceFlags: number\n  traceState?: string\n}\n\n// In-memory representation with full PendingMutation objects\nexport interface OfflineTransaction {\n  id: string\n  mutationFnName: string\n  mutations: Array<PendingMutation>\n  keys: Array<string>\n  idempotencyKey: string\n  createdAt: Date\n  retryCount: number\n  nextAttemptAt: number\n  /** Provider work has settled; only durable outbox deletion remains. */\n  outboxPhase?: `deletion-pending` | `rejection-pending`\n  lastError?: SerializedError\n  metadata?: Record<string, any>\n  spanContext?: SerializedSpanContext\n  version: 1\n}\n\n// Serialized representation for storage\nexport interface SerializedOfflineTransaction {\n  /** Absent for the original Date-marker format. */\n  valueEncoding?: 2 | 3\n  id: string\n  mutationFnName: string\n  mutations: Array<SerializedMutation>\n  keys: Array<string>\n  idempotencyKey: string\n  createdAt: string\n  retryCount: number\n  nextAttemptAt: number\n  /** Absent in older records and while mutationFn may still need to run. */\n  outboxPhase?: `deletion-pending` | `rejection-pending`\n  lastError?: SerializedError\n  metadata?: Record<string, any>\n  spanContext?: SerializedSpanContext\n  version: 1\n}\n\n// Storage diagnostics and mode\nexport type OfflineMode = `offline` | `online-only`\n\nexport type StorageDiagnosticCode =\n  | `STORAGE_AVAILABLE`\n  | `INDEXEDDB_UNAVAILABLE`\n  | `LOCALSTORAGE_UNAVAILABLE`\n  | `STORAGE_BLOCKED`\n  | `QUOTA_EXCEEDED`\n  | `UNKNOWN_ERROR`\n\nexport interface StorageDiagnostic {\n  code: StorageDiagnosticCode\n  mode: OfflineMode\n  message: string\n  error?: Error\n}\n\nexport interface OfflineConfig {\n  collections: Record<string, Collection<any, any, any, any, any>>\n  mutationFns: Record<string, OfflineMutationFn>\n  storage?: StorageAdapter\n  maxConcurrency?: number\n  jitter?: boolean\n  beforeRetry?: (\n    transactions: Array<OfflineTransaction>,\n  ) => Array<OfflineTransaction>\n  onUnknownMutationFn?: (name: string, tx: OfflineTransaction) => void\n  onLeadershipChange?: (isLeader: boolean) => void\n  onStorageFailure?: (diagnostic: StorageDiagnostic) => void\n  leaderElection?: LeaderElection\n  /**\n   * Custom online detector implementation.\n   * Defaults to WebOnlineDetector for browser environments.\n   * The '@tanstack/offline-transactions/react-native' entry point uses ReactNativeOnlineDetector automatically.\n   */\n  onlineDetector?: OnlineDetector\n}\n\nexport interface StorageAdapter {\n  get: (key: string) => Promise<string | null>\n  set: (key: string, value: string) => Promise<void>\n  delete: (key: string) => Promise<void>\n  keys: () => Promise<Array<string>>\n  clear: () => Promise<void>\n}\n\nexport interface RetryPolicy {\n  calculateDelay: (retryCount: number) => number\n  shouldRetry: (error: Error, retryCount: number) => boolean\n}\n\nexport interface LeaderElection {\n  requestLeadership: () => Promise<boolean>\n  releaseLeadership: () => void\n  isLeader: () => boolean\n  onLeadershipChange: (callback: (isLeader: boolean) => void) => () => void\n}\n\nexport interface TransactionSignaler {\n  readonly isOfflineEnabled: boolean\n  resolveTransaction: (transactionId: string, result: any) => void\n  rejectTransaction: (transactionId: string, error: Error) => void\n  registerRestorationTransaction: (\n    offlineTransactionId: string,\n    restorationTransaction: Transaction,\n  ) => void\n  isOnline: () => boolean\n}\n\nexport interface OnlineDetector {\n  subscribe: (callback: () => void) => () => void\n  notifyOnline: () => void\n  isOnline: () => boolean\n  dispose: () => void\n}\n\nexport interface CreateOfflineTransactionOptions {\n  id?: string\n  mutationFnName: string\n  autoCommit?: boolean\n  idempotencyKey?: string\n  metadata?: Record<string, any>\n}\n\nexport interface CreateOfflineActionOptions<T> {\n  mutationFnName: string\n  onMutate: (variables: T) => void\n}\n\nexport class NonRetriableError extends Error {\n  constructor(message: string) {\n    super(message)\n    this.name = `NonRetriableError`\n  }\n}\n"],"names":[],"mappings":"AAyKO,MAAM,0BAA0B,MAAM;AAAA,EAC3C,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/offline-transactions",
-  "version": "1.0.58",
+  "version": "1.0.61",
   "description": "Offline-first transaction capabilities for TanStack DB",
   "author": "TanStack",
   "license": "MIT",
@@ -52,7 +52,7 @@
     "skills"
   ],
   "dependencies": {
-    "@tanstack/db": "0.11.0"
+    "@tanstack/db": "0.11.3"
   },
   "peerDependencies": {
     "@react-native-community/netinfo": ">=11.0.0",

package/src/OfflineExecutor.ts

@@ -27,6 +27,7 @@ import { createOfflineAction } from './api/OfflineAction'
 
 // Replay
 import { withNestedSpan, withSpan } from './telemetry/tracer'
+import { NonRetriableError } from './types'
 import type {
   CreateOfflineActionOptions,
   CreateOfflineTransactionOptions,
@@ -448,12 +449,12 @@ export class OfflineExecutor {
       },
       async (span) => {
         if (!this.isOfflineEnabled || !this.outbox || !this.executor) {
-          span.setAttribute(`result`, `skipped_not_leader`)
-          this.resolveTransaction(transaction.id, undefined)
-          return
+          span.setAttribute(`result`, `rejected_not_admitted`)
+          throw new NonRetriableError(`Offline transaction was not admitted`)
         }
 
         try {
+          this.executor.assertHealthy()
           await this.outbox.add(transaction)
           // A shared queue error belongs to its execution, not every caller
           // that durably admitted a transaction. Per-ID signals settle callers.

package/src/executor/TransactionExecutor.ts

@@ -1,4 +1,5 @@
 import { createTransaction } from '@tanstack/db'
+import { OutboxTransactionNotFoundError } from '../outbox/OutboxManager'
 import { DefaultRetryPolicy } from '../retry/RetryPolicy'
 import { NonRetriableError } from '../types'
 import { withNestedSpan } from '../telemetry/tracer'
@@ -21,6 +22,7 @@ export class TransactionExecutor {
   private executionPromise: Promise<void> | null = null
   private offlineExecutor: TransactionSignaler
   private retryTimer: ReturnType<typeof setTimeout> | null = null
+  private fatalError: Error | null = null
 
   constructor(
     scheduler: KeyScheduler,
@@ -39,11 +41,13 @@ export class TransactionExecutor {
   }
 
   async execute(transaction: OfflineTransaction): Promise<void> {
+    this.assertHealthy()
     this.scheduler.schedule(transaction)
     await this.executeAll()
   }
 
   async executeAll(): Promise<void> {
+    this.assertHealthy()
     if (this.isExecuting) {
       return this.executionPromise!
     }
@@ -89,39 +93,62 @@ export class TransactionExecutor {
           'transaction.keyCount': transaction.keys.length,
         },
         async (span) => {
+          const terminalError =
+            transaction.outboxPhase === `rejection-pending`
+              ? this.getTerminalError(transaction)
+              : undefined
           this.scheduler.markStarted(transaction)
 
           if (transaction.retryCount > 0) {
             span.setAttribute(`retry.attempt`, transaction.retryCount)
           }
 
-          let result: void
-          try {
-            result = await this.runMutationFn(transaction)
-          } catch (error) {
-            const err =
-              error instanceof Error ? error : new Error(String(error))
+          if (!transaction.outboxPhase) {
+            try {
+              await this.runMutationFn(transaction)
+            } catch (error) {
+              const err =
+                error instanceof Error ? error : new Error(String(error))
 
-            span.setAttribute(`result`, `error`)
+              span.setAttribute(`result`, `error`)
 
-            await this.handleError(transaction, err)
-            ;(err as any)[HANDLED_EXECUTION_ERROR] = true
-            throw err
+              await this.handleError(transaction, err)
+              ;(err as any)[HANDLED_EXECUTION_ERROR] = true
+              throw err
+            }
           }
 
-          let removalError: unknown
+          // A successful provider call can outlive this executor. Persist that
+          // fact before removal so a restarted executor only retries deletion.
+          const deletionPending: OfflineTransaction = transaction.outboxPhase
+            ? transaction
+            : { ...transaction, outboxPhase: `deletion-pending` }
           try {
-            // Replay can still see this ID until durable deletion settles.
-            await this.outbox.remove(transaction.id)
+            await this.removeSettledTransaction(
+              deletionPending,
+              !transaction.outboxPhase,
+            )
           } catch (error) {
-            removalError = error
-          } finally {
-            this.scheduler.markCompleted(transaction)
+            const storageError = error as Error
+            span.recordException(storageError)
+            span.setAttribute(`result`, `outbox_failure`)
+            this.offlineExecutor.rejectTransaction(
+              transaction.id,
+              terminalError ?? storageError,
+            )
+            throw storageError
           }
 
-          span.setAttribute(`result`, `success`)
-          this.offlineExecutor.resolveTransaction(transaction.id, result)
-          if (removalError !== undefined) throw removalError
+          if (terminalError) {
+            span.setAttribute(`result`, `permanent_failure`)
+            this.offlineExecutor.rejectTransaction(
+              transaction.id,
+              terminalError,
+            )
+          } else {
+            span.setAttribute(`result`, `success`)
+            this.offlineExecutor.resolveTransaction(transaction.id, undefined)
+          }
         },
       )
     } catch (error) {
@@ -183,23 +210,30 @@ export class TransactionExecutor {
         span.setAttribute(`shouldRetry`, shouldRetry)
 
         if (!shouldRetry) {
-          let removalError: unknown
-          try {
-            await this.outbox.remove(transaction.id)
-          } catch (cleanupError) {
-            removalError = cleanupError
-          } finally {
-            this.scheduler.markCompleted(transaction)
+          const rejectionPending: OfflineTransaction = {
+            ...transaction,
+            outboxPhase: `rejection-pending`,
+            lastError: {
+              name: error.name,
+              message: error.message,
+              stack: error.stack,
+            },
           }
           console.warn(
             `Transaction ${transaction.id} failed permanently:`,
             error,
           )
+          try {
+            await this.removeSettledTransaction(rejectionPending, true)
+          } catch (storageError) {
+            span.recordException(storageError as Error)
+            span.setAttribute(`result`, `outbox_failure`)
+            this.offlineExecutor.rejectTransaction(transaction.id, error)
+            throw storageError
+          }
 
           span.setAttribute(`result`, `permanent_failure`)
-          // Signal permanent failure to the waiting transaction
           this.offlineExecutor.rejectTransaction(transaction.id, error)
-          if (removalError !== undefined) throw removalError
           return
         }
 
@@ -237,16 +271,65 @@ export class TransactionExecutor {
     )
   }
 
+  private async removeSettledTransaction(
+    transaction: OfflineTransaction,
+    persistMarker: boolean,
+  ): Promise<void> {
+    try {
+      if (persistMarker) {
+        try {
+          await this.outbox.update(transaction.id, transaction)
+        } catch (error) {
+          // A public removal can finish while the provider is still running.
+          if (!(error instanceof OutboxTransactionNotFoundError)) throw error
+        }
+      }
+      await this.outbox.remove(transaction.id)
+      this.scheduler.markCompleted(transaction)
+    } catch (error) {
+      const storageError =
+        error instanceof Error ? error : new Error(String(error))
+      this.fatalError = storageError
+      this.scheduler.markFailed(transaction)
+      this.clearRetryTimer()
+      throw storageError
+    }
+  }
+
+  assertHealthy(): void {
+    if (this.fatalError) throw this.fatalError
+  }
+
+  private getTerminalError(transaction: OfflineTransaction): Error {
+    if (!transaction.lastError)
+      throw new Error(`Terminal transaction ${transaction.id} has no error`)
+    const { name, message, stack } = transaction.lastError
+    const error =
+      name === `NonRetriableError`
+        ? new NonRetriableError(message)
+        : new Error(message)
+    error.name = name
+    error.stack = stack
+    return error
+  }
+
   async loadPendingTransactions(): Promise<void> {
     let removedIds: Array<string> = []
     await this.outbox.withAll((transactions) => {
       const { isOfflineEnabled } = this.offlineExecutor
       if (!isOfflineEnabled) return
-      let filteredTransactions = transactions
-
-      if (this.config.beforeRetry) {
-        filteredTransactions = this.config.beforeRetry(transactions)
-      }
+      const providerPending = transactions.filter(
+        (transaction) => !transaction.outboxPhase,
+      )
+      const selectedProvider = this.config.beforeRetry
+        ? this.config.beforeRetry(providerPending)
+        : providerPending
+      const selectedById = new Map(selectedProvider.map((tx) => [tx.id, tx]))
+      const filteredTransactions = transactions.flatMap((transaction) => {
+        if (transaction.outboxPhase) return [transaction]
+        const selected = selectedById.get(transaction.id)
+        return selected ? [selected] : []
+      })
 
       // The retry hook is user code and may synchronously revoke replay rights.
       if (!this.offlineExecutor.isOfflineEnabled) return
@@ -255,15 +338,18 @@ export class TransactionExecutor {
         this.scheduler.schedule(transaction),
       )
 
-      const retainedIds = new Set(filteredTransactions.map(({ id }) => id))
-      removedIds = transactions
-        .filter(({ id }) => !retainedIds.has(id))
+      removedIds = providerPending
+        .filter(({ id }) => !selectedById.has(id))
         .map(({ id }) => id)
       removedIds = this.scheduler.removePendingTransactions(removedIds)
 
       // Restore optimistic state for loaded transactions
       // This ensures the UI shows the optimistic data while transactions are pending
-      this.restoreOptimisticState(newlyLoaded)
+      this.restoreOptimisticState(
+        newlyLoaded.filter(
+          (transaction) => transaction.outboxPhase !== `rejection-pending`,
+        ),
+      )
 
       // Reset retry delays for all loaded transactions so they can run immediately
       this.resetRetryDelays()
@@ -374,7 +460,7 @@ export class TransactionExecutor {
     // Clear existing timer
     this.clearRetryTimer()
 
-    if (!this.canExecute()) {
+    if (this.fatalError || !this.canExecute()) {
       return
     }
 

package/src/outbox/OutboxManager.ts

@@ -6,6 +6,8 @@ import {
 import type { OfflineTransaction, StorageAdapter } from '../types'
 import type { Collection } from '@tanstack/db'
 
+export class OutboxTransactionNotFoundError extends Error {}
+
 export class OutboxManager {
   private storage: StorageAdapter
   private serializer: TransactionSerializer
@@ -158,7 +160,7 @@ export class OutboxManager {
     return withSpan(`outbox.update`, { 'transaction.id': id }, async () => {
       const existing = await this.get(id)
       if (!existing) {
-        throw new Error(`Transaction ${id} not found`)
+        throw new OutboxTransactionNotFoundError(`Transaction ${id} not found`)
       }
 
       const updated = { ...existing, ...updates }

package/src/outbox/TransactionSerializer.ts

@@ -94,6 +94,17 @@ function setDataProperty(
     })
 }
 
+function assertOutboxPhase(
+  phase: unknown,
+): asserts phase is `deletion-pending` | `rejection-pending` | undefined {
+  if (
+    phase !== undefined &&
+    phase !== `deletion-pending` &&
+    phase !== `rejection-pending`
+  )
+    throw new Error(`Unsupported transaction outbox phase`)
+}
+
 export class TransactionSerializer {
   private collections: Record<string, Collection<any, any, any, any, any>>
   private collectionIdToKey: Map<string, string>
@@ -110,6 +121,7 @@ export class TransactionSerializer {
   }
 
   serialize(transaction: OfflineTransaction): string {
+    assertOutboxPhase(transaction.outboxPhase)
     const serialized: SerializedOfflineTransaction = {
       ...transaction,
       valueEncoding: 3,
@@ -127,9 +139,11 @@ export class TransactionSerializer {
     // marker-shaped user objects; the encoding tag is not application metadata.
     const {
       valueEncoding,
+      outboxPhase,
       ...parsed
-    }: Omit<SerializedOfflineTransaction, `valueEncoding`> & {
+    }: Omit<SerializedOfflineTransaction, `valueEncoding` | `outboxPhase`> & {
       valueEncoding?: unknown
+      outboxPhase?: unknown
     } = JSON.parse(data)
     if (
       valueEncoding !== undefined &&
@@ -140,6 +154,7 @@ export class TransactionSerializer {
         `Unsupported transaction value encoding: ${valueEncoding}`,
       )
     }
+    assertOutboxPhase(outboxPhase)
 
     const createdAt = new Date(parsed.createdAt)
     if (isNaN(createdAt.getTime())) {
@@ -150,6 +165,7 @@ export class TransactionSerializer {
 
     return {
       ...parsed,
+      ...(outboxPhase === undefined ? {} : { outboxPhase }),
       createdAt,
       metadata:
         valueEncoding === 3

package/src/storage/IndexedDBAdapter.ts

@@ -147,6 +147,7 @@ export class IndexedDBAdapter extends BaseStorageAdapter {
       })
     } catch (error) {
       console.warn(`IndexedDB delete failed:`, error)
+      throw error
     }
   }
 

package/src/storage/LocalStorageAdapter.ts

@@ -84,7 +84,7 @@ export class LocalStorageAdapter extends BaseStorageAdapter {
       return Promise.resolve()
     } catch (error) {
       console.warn(`localStorage delete failed:`, error)
-      return Promise.resolve()
+      return Promise.reject(error)
     }
   }
 

package/src/types.ts

@@ -49,6 +49,8 @@ export interface OfflineTransaction {
   createdAt: Date
   retryCount: number
   nextAttemptAt: number
+  /** Provider work has settled; only durable outbox deletion remains. */
+  outboxPhase?: `deletion-pending` | `rejection-pending`
   lastError?: SerializedError
   metadata?: Record<string, any>
   spanContext?: SerializedSpanContext
@@ -67,6 +69,8 @@ export interface SerializedOfflineTransaction {
   createdAt: string
   retryCount: number
   nextAttemptAt: number
+  /** Absent in older records and while mutationFn may still need to run. */
+  outboxPhase?: `deletion-pending` | `rejection-pending`
   lastError?: SerializedError
   metadata?: Record<string, any>
   spanContext?: SerializedSpanContext