@tearleads/client-sdk 0.0.0-stage → 0.1.11

package/data/sync/documentSyncOutgoingBatch.js

@@ -0,0 +1,93 @@
+import { MAX_DOCUMENT_SYNC_OUTGOING_UPDATES, MAX_DOCUMENT_SYNC_REQUEST_BYTES, } from "../../internal/validators/util/index.js";
+export class DocumentSyncRequestLimitError extends Error {
+    name = "DocumentSyncRequestLimitError";
+}
+export function isDocumentSyncRequestLimitError(error) {
+    return (error instanceof DocumentSyncRequestLimitError ||
+        (error instanceof Error && error.name === "DocumentSyncRequestLimitError"));
+}
+function assertReservedCapacity(reservedDataCharacters, reservedUpdateCount) {
+    if (!Number.isSafeInteger(reservedDataCharacters) ||
+        reservedDataCharacters < 0 ||
+        reservedDataCharacters > MAX_DOCUMENT_SYNC_REQUEST_BYTES) {
+        throw new DocumentSyncRequestLimitError("Document sync reserved update data exceeds its limit");
+    }
+    if (!Number.isSafeInteger(reservedUpdateCount) ||
+        reservedUpdateCount < 0 ||
+        reservedUpdateCount > MAX_DOCUMENT_SYNC_OUTGOING_UPDATES) {
+        throw new Error("Document sync reserved update count exceeds its limit");
+    }
+}
+export function selectDocumentSyncOutgoingBatch(updates, options = {}) {
+    const reservedDataCharacters = options.reservedDataCharacters ?? 0;
+    const reservedUpdateCount = options.reservedUpdateCount ?? 0;
+    assertReservedCapacity(reservedDataCharacters, reservedUpdateCount);
+    const availableCount = MAX_DOCUMENT_SYNC_OUTGOING_UPDATES - reservedUpdateCount;
+    const availableDataCharacters = MAX_DOCUMENT_SYNC_REQUEST_BYTES - reservedDataCharacters;
+    const selected = [];
+    let selectedDataCharacters = 0;
+    for (const update of updates) {
+        if (selected.length >= availableCount) {
+            break;
+        }
+        if (update.updateData.length > MAX_DOCUMENT_SYNC_REQUEST_BYTES) {
+            throw new DocumentSyncRequestLimitError("Document sync update exceeds its data limit");
+        }
+        if (selectedDataCharacters + update.updateData.length >
+            availableDataCharacters) {
+            break;
+        }
+        selected.push(update);
+        selectedDataCharacters += update.updateData.length;
+    }
+    return selected;
+}
+const TEXT_ENCODER = new TextEncoder();
+function serializedBytes(value) {
+    return TEXT_ENCODER.encode(JSON.stringify(value)).byteLength;
+}
+export function limitDocumentSyncRequestBytes(request, options = {}) {
+    const requiredUpdateId = options.requiredOutgoingUpdateId;
+    if (requiredUpdateId !== undefined &&
+        request.outgoingUpdates[0]?.id !== requiredUpdateId) {
+        throw new Error("Document sync required update is not first in its batch");
+    }
+    const fitRequest = (candidate) => {
+        const selected = [];
+        let selectedRequestBytes = serializedBytes({
+            ...candidate,
+            outgoingUpdates: [],
+        });
+        if (selectedRequestBytes > MAX_DOCUMENT_SYNC_REQUEST_BYTES)
+            return null;
+        for (const update of candidate.outgoingUpdates) {
+            // The empty request already contains the array brackets. Each selected
+            // item contributes its own serialization and, after the first, one comma.
+            // This keeps exact UTF-8 accounting linear in the request size.
+            const addedBytes = serializedBytes(update) + (selected.length > 0 ? 1 : 0);
+            if (selectedRequestBytes + addedBytes > MAX_DOCUMENT_SYNC_REQUEST_BYTES) {
+                break;
+            }
+            selected.push(update);
+            selectedRequestBytes += addedBytes;
+        }
+        if (selected.length === candidate.outgoingUpdates.length)
+            return candidate;
+        return selected.length > 0
+            ? { ...candidate, outgoingUpdates: selected }
+            : null;
+    };
+    const bounded = fitRequest(request) ??
+        (request.localVersionVector === null
+            ? null
+            : fitRequest({ ...request, localVersionVector: null }));
+    if (!bounded) {
+        throw new DocumentSyncRequestLimitError("Document sync update cannot fit within the request limit");
+    }
+    if (requiredUpdateId !== undefined &&
+        bounded.outgoingUpdates[0]?.id !== requiredUpdateId) {
+        throw new DocumentSyncRequestLimitError("Document sync required update exceeds the request limit");
+    }
+    return bounded;
+}
+//# sourceMappingURL=documentSyncOutgoingBatch.js.map

