@tearleads/client-sdk 0.1.33 → 0.1.34

package/data/blobs/transferPool.js

@@ -0,0 +1,53 @@
+/** Bound byte I/O across documents sharing a client, including multipart parts. */
+export const BLOB_TRANSFER_CONCURRENCY = 4;
+const TRANSFER_IDLE_TIMEOUT_MS = 120_000;
+const pools = new WeakMap();
+export async function runBlobTransfer(client, transfer, timeoutMs = TRANSFER_IDLE_TIMEOUT_MS) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        throw new RangeError("Blob transfer timeout must be positive and finite");
+    let pool = pools.get(client);
+    if (!pool) {
+        pool = { active: 0, waiting: [] };
+        pools.set(client, pool);
+    }
+    if (pool.active >= BLOB_TRANSFER_CONCURRENCY) {
+        await new Promise((resolve) => pool.waiting.push(resolve));
+    }
+    else {
+        pool.active += 1;
+    }
+    const controller = new AbortController();
+    let timer;
+    const progress = () => {
+        controller.signal.throwIfAborted();
+        clearTimeout(timer);
+        timer = setTimeout(() => controller.abort(new Error("Blob transfer timed out")), timeoutMs);
+    };
+    progress();
+    try {
+        // A native bridge or custom transport may ignore abort. Bound its logical
+        // ownership anyway; callers must check the signal before accepting results.
+        return await new Promise((resolve, reject) => {
+            const aborted = () => reject(controller.signal.reason);
+            controller.signal.addEventListener("abort", aborted, { once: true });
+            void Promise.resolve()
+                .then(() => transfer(controller.signal, progress))
+                .then((value) => {
+                controller.signal.removeEventListener("abort", aborted);
+                resolve(value);
+            }, (error) => {
+                controller.signal.removeEventListener("abort", aborted);
+                reject(error);
+            });
+        });
+    }
+    finally {
+        clearTimeout(timer);
+        const next = pool.waiting.shift();
+        if (next)
+            next();
+        else
+            pool.active -= 1;
+    }
+}
+//# sourceMappingURL=transferPool.js.map

package/data/blobs/transferPool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transferPool.js","sourceRoot":"","sources":["transferPool.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC;AAC3C,MAAM,wBAAwB,GAAG,OAAO,CAAC;AAKzC,MAAM,KAAK,GAAG,IAAI,OAAO,EAAwB,CAAC;AAElD,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,MAAc,EACd,QAAmE,EACnE,SAAS,GAAG,wBAAwB;IAEpC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,SAAS,IAAI,CAAC;QAC/C,MAAM,IAAI,UAAU,CAAC,mDAAmD,CAAC,CAAC;IAC5E,IAAI,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7B,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,IAAI,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;QAClC,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC1B,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,IAAI,yBAAyB,EAAE,CAAC;QAC7C,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;IACnE,CAAC;SAAM,CAAC;QACN,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;IACnB,CAAC;IACD,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,IAAI,KAAgD,CAAC;IACrD,MAAM,QAAQ,GAAG,GAAG,EAAE;QACpB,UAAU,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC;QACnC,YAAY,CAAC,KAAK,CAAC,CAAC;QACpB,KAAK,GAAG,UAAU,CAChB,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC,EAC5D,SAAS,CACV,CAAC;IACJ,CAAC,CAAC;IACF,QAAQ,EAAE,CAAC;IACX,IAAI,CAAC;QACH,0EAA0E;QAC1E,4EAA4E;QAC5E,OAAO,MAAM,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAC9C,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACvD,UAAU,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YACrE,KAAK,OAAO,CAAC,OAAO,EAAE;iBACnB,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;iBACjD,IAAI,CACH,CAAC,KAAK,EAAE,EAAE;gBACR,UAAU,CAAC,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBACxD,OAAO,CAAC,KAAK,CAAC,CAAC;YACjB,CAAC,EACD,CAAC,KAAc,EAAE,EAAE;gBACjB,UAAU,CAAC,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBACxD,MAAM,CAAC,KAAK,CAAC,CAAC;YAChB,CAAC,CACF,CAAC;QACN,CAAC,CAAC,CAAC;IACL,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;QACpB,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QAClC,IAAI,IAAI;YAAE,IAAI,EAAE,CAAC;;YACZ,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;IACxB,CAAC;AACH,CAAC","sourcesContent":["/** Bound byte I/O across documents sharing a client, including multipart parts. */\nexport const BLOB_TRANSFER_CONCURRENCY = 4;\nconst TRANSFER_IDLE_TIMEOUT_MS = 120_000;\ninterface TransferPool {\n  active: number;\n  waiting: Array<() => void>;\n}\nconst pools = new WeakMap<object, TransferPool>();\n\nexport async function runBlobTransfer<T>(\n  client: object,\n  transfer: (signal: AbortSignal, progress: () => void) => Promise<T>,\n  timeoutMs = TRANSFER_IDLE_TIMEOUT_MS,\n): Promise<T> {\n  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)\n    throw new RangeError(\"Blob transfer timeout must be positive and finite\");\n  let pool = pools.get(client);\n  if (!pool) {\n    pool = { active: 0, waiting: [] };\n    pools.set(client, pool);\n  }\n  if (pool.active >= BLOB_TRANSFER_CONCURRENCY) {\n    await new Promise<void>((resolve) => pool.waiting.push(resolve));\n  } else {\n    pool.active += 1;\n  }\n  const controller = new AbortController();\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  const progress = () => {\n    controller.signal.throwIfAborted();\n    clearTimeout(timer);\n    timer = setTimeout(\n      () => controller.abort(new Error(\"Blob transfer timed out\")),\n      timeoutMs,\n    );\n  };\n  progress();\n  try {\n    // A native bridge or custom transport may ignore abort. Bound its logical\n    // ownership anyway; callers must check the signal before accepting results.\n    return await new Promise<T>((resolve, reject) => {\n      const aborted = () => reject(controller.signal.reason);\n      controller.signal.addEventListener(\"abort\", aborted, { once: true });\n      void Promise.resolve()\n        .then(() => transfer(controller.signal, progress))\n        .then(\n          (value) => {\n            controller.signal.removeEventListener(\"abort\", aborted);\n            resolve(value);\n          },\n          (error: unknown) => {\n            controller.signal.removeEventListener(\"abort\", aborted);\n            reject(error);\n          },\n        );\n    });\n  } finally {\n    clearTimeout(timer);\n    const next = pool.waiting.shift();\n    if (next) next();\n    else pool.active -= 1;\n  }\n}\n"]}

package/data/documents/blob/shared/types.d.ts

@@ -1,4 +1,4 @@
-import type { RequestFailureKind, UploadMultipartBlobPartBytesRequest } from "../../../../internal/api-client/index.js";
+import type { RequestFailureKind, RequestResultOptions, UploadMultipartBlobPartBytesRequest } from "../../../../internal/api-client/index.js";
 import type { BlobContentKeyTarget, BlobEnvelopeHeaderRecord, BlobEnvelopeRecord, WriteHeader } from "../../../../internal/crypto/index.js";
 import type { BlobAttachmentBindRequest, BlobAttachmentDetachRequest, BlobContentKeyBundleRequest, CompleteMultipartBlobStageRequest, InitiateMultipartBlobStageRequest } from "../../../../internal/validators/request/index.js";
 import type { BlobAttachmentBindResponse, BlobAttachmentDetachResponse, BlobAttachmentSummary, CompleteMultipartBlobStageResponse, DocumentWriterProjectionResponse, InitiateMultipartBlobStageResponse, MultipartBlobStageStatusResponse, UploadMultipartBlobPartResponse } from "../../../../internal/validators/response/index.js";
