SyncCoordinator | @sheetwrite/core

@sheetwrite/coreclass

Deterministic, transport-neutral optimistic sync. Local rendering is never blocked: changes queue immediately, while hosts explicitly call sendNext or retry to perform network work.

Package: @sheetwrite/core
Source: packages/core/src/sync.ts#L239

Members 18

constructor

constructor(grid: Gridinterface Grid {
  readonly store: Store;
  readonly actions: GridActions;
  setActiveSheet(id: SheetId): void;
  scrollToCell(addr: CellAddress): void;
  getCellAtPoint(
    clientX: number,
    clientY: number,
  ): CellAddress | null;
  getActiveSheet(): SheetId;
  getCellInput(row: number, col: number): CellInputSnapshot | null;
  getSelection(): Selection | null;
  setSelection(sel: Selection | null): void;
  setTheme(theme: Partial<Theme>): void;
  replaceTheme(theme: Partial<Theme> | undefined): void;
  // … 106 more lines — see the API reference
}interface Grid {
  readonly store: Store;
  readonly actions: GridActions;
  setActiveSheet(id: SheetId): void;
  scrollToCell(addr: CellAddress): void;
  getCellAtPoint(
    clientX: number,
    clientY: number,
  ): CellAddress | null;
  getActiveSheet(): SheetId;
  getCellInput(row: number, col: number): CellInputSnapshot | null;
  getSelection(): Selection | null;
  setSelection(sel: Selection | null): void;
  setTheme(theme: Partial<Theme>): void;
  replaceTheme(theme: Partial<Theme> | undefined): void;
  // … 106 more lines — see the API reference
}interface Grid {
  readonly store: Store;
  readonly actions: GridActions;
  setActiveSheet(
    id: SheetId,
  ): void;
  scrollToCell(
    addr: CellAddress,
  ): void;
  getCellAtPoint(
    clientX: number,
    clientY: number,
  ): CellAddress | null;
  getActiveSheet(): SheetId;
  getCellInput(
    row: number,
    col: number,
  ): CellInputSnapshot | null;
  getSelection(): Selection | null;
  // … 229 more lines — see the API reference
}Imperative grid handle for document commands, events, rendering, and teardown.API reference →, adapter: PersistenceAdapterinterface PersistenceAdapter {
  load(
    documentId: string,
    signal?: AbortSignal,
  ): Promise<WorkbookSnapshot>;
  commit(
    request: PersistenceCommitRequest,
  ): Promise<PersistenceCommitResponse>;
}interface PersistenceAdapter {
  load(
    documentId: string,
    signal?: AbortSignal,
  ): Promise<WorkbookSnapshot>;
  commit(
    request: PersistenceCommitRequest,
  ): Promise<PersistenceCommitResponse>;
}interface PersistenceAdapter {
  load(
    documentId: string,
    signal?: AbortSignal,
  ): Promise<WorkbookSnapshot>;
  commit(
    request: PersistenceCommitRequest,
  ): Promise<PersistenceCommitResponse>;
}Host load and commit contract for versioned workbook persistence.API reference →, options: SyncCoordinatorOptionsinterface SyncCoordinatorOptions {
  documentId: string;
  serverVersion: number;
  createMutationId?: () => string;
  pendingStorage?: PendingCommitStorage;
  initialConnection?: "offline" | "online";
  recoverVersionGap?: (
    request: SyncVersionGapRequest,
  ) => Promise<readonly VersionedOperation[] | WorkbookSnapshot>;
  limits?: Partial<SyncCoordinatorLimits>;
}interface SyncCoordinatorOptions {
  documentId: string;
  serverVersion: number;
  createMutationId?: () => string;
  pendingStorage?: PendingCommitStorage;
  initialConnection?: "offline" | "online";
  recoverVersionGap?: (
    request: SyncVersionGapRequest,
  ) => Promise<readonly VersionedOperation[] | WorkbookSnapshot>;
  limits?: Partial<SyncCoordinatorLimits>;
}interface SyncCoordinatorOptions {
  documentId: string;
  serverVersion: number;
  createMutationId?: () => string;
  pendingStorage?: PendingCommitStorage;
  initialConnection?:
    "offline" | "online";
  recoverVersionGap?: (
    request: SyncVersionGapRequest,
  ) => Promise<
    | readonly VersionedOperation[]
    | WorkbookSnapshot
  >;
  limits?: Partial<SyncCoordinatorLimits>;
}Document, version, durability, and online options for synchronization.API reference →);