package/data/sync/documentSyncOutgoingBatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"documentSyncOutgoingBatch.js","sourceRoot":"","sources":["documentSyncOutgoingBatch.ts"],"names":[],"mappings":"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","sourcesContent":["import type { DocumentSyncRequest } from \"@tearleads/validators/request\";\nimport {\n  MAX_DOCUMENT_SYNC_OUTGOING_UPDATES,\n  MAX_DOCUMENT_SYNC_REQUEST_BYTES,\n} from \"@tearleads/validators/util\";\n\ninterface DocumentSyncPendingUpdate {\n  readonly updateData: string;\n}\n\ninterface DocumentSyncOutgoingBatchOptions {\n  readonly reservedDataCharacters?: number | undefined;\n  readonly reservedUpdateCount?: number | undefined;\n}\n\nexport class DocumentSyncRequestLimitError extends Error {\n  override readonly name = \"DocumentSyncRequestLimitError\";\n}\n\nexport function isDocumentSyncRequestLimitError(\n  error: unknown,\n): error is DocumentSyncRequestLimitError {\n  return (\n    error instanceof DocumentSyncRequestLimitError ||\n    (error instanceof Error && error.name === \"DocumentSyncRequestLimitError\")\n  );\n}\n\nfunction assertReservedCapacity(\n  reservedDataCharacters: number,\n  reservedUpdateCount: number,\n): void {\n  if (\n    !Number.isSafeInteger(reservedDataCharacters) ||\n    reservedDataCharacters < 0 ||\n    reservedDataCharacters > MAX_DOCUMENT_SYNC_REQUEST_BYTES\n  ) {\n    throw new DocumentSyncRequestLimitError(\n      \"Document sync reserved update data exceeds its limit\",\n    );\n  }\n  if (\n    !Number.isSafeInteger(reservedUpdateCount) ||\n    reservedUpdateCount < 0 ||\n    reservedUpdateCount > MAX_DOCUMENT_SYNC_OUTGOING_UPDATES\n  ) {\n    throw new Error(\"Document sync reserved update count exceeds its limit\");\n  }\n}\n\nexport function selectDocumentSyncOutgoingBatch<\n  Update extends DocumentSyncPendingUpdate,\n>(\n  updates: readonly Update[],\n  options: DocumentSyncOutgoingBatchOptions = {},\n): Update[] {\n  const reservedDataCharacters = options.reservedDataCharacters ?? 0;\n  const reservedUpdateCount = options.reservedUpdateCount ?? 0;\n  assertReservedCapacity(reservedDataCharacters, reservedUpdateCount);\n\n  const availableCount =\n    MAX_DOCUMENT_SYNC_OUTGOING_UPDATES - reservedUpdateCount;\n  const availableDataCharacters =\n    MAX_DOCUMENT_SYNC_REQUEST_BYTES - reservedDataCharacters;\n  const selected: Update[] = [];\n  let selectedDataCharacters = 0;\n\n  for (const update of updates) {\n    if (selected.length >= availableCount) {\n      break;\n    }\n    if (update.updateData.length > MAX_DOCUMENT_SYNC_REQUEST_BYTES) {\n      throw new DocumentSyncRequestLimitError(\n        \"Document sync update exceeds its data limit\",\n      );\n    }\n    if (\n      selectedDataCharacters + update.updateData.length >\n      availableDataCharacters\n    ) {\n      break;\n    }\n    selected.push(update);\n    selectedDataCharacters += update.updateData.length;\n  }\n\n  return selected;\n}\n\nconst TEXT_ENCODER = new TextEncoder();\n\nfunction serializedBytes(value: unknown): number {\n  return TEXT_ENCODER.encode(JSON.stringify(value)).byteLength;\n}\n\nexport function limitDocumentSyncRequestBytes(\n  request: DocumentSyncRequest,\n  options: { readonly requiredOutgoingUpdateId?: string | undefined } = {},\n): DocumentSyncRequest {\n  const requiredUpdateId = options.requiredOutgoingUpdateId;\n  if (\n    requiredUpdateId !== undefined &&\n    request.outgoingUpdates[0]?.id !== requiredUpdateId\n  ) {\n    throw new Error(\"Document sync required update is not first in its batch\");\n  }\n\n  const fitRequest = (\n    candidate: DocumentSyncRequest,\n  ): DocumentSyncRequest | null => {\n    const selected: DocumentSyncRequest[\"outgoingUpdates\"] = [];\n    let selectedRequestBytes = serializedBytes({\n      ...candidate,\n      outgoingUpdates: [],\n    });\n    if (selectedRequestBytes > MAX_DOCUMENT_SYNC_REQUEST_BYTES) return null;\n    for (const update of candidate.outgoingUpdates) {\n      // The empty request already contains the array brackets. Each selected\n      // item contributes its own serialization and, after the first, one comma.\n      // This keeps exact UTF-8 accounting linear in the request size.\n      const addedBytes =\n        serializedBytes(update) + (selected.length > 0 ? 1 : 0);\n      if (selectedRequestBytes + addedBytes > MAX_DOCUMENT_SYNC_REQUEST_BYTES) {\n        break;\n      }\n      selected.push(update);\n      selectedRequestBytes += addedBytes;\n    }\n\n    if (selected.length === candidate.outgoingUpdates.length) return candidate;\n    return selected.length > 0\n      ? { ...candidate, outgoingUpdates: selected }\n      : null;\n  };\n\n  const bounded =\n    fitRequest(request) ??\n    (request.localVersionVector === null\n      ? null\n      : fitRequest({ ...request, localVersionVector: null }));\n  if (!bounded) {\n    throw new DocumentSyncRequestLimitError(\n      \"Document sync update cannot fit within the request limit\",\n    );\n  }\n  if (\n    requiredUpdateId !== undefined &&\n    bounded.outgoingUpdates[0]?.id !== requiredUpdateId\n  ) {\n    throw new DocumentSyncRequestLimitError(\n      \"Document sync required update exceeds the request limit\",\n    );\n  }\n\n  return bounded;\n}\n"]}

package/data/sync/outgoingUpdateSettlement.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Decide whether a sync lane should re-arm itself on the success path after
+ * sending outgoing updates and observing how many the server settled.
+ *
+ * Re-arm when the pass settled at least one update — i.e. it made real
+ * progress — and updates still remain unsettled. Each settled id is removed
+ * from a finite pending pool, so a progress-gated re-arm strictly shrinks that
+ * pool and is guaranteed to terminate.
+ *
+ * An accepted synthetic recovery baseline is also durable progress even
+ * though its id has no pending-queue row to settle. Re-arm when it left queued
+ * updates so a large baseline cannot strand the ordinary edits it displaced
+ * from the bounded request. Merely sending a baseline is not progress: a
+ * server that under-settles it must hit the same no-spin guard as other writes.
+ *
+ * Also re-arm when the pass re-keyed conflicted pending updates: the fresh
+ * ids exist precisely so the next pass can submit them, and without a re-arm
+ * they wait for an unrelated edit or remote event. For an honest server this
+ * terminates on its own (it can conflict on a given id at most once — a
+ * re-keyed id is one it has never been shown), but honesty is not assumed:
+ * a buggy or malicious server that keeps 409ing fresh ids — or a proxy
+ * replaying cached conflict bodies — would otherwise drive a network-speed
+ * re-key loop on a lane that keeps reporting `completed`, so the failed-lane
+ * backoff never engages. The lane's consecutive rekey-only pass counter
+ * bounds that: once it reaches the cap the lane stops self-arming and the
+ * still-pending work waits for the next external signal (edit, remote event,
+ * lane restart).
+ *
+ * A server that under-settles without conflicting (accepts fewer ids than
+ * were sent, settling and re-keying none) must not drive an unbounded
+ * success-path re-arm: the lane goes idle and a later mutation / sync signal
+ * retries the still-pending work. Without this guard the lane busy-loops at
+ * one pass per macrotask forever while still reporting `completed`, and the
+ * coordinator never reaches idle.
+ */
+export declare const MAX_CONSECUTIVE_REKEY_ONLY_PASSES = 3;
+interface OutgoingSettlementLane {
+    rekeyOnlyPassCount?: number | undefined;
+}
+interface OutgoingSettlementPass {
+    readonly exhaustedPendingUpdateCount: number;
+    readonly outgoingUpdateCount: number;
+    readonly rekeyedUpdateCount: number;
+    readonly settledUpdateCount: number;
+    readonly acceptedRecoveryBaseline?: boolean | undefined;
+}
+/**
+ * Record a completed pass's settlement outcome on the lane and decide whether
+ * the lane should immediately re-arm. Settling anything (or not re-keying at
+ * all) proves the loop is not rekey-driven and resets the lane's consecutive
+ * rekey-only counter.
+ */
+export declare function settleOutgoingPassAndDecideReArm(lane: OutgoingSettlementLane, pass: OutgoingSettlementPass): boolean;
+export {};