@@ -31,7 +31,7 @@ export interface BlobAttachmentApi {
     getDocumentWriterProjection(documentId: string): Promise<DocumentWriterProjectionResponse | null>;
     getMultipartBlobStage(stageId: string): Promise<MultipartBlobStageStatusResponse | null>;
     initiateMultipartBlobStage(input: InitiateMultipartBlobStageRequest): Promise<InitiateMultipartBlobStageResponse | null>;
-    uploadMultipartBlobPartBytes(stageId: string, partNumber: number, input: UploadMultipartBlobPartBytesRequest): Promise<UploadMultipartBlobPartResponse | null>;
+    uploadMultipartBlobPartBytes(stageId: string, partNumber: number, input: UploadMultipartBlobPartBytesRequest, options?: RequestResultOptions): Promise<UploadMultipartBlobPartResponse | null>;
 }
 export interface BlobAttachmentDetachApi {
     detachBlobAttachment(blobId: string, bindingId: string, input: BlobAttachmentDetachRequest, options?: BlobAttachmentRequestOptions): Promise<BlobAttachmentDetachResponse | null>;

package/data/documents/blob/shared/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["types.ts"],"names":[],"mappings":"AAmCA,MAAM,CAAC,MAAM,mCAAmC,GAC9C,wCAAwC,CAAC;AAC3C,MAAM,CAAC,MAAM,8BAA8B,GACzC,mCAAmC,CAAC;AACtC,MAAM,CAAC,MAAM,gCAAgC,GAC3C,qCAAqC,CAAC;AACxC,MAAM,CAAC,MAAM,6BAA6B,GACxC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,yCAAyC,CAAC,CAAC;AACtE,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,WAAW,EAAE,CAAC","sourcesContent":["import type {\n  RequestFailureKind,\n  UploadMultipartBlobPartBytesRequest,\n} from \"@tearleads/api-client\";\nimport type {\n  BlobContentKeyTarget,\n  BlobEnvelopeHeaderRecord,\n  BlobEnvelopeRecord,\n  WriteHeader,\n} from \"@tearleads/crypto\";\nimport type {\n  BlobAttachmentBindRequest,\n  BlobAttachmentDetachRequest,\n  BlobContentKeyBundleRequest,\n  CompleteMultipartBlobStageRequest,\n  InitiateMultipartBlobStageRequest,\n} from \"@tearleads/validators/request\";\nimport type {\n  BlobAttachmentBindResponse,\n  BlobAttachmentDetachResponse,\n  BlobAttachmentSummary,\n  CompleteMultipartBlobStageResponse,\n  DocumentWriterProjectionResponse,\n  InitiateMultipartBlobStageResponse,\n  MultipartBlobStageStatusResponse,\n  UploadMultipartBlobPartResponse,\n} from \"@tearleads/validators/response\";\nimport type { BlobByteSourceInput, BlobBytes } from \"../../../blobContracts\";\nimport type {\n  ProjectionUserKeyResolver,\n  ReferencedPrincipalPolicyWarmer,\n} from \"../../../keyingProjectionVerification\";\nimport type { ExecSql } from \"../../../sqlite/sqlSchema\";\nimport type { DocumentCreateAuthor } from \"../../shared/types\";\n\nexport const BLOB_CONTENT_RECORD_KEY_INFO_DOMAIN =\n  \"tearleads.blob.content-record-key-info\";\nexport const BLOB_CONTENT_RECORD_AAD_DOMAIN =\n  \"tearleads.blob.content-record-aad\";\nexport const BLOB_CONTENT_RECORD_NONCE_DOMAIN =\n  \"tearleads.blob.content-record-nonce\";\nexport const BLOB_CONTENT_RECORD_HKDF_SALT: Uint8Array<ArrayBuffer> =\n  new TextEncoder().encode(\"tearleads.blob.content-record-hkdf-salt\");\nexport const TEXT_ENCODER = new TextEncoder();\n\nexport interface BlobAttachmentRequestOptions {\n  readonly expectedPaymentRequiredOrganizationId?: string | undefined;\n}\n\nexport interface BlobAttachmentApi {\n  bindBlobAttachment(\n    blobId: string,\n    input: BlobAttachmentBindRequest,\n    options?: BlobAttachmentRequestOptions,\n  ): Promise<BlobAttachmentBindResponse | null>;\n  clearWriterProjectionCaches?(): void;\n  evictDocumentWriterProjection?(documentId: string): void;\n  getRequestFailure?(input: {\n    method: \"DELETE\" | \"GET\" | \"POST\" | \"PUT\";\n    path: string;\n  }): {\n    readonly code?: string | undefined;\n    readonly kind: RequestFailureKind;\n    readonly message: string;\n    readonly status: number | null;\n  } | null;\n  completeMultipartBlobStage(\n    stageId: string,\n    input: CompleteMultipartBlobStageRequest,\n  ): Promise<CompleteMultipartBlobStageResponse | null>;\n  getDocumentWriterProjection(\n    documentId: string,\n  ): Promise<DocumentWriterProjectionResponse | null>;\n  getMultipartBlobStage(\n    stageId: string,\n  ): Promise<MultipartBlobStageStatusResponse | null>;\n  initiateMultipartBlobStage(\n    input: InitiateMultipartBlobStageRequest,\n  ): Promise<InitiateMultipartBlobStageResponse | null>;\n  uploadMultipartBlobPartBytes(\n    stageId: string,\n    partNumber: number,\n    input: UploadMultipartBlobPartBytesRequest,\n  ): Promise<UploadMultipartBlobPartResponse | null>;\n}\n\nexport interface BlobAttachmentDetachApi {\n  detachBlobAttachment(\n    blobId: string,\n    bindingId: string,\n    input: BlobAttachmentDetachRequest,\n    options?: BlobAttachmentRequestOptions,\n  ): Promise<BlobAttachmentDetachResponse | null>;\n  getDocumentWriterProjection(\n    documentId: string,\n  ): Promise<DocumentWriterProjectionResponse | null>;\n}\n\nexport type { BlobContentKeyTarget };\n\n/**\n * Aliases of the crypto parser's own types. The parser is shared with the API,\n * so restating these shapes here would let the two drift apart silently.\n */\nexport type BlobEncryptedBytesRecord = BlobEnvelopeRecord;\n\n/**\n * The envelope as the header establishes it. Streaming readers hold this\n * before any ciphertext is read, so it has no `chunks`: an empty array there\n * would read as an empty object rather than an unread one.\n */\nexport type BlobEncryptedBytesHeader = BlobEnvelopeHeaderRecord;\n\nexport type BlobEncryptedChunk = BlobEnvelopeRecord[\"chunks\"][number];\n\nexport interface BlobSourceSnapshot {\n  readonly byteLength: number;\n  readonly chunkSha256: readonly string[];\n  readonly chunkSize: number;\n  readonly sha256: string;\n}\n\nexport interface BlobEncryptionPlan {\n  readonly byteLength: number;\n  readonly chunkSize: number;\n  readonly metadataHash: string;\n  readonly partCount: number;\n  readonly plaintextByteLength: number;\n  readonly plaintextSha256: string;\n  readonly sha256: string;\n  encryptPart(index: number): Promise<BlobBytes>;\n  getPartByteLength(index: number): number;\n}\n\nexport interface DocumentManifestIdentity {\n  documentId: string;\n  manifestHash: string;\n  organizationId: string;\n}\n\nexport interface BlobAttachmentMaterial {\n  blobAccessManifestHash: string;\n  contentKeyBundle: BlobContentKeyBundleRequest;\n  encrypted: BlobEncryptionPlan;\n  manifestIdentity: DocumentManifestIdentity;\n  targetHash: string;\n  targets: BlobContentKeyTarget[];\n  writerProjection: DocumentWriterProjectionResponse;\n}\n\n/**\n * Progress for an in-flight multipart blob upload.\n */\nexport interface MultipartUploadProgress {\n  readonly bytesTotal: number;\n  readonly bytesUploaded: number;\n  readonly partsCompleted: number;\n  readonly partsTotal: number;\n}\n\nexport type MultipartUploadProgressListener = (\n  progress: MultipartUploadProgress,\n) => void;\n\n/**\n * Fires once a multipart stage has been opened (or resumed), with its id and\n * plaintext chunk size. Callers persist both so a later attempt can reproduce\n * the same encrypted parts and resume instead of orphaning the partial upload.\n */\nexport type MultipartStageResolvedListener = (input: {\n  readonly partSize: number;\n  readonly stageId: string;\n}) => void | Promise<void>;\n\nexport interface UploadDocumentAttachmentInput {\n  apiClient: BlobAttachmentApi;\n  author: DocumentCreateAuthor;\n  blobId?: string | undefined;\n  bindingId?: string | undefined;\n  bytes: BlobByteSourceInput;\n  contentKey?: Uint8Array | undefined;\n  contentKeyEpoch?: number | undefined;\n  documentId: string;\n  eventId?: string | undefined;\n  execSql: ExecSql;\n  expectedBindingId: string | null;\n  isRemoteSyncBlocked?: ((organizationId: string) => boolean) | undefined;\n  // A persisted nonce seed. The plaintext digest derives the envelope IV from\n  // it, then each chunk derives a unique IV. Same-source retries reproduce the\n  // encrypted parts; changed bytes cannot reuse their AES-GCM nonces.\n  nonceSeed?: Uint8Array | undefined;\n  multipart?: MultipartBlobUploadOptions | undefined;\n  onMultipartProgress?: MultipartUploadProgressListener | undefined;\n  onStageResolved?: MultipartStageResolvedListener | undefined;\n  resolveProjectionUserKey: ProjectionUserKeyResolver;\n  signedAt?: string | undefined;\n  slotId: string;\n  targetSecretKey: Uint8Array;\n  warmReferencedPrincipalPolicies?: ReferencedPrincipalPolicyWarmer | undefined;\n  writerProjection?: DocumentWriterProjectionResponse | undefined;\n}\n\nexport interface MultipartBlobUploadOptions {\n  /** Exactly 5 MiB per plaintext encryption chunk; transport parts include envelope overhead. */\n  readonly partSize: number;\n  // The id of a previously opened stage to resume. When set, the upload refetches\n  // that stage and skips parts the server already has instead of opening a new\n  // one; if the stage is gone (expired), it falls back to a fresh stage.\n  readonly resumeStageId?: string | undefined;\n  readonly uploadConcurrency?: number | undefined;\n}\n\nexport interface UploadDocumentAttachmentResult {\n  blobId: string;\n  bindingId: string;\n  request: BlobAttachmentBindRequest;\n  response: BlobAttachmentBindResponse;\n  sha256: string;\n  byteLength: number;\n  writeHeader: WriteHeader;\n  writeHeaderHash: string;\n  writerProjection: DocumentWriterProjectionResponse;\n}\n\nexport interface DetachDocumentAttachmentInput {\n  apiClient: BlobAttachmentDetachApi;\n  author: DocumentCreateAuthor;\n  bindingId: string;\n  blobId: string;\n  documentId: string;\n  eventId?: string | undefined;\n  execSql: ExecSql;\n  isRemoteSyncBlocked?: ((organizationId: string) => boolean) | undefined;\n  resolveProjectionUserKey: ProjectionUserKeyResolver;\n  signedAt?: string | undefined;\n  slotId: string;\n  stillCurrent?: (() => boolean) | undefined;\n  warmReferencedPrincipalPolicies?: ReferencedPrincipalPolicyWarmer | undefined;\n  writerProjection?: DocumentWriterProjectionResponse | undefined;\n}\n\nexport interface DetachDocumentAttachmentResult {\n  request: BlobAttachmentDetachRequest;\n  response: BlobAttachmentDetachResponse;\n  writerProjection: DocumentWriterProjectionResponse;\n}\n\nexport interface DecryptDocumentAttachmentBlobInput {\n  binding: BlobAttachmentSummary;\n  encryptedBytes: BlobBytes;\n  expectedDocumentId: string;\n  expectedSlotId: string;\n  execSql: ExecSql;\n  resolveProjectionUserKey: ProjectionUserKeyResolver;\n  targetSecretKey: Uint8Array;\n  stillCurrent?: (() => boolean) | undefined;\n  warmReferencedPrincipalPolicies?: ReferencedPrincipalPolicyWarmer | undefined;\n  writerProjection: DocumentWriterProjectionResponse;\n}\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["types.ts"],"names":[],"mappings":"AAoCA,MAAM,CAAC,MAAM,mCAAmC,GAC9C,wCAAwC,CAAC;AAC3C,MAAM,CAAC,MAAM,8BAA8B,GACzC,mCAAmC,CAAC;AACtC,MAAM,CAAC,MAAM,gCAAgC,GAC3C,qCAAqC,CAAC;AACxC,MAAM,CAAC,MAAM,6BAA6B,GACxC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,yCAAyC,CAAC,CAAC;AACtE,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,WAAW,EAAE,CAAC","sourcesContent":["import type {\n  RequestFailureKind,\n  RequestResultOptions,\n  UploadMultipartBlobPartBytesRequest,\n} from \"@tearleads/api-client\";\nimport type {\n  BlobContentKeyTarget,\n  BlobEnvelopeHeaderRecord,\n  BlobEnvelopeRecord,\n  WriteHeader,\n} from \"@tearleads/crypto\";\nimport type {\n  BlobAttachmentBindRequest,\n  BlobAttachmentDetachRequest,\n  BlobContentKeyBundleRequest,\n  CompleteMultipartBlobStageRequest,\n  InitiateMultipartBlobStageRequest,\n} from \"@tearleads/validators/request\";\nimport type {\n  BlobAttachmentBindResponse,\n  BlobAttachmentDetachResponse,\n  BlobAttachmentSummary,\n  CompleteMultipartBlobStageResponse,\n  DocumentWriterProjectionResponse,\n  InitiateMultipartBlobStageResponse,\n  MultipartBlobStageStatusResponse,\n  UploadMultipartBlobPartResponse,\n} from \"@tearleads/validators/response\";\nimport type { BlobByteSourceInput, BlobBytes } from \"../../../blobContracts\";\nimport type {\n  ProjectionUserKeyResolver,\n  ReferencedPrincipalPolicyWarmer,\n} from \"../../../keyingProjectionVerification\";\nimport type { ExecSql } from \"../../../sqlite/sqlSchema\";\nimport type { DocumentCreateAuthor } from \"../../shared/types\";\n\nexport const BLOB_CONTENT_RECORD_KEY_INFO_DOMAIN =\n  \"tearleads.blob.content-record-key-info\";\nexport const BLOB_CONTENT_RECORD_AAD_DOMAIN =\n  \"tearleads.blob.content-record-aad\";\nexport const BLOB_CONTENT_RECORD_NONCE_DOMAIN =\n  \"tearleads.blob.content-record-nonce\";\nexport const BLOB_CONTENT_RECORD_HKDF_SALT: Uint8Array<ArrayBuffer> =\n  new TextEncoder().encode(\"tearleads.blob.content-record-hkdf-salt\");\nexport const TEXT_ENCODER = new TextEncoder();\n\nexport interface BlobAttachmentRequestOptions {\n  readonly expectedPaymentRequiredOrganizationId?: string | undefined;\n}\n\nexport interface BlobAttachmentApi {\n  bindBlobAttachment(\n    blobId: string,\n    input: BlobAttachmentBindRequest,\n    options?: BlobAttachmentRequestOptions,\n  ): Promise<BlobAttachmentBindResponse | null>;\n  clearWriterProjectionCaches?(): void;\n  evictDocumentWriterProjection?(documentId: string): void;\n  getRequestFailure?(input: {\n    method: \"DELETE\" | \"GET\" | \"POST\" | \"PUT\";\n    path: string;\n  }): {\n    readonly code?: string | undefined;\n    readonly kind: RequestFailureKind;\n    readonly message: string;\n    readonly status: number | null;\n  } | null;\n  completeMultipartBlobStage(\n    stageId: string,\n    input: CompleteMultipartBlobStageRequest,\n  ): Promise<CompleteMultipartBlobStageResponse | null>;\n  getDocumentWriterProjection(\n    documentId: string,\n  ): Promise<DocumentWriterProjectionResponse | null>;\n  getMultipartBlobStage(\n    stageId: string,\n  ): Promise<MultipartBlobStageStatusResponse | null>;\n  initiateMultipartBlobStage(\n    input: InitiateMultipartBlobStageRequest,\n  ): Promise<InitiateMultipartBlobStageResponse | null>;\n  uploadMultipartBlobPartBytes(\n    stageId: string,\n    partNumber: number,\n    input: UploadMultipartBlobPartBytesRequest,\n    options?: RequestResultOptions,\n  ): Promise<UploadMultipartBlobPartResponse | null>;\n}\n\nexport interface BlobAttachmentDetachApi {\n  detachBlobAttachment(\n    blobId: string,\n    bindingId: string,\n    input: BlobAttachmentDetachRequest,\n    options?: BlobAttachmentRequestOptions,\n  ): Promise<BlobAttachmentDetachResponse | null>;\n  getDocumentWriterProjection(\n    documentId: string,\n  ): Promise<DocumentWriterProjectionResponse | null>;\n}\n\nexport type { BlobContentKeyTarget };\n\n/**\n * Aliases of the crypto parser's own types. The parser is shared with the API,\n * so restating these shapes here would let the two drift apart silently.\n */\nexport type BlobEncryptedBytesRecord = BlobEnvelopeRecord;\n\n/**\n * The envelope as the header establishes it. Streaming readers hold this\n * before any ciphertext is read, so it has no `chunks`: an empty array there\n * would read as an empty object rather than an unread one.\n */\nexport type BlobEncryptedBytesHeader = BlobEnvelopeHeaderRecord;\n\nexport type BlobEncryptedChunk = BlobEnvelopeRecord[\"chunks\"][number];\n\nexport interface BlobSourceSnapshot {\n  readonly byteLength: number;\n  readonly chunkSha256: readonly string[];\n  readonly chunkSize: number;\n  readonly sha256: string;\n}\n\nexport interface BlobEncryptionPlan {\n  readonly byteLength: number;\n  readonly chunkSize: number;\n  readonly metadataHash: string;\n  readonly partCount: number;\n  readonly plaintextByteLength: number;\n  readonly plaintextSha256: string;\n  readonly sha256: string;\n  encryptPart(index: number): Promise<BlobBytes>;\n  getPartByteLength(index: number): number;\n}\n\nexport interface DocumentManifestIdentity {\n  documentId: string;\n  manifestHash: string;\n  organizationId: string;\n}\n\nexport interface BlobAttachmentMaterial {\n  blobAccessManifestHash: string;\n  contentKeyBundle: BlobContentKeyBundleRequest;\n  encrypted: BlobEncryptionPlan;\n  manifestIdentity: DocumentManifestIdentity;\n  targetHash: string;\n  targets: BlobContentKeyTarget[];\n  writerProjection: DocumentWriterProjectionResponse;\n}\n\n/**\n * Progress for an in-flight multipart blob upload.\n */\nexport interface MultipartUploadProgress {\n  readonly bytesTotal: number;\n  readonly bytesUploaded: number;\n  readonly partsCompleted: number;\n  readonly partsTotal: number;\n}\n\nexport type MultipartUploadProgressListener = (\n  progress: MultipartUploadProgress,\n) => void;\n\n/**\n * Fires once a multipart stage has been opened (or resumed), with its id and\n * plaintext chunk size. Callers persist both so a later attempt can reproduce\n * the same encrypted parts and resume instead of orphaning the partial upload.\n */\nexport type MultipartStageResolvedListener = (input: {\n  readonly partSize: number;\n  readonly stageId: string;\n}) => void | Promise<void>;\n\nexport interface UploadDocumentAttachmentInput {\n  apiClient: BlobAttachmentApi;\n  author: DocumentCreateAuthor;\n  blobId?: string | undefined;\n  bindingId?: string | undefined;\n  bytes: BlobByteSourceInput;\n  contentKey?: Uint8Array | undefined;\n  contentKeyEpoch?: number | undefined;\n  documentId: string;\n  eventId?: string | undefined;\n  execSql: ExecSql;\n  expectedBindingId: string | null;\n  isRemoteSyncBlocked?: ((organizationId: string) => boolean) | undefined;\n  // A persisted nonce seed. The plaintext digest derives the envelope IV from\n  // it, then each chunk derives a unique IV. Same-source retries reproduce the\n  // encrypted parts; changed bytes cannot reuse their AES-GCM nonces.\n  nonceSeed?: Uint8Array | undefined;\n  multipart?: MultipartBlobUploadOptions | undefined;\n  onMultipartProgress?: MultipartUploadProgressListener | undefined;\n  onStageResolved?: MultipartStageResolvedListener | undefined;\n  resolveProjectionUserKey: ProjectionUserKeyResolver;\n  signedAt?: string | undefined;\n  slotId: string;\n  targetSecretKey: Uint8Array;\n  warmReferencedPrincipalPolicies?: ReferencedPrincipalPolicyWarmer | undefined;\n  writerProjection?: DocumentWriterProjectionResponse | undefined;\n}\n\nexport interface MultipartBlobUploadOptions {\n  /** Exactly 5 MiB per plaintext encryption chunk; transport parts include envelope overhead. */\n  readonly partSize: number;\n  // The id of a previously opened stage to resume. When set, the upload refetches\n  // that stage and skips parts the server already has instead of opening a new\n  // one; if the stage is gone (expired), it falls back to a fresh stage.\n  readonly resumeStageId?: string | undefined;\n  readonly uploadConcurrency?: number | undefined;\n}\n\nexport interface UploadDocumentAttachmentResult {\n  blobId: string;\n  bindingId: string;\n  request: BlobAttachmentBindRequest;\n  response: BlobAttachmentBindResponse;\n  sha256: string;\n  byteLength: number;\n  writeHeader: WriteHeader;\n  writeHeaderHash: string;\n  writerProjection: DocumentWriterProjectionResponse;\n}\n\nexport interface DetachDocumentAttachmentInput {\n  apiClient: BlobAttachmentDetachApi;\n  author: DocumentCreateAuthor;\n  bindingId: string;\n  blobId: string;\n  documentId: string;\n  eventId?: string | undefined;\n  execSql: ExecSql;\n  isRemoteSyncBlocked?: ((organizationId: string) => boolean) | undefined;\n  resolveProjectionUserKey: ProjectionUserKeyResolver;\n  signedAt?: string | undefined;\n  slotId: string;\n  stillCurrent?: (() => boolean) | undefined;\n  warmReferencedPrincipalPolicies?: ReferencedPrincipalPolicyWarmer | undefined;\n  writerProjection?: DocumentWriterProjectionResponse | undefined;\n}\n\nexport interface DetachDocumentAttachmentResult {\n  request: BlobAttachmentDetachRequest;\n  response: BlobAttachmentDetachResponse;\n  writerProjection: DocumentWriterProjectionResponse;\n}\n\nexport interface DecryptDocumentAttachmentBlobInput {\n  binding: BlobAttachmentSummary;\n  encryptedBytes: BlobBytes;\n  expectedDocumentId: string;\n  expectedSlotId: string;\n  execSql: ExecSql;\n  resolveProjectionUserKey: ProjectionUserKeyResolver;\n  targetSecretKey: Uint8Array;\n  stillCurrent?: (() => boolean) | undefined;\n  warmReferencedPrincipalPolicies?: ReferencedPrincipalPolicyWarmer | undefined;\n  writerProjection: DocumentWriterProjectionResponse;\n}\n"]}