applyVersionedOperation

applyVersionedOperation: (operation: VersionedOperationinterface VersionedOperation {
  version: number;
  readonly operations: readonly DocumentOp[];
  clientMutationId?: string;
}interface VersionedOperation {
  version: number;
  readonly operations: readonly DocumentOp[];
  clientMutationId?: string;
}interface VersionedOperation {
  version: number;
  readonly operations: readonly DocumentOp[];
  clientMutationId?: string;
}Remote document operations paired with a contiguous server version.API reference →) => Promise<void>;

destroy

destroy: () => void;

flush

flush: () => Promise<readonly PersistenceCommitResponsetype PersistenceCommitResponse =
  | { status: "applied"; version: number; clientMutationId: string }
  | {
      status: "duplicate";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "conflict";
      currentVersion: number;
      operationsSinceBase?: readonly VersionedOperation[];
      snapshot?: WorkbookSnapshot;
    };type PersistenceCommitResponse =
  | { status: "applied"; version: number; clientMutationId: string }
  | {
      status: "duplicate";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "conflict";
      currentVersion: number;
      operationsSinceBase?: readonly VersionedOperation[];
      snapshot?: WorkbookSnapshot;
    };type PersistenceCommitResponse =
  | {
      status: "applied";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "duplicate";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "conflict";
      currentVersion: number;
      operationsSinceBase?: readonly VersionedOperation[];
      snapshot?: WorkbookSnapshot;
    };Applied, duplicate, or conflict acknowledgement from persistence. applied confirms the submitted operations unchanged; normalization must conflict.API reference →[]>;

handleResponse Public for transports that deliver responses independently of send promises.

handleResponse: (response: PersistenceCommitResponsetype PersistenceCommitResponse =
  | { status: "applied"; version: number; clientMutationId: string }
  | {
      status: "duplicate";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "conflict";
      currentVersion: number;
      operationsSinceBase?: readonly VersionedOperation[];
      snapshot?: WorkbookSnapshot;
    };type PersistenceCommitResponse =
  | { status: "applied"; version: number; clientMutationId: string }
  | {
      status: "duplicate";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "conflict";
      currentVersion: number;
      operationsSinceBase?: readonly VersionedOperation[];
      snapshot?: WorkbookSnapshot;
    };type PersistenceCommitResponse =
  | {
      status: "applied";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "duplicate";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "conflict";
      currentVersion: number;
      operationsSinceBase?: readonly VersionedOperation[];
      snapshot?: WorkbookSnapshot;
    };Applied, duplicate, or conflict acknowledgement from persistence. applied confirms the submitted operations unchanged; normalization must conflict.API reference →, requestedMutationId?: string) => Promise<void>;

on

on: (listener: SyncListener) => () => void;

pendingCommits

pendingCommits: () => readonly SyncMutationRecordinterface SyncMutationRecord {
  status: SyncMutationStatus;
  documentId: string;
  baseVersion: number;
  clientMutationId: string;
  readonly operations: readonly DocumentOp[];
}interface SyncMutationRecord {
  status: SyncMutationStatus;
  documentId: string;
  baseVersion: number;
  clientMutationId: string;
  readonly operations: readonly DocumentOp[];
}interface SyncMutationRecord {
  status: SyncMutationStatus;
  documentId: string;
  baseVersion: number;
  clientMutationId: string;
  readonly operations: readonly DocumentOp[];
}Pending commit paired with its current synchronization status.API reference →[];

pendingCount

pendingCount: number;

ready Resolves after durable work is restored and every startup commit is visible locally.

ready: () => Promise<void>;

resumeAfterReload Resume only after the host remounted/reloaded document state and reapplied retained local operations.