package/data/sync/outgoingUpdateSettlement.js

@@ -0,0 +1,60 @@
+/**
+ * Decide whether a sync lane should re-arm itself on the success path after
+ * sending outgoing updates and observing how many the server settled.
+ *
+ * Re-arm when the pass settled at least one update — i.e. it made real
+ * progress — and updates still remain unsettled. Each settled id is removed
+ * from a finite pending pool, so a progress-gated re-arm strictly shrinks that
+ * pool and is guaranteed to terminate.
+ *
+ * An accepted synthetic recovery baseline is also durable progress even
+ * though its id has no pending-queue row to settle. Re-arm when it left queued
+ * updates so a large baseline cannot strand the ordinary edits it displaced
+ * from the bounded request. Merely sending a baseline is not progress: a
+ * server that under-settles it must hit the same no-spin guard as other writes.
+ *
+ * Also re-arm when the pass re-keyed conflicted pending updates: the fresh
+ * ids exist precisely so the next pass can submit them, and without a re-arm
+ * they wait for an unrelated edit or remote event. For an honest server this
+ * terminates on its own (it can conflict on a given id at most once — a
+ * re-keyed id is one it has never been shown), but honesty is not assumed:
+ * a buggy or malicious server that keeps 409ing fresh ids — or a proxy
+ * replaying cached conflict bodies — would otherwise drive a network-speed
+ * re-key loop on a lane that keeps reporting `completed`, so the failed-lane
+ * backoff never engages. The lane's consecutive rekey-only pass counter
+ * bounds that: once it reaches the cap the lane stops self-arming and the
+ * still-pending work waits for the next external signal (edit, remote event,
+ * lane restart).
+ *
+ * A server that under-settles without conflicting (accepts fewer ids than
+ * were sent, settling and re-keying none) must not drive an unbounded
+ * success-path re-arm: the lane goes idle and a later mutation / sync signal
+ * retries the still-pending work. Without this guard the lane busy-loops at
+ * one pass per macrotask forever while still reporting `completed`, and the
+ * coordinator never reaches idle.
+ */
+export const MAX_CONSECUTIVE_REKEY_ONLY_PASSES = 3;
+function isRekeyOnlyPass(pass) {
+    return pass.rekeyedUpdateCount > 0 && pass.settledUpdateCount === 0;
+}
+/**
+ * Record a completed pass's settlement outcome on the lane and decide whether
+ * the lane should immediately re-arm. Settling anything (or not re-keying at
+ * all) proves the loop is not rekey-driven and resets the lane's consecutive
+ * rekey-only counter.
+ */
+export function settleOutgoingPassAndDecideReArm(lane, pass) {
+    if (pass.exhaustedPendingUpdateCount > 0) {
+        lane.rekeyOnlyPassCount = 0;
+        return false;
+    }
+    const rekeyOnlyPassCount = lane.rekeyOnlyPassCount ?? 0;
+    lane.rekeyOnlyPassCount = isRekeyOnlyPass(pass) ? rekeyOnlyPassCount + 1 : 0;
+    return ((isRekeyOnlyPass(pass) &&
+        rekeyOnlyPassCount < MAX_CONSECUTIVE_REKEY_ONLY_PASSES) ||
+        (pass.acceptedRecoveryBaseline === true &&
+            pass.outgoingUpdateCount > pass.settledUpdateCount) ||
+        (pass.settledUpdateCount > 0 &&
+            pass.outgoingUpdateCount > pass.settledUpdateCount));
+}
+//# sourceMappingURL=outgoingUpdateSettlement.js.map