package/data/sync/coordinatorLaneRun.js

@@ -0,0 +1,154 @@
+import { describeSyncLaneError, publishSyncCoordinatorSnapshot, } from "./coordinatorState.js";
+import { createSyncTimestamp } from "./syncTelemetry.js";
+const SYNC_LANE_WATCHDOG_MS = 120_000;
+const FAILED_LANE_REARM_BACKOFF_MS = 1000;
+// Keyed on the registered config so a discarded lane is collectable.
+const lastReportedFailureByConfig = new WeakMap();
+// Local-only dedup key. describeSyncLaneError joins messages without their
+// types, so the name keeps a swallowed DatabaseUnavailableError distinct from
+// a plain Error carrying the same text; the cause chain keeps a re-wrapped
+// failure distinct from its origin.
+function describeSyncLaneFailureSignature(error) {
+    const name = error instanceof Error ? error.name : typeof error;
+    return JSON.stringify([name, describeSyncLaneError(error)]);
+}
+// Observability only: a failing lane re-arms every FAILED_LANE_REARM_BACKOFF_MS
+// for the rest of the session, and mobile WebViews are never reloaded, so an
+// unrecoverable lane would report once a second. The signature is deliberately
+// never cleared on a completed run: alternating success and failure would
+// re-admit the same report every pass and evict the surrounding diagnostic
+// trail from the host's bounded log.
+function reportUnexpectedSyncLaneFailure(state, error) {
+    const report = state.config.reportUnexpectedError;
+    if (!report)
+        return;
+    const signature = describeSyncLaneFailureSignature(error);
+    if (lastReportedFailureByConfig.get(state.config) === signature)
+        return;
+    lastReportedFailureByConfig.set(state.config, signature);
+    try {
+        void Promise.resolve(report(error)).catch(() => undefined);
+    }
+    catch {
+        // Hosts may throw synchronously or return a rejected promise.
+    }
+}
+async function runSyncLane(state) {
+    try {
+        await state.config.run();
+        return { status: "completed" };
+    }
+    catch (error) {
+        if (state.config.shouldIgnoreError?.(error)) {
+            return { status: "completed" };
+        }
+        reportUnexpectedSyncLaneFailure(state, error);
+        if (state.config.onUnexpectedError) {
+            state.config.onUnexpectedError(error);
+            return { status: "failed", error };
+        }
+        throw error;
+    }
+}
+// Console-only on purpose. This runs only when the lane's OWN error handler
+// already threw, so it must never route through reportUnexpectedSyncLaneFailure
+// as well: re-entering a handler that just threw would reject runResultPromise
+// from inside its own onRejected callback, leaving `running` true and
+// `activeRunToken` set, which wedges the lane for the rest of the session.
+function reportUnexpectedSyncLaneError(state, error) {
+    console.error(`Failed to run sync lane ${state.key}:`, error);
+}
+function recordSyncLaneRunResult(lane, runResult) {
+    lane.lastActionAt = createSyncTimestamp();
+    if (runResult.status === "failed") {
+        lane.errorCount += 1;
+        lane.lastAction = "failed";
+        lane.lastError = describeSyncLaneError(runResult.error);
+        lane.lastFailedAt = lane.lastActionAt;
+    }
+    else {
+        lane.lastAction = "completed";
+        lane.lastCompletedAt = lane.lastActionAt;
+        lane.lastError = null;
+    }
+}
+// Replace the watchdog failure with the late result, then release queued work.
+function settleAbandonedSyncLaneRun(coordinatorState, lane, runToken, runResult, wake) {
+    if (lane.activeRunToken !== runToken) {
+        return;
+    }
+    lane.activeRunToken = null;
+    lane.runAbandoned = false;
+    recordSyncLaneRunResult(lane, runResult);
+    publishSyncCoordinatorSnapshot(coordinatorState);
+    if (!coordinatorState.disposed && lane.requested) {
+        wake();
+    }
+}
+function startSyncLaneRun(coordinatorState, lane) {
+    lane.requested = false;
+    lane.notBeforeAtMs = null;
+    lane.running = true;
+    lane.runCount += 1;
+    lane.lastAction = "started";
+    lane.lastActionAt = createSyncTimestamp();
+    lane.lastStartedAt = lane.lastActionAt;
+    lane.runAbandoned = false;
+    const runToken = {};
+    lane.activeRunToken = runToken;
+    publishSyncCoordinatorSnapshot(coordinatorState);
+    // Keep follow-up requests even on failure to preserve phase ordering; see
+    // docs/client-sync-ordering.md.
+    // The fallback also catches errors thrown by the lane's error handlers.
+    const runResultPromise = runSyncLane(lane).then((result) => result, (error) => {
+        reportUnexpectedSyncLaneError(lane, error);
+        return { status: "failed", error };
+    });
+    return { runToken, runResultPromise };
+}
+export async function runCoordinatorLane(coordinatorState, lane, wake) {
+    const { runToken, runResultPromise } = startSyncLaneRun(coordinatorState, lane);
+    // Clamp overrides to at least 1ms so every run has a chance to complete.
+    const watchdogMs = Math.max(1, lane.config.watchdogMs ?? SYNC_LANE_WATCHDOG_MS);
+    let watchdogTimer = null;
+    const raceOutcome = await Promise.race([
+        runResultPromise.then((result) => ({
+            kind: "settled",
+            result,
+        })),
+        new Promise((resolve) => {
+            watchdogTimer = setTimeout(() => resolve({ kind: "timed-out" }), watchdogMs);
+        }),
+    ]);
+    if (watchdogTimer !== null) {
+        clearTimeout(watchdogTimer);
+    }
+    lane.running = false;
+    let runResult;
+    if (raceOutcome.kind === "settled") {
+        lane.activeRunToken = null;
+        runResult = raceOutcome.result;
+    }
+    else {
+        lane.runAbandoned = true;
+        runResult = {
+            status: "failed",
+            error: new Error(`Sync lane watchdog: run exceeded ${watchdogMs}ms; continuing with other lanes`),
+        };
+        void runResultPromise.then((result) => settleAbandonedSyncLaneRun(coordinatorState, lane, runToken, result, wake));
+    }
+    recordSyncLaneRunResult(lane, runResult);
+    publishSyncCoordinatorSnapshot(coordinatorState);
+    if (runResult.status === "failed" &&
+        lane.requested &&
+        raceOutcome.kind === "settled") {
+        // A fresh hint cannot bypass a failed lane's cooldown. Other document
+        // lanes remain runnable; structural retries still preserve the barrier.
+        lane.backingOff = true;
+        setTimeout(() => {
+            lane.backingOff = false;
+            wake();
+        }, FAILED_LANE_REARM_BACKOFF_MS);
+    }
+}
+//# sourceMappingURL=coordinatorLaneRun.js.map