resumeAfterReload: (snapshot: WorkbookSnapshotinterface WorkbookSnapshot {
  schemaVersion: 1;
  documentId?: string;
  version?: number;
  workbook: {
    activeSheet: SheetId;
    namedRanges?: NamedRangeSnapshot[];
  };
  sheets: SheetSnapshot[];
}interface WorkbookSnapshot {
  schemaVersion: 1;
  documentId?: string;
  version?: number;
  workbook: {
    activeSheet: SheetId;
    namedRanges?: NamedRangeSnapshot[];
  };
  sheets: SheetSnapshot[];
}interface WorkbookSnapshot {
  schemaVersion: 1;
  documentId?: string;
  version?: number;
  workbook: {
    activeSheet: SheetId;
    namedRanges?: NamedRangeSnapshot[];
  };
  sheets: SheetSnapshot[];
}Schema-versioned serializable workbook document.API reference →) => Promise<void>;

Resume only after the host remounted/reloaded document state and reapplied retained local operations. No lossy structural merge is attempted here.

retry Explicit retry; the original mutation ID and durable record are retained.

retry: (clientMutationId: string) => Promise<PersistenceCommitResponsetype PersistenceCommitResponse =
  | { status: "applied"; version: number; clientMutationId: string }
  | {
      status: "duplicate";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "conflict";
      currentVersion: number;
      operationsSinceBase?: readonly VersionedOperation[];
      snapshot?: WorkbookSnapshot;
    };type PersistenceCommitResponse =
  | { status: "applied"; version: number; clientMutationId: string }
  | {
      status: "duplicate";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "conflict";
      currentVersion: number;
      operationsSinceBase?: readonly VersionedOperation[];
      snapshot?: WorkbookSnapshot;
    };type PersistenceCommitResponse =
  | {
      status: "applied";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "duplicate";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "conflict";
      currentVersion: number;
      operationsSinceBase?: readonly VersionedOperation[];
      snapshot?: WorkbookSnapshot;
    };Applied, duplicate, or conflict acknowledgement from persistence. applied confirms the submitted operations unchanged; normalization must conflict.API reference → | null>;

retryPersistence

retryPersistence: (clientMutationId: string) => Promise<boolean>;

send

send: (clientMutationId: string) => Promise<PersistenceCommitResponsetype PersistenceCommitResponse =
  | { status: "applied"; version: number; clientMutationId: string }
  | {
      status: "duplicate";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "conflict";
      currentVersion: number;
      operationsSinceBase?: readonly VersionedOperation[];
      snapshot?: WorkbookSnapshot;
    };type PersistenceCommitResponse =
  | { status: "applied"; version: number; clientMutationId: string }
  | {
      status: "duplicate";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "conflict";
      currentVersion: number;
      operationsSinceBase?: readonly VersionedOperation[];
      snapshot?: WorkbookSnapshot;
    };type PersistenceCommitResponse =
  | {
      status: "applied";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "duplicate";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "conflict";
      currentVersion: number;
      operationsSinceBase?: readonly VersionedOperation[];
      snapshot?: WorkbookSnapshot;
    };Applied, duplicate, or conflict acknowledgement from persistence. applied confirms the submitted operations unchanged; normalization must conflict.API reference → | null>;

sendNext

sendNext: () => Promise<PersistenceCommitResponsetype PersistenceCommitResponse =
  | { status: "applied"; version: number; clientMutationId: string }
  | {
      status: "duplicate";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "conflict";
      currentVersion: number;
      operationsSinceBase?: readonly VersionedOperation[];
      snapshot?: WorkbookSnapshot;
    };type PersistenceCommitResponse =
  | { status: "applied"; version: number; clientMutationId: string }
  | {
      status: "duplicate";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "conflict";
      currentVersion: number;
      operationsSinceBase?: readonly VersionedOperation[];
      snapshot?: WorkbookSnapshot;
    };type PersistenceCommitResponse =
  | {
      status: "applied";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "duplicate";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "conflict";
      currentVersion: number;
      operationsSinceBase?: readonly VersionedOperation[];
      snapshot?: WorkbookSnapshot;
    };Applied, duplicate, or conflict acknowledgement from persistence. applied confirms the submitted operations unchanged; normalization must conflict.API reference → | null>;