package/data/sync/outgoingUpdateSettlement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outgoingUpdateSettlement.js","sourceRoot":"","sources":["outgoingUpdateSettlement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,MAAM,CAAC,MAAM,iCAAiC,GAAG,CAAC,CAAC;AAcnD,SAAS,eAAe,CAAC,IAA4B;IACnD,OAAO,IAAI,CAAC,kBAAkB,GAAG,CAAC,IAAI,IAAI,CAAC,kBAAkB,KAAK,CAAC,CAAC;AACtE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gCAAgC,CAC9C,IAA4B,EAC5B,IAA4B;IAE5B,IAAI,IAAI,CAAC,2BAA2B,GAAG,CAAC,EAAE,CAAC;QACzC,IAAI,CAAC,kBAAkB,GAAG,CAAC,CAAC;QAC5B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,kBAAkB,GAAG,IAAI,CAAC,kBAAkB,IAAI,CAAC,CAAC;IACxD,IAAI,CAAC,kBAAkB,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,kBAAkB,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAE7E,OAAO,CACL,CAAC,eAAe,CAAC,IAAI,CAAC;QACpB,kBAAkB,GAAG,iCAAiC,CAAC;QACzD,CAAC,IAAI,CAAC,wBAAwB,KAAK,IAAI;YACrC,IAAI,CAAC,mBAAmB,GAAG,IAAI,CAAC,kBAAkB,CAAC;QACrD,CAAC,IAAI,CAAC,kBAAkB,GAAG,CAAC;YAC1B,IAAI,CAAC,mBAAmB,GAAG,IAAI,CAAC,kBAAkB,CAAC,CACtD,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Decide whether a sync lane should re-arm itself on the success path after\n * sending outgoing updates and observing how many the server settled.\n *\n * Re-arm when the pass settled at least one update — i.e. it made real\n * progress — and updates still remain unsettled. Each settled id is removed\n * from a finite pending pool, so a progress-gated re-arm strictly shrinks that\n * pool and is guaranteed to terminate.\n *\n * An accepted synthetic recovery baseline is also durable progress even\n * though its id has no pending-queue row to settle. Re-arm when it left queued\n * updates so a large baseline cannot strand the ordinary edits it displaced\n * from the bounded request. Merely sending a baseline is not progress: a\n * server that under-settles it must hit the same no-spin guard as other writes.\n *\n * Also re-arm when the pass re-keyed conflicted pending updates: the fresh\n * ids exist precisely so the next pass can submit them, and without a re-arm\n * they wait for an unrelated edit or remote event. For an honest server this\n * terminates on its own (it can conflict on a given id at most once — a\n * re-keyed id is one it has never been shown), but honesty is not assumed:\n * a buggy or malicious server that keeps 409ing fresh ids — or a proxy\n * replaying cached conflict bodies — would otherwise drive a network-speed\n * re-key loop on a lane that keeps reporting `completed`, so the failed-lane\n * backoff never engages. The lane's consecutive rekey-only pass counter\n * bounds that: once it reaches the cap the lane stops self-arming and the\n * still-pending work waits for the next external signal (edit, remote event,\n * lane restart).\n *\n * A server that under-settles without conflicting (accepts fewer ids than\n * were sent, settling and re-keying none) must not drive an unbounded\n * success-path re-arm: the lane goes idle and a later mutation / sync signal\n * retries the still-pending work. Without this guard the lane busy-loops at\n * one pass per macrotask forever while still reporting `completed`, and the\n * coordinator never reaches idle.\n */\n\nexport const MAX_CONSECUTIVE_REKEY_ONLY_PASSES = 3;\n\ninterface OutgoingSettlementLane {\n  rekeyOnlyPassCount?: number | undefined;\n}\n\ninterface OutgoingSettlementPass {\n  readonly exhaustedPendingUpdateCount: number;\n  readonly outgoingUpdateCount: number;\n  readonly rekeyedUpdateCount: number;\n  readonly settledUpdateCount: number;\n  readonly acceptedRecoveryBaseline?: boolean | undefined;\n}\n\nfunction isRekeyOnlyPass(pass: OutgoingSettlementPass): boolean {\n  return pass.rekeyedUpdateCount > 0 && pass.settledUpdateCount === 0;\n}\n\n/**\n * Record a completed pass's settlement outcome on the lane and decide whether\n * the lane should immediately re-arm. Settling anything (or not re-keying at\n * all) proves the loop is not rekey-driven and resets the lane's consecutive\n * rekey-only counter.\n */\nexport function settleOutgoingPassAndDecideReArm(\n  lane: OutgoingSettlementLane,\n  pass: OutgoingSettlementPass,\n): boolean {\n  if (pass.exhaustedPendingUpdateCount > 0) {\n    lane.rekeyOnlyPassCount = 0;\n    return false;\n  }\n\n  const rekeyOnlyPassCount = lane.rekeyOnlyPassCount ?? 0;\n  lane.rekeyOnlyPassCount = isRekeyOnlyPass(pass) ? rekeyOnlyPassCount + 1 : 0;\n\n  return (\n    (isRekeyOnlyPass(pass) &&\n      rekeyOnlyPassCount < MAX_CONSECUTIVE_REKEY_ONLY_PASSES) ||\n    (pass.acceptedRecoveryBaseline === true &&\n      pass.outgoingUpdateCount > pass.settledUpdateCount) ||\n    (pass.settledUpdateCount > 0 &&\n      pass.outgoingUpdateCount > pass.settledUpdateCount)\n  );\n}\n"]}

package/data/sync/sequence.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Shared convergence-safety predicate for sync lanes that snapshot an enqueue
+ * sequence before an async window and decide afterwards whether the signal they
+ * consumed may be cleared. The sequence is unchanged only when no fresh remote
+ * event advanced it mid-pass; a moved sequence means the consumed signal must
+ * survive for the coalesced re-run.
+ */
+export declare const sequenceUnchanged: (current: number, consumed: number) => boolean;

package/data/sync/sequence.js

@@ -0,0 +1,9 @@
+/**
+ * Shared convergence-safety predicate for sync lanes that snapshot an enqueue
+ * sequence before an async window and decide afterwards whether the signal they
+ * consumed may be cleared. The sequence is unchanged only when no fresh remote
+ * event advanced it mid-pass; a moved sequence means the consumed signal must
+ * survive for the coalesced re-run.
+ */
+export const sequenceUnchanged = (current, consumed) => current === consumed;
+//# sourceMappingURL=sequence.js.map

package/data/sync/sequence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sequence.js","sourceRoot":"","sources":["sequence.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,OAAe,EAAE,QAAgB,EAAW,EAAE,CAC9E,OAAO,KAAK,QAAQ,CAAC","sourcesContent":["/**\n * Shared convergence-safety predicate for sync lanes that snapshot an enqueue\n * sequence before an async window and decide afterwards whether the signal they\n * consumed may be cleared. The sequence is unchanged only when no fresh remote\n * event advanced it mid-pass; a moved sequence means the consumed signal must\n * survive for the coalesced re-run.\n */\nexport const sequenceUnchanged = (current: number, consumed: number): boolean =>\n  current === consumed;\n"]}

package/data/sync/syncCoordinator.d.ts

@@ -0,0 +1,32 @@
+import type { DomainScope } from "../domainScope.js";
+import { type SyncIdleOptions } from "./coordinatorPump.js";
+import type { SyncLane, SyncLaneConfig } from "./syncLaneConfig.js";
+import type { DomainSyncSnapshot } from "./syncTelemetry.js";
+import type { UploadSyncLane, UploadSyncLaneOptions } from "./uploadLane.js";
+export type { SyncIdleOptions } from "./coordinatorPump.js";
+export { isDatabaseUnavailableError } from "./databaseUnavailable.js";
+export type { SyncLane, SyncLaneConfig } from "./syncLaneConfig.js";
+export { didRegainSyncPrerequisites, type SyncRuntimeStatus, } from "./syncPrerequisites.js";
+export type { DomainSyncSnapshot, SyncLaneLastAction, SyncLanePhase, SyncLaneProgress, SyncLaneSnapshot, SyncLaneStatus, } from "./syncTelemetry.js";
+export type { UploadSyncLane, UploadSyncLaneOptions } from "./uploadLane.js";
+export interface DomainSyncCoordinator {
+    beginUploadLane: (key: string, options?: UploadSyncLaneOptions) => UploadSyncLane;
+    dispose: () => void;
+    getSnapshot: () => DomainSyncSnapshot;
+    registerLane: (key: string, config: SyncLaneConfig) => SyncLane;
+    requestAllLanes: () => void;
+    requestLane: (key: string) => void;
+    hasPendingWork: () => boolean;
+    isDisposed: () => boolean;
+    subscribe: (listener: () => void) => () => void;
+    waitForIdle: (options?: SyncIdleOptions) => Promise<boolean>;
+}
+export declare function getOrCreateDomainSyncCoordinator(domainScope: DomainScope): DomainSyncCoordinator;
+export declare function hasDomainSyncCoordinatorPendingWork(domainScope: DomainScope): boolean;
+export declare function requestAllDomainSyncLanes(domainScope: DomainScope): void;
+export declare function requestDomainSyncLane(domainScope: DomainScope, key: string): void;
+export declare function disposeDomainSyncCoordinator(domainScope: DomainScope): void;
+export declare function getDomainSyncCoordinatorSnapshot(domainScope: DomainScope): DomainSyncSnapshot;
+export declare function subscribeToDomainSyncCoordinator(domainScope: DomainScope, listener: () => void): () => void;
+export declare function beginDomainSyncUploadLane(domainScope: DomainScope, key: string, options?: UploadSyncLaneOptions): UploadSyncLane;
+export declare function waitForDomainSyncCoordinatorToSettle(domainScope: DomainScope, options?: SyncIdleOptions): Promise<boolean>;

