@baukit/sync-client 0.7.2 → 0.7.3

package/src/store.ts

@@ -0,0 +1,336 @@
+import type { SyncFailure } from './error.js';
+
+/** Sync activity, as named by the offline-readiness contract. */
+export type SyncStatus = 'idle' | 'syncing' | 'pending' | 'attention' | 'auth' | 'error';
+
+/** Progress of the initial pull that a cold start must complete. */
+export type InitialPullStatus = 'uninitialized' | 'pulling' | 'settled';
+
+/** Readiness of the local store, derived from pull progress and delivery. */
+export type LocalStoreReadiness =
+  'uninitialized' | 'pulling' | 'hydrated-empty' | 'hydrated-populated';
+
+/** Initial readiness as the offline-readiness contract names it. */
+export type InitialSyncState =
+  'unknown' | 'syncing' | 'offline-cached' | 'sync-error-cached' | 'settled';
+
+/**
+ * One rejection that needs product or user action. `entityType` and `entityId`
+ * are opaque to baukit; products name their own entities.
+ */
+export type SyncAttentionItem<
+  T = {
+    entityType: string;
+    entityId: string;
+  },
+> = T;
+
+export interface SyncStatusSnapshot<TAttention = SyncAttentionItem> {
+  status: SyncStatus;
+  lastAttemptAt: string | null;
+  lastSuccessAt: string | null;
+  /** @deprecated Use `lastSuccessAt`. This field will be removed after one release cycle. */
+  lastSyncAt: string | null;
+  error: string | null;
+  failure: SyncFailure | null;
+  retrying: boolean;
+  retryAt: string | null;
+  attention: readonly TAttention[];
+  pendingCount: number;
+  initialPullStatus: InitialPullStatus;
+  /** Increments whenever a run delivers a new authoritative snapshot. */
+  refreshRevision: number;
+  /** Set when identity or corruption makes the local store unusable. */
+  securityBlock: string | null;
+}
+
+export interface LocalStoreReadinessInput {
+  initialPullStatus: InitialPullStatus;
+  refreshRevision: number;
+  deliveredRevision: number | null;
+  hasData: boolean;
+}
+
+export interface SyncStatusHydration<TAttention = SyncAttentionItem> {
+  lastAttemptAt: string | null;
+  lastSuccessAt: string | null;
+  attention?: readonly TAttention[];
+  pendingCount?: number;
+}
+
+export interface SyncFailureUpdate {
+  /** Defaults to the store's current pending count. */
+  pendingCount?: number;
+  /** Defaults to the current time. */
+  attemptAt?: string;
+  /** Marks a retry as scheduled. Rate-limit failures use their own `retryAt`. */
+  retryAt?: string | null;
+}
+
+export interface SyncStatusStoreOptions {
+  clock?: () => string;
+}
+
+function initialSnapshot<TAttention>(): SyncStatusSnapshot<TAttention> {
+  return {
+    status: 'idle',
+    lastAttemptAt: null,
+    lastSuccessAt: null,
+    lastSyncAt: null,
+    error: null,
+    failure: null,
+    retrying: false,
+    retryAt: null,
+    attention: [],
+    pendingCount: 0,
+    initialPullStatus: 'uninitialized',
+    refreshRevision: 0,
+    securityBlock: null,
+  };
+}
+
+/**
+ * Maps pull progress and snapshot delivery onto local-store readiness.
+ *
+ * A consumer that has not yet received the newest `refreshRevision` still reads
+ * stale data, so it stays `pulling` rather than claiming a settled empty state.
+ */
+export function deriveLocalStoreReadiness({
+  initialPullStatus,
+  refreshRevision,
+  deliveredRevision,
+  hasData,
+}: LocalStoreReadinessInput): LocalStoreReadiness {
+  if (initialPullStatus === 'uninitialized') return 'uninitialized';
+  if (initialPullStatus === 'pulling' || deliveredRevision !== refreshRevision) return 'pulling';
+  return hasData ? 'hydrated-populated' : 'hydrated-empty';
+}
+
+/** Maps a snapshot onto the contract's initial-readiness vocabulary. */
+export function deriveInitialSyncState({
+  initialPullStatus,
+  lastSuccessAt,
+  status,
+  failure,
+}: Pick<
+  SyncStatusSnapshot,
+  'failure' | 'initialPullStatus' | 'lastSuccessAt' | 'status'
+>): InitialSyncState {
+  if (initialPullStatus === 'uninitialized') return 'unknown';
+  if (initialPullStatus === 'pulling') return 'syncing';
+  if (lastSuccessAt === null && failure !== null) {
+    return failure.kind === 'network' ? 'offline-cached' : 'sync-error-cached';
+  }
+  if (status === 'error' && lastSuccessAt === null) return 'sync-error-cached';
+  return 'settled';
+}
+
+function settledStatus(attentionCount: number, pendingCount: number): SyncStatus {
+  if (attentionCount > 0) return 'attention';
+  return pendingCount > 0 ? 'pending' : 'idle';
+}
+
+/**
+ * Observable sync status, with no React and no state library.
+ *
+ * Products subscribe directly, or adapt {@link SyncStatusStore.subscribe} and
+ * {@link SyncStatusStore.getSnapshot} to whatever their UI layer expects.
+ */
+export class SyncStatusStore<TAttention = SyncAttentionItem> {
+  private snapshot: SyncStatusSnapshot<TAttention> = initialSnapshot();
+  private readonly listeners = new Set<(snapshot: SyncStatusSnapshot<TAttention>) => void>();
+  private readonly clock: () => string;
+
+  constructor(options: SyncStatusStoreOptions = {}) {
+    this.clock = options.clock ?? (() => new Date().toISOString());
+  }
+
+  getSnapshot(): SyncStatusSnapshot<TAttention> {
+    return this.snapshot;
+  }
+
+  subscribe(listener: (snapshot: SyncStatusSnapshot<TAttention>) => void): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  setSyncing(attemptAt = this.clock()): void {
+    this.set((state) => ({
+      status: 'syncing',
+      lastAttemptAt: attemptAt,
+      error: null,
+      retryAt: null,
+      initialPullStatus: state.lastSuccessAt === null ? 'pulling' : 'settled',
+    }));
+  }
+
+  setIdle(successAt: string): void {
+    this.set((state) => ({
+      status: 'idle',
+      lastAttemptAt: successAt,
+      lastSuccessAt: successAt,
+      error: null,
+      failure: null,
+      retrying: false,
+      retryAt: null,
+      attention: [],
+      pendingCount: 0,
+      initialPullStatus: 'settled',
+      refreshRevision: state.refreshRevision + 1,
+    }));
+  }
+
+  setAttention(items: readonly TAttention[], pendingCount: number): void {
+    this.set((state) => ({
+      status: items.length > 0 ? 'attention' : 'pending',
+      error: null,
+      failure: null,
+      retrying: false,
+      retryAt: null,
+      attention: [...items],
+      pendingCount,
+      initialPullStatus: 'settled',
+      refreshRevision: state.refreshRevision + 1,
+    }));
+  }
+
+  setAuth(message: string, update: SyncFailureUpdate = {}): void {
+    this.setFailure({ kind: 'auth' }, message, update);
+  }
+
+  setFailure(failure: SyncFailure, message: string, update: SyncFailureUpdate = {}): void {
+    this.set((state) => {
+      const nextPendingCount = update.pendingCount ?? state.pendingCount;
+      const retryAt = failure.kind === 'rate_limited' ? failure.retryAt : (update.retryAt ?? null);
+      return {
+        status:
+          failure.kind === 'auth'
+            ? 'auth'
+            : state.attention.length > 0
+              ? 'attention'
+              : nextPendingCount > 0
+                ? 'pending'
+                : 'error',
+        lastAttemptAt: update.attemptAt ?? this.clock(),
+        error: message,
+        failure,
+        retrying: retryAt !== null,
+        retryAt,
+        pendingCount: nextPendingCount,
+        initialPullStatus: 'settled',
+        refreshRevision: state.refreshRevision + 1,
+      };
+    });
+  }
+
+  setRetrying(retryAt: string, pendingCount?: number): void {
+    this.set((state) => {
+      const nextPendingCount = pendingCount ?? state.pendingCount;
+      return {
+        status:
+          state.attention.length > 0 ? 'attention' : nextPendingCount > 0 ? 'pending' : 'error',
+        retrying: true,
+        retryAt,
+        pendingCount: nextPendingCount,
+      };
+    });
+  }
+
+  /** @deprecated Use `setFailure` with typed metadata. */
+  setError(message: string, pendingCount?: number): void {
+    this.setFailure(
+      { kind: 'network' },
+      message,
+      pendingCount === undefined ? {} : { pendingCount },
+    );
+  }
+
+  /** Restores persisted status on a cold start, before the first run. */
+  hydrate(hydration: SyncStatusHydration<TAttention>): void;
+  /** @deprecated Pass a `SyncStatusHydration` object with both timestamps. */
+  hydrate(lastSyncAt: string | null, items?: readonly TAttention[], pendingCount?: number): void;
+  hydrate(
+    hydrationOrLastSyncAt: SyncStatusHydration<TAttention> | string | null,
+    legacyItems: readonly TAttention[] = [],
+    legacyPendingCount = 0,
+  ): void {
+    const hydration: SyncStatusHydration<TAttention> =
+      typeof hydrationOrLastSyncAt === 'object' && hydrationOrLastSyncAt !== null
+        ? hydrationOrLastSyncAt
+        : {
+            lastAttemptAt: hydrationOrLastSyncAt,
+            lastSuccessAt: hydrationOrLastSyncAt,
+            attention: legacyItems,
+            pendingCount: legacyPendingCount,
+          };
+    const items = hydration.attention ?? [];
+    const pendingCount = hydration.pendingCount ?? 0;
+    this.set((state) => ({
+      status: settledStatus(items.length, pendingCount),
+      lastAttemptAt: hydration.lastAttemptAt,
+      lastSuccessAt: hydration.lastSuccessAt,
+      error: null,
+      failure: null,
+      retrying: false,
+      retryAt: null,
+      attention: [...items],
+      pendingCount,
+      initialPullStatus: hydration.lastSuccessAt === null ? 'uninitialized' : 'settled',
+      refreshRevision: state.refreshRevision + 1,
+    }));
+  }
+
+  reset(): void {
+    this.set(() => initialSnapshot());
+  }
+
+  setSecurityBlock(
+    message: string,
+    failure: Extract<SyncFailure, { kind: 'partition_mismatch' | 'local_apply' }> = {
+      kind: 'local_apply',
+    },
+  ): void {
+    this.set(() => ({
+      status: 'error',
+      lastAttemptAt: this.clock(),
+      error: message,
+      failure,
+      retrying: false,
+      retryAt: null,
+      initialPullStatus: 'settled',
+      securityBlock: message,
+    }));
+  }
+
+  resumeAfterAuth(): void {
+    this.set((state) => ({
+      status: settledStatus(state.attention.length, state.pendingCount),
+      error: null,
+      failure: null,
+      retrying: false,
+      retryAt: null,
+    }));
+  }
+
+  private set(
+    update: (state: SyncStatusSnapshot<TAttention>) => Partial<SyncStatusSnapshot<TAttention>>,
+  ): void {
+    const next = { ...this.snapshot, ...update(this.snapshot) };
+    this.snapshot = { ...next, lastSyncAt: next.lastSuccessAt };
+    this.listeners.forEach((listener) => {
+      listener(this.snapshot);
+    });
+  }
+}
+
+/** Write-only view a sync run uses to report progress. */
+export interface SyncStatusSink<TAttention = SyncAttentionItem> {
+  setSyncing(attemptAt?: string): void;
+  setIdle(successAt: string): void;
+  setAttention(items: readonly TAttention[], pendingCount: number): void;
+  setAuth(message: string, update?: SyncFailureUpdate): void;
+  setFailure(failure: SyncFailure, message: string, update?: SyncFailureUpdate): void;
+  setRetrying(retryAt: string, pendingCount?: number): void;
+}