serverVersion

serverVersion: number;

setOnline Update connectivity. Reconnection drains durable work in order; going offline aborts in-flight requests so retries retain their mutation IDs.

setOnline: (online: boolean) => void;

state

state: SyncStateSnapshotinterface SyncStateSnapshot {
  connection: SyncConnectionState;
  activity: SyncActivityState;
  pendingCount: number;
  pendingOperations: number;
  pendingEncodedBytes: number;
  pendingCapacity: SyncPendingCapacityState;
  serverVersion: number;
}interface SyncStateSnapshot {
  connection: SyncConnectionState;
  activity: SyncActivityState;
  pendingCount: number;
  pendingOperations: number;
  pendingEncodedBytes: number;
  pendingCapacity: SyncPendingCapacityState;
  serverVersion: number;
}interface SyncStateSnapshot {
  connection: SyncConnectionState;
  activity: SyncActivityState;
  pendingCount: number;
  pendingOperations: number;
  pendingEncodedBytes: number;
  pendingCapacity: SyncPendingCapacityState;
  serverVersion: number;
}Immutable observable synchronization state.API reference →;

subscribe

subscribe: (source: RemoteOperationSourceinterface RemoteOperationSource {
  subscribe(
    listener: (
      operation: VersionedOperation,
    ) => void | Promise<void>,
    signal?: AbortSignal,
  ): undefined | (() => void);
}interface RemoteOperationSource {
  subscribe(
    listener: (
      operation: VersionedOperation,
    ) => void | Promise<void>,
    signal?: AbortSignal,
  ): undefined | (() => void);
}interface RemoteOperationSource {
  subscribe(
    listener: (
      operation: VersionedOperation,
    ) => void | Promise<void>,
    signal?: AbortSignal,
  ): undefined | (() => void);
}Host subscription contract for ordered versioned operations. Sources that can pause intake should await the listener promise to preserve backpressure.API reference → | AsyncIterable<VersionedOperationinterface VersionedOperation {
  version: number;
  readonly operations: readonly DocumentOp[];
  clientMutationId?: string;
}interface VersionedOperation {
  version: number;
  readonly operations: readonly DocumentOp[];
  clientMutationId?: string;
}interface VersionedOperation {
  version: number;
  readonly operations: readonly DocumentOp[];
  clientMutationId?: string;
}Remote document operations paired with a contiguous server version.API reference →>) => () => void

Declaration

View full TypeScript declaration