package/data/sync/syncCoordinator.js

@@ -0,0 +1,160 @@
+import { requestAllPumpDrivenLanes, requestLaneSync, requestLaneSyncAfter, waitForIdleLanes, } from "./coordinatorPump.js";
+import { hasPendingLaneWork, INITIAL_SYNC_LANE_RUN_STATE, publishSyncCoordinatorSnapshot, } from "./coordinatorState.js";
+import { createDomainSyncSnapshot, createSyncTimestamp } from "./syncTelemetry.js";
+import { beginUploadLane } from "./uploadLane.js";
+// Re-exported here because lanes reach it as a shouldIgnoreError alongside the
+// rest of the coordinator surface; it lives beside this coordinator with the
+// error type it discriminates on.
+export { isDatabaseUnavailableError } from "./databaseUnavailable.js";
+export { didRegainSyncPrerequisites, } from "./syncPrerequisites.js";
+const coordinatorsByScope = new WeakMap();
+function createSyncLaneHandle(coordinatorState, lane) {
+    return {
+        isDisposed: () => coordinatorState.disposed,
+        requestSync: () => requestLaneSync(coordinatorState, lane),
+        requestSyncAfter: (delayMs) => requestLaneSyncAfter(coordinatorState, lane, delayMs),
+    };
+}
+function createDomainSyncCoordinator() {
+    const coordinatorState = {
+        disposed: false,
+        lanes: new Map(),
+        listeners: new Set(),
+        nextRegistrationIndex: 0,
+        pump: null,
+        snapshot: createDomainSyncSnapshot({
+            hasPendingWork: false,
+            lanes: [],
+            pumpActive: false,
+        }),
+    };
+    return {
+        beginUploadLane(key, options = {}) {
+            return beginUploadLane(coordinatorState, key, options);
+        },
+        dispose() {
+            coordinatorState.disposed = true;
+            // Drop queued work so waitForIdle reports settled immediately and a
+            // lane left re-requested by an in-flight run does not survive teardown.
+            for (const lane of coordinatorState.lanes.values()) {
+                lane.requested = false;
+                lane.notBeforeAtMs = null;
+            }
+            // Publish the final settled snapshot, then release listener closures:
+            // the coordinator is dropped from the registry and a remount subscribes
+            // to a fresh one.
+            publishSyncCoordinatorSnapshot(coordinatorState);
+            coordinatorState.listeners.clear();
+        },
+        getSnapshot() {
+            return coordinatorState.snapshot;
+        },
+        hasPendingWork() {
+            return (!!coordinatorState.pump ||
+                hasPendingLaneWork(coordinatorState.lanes.values()));
+        },
+        isDisposed() {
+            return coordinatorState.disposed;
+        },
+        registerLane(key, config) {
+            const existingLane = coordinatorState.lanes.get(key);
+            if (existingLane) {
+                existingLane.config = config;
+                existingLane.blobStorageKey = null;
+                existingLane.pumpDriven = true;
+                publishSyncCoordinatorSnapshot(coordinatorState);
+                return createSyncLaneHandle(coordinatorState, existingLane);
+            }
+            const registeredAt = createSyncTimestamp();
+            const nextLane = {
+                ...INITIAL_SYNC_LANE_RUN_STATE,
+                blobStorageKey: null,
+                config,
+                errorCount: 0,
+                key,
+                lastAction: "registered",
+                lastActionAt: registeredAt,
+                lastCompletedAt: null,
+                lastError: null,
+                lastFailedAt: null,
+                lastRequestedAt: null,
+                lastStartedAt: null,
+                notBeforeAtMs: null,
+                progress: null,
+                pumpDriven: true,
+                registrationIndex: coordinatorState.nextRegistrationIndex,
+                requestCount: 0,
+                requested: false,
+            };
+            coordinatorState.nextRegistrationIndex += 1;
+            coordinatorState.lanes.set(key, nextLane);
+            publishSyncCoordinatorSnapshot(coordinatorState);
+            return createSyncLaneHandle(coordinatorState, nextLane);
+        },
+        requestAllLanes() {
+            requestAllPumpDrivenLanes(coordinatorState);
+        },
+        requestLane(key) {
+            const lane = coordinatorState.lanes.get(key);
+            if (lane?.pumpDriven) {
+                requestLaneSync(coordinatorState, lane);
+            }
+        },
+        subscribe(listener) {
+            coordinatorState.listeners.add(listener);
+            return () => {
+                coordinatorState.listeners.delete(listener);
+            };
+        },
+        waitForIdle(options) {
+            return waitForIdleLanes(coordinatorState, options);
+        },
+    };
+}
+export function getOrCreateDomainSyncCoordinator(domainScope) {
+    const existingCoordinator = coordinatorsByScope.get(domainScope);
+    if (existingCoordinator) {
+        return existingCoordinator;
+    }
+    const nextCoordinator = createDomainSyncCoordinator();
+    coordinatorsByScope.set(domainScope, nextCoordinator);
+    return nextCoordinator;
+}
+export function hasDomainSyncCoordinatorPendingWork(domainScope) {
+    return coordinatorsByScope.get(domainScope)?.hasPendingWork() ?? false;
+}
+// Re-request every pump-driven lane for a scope: a user-driven "sync now" that
+// retries durable work stranded by a transient failure. Observational upload
+// telemetry is never directly pumped. A no-op when no coordinator exists yet
+// (nothing has been synced) or it has been disposed.
+export function requestAllDomainSyncLanes(domainScope) {
+    coordinatorsByScope.get(domainScope)?.requestAllLanes();
+}
+export function requestDomainSyncLane(domainScope, key) {
+    coordinatorsByScope.get(domainScope)?.requestLane(key);
+}
+// Force-stop the coordinator for a scope and drop it from the registry, so a
+// pump cannot outlive the runtime/React tree that created it. A later
+// getOrCreate for the same scope builds a fresh coordinator.
+export function disposeDomainSyncCoordinator(domainScope) {
+    const coordinator = coordinatorsByScope.get(domainScope);
+    if (!coordinator) {
+        return;
+    }
+    coordinator.dispose();
+    coordinatorsByScope.delete(domainScope);
+}
+export function getDomainSyncCoordinatorSnapshot(domainScope) {
+    return getOrCreateDomainSyncCoordinator(domainScope).getSnapshot();
+}
+export function subscribeToDomainSyncCoordinator(domainScope, listener) {
+    return getOrCreateDomainSyncCoordinator(domainScope).subscribe(listener);
+}
+export function beginDomainSyncUploadLane(domainScope, key, options) {
+    return getOrCreateDomainSyncCoordinator(domainScope).beginUploadLane(key, options);
+}
+export function waitForDomainSyncCoordinatorToSettle(domainScope, options) {
+    return (coordinatorsByScope.get(domainScope)?.waitForIdle(options) ??
+        Promise.resolve(true));
+}
+//# sourceMappingURL=syncCoordinator.js.map