package/src/transport.test.ts

@@ -0,0 +1,360 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  SyncAuthError,
+  SyncLocalApplyError,
+  SyncNetworkError,
+  SyncPartitionMismatchError,
+  SyncPayloadCompatibilityError,
+  SyncRateLimitError,
+  SyncServerError,
+  SyncTransportError,
+  syncFailureFromError,
+} from './error.js';
+import {
+  commitCursorAfterLocalTransaction,
+  parseRetryAfter,
+  SyncTransport,
+  validatePullPage,
+  type PullPagePosition,
+  type SyncFetch,
+  type SyncFetchResponse,
+  type SyncPrebuiltRequest,
+} from './transport.js';
+
+function response(status: number, body: string, retryAfter?: string): SyncFetchResponse {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    headers: {
+      get: (name) => (name.toLowerCase() === 'retry-after' ? (retryAfter ?? null) : null),
+    },
+    text: () => Promise.resolve(body),
+  };
+}
+
+function transport(fetch: SyncFetch, overrides: { partitionHeader?: string } = {}): SyncTransport {
+  return new SyncTransport({
+    baseUrl: 'https://api.example.test/',
+    fetch,
+    authHeaders: () => ({ Authorization: 'Bearer token' }),
+    ...overrides,
+  });
+}
+
+describe('SyncTransport', () => {
+  it('sends auth headers, the partition header, and a JSON body', async () => {
+    const fetch = vi.fn<SyncFetch>(() => Promise.resolve(response(200, '{"accepted":1}')));
+
+    const result = await transport(fetch).request<{ accepted: number }>('/sync/push', {
+      method: 'POST',
+      body: { changes: [] },
+      partitionId: 'partition-1',
+    });
+
+    expect(result).toEqual({ accepted: 1 });
+    expect(fetch).toHaveBeenCalledWith('https://api.example.test/sync/push', {
+      method: 'POST',
+      headers: {
+        Authorization: 'Bearer token',
+        'Content-Type': 'application/json',
+        'X-Partition-Id': 'partition-1',
+      },
+      body: '{"changes":[]}',
+    });
+  });
+
+  it('awaits an async auth header provider', async () => {
+    const fetch = vi.fn<SyncFetch>(() => Promise.resolve(response(200, '{}')));
+    const client = new SyncTransport({
+      baseUrl: 'https://api.example.test',
+      fetch,
+      authHeaders: () => Promise.resolve({ Authorization: 'Bearer fresh' }),
+    });
+
+    await client.request('/sync/pull');
+
+    expect(fetch.mock.calls[0]?.[1]?.headers).toEqual({ Authorization: 'Bearer fresh' });
+  });
+
+  it('delegates a relative request to a prebuilt product API client', async () => {
+    const request = vi.fn(() => Promise.resolve({ accepted: 1 }));
+    const client = new SyncTransport({ request: request as SyncPrebuiltRequest });
+
+    const result = await client.request<{ accepted: number }>('/sync/push', {
+      method: 'POST',
+      query: { limit: '50' },
+      body: { changes: [] },
+      partitionId: 'partition-1',
+    });
+
+    expect(result).toEqual({ accepted: 1 });
+    expect(request).toHaveBeenCalledWith('/sync/push?limit=50', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Partition-Id': 'partition-1',
+      },
+      body: '{"changes":[]}',
+    });
+  });
+
+  it('leaves a prebuilt request function in charge of its errors', async () => {
+    const failure = new Error('session recovery failed');
+    const request: SyncPrebuiltRequest = () => Promise.reject(failure);
+    const client = new SyncTransport({ request });
+
+    await expect(client.request('/sync/pull')).rejects.toBe(failure);
+  });
+
+  it('appends query parameters and honours a custom partition header', async () => {
+    const fetch = vi.fn<SyncFetch>(() => Promise.resolve(response(200, '{}')));
+
+    await transport(fetch, { partitionHeader: 'X-Profile' }).request('/sync/pull', {
+      query: { sinceRevision: '12', limit: '500' },
+      partitionId: 'profile-9',
+    });
+
+    expect(fetch.mock.calls[0]?.[0]).toBe(
+      'https://api.example.test/sync/pull?sinceRevision=12&limit=500',
+    );
+    expect(fetch.mock.calls[0]?.[1]?.headers).toMatchObject({ 'X-Profile': 'profile-9' });
+  });
+
+  it('omits the partition header when no partition is supplied', async () => {
+    const fetch = vi.fn<SyncFetch>(() => Promise.resolve(response(200, '{}')));
+
+    await transport(fetch).request('/sync/pull', { partitionId: null });
+
+    expect(fetch.mock.calls[0]?.[1]?.headers).toEqual({ Authorization: 'Bearer token' });
+  });
+
+  it('maps 401 to a non-retryable auth error', async () => {
+    const fetch: SyncFetch = () =>
+      Promise.resolve(response(401, '{"message":"token expired","code":"unauthorized"}'));
+
+    const error = await transport(fetch)
+      .request('/sync/push')
+      .catch((caught: unknown) => caught);
+
+    expect(error).toBeInstanceOf(SyncAuthError);
+    expect((error as SyncAuthError).retryable).toBe(false);
+    expect((error as SyncAuthError).message).toBe('token expired');
+  });
+
+  it('maps the partition mismatch code ahead of the status', async () => {
+    const fetch: SyncFetch = () =>
+      Promise.resolve(
+        response(
+          401,
+          '{"code":"partition_identity_mismatch","message":"this database was erased"}',
+        ),
+      );
+
+    const error = await transport(fetch)
+      .request('/sync/push')
+      .catch((caught: unknown) => caught);
+
+    expect(error).toBeInstanceOf(SyncPartitionMismatchError);
+    expect((error as SyncPartitionMismatchError).retryable).toBe(false);
+  });
+
+  it.each([408, 429, 500, 503])('treats %i as retryable', async (status) => {
+    const fetch: SyncFetch = () => Promise.resolve(response(status, '{}'));
+
+    const error = await transport(fetch)
+      .request('/sync/push')
+      .catch((caught: unknown) => caught);
+
+    expect(error).toBeInstanceOf(SyncTransportError);
+    expect((error as SyncTransportError).retryable).toBe(true);
+  });
+
+  it('maps 429 to a typed rate-limit error with the parsed retry time', async () => {
+    const now = Date.parse('2026-08-22T10:00:00Z');
+    const fetch: SyncFetch = () => Promise.resolve(response(429, '{"message":"slow down"}', '17'));
+    const client = new SyncTransport({
+      baseUrl: 'https://api.example.test',
+      fetch,
+      authHeaders: () => ({}),
+      now: () => now,
+    });
+
+    const error = await client.request('/sync/pull').catch((caught: unknown) => caught);
+
+    expect(error).toBeInstanceOf(SyncRateLimitError);
+    expect(error).toMatchObject({
+      kind: 'rate_limited',
+      retryable: true,
+      retryAfter: '17',
+      retryAt: '2026-08-22T10:00:17.000Z',
+    });
+    expect(error).not.toBeInstanceOf(SyncNetworkError);
+  });
+
+  it.each([400, 404, 409, 422])('treats %i as non-retryable', async (status) => {
+    const fetch: SyncFetch = () => Promise.resolve(response(status, '{}'));
+
+    const error = await transport(fetch)
+      .request('/sync/push')
+      .catch((caught: unknown) => caught);
+
+    expect(error).toBeInstanceOf(SyncTransportError);
+    expect(error).toBeInstanceOf(SyncServerError);
+    expect((error as SyncTransportError).retryable).toBe(false);
+    expect((error as SyncTransportError).message).toBe(
+      `sync request failed with status ${String(status)}`,
+    );
+  });
+
+  it('maps a network failure to a retryable error carrying the cause', async () => {
+    const cause = new Error('network down');
+    const fetch: SyncFetch = () => Promise.reject(cause);
+
+    const error = await transport(fetch)
+      .request('/sync/push')
+      .catch((caught: unknown) => caught);
+
+    expect(error).toBeInstanceOf(SyncTransportError);
+    expect(error).toBeInstanceOf(SyncNetworkError);
+    expect((error as SyncTransportError).retryable).toBe(true);
+    expect((error as SyncTransportError).message).toBe('network down');
+    expect((error as SyncTransportError).cause).toBe(cause);
+  });
+
+  it('maps an unparsable success body to a non-retryable error', async () => {
+    const fetch: SyncFetch = () => Promise.resolve(response(200, 'not json'));
+
+    const error = await transport(fetch)
+      .request('/sync/push')
+      .catch((caught: unknown) => caught);
+
+    expect(error).toBeInstanceOf(SyncPayloadCompatibilityError);
+    expect(error).toBeInstanceOf(SyncTransportError);
+    expect((error as SyncTransportError).retryable).toBe(false);
+  });
+
+  it('falls back to a status message when the error body is not JSON', async () => {
+    const fetch: SyncFetch = () => Promise.resolve(response(500, '<html>gateway</html>'));
+
+    const error = await transport(fetch)
+      .request('/sync/push')
+      .catch((caught: unknown) => caught);
+
+    expect((error as SyncTransportError).message).toBe('sync request failed with status 500');
+    expect((error as SyncTransportError).retryable).toBe(true);
+  });
+
+  it('accepts an empty success body', async () => {
+    const fetch: SyncFetch = () => Promise.resolve(response(204, ''));
+
+    await expect(transport(fetch).request('/sync/ack')).resolves.toBeUndefined();
+  });
+});
+
+describe('parseRetryAfter', () => {
+  const now = Date.parse('2026-08-22T10:00:00Z');
+  const fallback = '2026-08-22T10:00:42.000Z';
+
+  it('accepts delta seconds', () => {
+    expect(parseRetryAfter('12', { now, fallbackMs: 42_000 })).toBe('2026-08-22T10:00:12.000Z');
+  });
+
+  it('accepts an HTTP date', () => {
+    expect(parseRetryAfter('Sat, 22 Aug 2026 10:02:00 GMT', { now, fallbackMs: 42_000 })).toBe(
+      '2026-08-22T10:02:00.000Z',
+    );
+  });
+
+  it.each([
+    ['a past date', 'Sat, 22 Aug 2026 09:59:00 GMT'],
+    ['a negative delta', '-5'],
+    ['garbage', 'later'],
+    ['a missing header', null],
+  ])('uses the injected fallback for %s', (_label, value) => {
+    expect(parseRetryAfter(value, { now, fallbackMs: 42_000 })).toBe(fallback);
+  });
+});
+
+describe('syncFailureFromError', () => {
+  it('keeps every failure category distinct', () => {
+    const retryAt = '2026-08-22T10:02:00.000Z';
+
+    expect([
+      syncFailureFromError(new SyncAuthError('auth')),
+      syncFailureFromError(new SyncPartitionMismatchError('partition')),
+      syncFailureFromError(new SyncRateLimitError('limited', retryAt, '120')),
+      syncFailureFromError(new SyncNetworkError('offline')),
+      syncFailureFromError(new SyncServerError('server', true)),
+      syncFailureFromError(new SyncPayloadCompatibilityError('payload')),
+      syncFailureFromError(new SyncLocalApplyError('apply')),
+    ]).toEqual([
+      { kind: 'auth' },
+      { kind: 'partition_mismatch' },
+      { kind: 'rate_limited', retryAt },
+      { kind: 'network' },
+      { kind: 'server' },
+      { kind: 'payload_compatibility' },
+      { kind: 'local_apply' },
+    ]);
+  });
+});
+
+describe('validatePullPage', () => {
+  const compare = (left: number, right: number): number => left - right;
+  const validate = (current: number, page: PullPagePosition<number>) =>
+    validatePullPage(current, page, compare);
+
+  it('returns a progressing page', () => {
+    const page = { nextCursor: 4, hasMore: true, changes: ['row'] };
+
+    expect(validate(3, page)).toBe(page);
+  });
+
+  it('rejects a regressing cursor', () => {
+    expect(() => validate(3, { nextCursor: 2, hasMore: false })).toThrow(
+      SyncPayloadCompatibilityError,
+    );
+  });
+
+  it('rejects hasMore without progress instead of allowing another loop', () => {
+    expect(() => validate(3, { nextCursor: 3, hasMore: true })).toThrow(
+      SyncPayloadCompatibilityError,
+    );
+  });
+});
+
+describe('commitCursorAfterLocalTransaction', () => {
+  it('commits the cursor after the local transaction resolves', async () => {
+    const calls: string[] = [];
+
+    const result = await commitCursorAfterLocalTransaction({
+      nextCursor: 8,
+      transaction: () => {
+        calls.push('transaction');
+        return Promise.resolve('applied');
+      },
+      commitCursor: (cursor) => {
+        calls.push(`cursor:${String(cursor)}`);
+      },
+    });
+
+    expect(result).toBe('applied');
+    expect(calls).toEqual(['transaction', 'cursor:8']);
+  });
+
+  it('leaves the cursor unchanged when the local transaction fails', async () => {
+    let cursor = 3;
+
+    const task = commitCursorAfterLocalTransaction({
+      nextCursor: 8,
+      transaction: () => Promise.reject(new Error('constraint failed')),
+      commitCursor: (nextCursor) => {
+        cursor = nextCursor;
+      },
+    });
+
+    await expect(task).rejects.toBeInstanceOf(SyncLocalApplyError);
+    expect(cursor).toBe(3);
+  });
+});