package/data/sync/coordinatorLaneRun.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinatorLaneRun.js","sourceRoot":"","sources":["coordinatorLaneRun.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  DomainSyncCoordinatorState,\n  SyncLaneState,\n} from \"./coordinatorState\";\nimport {\n  describeSyncLaneError,\n  publishSyncCoordinatorSnapshot,\n} from \"./coordinatorState\";\nimport type { SyncLaneConfig } from \"./syncLaneConfig\";\nimport { createSyncTimestamp } from \"./syncTelemetry\";\n\nconst SYNC_LANE_WATCHDOG_MS = 120_000;\nconst FAILED_LANE_REARM_BACKOFF_MS = 1000;\n\ntype SyncLaneRunResult =\n  | { status: \"completed\" }\n  | { status: \"failed\"; error: unknown };\n\n// Keyed on the registered config so a discarded lane is collectable.\nconst lastReportedFailureByConfig = new WeakMap<SyncLaneConfig, string>();\n\n// Local-only dedup key. describeSyncLaneError joins messages without their\n// types, so the name keeps a swallowed DatabaseUnavailableError distinct from\n// a plain Error carrying the same text; the cause chain keeps a re-wrapped\n// failure distinct from its origin.\nfunction describeSyncLaneFailureSignature(error: unknown): string {\n  const name = error instanceof Error ? error.name : typeof error;\n  return JSON.stringify([name, describeSyncLaneError(error)]);\n}\n\n// Observability only: a failing lane re-arms every FAILED_LANE_REARM_BACKOFF_MS\n// for the rest of the session, and mobile WebViews are never reloaded, so an\n// unrecoverable lane would report once a second. The signature is deliberately\n// never cleared on a completed run: alternating success and failure would\n// re-admit the same report every pass and evict the surrounding diagnostic\n// trail from the host's bounded log.\nfunction reportUnexpectedSyncLaneFailure(\n  state: SyncLaneState,\n  error: unknown,\n): void {\n  const report = state.config.reportUnexpectedError;\n  if (!report) return;\n  const signature = describeSyncLaneFailureSignature(error);\n  if (lastReportedFailureByConfig.get(state.config) === signature) return;\n  lastReportedFailureByConfig.set(state.config, signature);\n  try {\n    void Promise.resolve(report(error)).catch(() => undefined);\n  } catch {\n    // Hosts may throw synchronously or return a rejected promise.\n  }\n}\n\nasync function runSyncLane(state: SyncLaneState): Promise<SyncLaneRunResult> {\n  try {\n    await state.config.run();\n    return { status: \"completed\" };\n  } catch (error: unknown) {\n    if (state.config.shouldIgnoreError?.(error)) {\n      return { status: \"completed\" };\n    }\n    reportUnexpectedSyncLaneFailure(state, error);\n\n    if (state.config.onUnexpectedError) {\n      state.config.onUnexpectedError(error);\n      return { status: \"failed\", error };\n    }\n\n    throw error;\n  }\n}\n\n// Console-only on purpose. This runs only when the lane's OWN error handler\n// already threw, so it must never route through reportUnexpectedSyncLaneFailure\n// as well: re-entering a handler that just threw would reject runResultPromise\n// from inside its own onRejected callback, leaving `running` true and\n// `activeRunToken` set, which wedges the lane for the rest of the session.\nfunction reportUnexpectedSyncLaneError(state: SyncLaneState, error: unknown) {\n  console.error(`Failed to run sync lane ${state.key}:`, error);\n}\n\nfunction recordSyncLaneRunResult(\n  lane: SyncLaneState,\n  runResult: SyncLaneRunResult,\n): void {\n  lane.lastActionAt = createSyncTimestamp();\n  if (runResult.status === \"failed\") {\n    lane.errorCount += 1;\n    lane.lastAction = \"failed\";\n    lane.lastError = describeSyncLaneError(runResult.error);\n    lane.lastFailedAt = lane.lastActionAt;\n  } else {\n    lane.lastAction = \"completed\";\n    lane.lastCompletedAt = lane.lastActionAt;\n    lane.lastError = null;\n  }\n}\n\n// Replace the watchdog failure with the late result, then release queued work.\nfunction settleAbandonedSyncLaneRun(\n  coordinatorState: DomainSyncCoordinatorState,\n  lane: SyncLaneState,\n  runToken: object,\n  runResult: SyncLaneRunResult,\n  wake: () => void,\n): void {\n  if (lane.activeRunToken !== runToken) {\n    return;\n  }\n  lane.activeRunToken = null;\n  lane.runAbandoned = false;\n  recordSyncLaneRunResult(lane, runResult);\n  publishSyncCoordinatorSnapshot(coordinatorState);\n  if (!coordinatorState.disposed && lane.requested) {\n    wake();\n  }\n}\n\nfunction startSyncLaneRun(\n  coordinatorState: DomainSyncCoordinatorState,\n  lane: SyncLaneState,\n) {\n  lane.requested = false;\n  lane.notBeforeAtMs = null;\n  lane.running = true;\n  lane.runCount += 1;\n  lane.lastAction = \"started\";\n  lane.lastActionAt = createSyncTimestamp();\n  lane.lastStartedAt = lane.lastActionAt;\n  lane.runAbandoned = false;\n  const runToken = {};\n  lane.activeRunToken = runToken;\n  publishSyncCoordinatorSnapshot(coordinatorState);\n\n  // Keep follow-up requests even on failure to preserve phase ordering; see\n  // docs/client-sync-ordering.md.\n  // The fallback also catches errors thrown by the lane's error handlers.\n  const runResultPromise: Promise<SyncLaneRunResult> = runSyncLane(lane).then(\n    (result) => result,\n    (error: unknown) => {\n      reportUnexpectedSyncLaneError(lane, error);\n      return { status: \"failed\", error };\n    },\n  );\n\n  return { runToken, runResultPromise };\n}\n\nexport async function runCoordinatorLane(\n  coordinatorState: DomainSyncCoordinatorState,\n  lane: SyncLaneState,\n  wake: () => void,\n): Promise<void> {\n  const { runToken, runResultPromise } = startSyncLaneRun(\n    coordinatorState,\n    lane,\n  );\n  // Clamp overrides to at least 1ms so every run has a chance to complete.\n  const watchdogMs = Math.max(\n    1,\n    lane.config.watchdogMs ?? SYNC_LANE_WATCHDOG_MS,\n  );\n  let watchdogTimer: ReturnType<typeof setTimeout> | null = null;\n  const raceOutcome = await Promise.race([\n    runResultPromise.then((result) => ({\n      kind: \"settled\" as const,\n      result,\n    })),\n    new Promise<{ kind: \"timed-out\" }>((resolve) => {\n      watchdogTimer = setTimeout(\n        () => resolve({ kind: \"timed-out\" }),\n        watchdogMs,\n      );\n    }),\n  ]);\n  if (watchdogTimer !== null) {\n    clearTimeout(watchdogTimer);\n  }\n\n  lane.running = false;\n  let runResult: SyncLaneRunResult;\n  if (raceOutcome.kind === \"settled\") {\n    lane.activeRunToken = null;\n    runResult = raceOutcome.result;\n  } else {\n    lane.runAbandoned = true;\n    runResult = {\n      status: \"failed\",\n      error: new Error(\n        `Sync lane watchdog: run exceeded ${watchdogMs}ms; continuing with other lanes`,\n      ),\n    };\n    void runResultPromise.then((result) =>\n      settleAbandonedSyncLaneRun(\n        coordinatorState,\n        lane,\n        runToken,\n        result,\n        wake,\n      ),\n    );\n  }\n  recordSyncLaneRunResult(lane, runResult);\n  publishSyncCoordinatorSnapshot(coordinatorState);\n\n  if (\n    runResult.status === \"failed\" &&\n    lane.requested &&\n    raceOutcome.kind === \"settled\"\n  ) {\n    // A fresh hint cannot bypass a failed lane's cooldown. Other document\n    // lanes remain runnable; structural retries still preserve the barrier.\n    lane.backingOff = true;\n    setTimeout(() => {\n      lane.backingOff = false;\n      wake();\n    }, FAILED_LANE_REARM_BACKOFF_MS);\n  }\n}\n"]}