package/data/sync/syncCoordinator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncCoordinator.js","sourceRoot":"","sources":["syncCoordinator.ts"],"names":[],"mappings":"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","sourcesContent":["import type { DomainScope } from \"../domainScope\";\nimport {\n  requestAllPumpDrivenLanes,\n  requestLaneSync,\n  requestLaneSyncAfter,\n  type SyncIdleOptions,\n  waitForIdleLanes,\n} from \"./coordinatorPump\";\nimport type {\n  DomainSyncCoordinatorState,\n  SyncLaneState,\n} from \"./coordinatorState\";\nimport {\n  hasPendingLaneWork,\n  INITIAL_SYNC_LANE_RUN_STATE,\n  publishSyncCoordinatorSnapshot,\n} from \"./coordinatorState\";\nimport type { SyncLane, SyncLaneConfig } from \"./syncLaneConfig\";\nimport type { DomainSyncSnapshot } from \"./syncTelemetry\";\nimport { createDomainSyncSnapshot, createSyncTimestamp } from \"./syncTelemetry\";\nimport type { UploadSyncLane, UploadSyncLaneOptions } from \"./uploadLane\";\nimport { beginUploadLane } from \"./uploadLane\";\n\nexport type { SyncIdleOptions } from \"./coordinatorPump\";\n// Re-exported here because lanes reach it as a shouldIgnoreError alongside the\n// rest of the coordinator surface; it lives beside this coordinator with the\n// error type it discriminates on.\nexport { isDatabaseUnavailableError } from \"./databaseUnavailable\";\nexport type { SyncLane, SyncLaneConfig } from \"./syncLaneConfig\";\nexport {\n  didRegainSyncPrerequisites,\n  type SyncRuntimeStatus,\n} from \"./syncPrerequisites\";\nexport type {\n  DomainSyncSnapshot,\n  SyncLaneLastAction,\n  SyncLanePhase,\n  SyncLaneProgress,\n  SyncLaneSnapshot,\n  SyncLaneStatus,\n} from \"./syncTelemetry\";\nexport type { UploadSyncLane, UploadSyncLaneOptions } from \"./uploadLane\";\n\nexport interface DomainSyncCoordinator {\n  beginUploadLane: (\n    key: string,\n    options?: UploadSyncLaneOptions,\n  ) => UploadSyncLane;\n  // Force-stop the pump, drop all queued lane work, and refuse further runs.\n  dispose: () => void;\n  getSnapshot: () => DomainSyncSnapshot;\n  registerLane: (key: string, config: SyncLaneConfig) => SyncLane;\n  // Re-request every pump-driven lane — a manual \"sync now\" that re-drives\n  // durable owners stranded by a transient failure. Observational upload rows\n  // are updated only by those owners' real attachment upload attempts.\n  requestAllLanes: () => void;\n  // Request one registered pump lane without re-driving unrelated owners.\n  requestLane: (key: string) => void;\n  hasPendingWork: () => boolean;\n  isDisposed: () => boolean;\n  subscribe: (listener: () => void) => () => void;\n  waitForIdle: (options?: SyncIdleOptions) => Promise<boolean>;\n}\n\nconst coordinatorsByScope = new WeakMap<DomainScope, DomainSyncCoordinator>();\n\nfunction createSyncLaneHandle(\n  coordinatorState: DomainSyncCoordinatorState,\n  lane: SyncLaneState,\n): SyncLane {\n  return {\n    isDisposed: () => coordinatorState.disposed,\n    requestSync: () => requestLaneSync(coordinatorState, lane),\n    requestSyncAfter: (delayMs) =>\n      requestLaneSyncAfter(coordinatorState, lane, delayMs),\n  };\n}\n\nfunction createDomainSyncCoordinator(): DomainSyncCoordinator {\n  const coordinatorState: DomainSyncCoordinatorState = {\n    disposed: false,\n    lanes: new Map<string, SyncLaneState>(),\n    listeners: new Set(),\n    nextRegistrationIndex: 0,\n    pump: null,\n    snapshot: createDomainSyncSnapshot({\n      hasPendingWork: false,\n      lanes: [],\n      pumpActive: false,\n    }),\n  };\n\n  return {\n    beginUploadLane(key: string, options: UploadSyncLaneOptions = {}) {\n      return beginUploadLane(coordinatorState, key, options);\n    },\n    dispose() {\n      coordinatorState.disposed = true;\n      // Drop queued work so waitForIdle reports settled immediately and a\n      // lane left re-requested by an in-flight run does not survive teardown.\n      for (const lane of coordinatorState.lanes.values()) {\n        lane.requested = false;\n        lane.notBeforeAtMs = null;\n      }\n      // Publish the final settled snapshot, then release listener closures:\n      // the coordinator is dropped from the registry and a remount subscribes\n      // to a fresh one.\n      publishSyncCoordinatorSnapshot(coordinatorState);\n      coordinatorState.listeners.clear();\n    },\n    getSnapshot() {\n      return coordinatorState.snapshot;\n    },\n    hasPendingWork() {\n      return (\n        !!coordinatorState.pump ||\n        hasPendingLaneWork(coordinatorState.lanes.values())\n      );\n    },\n    isDisposed() {\n      return coordinatorState.disposed;\n    },\n    registerLane(key: string, config: SyncLaneConfig): SyncLane {\n      const existingLane = coordinatorState.lanes.get(key);\n      if (existingLane) {\n        existingLane.config = config;\n        existingLane.blobStorageKey = null;\n        existingLane.pumpDriven = true;\n        publishSyncCoordinatorSnapshot(coordinatorState);\n        return createSyncLaneHandle(coordinatorState, existingLane);\n      }\n\n      const registeredAt = createSyncTimestamp();\n      const nextLane: SyncLaneState = {\n        ...INITIAL_SYNC_LANE_RUN_STATE,\n        blobStorageKey: null,\n        config,\n        errorCount: 0,\n        key,\n        lastAction: \"registered\",\n        lastActionAt: registeredAt,\n        lastCompletedAt: null,\n        lastError: null,\n        lastFailedAt: null,\n        lastRequestedAt: null,\n        lastStartedAt: null,\n        notBeforeAtMs: null,\n        progress: null,\n        pumpDriven: true,\n        registrationIndex: coordinatorState.nextRegistrationIndex,\n        requestCount: 0,\n        requested: false,\n      };\n      coordinatorState.nextRegistrationIndex += 1;\n      coordinatorState.lanes.set(key, nextLane);\n      publishSyncCoordinatorSnapshot(coordinatorState);\n      return createSyncLaneHandle(coordinatorState, nextLane);\n    },\n    requestAllLanes() {\n      requestAllPumpDrivenLanes(coordinatorState);\n    },\n    requestLane(key: string) {\n      const lane = coordinatorState.lanes.get(key);\n      if (lane?.pumpDriven) {\n        requestLaneSync(coordinatorState, lane);\n      }\n    },\n    subscribe(listener: () => void) {\n      coordinatorState.listeners.add(listener);\n      return () => {\n        coordinatorState.listeners.delete(listener);\n      };\n    },\n    waitForIdle(options?: SyncIdleOptions) {\n      return waitForIdleLanes(coordinatorState, options);\n    },\n  };\n}\n\nexport function getOrCreateDomainSyncCoordinator(\n  domainScope: DomainScope,\n): DomainSyncCoordinator {\n  const existingCoordinator = coordinatorsByScope.get(domainScope);\n  if (existingCoordinator) {\n    return existingCoordinator;\n  }\n\n  const nextCoordinator = createDomainSyncCoordinator();\n  coordinatorsByScope.set(domainScope, nextCoordinator);\n  return nextCoordinator;\n}\n\nexport function hasDomainSyncCoordinatorPendingWork(\n  domainScope: DomainScope,\n): boolean {\n  return coordinatorsByScope.get(domainScope)?.hasPendingWork() ?? false;\n}\n\n// Re-request every pump-driven lane for a scope: a user-driven \"sync now\" that\n// retries durable work stranded by a transient failure. Observational upload\n// telemetry is never directly pumped. A no-op when no coordinator exists yet\n// (nothing has been synced) or it has been disposed.\nexport function requestAllDomainSyncLanes(domainScope: DomainScope): void {\n  coordinatorsByScope.get(domainScope)?.requestAllLanes();\n}\n\nexport function requestDomainSyncLane(\n  domainScope: DomainScope,\n  key: string,\n): void {\n  coordinatorsByScope.get(domainScope)?.requestLane(key);\n}\n\n// Force-stop the coordinator for a scope and drop it from the registry, so a\n// pump cannot outlive the runtime/React tree that created it. A later\n// getOrCreate for the same scope builds a fresh coordinator.\nexport function disposeDomainSyncCoordinator(domainScope: DomainScope): void {\n  const coordinator = coordinatorsByScope.get(domainScope);\n  if (!coordinator) {\n    return;\n  }\n\n  coordinator.dispose();\n  coordinatorsByScope.delete(domainScope);\n}\n\nexport function getDomainSyncCoordinatorSnapshot(\n  domainScope: DomainScope,\n): DomainSyncSnapshot {\n  return getOrCreateDomainSyncCoordinator(domainScope).getSnapshot();\n}\n\nexport function subscribeToDomainSyncCoordinator(\n  domainScope: DomainScope,\n  listener: () => void,\n): () => void {\n  return getOrCreateDomainSyncCoordinator(domainScope).subscribe(listener);\n}\n\nexport function beginDomainSyncUploadLane(\n  domainScope: DomainScope,\n  key: string,\n  options?: UploadSyncLaneOptions,\n): UploadSyncLane {\n  return getOrCreateDomainSyncCoordinator(domainScope).beginUploadLane(\n    key,\n    options,\n  );\n}\n\nexport function waitForDomainSyncCoordinatorToSettle(\n  domainScope: DomainScope,\n  options?: SyncIdleOptions,\n): Promise<boolean> {\n  return (\n    coordinatorsByScope.get(domainScope)?.waitForIdle(options) ??\n    Promise.resolve(true)\n  );\n}\n"]}