class SyncCoordinator {
  constructor(
    grid: Gridinterface Grid {
  readonly store: Store;
  readonly actions: GridActions;
  setActiveSheet(id: SheetId): void;
  scrollToCell(addr: CellAddress): void;
  getCellAtPoint(
    clientX: number,
    clientY: number,
  ): CellAddress | null;
  getActiveSheet(): SheetId;
  getCellInput(row: number, col: number): CellInputSnapshot | null;
  getSelection(): Selection | null;
  setSelection(sel: Selection | null): void;
  setTheme(theme: Partial<Theme>): void;
  replaceTheme(theme: Partial<Theme> | undefined): void;
  // … 106 more lines — see the API reference
}interface Grid {
  readonly store: Store;
  readonly actions: GridActions;
  setActiveSheet(id: SheetId): void;
  scrollToCell(addr: CellAddress): void;
  getCellAtPoint(
    clientX: number,
    clientY: number,
  ): CellAddress | null;
  getActiveSheet(): SheetId;
  getCellInput(row: number, col: number): CellInputSnapshot | null;
  getSelection(): Selection | null;
  setSelection(sel: Selection | null): void;
  setTheme(theme: Partial<Theme>): void;
  replaceTheme(theme: Partial<Theme> | undefined): void;
  // … 106 more lines — see the API reference
}interface Grid {
  readonly store: Store;
  readonly actions: GridActions;
  setActiveSheet(
    id: SheetId,
  ): void;
  scrollToCell(
    addr: CellAddress,
  ): void;
  getCellAtPoint(
    clientX: number,
    clientY: number,
  ): CellAddress | null;
  getActiveSheet(): SheetId;
  getCellInput(
    row: number,
    col: number,
  ): CellInputSnapshot | null;
  getSelection(): Selection | null;
  // … 229 more lines — see the API reference
}Imperative grid handle for document commands, events, rendering, and teardown.API reference →,
    adapter: PersistenceAdapterinterface PersistenceAdapter {
  load(
    documentId: string,
    signal?: AbortSignal,
  ): Promise<WorkbookSnapshot>;
  commit(
    request: PersistenceCommitRequest,
  ): Promise<PersistenceCommitResponse>;
}interface PersistenceAdapter {
  load(
    documentId: string,
    signal?: AbortSignal,
  ): Promise<WorkbookSnapshot>;
  commit(
    request: PersistenceCommitRequest,
  ): Promise<PersistenceCommitResponse>;
}interface PersistenceAdapter {
  load(
    documentId: string,
    signal?: AbortSignal,
  ): Promise<WorkbookSnapshot>;
  commit(
    request: PersistenceCommitRequest,
  ): Promise<PersistenceCommitResponse>;
}Host load and commit contract for versioned workbook persistence.API reference →,
    options: SyncCoordinatorOptionsinterface SyncCoordinatorOptions {
  documentId: string;
  serverVersion: number;
  createMutationId?: () => string;
  pendingStorage?: PendingCommitStorage;
  initialConnection?: "offline" | "online";
  recoverVersionGap?: (
    request: SyncVersionGapRequest,
  ) => Promise<readonly VersionedOperation[] | WorkbookSnapshot>;
  limits?: Partial<SyncCoordinatorLimits>;
}interface SyncCoordinatorOptions {
  documentId: string;
  serverVersion: number;
  createMutationId?: () => string;
  pendingStorage?: PendingCommitStorage;
  initialConnection?: "offline" | "online";
  recoverVersionGap?: (
    request: SyncVersionGapRequest,
  ) => Promise<readonly VersionedOperation[] | WorkbookSnapshot>;
  limits?: Partial<SyncCoordinatorLimits>;
}interface SyncCoordinatorOptions {
  documentId: string;
  serverVersion: number;
  createMutationId?: () => string;
  pendingStorage?: PendingCommitStorage;
  initialConnection?:
    "offline" | "online";
  recoverVersionGap?: (
    request: SyncVersionGapRequest,
  ) => Promise<
    | readonly VersionedOperation[]
    | WorkbookSnapshot
  >;
  limits?: Partial<SyncCoordinatorLimits>;
}Document, version, durability, and online options for synchronization.API reference →,
  );
  applyVersionedOperation: (operation: VersionedOperationinterface VersionedOperation {
  version: number;
  readonly operations: readonly DocumentOp[];
  clientMutationId?: string;
}interface VersionedOperation {
  version: number;
  readonly operations: readonly DocumentOp[];
  clientMutationId?: string;
}interface VersionedOperation {
  version: number;
  readonly operations: readonly DocumentOp[];
  clientMutationId?: string;
}Remote document operations paired with a contiguous server version.API reference →) => Promise<void>;
  destroy: () => void;
  flush: () => Promise<readonly PersistenceCommitResponsetype PersistenceCommitResponse =
  | { status: "applied"; version: number; clientMutationId: string }
  | {
      status: "duplicate";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "conflict";
      currentVersion: number;
      operationsSinceBase?: readonly VersionedOperation[];
      snapshot?: WorkbookSnapshot;
    };type PersistenceCommitResponse =
  | { status: "applied"; version: number; clientMutationId: string }
  | {
      status: "duplicate";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "conflict";
      currentVersion: number;
      operationsSinceBase?: readonly VersionedOperation[];
      snapshot?: WorkbookSnapshot;
    };type PersistenceCommitResponse =
  | {
      status: "applied";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "duplicate";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "conflict";
      currentVersion: number;
      operationsSinceBase?: readonly VersionedOperation[];
      snapshot?: WorkbookSnapshot;
    };Applied, duplicate, or conflict acknowledgement from persistence. applied confirms the submitted operations unchanged; normalization must conflict.API reference →[]>;
  handleResponse: (
    response: PersistenceCommitResponsetype PersistenceCommitResponse =
  | { status: "applied"; version: number; clientMutationId: string }
  | {
      status: "duplicate";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "conflict";
      currentVersion: number;
      operationsSinceBase?: readonly VersionedOperation[];
      snapshot?: WorkbookSnapshot;
    };type PersistenceCommitResponse =
  | { status: "applied"; version: number; clientMutationId: string }
  | {
      status: "duplicate";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "conflict";
      currentVersion: number;
      operationsSinceBase?: readonly VersionedOperation[];
      snapshot?: WorkbookSnapshot;
    };type PersistenceCommitResponse =
  | {
      status: "applied";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "duplicate";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "conflict";
      currentVersion: number;
      operationsSinceBase?: readonly VersionedOperation[];
      snapshot?: WorkbookSnapshot;
    };Applied, duplicate, or conflict acknowledgement from persistence. applied confirms the submitted operations unchanged; normalization must conflict.API reference →,
    requestedMutationId?: string,
  ) => Promise<void>;
  on: (listener: SyncListener) => () => void;
  pendingCommits: () => readonly SyncMutationRecordinterface SyncMutationRecord {
  status: SyncMutationStatus;
  documentId: string;
  baseVersion: number;
  clientMutationId: string;
  readonly operations: readonly DocumentOp[];
}interface SyncMutationRecord {
  status: SyncMutationStatus;
  documentId: string;
  baseVersion: number;
  clientMutationId: string;
  readonly operations: readonly DocumentOp[];
}interface SyncMutationRecord {
  status: SyncMutationStatus;
  documentId: string;
  baseVersion: number;
  clientMutationId: string;
  readonly operations: readonly DocumentOp[];
}Pending commit paired with its current synchronization status.API reference →[];
  pendingCount: number;
  ready: () => Promise<void>;
  resumeAfterReload: (snapshot: WorkbookSnapshotinterface WorkbookSnapshot {
  schemaVersion: 1;
  documentId?: string;
  version?: number;
  workbook: {
    activeSheet: SheetId;
    namedRanges?: NamedRangeSnapshot[];
  };
  sheets: SheetSnapshot[];
}interface WorkbookSnapshot {
  schemaVersion: 1;
  documentId?: string;
  version?: number;
  workbook: {
    activeSheet: SheetId;
    namedRanges?: NamedRangeSnapshot[];
  };
  sheets: SheetSnapshot[];
}interface WorkbookSnapshot {
  schemaVersion: 1;
  documentId?: string;
  version?: number;
  workbook: {
    activeSheet: SheetId;
    namedRanges?: NamedRangeSnapshot[];
  };
  sheets: SheetSnapshot[];
}Schema-versioned serializable workbook document.API reference →) => Promise<void>;
  retry: (
    clientMutationId: string,
  ) => Promise<PersistenceCommitResponsetype PersistenceCommitResponse =
  | { status: "applied"; version: number; clientMutationId: string }
  | {
      status: "duplicate";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "conflict";
      currentVersion: number;
      operationsSinceBase?: readonly VersionedOperation[];
      snapshot?: WorkbookSnapshot;
    };type PersistenceCommitResponse =
  | { status: "applied"; version: number; clientMutationId: string }
  | {
      status: "duplicate";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "conflict";
      currentVersion: number;
      operationsSinceBase?: readonly VersionedOperation[];
      snapshot?: WorkbookSnapshot;
    };type PersistenceCommitResponse =
  | {
      status: "applied";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "duplicate";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "conflict";
      currentVersion: number;
      operationsSinceBase?: readonly VersionedOperation[];
      snapshot?: WorkbookSnapshot;
    };Applied, duplicate, or conflict acknowledgement from persistence. applied confirms the submitted operations unchanged; normalization must conflict.API reference → | null>;
  retryPersistence: (clientMutationId: string) => Promise<boolean>;
  send: (
    clientMutationId: string,
  ) => Promise<PersistenceCommitResponsetype PersistenceCommitResponse =
  | { status: "applied"; version: number; clientMutationId: string }
  | {
      status: "duplicate";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "conflict";
      currentVersion: number;
      operationsSinceBase?: readonly VersionedOperation[];
      snapshot?: WorkbookSnapshot;
    };type PersistenceCommitResponse =
  | { status: "applied"; version: number; clientMutationId: string }
  | {
      status: "duplicate";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "conflict";
      currentVersion: number;
      operationsSinceBase?: readonly VersionedOperation[];
      snapshot?: WorkbookSnapshot;
    };type PersistenceCommitResponse =
  | {
      status: "applied";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "duplicate";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "conflict";
      currentVersion: number;
      operationsSinceBase?: readonly VersionedOperation[];
      snapshot?: WorkbookSnapshot;
    };Applied, duplicate, or conflict acknowledgement from persistence. applied confirms the submitted operations unchanged; normalization must conflict.API reference → | null>;
  sendNext: () => Promise<PersistenceCommitResponsetype PersistenceCommitResponse =
  | { status: "applied"; version: number; clientMutationId: string }
  | {
      status: "duplicate";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "conflict";
      currentVersion: number;
      operationsSinceBase?: readonly VersionedOperation[];
      snapshot?: WorkbookSnapshot;
    };type PersistenceCommitResponse =
  | { status: "applied"; version: number; clientMutationId: string }
  | {
      status: "duplicate";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "conflict";
      currentVersion: number;
      operationsSinceBase?: readonly VersionedOperation[];
      snapshot?: WorkbookSnapshot;
    };type PersistenceCommitResponse =
  | {
      status: "applied";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "duplicate";
      version: number;
      clientMutationId: string;
    }
  | {
      status: "conflict";
      currentVersion: number;
      operationsSinceBase?: readonly VersionedOperation[];
      snapshot?: WorkbookSnapshot;
    };Applied, duplicate, or conflict acknowledgement from persistence. applied confirms the submitted operations unchanged; normalization must conflict.API reference → | null>;
  serverVersion: number;
  setOnline: (online: boolean) => void;
  state: SyncStateSnapshotinterface SyncStateSnapshot {
  connection: SyncConnectionState;
  activity: SyncActivityState;
  pendingCount: number;
  pendingOperations: number;
  pendingEncodedBytes: number;
  pendingCapacity: SyncPendingCapacityState;
  serverVersion: number;
}interface SyncStateSnapshot {
  connection: SyncConnectionState;
  activity: SyncActivityState;
  pendingCount: number;
  pendingOperations: number;
  pendingEncodedBytes: number;
  pendingCapacity: SyncPendingCapacityState;
  serverVersion: number;
}interface SyncStateSnapshot {
  connection: SyncConnectionState;
  activity: SyncActivityState;
  pendingCount: number;
  pendingOperations: number;
  pendingEncodedBytes: number;
  pendingCapacity: SyncPendingCapacityState;
  serverVersion: number;
}Immutable observable synchronization state.API reference →;
  subscribe: (
    source: RemoteOperationSourceinterface RemoteOperationSource {
  subscribe(
    listener: (
      operation: VersionedOperation,
    ) => void | Promise<void>,
    signal?: AbortSignal,
  ): undefined | (() => void);
}interface RemoteOperationSource {
  subscribe(
    listener: (
      operation: VersionedOperation,
    ) => void | Promise<void>,
    signal?: AbortSignal,
  ): undefined | (() => void);
}interface RemoteOperationSource {
  subscribe(
    listener: (
      operation: VersionedOperation,
    ) => void | Promise<void>,
    signal?: AbortSignal,
  ): undefined | (() => void);
}Host subscription contract for ordered versioned operations. Sources that can pause intake should await the listener promise to preserve backpressure.API reference → | AsyncIterable<VersionedOperationinterface VersionedOperation {
  version: number;
  readonly operations: readonly DocumentOp[];
  clientMutationId?: string;
}interface VersionedOperation {
  version: number;
  readonly operations: readonly DocumentOp[];
  clientMutationId?: string;
}interface VersionedOperation {
  version: number;
  readonly operations: readonly DocumentOp[];
  clientMutationId?: string;
}Remote document operations paired with a contiguous server version.API reference →>,
  ) => () => void;
}