package/data/sync/coordinatorPump.js

@@ -1,85 +1,46 @@
-import { describeSyncLaneError, hasPendingLaneWork, publishSyncCoordinatorSnapshot, } from "./coordinatorState.js";
+import { runCoordinatorLane } from "./coordinatorLaneRun.js";
+import { hasPendingLaneWork, publishSyncCoordinatorSnapshot, } from "./coordinatorState.js";
 import { compareSyncLaneOrder, createSyncTimestamp } from "./syncTelemetry.js";
 const DEFAULT_SYNC_IDLE_INTERVAL_MS = 10;
 const DEFAULT_SYNC_IDLE_QUIET_MS = 0;
 const DEFAULT_SYNC_IDLE_TIMEOUT_MS = 500;
-// Slow down repeated failures and yield periodically during successful bursts
-// so lanes that keep requesting work cannot starve timers or other tasks.
-const FAILED_LANE_REARM_BACKOFF_MS = 1000;
-// Allow normal convergence bursts to finish without a timer delay.
+const DOCUMENT_LANE_CONCURRENCY = 4;
 const SYNC_PUMP_MACROTASK_YIELD_INTERVAL = 16;
-// A timed-out run keeps its lane occupied until it settles, but releases the
-// serial pump so other lanes can proceed.
-const SYNC_LANE_WATCHDOG_MS = 120_000;
-// Keyed on the registered config so a discarded lane is collectable.
-const lastReportedFailureByConfig = new WeakMap();
-// Local-only dedup key. describeSyncLaneError joins messages without their
-// types, so the name keeps a swallowed DatabaseUnavailableError distinct from
-// a plain Error carrying the same text; the cause chain keeps a re-wrapped
-// failure distinct from its origin.
-function describeSyncLaneFailureSignature(error) {
-    const name = error instanceof Error ? error.name : typeof error;
-    return JSON.stringify([name, describeSyncLaneError(error)]);
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
 }