package/data/sync/syncLaneConfig.d.ts

@@ -0,0 +1,16 @@
+import type { SyncLanePhase } from "./syncTelemetry.js";
+export interface SyncLane {
+    isDisposed?: () => boolean;
+    requestSync: () => void;
+    requestSyncAfter: (delayMs: number) => void;
+}
+export interface SyncLaneConfig {
+    label?: string | undefined;
+    onUnexpectedError?: (error: unknown) => void;
+    phase?: SyncLanePhase;
+    /** Observability only. Must not change lane behavior. */
+    reportUnexpectedError?: (error: unknown) => void;
+    run: () => Promise<void>;
+    shouldIgnoreError?: (error: unknown) => boolean;
+    watchdogMs?: number;
+}

package/data/sync/syncLaneConfig.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=syncLaneConfig.js.map

package/data/sync/syncLaneConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncLaneConfig.js","sourceRoot":"","sources":["syncLaneConfig.ts"],"names":[],"mappings":"","sourcesContent":["import type { SyncLanePhase } from \"./syncTelemetry\";\n\nexport interface SyncLane {\n  isDisposed?: () => boolean;\n  requestSync: () => void;\n  requestSyncAfter: (delayMs: number) => void;\n}\n\nexport interface SyncLaneConfig {\n  label?: string | undefined;\n  onUnexpectedError?: (error: unknown) => void;\n  phase?: SyncLanePhase;\n  /** Observability only. Must not change lane behavior. */\n  reportUnexpectedError?: (error: unknown) => void;\n  run: () => Promise<void>;\n  shouldIgnoreError?: (error: unknown) => boolean;\n  // Per-run liveness bound. When a run exceeds it, the pump records a watchdog\n  // failure and moves on to other lanes instead of head-of-line blocking the\n  // whole queue; the abandoned run is not cancelled, and its real outcome\n  // overwrites the watchdog verdict when it eventually settles. Defaults to\n  // the coordinator's SYNC_LANE_WATCHDOG_MS.\n  watchdogMs?: number;\n}\n"]}

package/data/sync/syncPrerequisites.d.ts

@@ -0,0 +1,12 @@
+export interface SyncRuntimeStatus {
+    crypto: {
+        encapsulationKeyPair: unknown;
+    };
+    auth: {
+        isAuthenticated: boolean;
+    };
+    state: {
+        online: boolean;
+    };
+}
+export declare function didRegainSyncPrerequisites<TRuntime extends SyncRuntimeStatus>(previousRuntime: TRuntime, nextRuntime: TRuntime): boolean;

package/data/sync/syncPrerequisites.js

@@ -0,0 +1,8 @@
+export function didRegainSyncPrerequisites(previousRuntime, nextRuntime) {
+    return ((!previousRuntime.state.online && nextRuntime.state.online) ||
+        (!previousRuntime.auth.isAuthenticated &&
+            nextRuntime.auth.isAuthenticated) ||
+        (!previousRuntime.crypto.encapsulationKeyPair &&
+            !!nextRuntime.crypto.encapsulationKeyPair));
+}
+//# sourceMappingURL=syncPrerequisites.js.map

package/data/sync/syncPrerequisites.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncPrerequisites.js","sourceRoot":"","sources":["syncPrerequisites.ts"],"names":[],"mappings":"AAMA,MAAM,UAAU,0BAA0B,CACxC,eAAyB,EACzB,WAAqB;IAErB,OAAO,CACL,CAAC,CAAC,eAAe,CAAC,KAAK,CAAC,MAAM,IAAI,WAAW,CAAC,KAAK,CAAC,MAAM,CAAC;QAC3D,CAAC,CAAC,eAAe,CAAC,IAAI,CAAC,eAAe;YACpC,WAAW,CAAC,IAAI,CAAC,eAAe,CAAC;QACnC,CAAC,CAAC,eAAe,CAAC,MAAM,CAAC,oBAAoB;YAC3C,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAC7C,CAAC;AACJ,CAAC","sourcesContent":["export interface SyncRuntimeStatus {\n  crypto: { encapsulationKeyPair: unknown };\n  auth: { isAuthenticated: boolean };\n  state: { online: boolean };\n}\n\nexport function didRegainSyncPrerequisites<TRuntime extends SyncRuntimeStatus>(\n  previousRuntime: TRuntime,\n  nextRuntime: TRuntime,\n): boolean {\n  return (\n    (!previousRuntime.state.online && nextRuntime.state.online) ||\n    (!previousRuntime.auth.isAuthenticated &&\n      nextRuntime.auth.isAuthenticated) ||\n    (!previousRuntime.crypto.encapsulationKeyPair &&\n      !!nextRuntime.crypto.encapsulationKeyPair)\n  );\n}\n"]}

package/data/sync/syncTelemetry.d.ts

@@ -0,0 +1,86 @@
+export type SyncLanePhase = "structural" | "document" | "blob";
+export type SyncLaneStatus = "idle" | "queued" | "running" | "complete" | "error";
+export type SyncLaneLastAction = "registered" | "requested" | "started" | "completed" | "failed";
+/**
+ * Fine-grained progress for lanes that expose it (currently multipart blob
+ * uploads). Coarse status lanes leave this null and fall back to the
+ * status-keyed progress bar in the visualizer.
+ */
+export interface SyncLaneProgress {
+    bytesTotal: number;
+    bytesUploaded: number;
+    partsCompleted: number;
+    partsTotal: number;
+}
+export interface SyncLaneSnapshot {
+    /** Storage key used to open the associated blob, when this is a blob lane. */
+    blobStorageKey: string | null;
+    errorCount: number;
+    key: string;
+    label: string;
+    lastAction: SyncLaneLastAction;
+    lastActionAt: string;
+    lastCompletedAt: string | null;
+    lastError: string | null;
+    lastFailedAt: string | null;
+    lastRequestedAt: string | null;
+    lastStartedAt: string | null;
+    phase: SyncLanePhase;
+    progress: SyncLaneProgress | null;
+    registrationIndex: number;
+    requestCount: number;
+    requested: boolean;
+    runAbandoned: boolean;
+    runCount: number;
+    running: boolean;
+    status: SyncLaneStatus;
+}
+export interface DomainSyncSnapshot {
+    hasPendingWork: boolean;
+    lanes: ReadonlyArray<SyncLaneSnapshot>;
+    pumpActive: boolean;
+    updatedAt: string;
+}
+interface SyncLaneTelemetryConfig {
+    label?: string | undefined;
+    phase?: SyncLanePhase | undefined;
+}
+interface SyncLaneTelemetryState {
+    blobStorageKey: string | null;
+    config: SyncLaneTelemetryConfig;
+    errorCount: number;
+    key: string;
+    lastAction: SyncLaneLastAction;
+    lastActionAt: string;
+    lastCompletedAt: string | null;
+    lastError: string | null;
+    lastFailedAt: string | null;
+    lastRequestedAt: string | null;
+    lastStartedAt: string | null;
+    progress?: SyncLaneProgress | null;
+    registrationIndex: number;
+    requestCount: number;
+    requested: boolean;
+    runAbandoned: boolean;
+    runCount: number;
+    running: boolean;
+}
+/**
+ * Structural subset of a sync lane needed to order it: its phase and the
+ * registration index that breaks phase ties. Accepts both the coordinator's
+ * `SyncLaneState` and the telemetry `SyncLaneTelemetryState`.
+ */
+interface SyncLaneOrderInput {
+    config: {
+        phase?: SyncLanePhase | undefined;
+    };
+    registrationIndex: number;
+}
+export declare function createSyncTimestamp(): string;
+export declare function compareSyncLaneOrder(left: SyncLaneOrderInput, right: SyncLaneOrderInput): number;
+export declare function createDomainSyncSnapshot(input: {
+    hasPendingWork: boolean;
+    lanes: Iterable<SyncLaneTelemetryState>;
+    pumpActive: boolean;
+}): DomainSyncSnapshot;
+export {};