-// Observability only: a failing lane re-arms every FAILED_LANE_REARM_BACKOFF_MS
-// for the rest of the session, and mobile WebViews are never reloaded, so an
-// unrecoverable lane would report once a second. The signature is deliberately
-// never cleared on a completed run: alternating success and failure would
-// re-admit the same report every pass and evict the surrounding diagnostic
-// trail from the host's bounded log.
-function reportUnexpectedSyncLaneFailure(state, error) {
-    const report = state.config.reportUnexpectedError;
-    if (!report)
-        return;
-    const signature = describeSyncLaneFailureSignature(error);
-    if (lastReportedFailureByConfig.get(state.config) === signature)
-        return;
-    lastReportedFailureByConfig.set(state.config, signature);
+// Priority is a scheduling hint, never permission to abandon active workers.
+function readLanePriority(lane) {
     try {
-        void Promise.resolve(report(error)).catch(() => undefined);
+        const priority = lane.config.priority?.() ?? 0;
+        return Number.isFinite(priority) ? priority : 0;
     }
     catch {
-        // Hosts may throw synchronously or return a rejected promise.
+        return 0;
     }
 }
-async function runSyncLane(state) {
-    try {
-        await state.config.run();
-        return { status: "completed" };
+function compareRequestedLanes(left, right) {
+    if ((left.config.phase ?? "document") !== (right.config.phase ?? "document")) {
+        return compareSyncLaneOrder(left, right);
     }
-    catch (error) {
-        if (state.config.shouldIgnoreError?.(error)) {
-            return { status: "completed" };
-        }
-        reportUnexpectedSyncLaneFailure(state, error);
-        if (state.config.onUnexpectedError) {
-            state.config.onUnexpectedError(error);
-            return { status: "failed", error };
-        }
-        throw error;
-    }
-}
-// Console-only on purpose. This runs only when the lane's OWN error handler
-// already threw, so it must never route through reportUnexpectedSyncLaneFailure
-// as well: re-entering a handler that just threw would reject runResultPromise
-// from inside its own onRejected callback, leaving `running` true and
-// `activeRunToken` set, which wedges the lane for the rest of the session.
-function reportUnexpectedSyncLaneError(state, error) {
-    console.error(`Failed to run sync lane ${state.key}:`, error);
-}
-function delay(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+    return (readLanePriority(left) - readLanePriority(right) ||
+        left.lastRunOrder - right.lastRunOrder ||
+        compareSyncLaneOrder(left, right));
 }
 // An abandoned run still owns its lane. Its eventual settlement will restart
 // the pump; trying to restart earlier would spin without runnable work.
 function isRequestedLaneAvailable(lane) {
     return lane.pumpDriven && lane.requested && lane.activeRunToken === null;
 }
-function hasRequestedLaneWork(lanes) {
+function hasRunnableLaneWork(laneValues) {
+    const lanes = Array.from(laneValues);
+    const structuralPending = lanes.some((lane) => lane.config.phase === "structural" && isRequestedLaneAvailable(lane));
     const now = Date.now();
     for (const lane of lanes) {
-        if (isRequestedLaneAvailable(lane) &&
-            (lane.notBeforeAtMs === null || lane.notBeforeAtMs <= now)) {
+        if ((!structuralPending || lane.config.phase === "structural") &&
+            isRequestedLaneAvailable(lane) &&
+            (lane.notBeforeAtMs === null || lane.notBeforeAtMs <= now) &&
+            !lane.backingOff) {
             return true;
         }
     }
@@ -90,123 +51,65 @@ function selectNextRequestedLane(lanes) {
     const now = Date.now();
     for (const lane of lanes) {
         if (!isRequestedLaneAvailable(lane) ||
-            (lane.notBeforeAtMs !== null && lane.notBeforeAtMs > now)) {
+            (lane.notBeforeAtMs !== null && lane.notBeforeAtMs > now) ||
+            lane.backingOff) {
             continue;
         }
-        if (!selectedLane || compareSyncLaneOrder(lane, selectedLane) < 0) {
+        if (!selectedLane || compareRequestedLanes(lane, selectedLane) < 0) {
             selectedLane = lane;
         }
     }
     return selectedLane;
 }
-function recordSyncLaneRunResult(lane, runResult) {
-    lane.lastActionAt = createSyncTimestamp();
-    if (runResult.status === "failed") {
-        lane.errorCount += 1;
-        lane.lastAction = "failed";
-        lane.lastError = describeSyncLaneError(runResult.error);
-        lane.lastFailedAt = lane.lastActionAt;
-    }
-    else {
-        lane.lastAction = "completed";
-        lane.lastCompletedAt = lane.lastActionAt;
-        lane.lastError = null;
-    }
-}
-// Replace the watchdog failure with the late result, then release queued work.
-function settleAbandonedSyncLaneRun(coordinatorState, lane, runToken, runResult) {
-    if (lane.activeRunToken !== runToken) {
-        return;
-    }
-    lane.activeRunToken = null;
-    lane.runAbandoned = false;
-    recordSyncLaneRunResult(lane, runResult);
-    publishSyncCoordinatorSnapshot(coordinatorState);
-    if (!coordinatorState.disposed &&
-        hasRequestedLaneWork(coordinatorState.lanes.values())) {
-        scheduleCoordinatorPump(coordinatorState);
-    }
-}
-function startSyncLaneRun(coordinatorState, lane) {
-    lane.requested = false;
-    lane.notBeforeAtMs = null;
-    lane.running = true;
-    lane.runCount += 1;
-    lane.lastAction = "started";
-    lane.lastActionAt = createSyncTimestamp();
-    lane.lastStartedAt = lane.lastActionAt;
-    lane.runAbandoned = false;
-    const runToken = {};
-    lane.activeRunToken = runToken;
-    publishSyncCoordinatorSnapshot(coordinatorState);
-    // Keep follow-up requests even on failure to preserve phase ordering; see
-    // docs/client-sync-ordering.md.
-    // The fallback also catches errors thrown by the lane's error handlers.
-    const runResultPromise = runSyncLane(lane).then((result) => result, (error) => {
-        reportUnexpectedSyncLaneError(lane, error);
-        return { status: "failed", error };
-    });
-    return { runToken, runResultPromise };
-}
-async function runRequestedSyncLanes(coordinatorState) {
-    let runsSinceMacrotaskYield = 0;
-    // Disposal can happen during a run. Finish it before selecting more work.
-    while (!coordinatorState.disposed) {
-        const lane = selectNextRequestedLane(coordinatorState.lanes.values());
-        if (!lane) {
-            return;
-        }
-        const { runToken, runResultPromise } = startSyncLaneRun(coordinatorState, lane);
-        // Clamp overrides to at least 1ms so every run has a chance to complete.
-        const watchdogMs = Math.max(1, lane.config.watchdogMs ?? SYNC_LANE_WATCHDOG_MS);
-        let watchdogTimer = null;
-        const raceOutcome = await Promise.race([
-            runResultPromise.then((result) => ({
-                kind: "settled",
-                result,
-            })),
-            new Promise((resolve) => {
-                watchdogTimer = setTimeout(() => resolve({ kind: "timed-out" }), watchdogMs);
-            }),
-        ]);
-        if (watchdogTimer !== null) {
-            clearTimeout(watchdogTimer);
-        }
-        lane.running = false;
-        let runResult;
-        if (raceOutcome.kind === "settled") {
-            lane.activeRunToken = null;
-            runResult = raceOutcome.result;
-        }
-        else {
-            lane.runAbandoned = true;
-            runResult = {
-                status: "failed",
-                error: new Error(`Sync lane watchdog: run exceeded ${watchdogMs}ms; continuing with other lanes`),
-            };
-            void runResultPromise.then((result) => settleAbandonedSyncLaneRun(coordinatorState, lane, runToken, result));
-        }
-        recordSyncLaneRunResult(lane, runResult);
-        publishSyncCoordinatorSnapshot(coordinatorState);
-        runsSinceMacrotaskYield += 1;
-        if (runResult.status === "failed" &&
-            lane.requested &&
-            raceOutcome.kind === "settled") {
-            // Timed-out runs cannot run again until they settle, so only ordinary
-            // failures need backoff. Other lanes can proceed immediately on timeout.
-            await delay(FAILED_LANE_REARM_BACKOFF_MS);
-            runsSinceMacrotaskYield = 0;
-        }
-        else if (runsSinceMacrotaskYield >= SYNC_PUMP_MACROTASK_YIELD_INTERVAL) {
-            // Awaiting resolved promises only yields microtasks. A timer also lets
-            // the event loop advance when lanes keep requesting each other.
-            await delay(0);
-            runsSinceMacrotaskYield = 0;
+async function runRequestedSyncLanes(state) {
+    const running = new Map();
+    let startsSinceYield = 0;
+    while (!state.disposed || running.size > 0) {
+        // Install the wake-up before selecting or starting work. New requests can
+        // fill unused workers even while another document is waiting on the network.
+        const wakeup = new Promise((resolve) => {
+            state.wakePump = resolve;
+        });
+        let lane = state.disposed
+            ? null
+            : selectNextRequestedLane(state.lanes.values());
+        const structuralPending = Array.from(state.lanes.values()).some((candidate) => candidate.pumpDriven &&
+            candidate.config.phase === "structural" &&
+            (candidate.running ||
+                (candidate.requested && candidate.activeRunToken === null)));
+        const structuralRunning = Array.from(running.keys()).some((candidate) => candidate.config.phase === "structural");
+        if (lane &&
+            (running.size >= DOCUMENT_LANE_CONCURRENCY ||
+                structuralRunning ||
+                (lane.config.phase === "structural"
+                    ? running.size > 0
+                    : structuralPending)))
+            lane = null;
+        if (lane) {
+            const startedLane = lane;
+            lane.lastRunOrder = ++state.nextRunOrder;
+            const run = runCoordinatorLane(state, lane, () => scheduleCoordinatorPump(state)).finally(() => {
+                running.delete(startedLane);
+                state.wakePump?.();
+            });
+            running.set(lane, run);
+            if (++startsSinceYield >= SYNC_PUMP_MACROTASK_YIELD_INTERVAL) {
+                await delay(0);
+                startsSinceYield = 0;
+            }
+            continue;
         }
+        if (running.size === 0)
+            break;
+        await wakeup;
     }
+    state.wakePump = null;
 }
 function scheduleCoordinatorPump(coordinatorState) {
-    if (coordinatorState.pump || coordinatorState.disposed) {
+    if (coordinatorState.disposed)
+        return;
+    if (coordinatorState.pump) {
+        coordinatorState.wakePump?.();
         return;
     }
     coordinatorState.pump = Promise.resolve()
@@ -215,7 +118,7 @@ function scheduleCoordinatorPump(coordinatorState) {
         coordinatorState.pump = null;
         publishSyncCoordinatorSnapshot(coordinatorState);
         if (!coordinatorState.disposed &&
-            hasRequestedLaneWork(coordinatorState.lanes.values())) {
+            hasRunnableLaneWork(coordinatorState.lanes.values())) {
             scheduleCoordinatorPump(coordinatorState);
         }
     });