@tearleads/client-sdk 0.1.63 → 0.1.65

package/data/documents/shared/sync/documentSyncUpdateIsolation.d.ts

@@ -0,0 +1,55 @@
+import { createDocument } from "../../../../internal/loro/index.js";
+import type { DocumentSyncResponse } from "../../../../internal/validators/response/index.js";
+import type { DecryptedDocumentSyncUpdate, SyncRemoteDocumentResult } from "../types.js";
+type DocumentSyncUpdateIsolationStage = "content_key" | "decrypt" | "encrypted_record" | "loro_import" | "loro_metadata" | "plaintext_integrity" | "write_header";
+type SyncResponseUpdate = DocumentSyncResponse["updates"][number];
+type SyncDocument = Awaited<ReturnType<typeof createDocument>>;
+export type IncomingDocumentSyncUpdateValidator = (result: Pick<SyncRemoteDocumentResult, "decryptedUpdates" | "response">) => void | Promise<void>;
+export declare class DocumentSyncUpdateIsolationError extends Error {
+    readonly attribution: "batch" | "update";
+    readonly authorFingerprint: string | null;
+    readonly batchUpdateIds: readonly string[];
+    readonly checkpointKind: "rotate_baseline" | null;
+    readonly ciphertextHash: string | null;
+    readonly contentKeyEpoch: number | null;
+    readonly documentId: string | null;
+    readonly metadataHash: string | null;
+    readonly stage: DocumentSyncUpdateIsolationStage;
+    readonly updateId: string | null;
+    readonly writerUserId: string | null;
+    constructor(input: {
+        batchUpdateIds?: readonly string[] | undefined;
+        cause: unknown;
+        responseUpdate?: SyncResponseUpdate | undefined;
+        stage: DocumentSyncUpdateIsolationStage;
+        updateId: string | null;
+    });
+}
+export declare function isolateDocumentSyncBatchError(input: {
+    cause: unknown;
+    stage: DocumentSyncUpdateIsolationStage;
+    updateIds: readonly string[];
+}): DocumentSyncUpdateIsolationError;
+export declare function isolateDocumentSyncUpdateError(input: {
+    cause: unknown;
+    responseUpdate?: SyncResponseUpdate | undefined;
+    stage: DocumentSyncUpdateIsolationStage;
+    updateId: string;
+}): DocumentSyncUpdateIsolationError;
+export declare function isDocumentSyncUpdateIsolationError(error: unknown): error is DocumentSyncUpdateIsolationError;
+/** Applies checkpoints with the snapshot API before batching ordinary deltas. */
+export declare function importDecryptedDocumentSyncUpdates(document: SyncDocument, updates: readonly DecryptedDocumentSyncUpdate[]): void;
+/** @internal Exported only to exercise the bounded exact-attribution policy. */
+export declare function findUniqueRepairingCandidate<T>(candidates: readonly T[], repairsBatch: (candidate: T, candidateIndex: number) => Promise<boolean>): Promise<T | null>;
+/**
+ * Proves that a decrypted response can be imported before the live document or
+ * any durable sync frontier is mutated. On failure, retries the page without
+ * each candidate so valid sibling dependencies remain in the same batch while
+ * the update whose removal repairs the batch is attributed exactly.
+ */
+export declare function validateDocumentSyncUpdateImports(input: {
+    currentDocument: Awaited<ReturnType<typeof createDocument>>;
+    decryptedUpdates: readonly DecryptedDocumentSyncUpdate[];
+    responseUpdates?: readonly SyncResponseUpdate[] | undefined;
+}): Promise<void>;
+export {};

package/data/documents/shared/sync/documentSyncUpdateIsolation.js

@@ -0,0 +1,298 @@
+import { createDocument, exportFullHistorySnapshot, importSnapshot, importUpdates, LoroImportUnresolvedDependenciesError, updateMatchesDocumentHistory, } from "../../../../internal/loro/index.js";
+const MAX_EXACT_ISOLATION_CANDIDATES = 8;
+const MAX_EXACT_ISOLATION_RETRY_BYTES = 8 * 1024 * 1024;
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function optionalHeaderField(update, field) {
+    const header = update?.writeHeader;
+    return header && typeof header === "object"
+        ? Reflect.get(header, field)
+        : undefined;
+}
+function optionalHeaderString(update, field) {
+    const value = optionalHeaderField(update, field);
+    return typeof value === "string" ? value : null;
+}
+function optionalHeaderEpoch(update) {
+    const value = optionalHeaderField(update, "contentKeyEpoch");
+    return typeof value === "number" && Number.isSafeInteger(value)
+        ? value
+        : null;
+}
+export class DocumentSyncUpdateIsolationError extends Error {
+    attribution;
+    authorFingerprint;
+    batchUpdateIds;
+    checkpointKind;
+    ciphertextHash;
+    contentKeyEpoch;
+    documentId;
+    metadataHash;
+    stage;
+    updateId;
+    writerUserId;
+    constructor(input) {
+        const causeMessage = errorMessage(input.cause);
+        const writerUserId = optionalHeaderString(input.responseUpdate, "writerUserId");
+        const author = writerUserId ?? input.responseUpdate?.authorFingerprint ?? "unknown";
+        const fingerprint = input.responseUpdate?.authorFingerprint ?? "unknown";
+        const epoch = optionalHeaderEpoch(input.responseUpdate) ?? "unknown";
+        const batchUpdateIds = input.updateId === null ? (input.batchUpdateIds ?? []) : [];
+        const subject = input.updateId === null
+            ? `response batch containing ${batchUpdateIds.length} updates; exact update and writer unknown`
+            : `update ${input.updateId} from writer ${author} (fingerprint ${fingerprint}, epoch ${epoch})`;
+        super(`Document sync quarantined ${subject} during ${input.stage}: ${causeMessage}`, { cause: input.cause });
+        this.name = "DocumentSyncUpdateIsolationError";
+        this.attribution = input.updateId === null ? "batch" : "update";
+        this.authorFingerprint = input.responseUpdate?.authorFingerprint ?? null;
+        this.batchUpdateIds = [...batchUpdateIds];
+        this.checkpointKind =
+            input.responseUpdate?.checkpointKind === "rotate_baseline"
+                ? "rotate_baseline"
+                : null;
+        this.ciphertextHash = optionalHeaderString(input.responseUpdate, "ciphertextHash");
+        this.contentKeyEpoch = optionalHeaderEpoch(input.responseUpdate);
+        this.documentId = input.responseUpdate?.documentId ?? null;
+        this.metadataHash = optionalHeaderString(input.responseUpdate, "metadataHash");
+        this.stage = input.stage;
+        this.updateId = input.updateId;
+        this.writerUserId = writerUserId;
+    }
+}
+export function isolateDocumentSyncBatchError(input) {
+    return new DocumentSyncUpdateIsolationError({
+        batchUpdateIds: input.updateIds,
+        cause: input.cause,
+        stage: input.stage,
+        updateId: null,
+    });
+}
+export function isolateDocumentSyncUpdateError(input) {
+    return input.cause instanceof DocumentSyncUpdateIsolationError
+        ? input.cause
+        : new DocumentSyncUpdateIsolationError(input);
+}
+export function isDocumentSyncUpdateIsolationError(error) {
+    return error instanceof DocumentSyncUpdateIsolationError;
+}
+function responseUpdatesById(updates) {
+    return new Map((updates ?? []).map((update) => [update.id, update]));
+}
+function firstDuplicateUpdateId(updates) {
+    const seen = new Set();
+    for (const update of updates) {
+        if (seen.has(update.id))
+            return update.id;
+        seen.add(update.id);
+    }
+    return null;
+}
+function assertImportedUpdatesMatchValidatedHistory(input) {
+    const collisions = input.updates.filter((update) => !updateMatchesDocumentHistory(input.document, update.updateData));
+    if (collisions.length === 0)
+        return;
+    const cause = new Error("incoming Loro update reuses an already-covered frontier with different operations");
+    const [collision] = collisions;
+    if (input.updates.length === 1 && collision) {
+        throw isolateDocumentSyncUpdateError({
+            cause,
+            responseUpdate: input.responseById.get(collision.id),
+            stage: "loro_import",
+            updateId: collision.id,
+        });
+    }
+    throw isolateDocumentSyncBatchError({
+        cause,
+        stage: "loro_import",
+        updateIds: input.updates.map((update) => update.id),
+    });
+}
+async function createValidationDocument(snapshot) {
+    const document = await createDocument(crypto.randomUUID());
+    try {
+        importSnapshot(document, snapshot);
+        return document;
+    }
+    catch (error) {
+        document.free();
+        throw error;
+    }
+}
+function splitDocumentSyncUpdates(updates) {
+    const checkpoints = [];
+    const ordinaryUpdates = [];
+    for (const update of updates) {
+        if (update.checkpointKind === "rotate_baseline" &&
+            update.checkpointPayloadKind === "full_history_snapshot") {
+            checkpoints.push(update);
+        }
+        else {
+            ordinaryUpdates.push(update);
+        }
+    }
+    return { checkpoints, ordinaryUpdates };
+}
+/** Applies checkpoints with the snapshot API before batching ordinary deltas. */
+export function importDecryptedDocumentSyncUpdates(document, updates) {
+    const { checkpoints, ordinaryUpdates } = splitDocumentSyncUpdates(updates);
+    for (const checkpoint of checkpoints) {
+        importSnapshot(document, checkpoint.updateData);
+    }
+    if (ordinaryUpdates.length > 0) {
+        importUpdates(document, ordinaryUpdates.map((update) => update.updateData));
+    }
+}
+async function validateDecryptedUpdateBatch(input) {
+    const document = await createValidationDocument(input.currentSnapshot);
+    try {
+        const { checkpoints, ordinaryUpdates } = splitDocumentSyncUpdates(input.updates);
+        for (const checkpoint of checkpoints) {
+            importSnapshot(document, checkpoint.updateData);
+        }
+        if (ordinaryUpdates.length > 0) {
+            importUpdates(document, ordinaryUpdates.map((update) => update.updateData));
+        }
+        if (input.responseById) {
+            // Validate against the completed scratch history, not only the live
+            // pre-page frontier. If two updates in this page reuse one peer/counter
+            // with different operations, Loro accepts one and treats the other as a
+            // no-op; only the accepted history can match both when they are equal.
+            assertImportedUpdatesMatchValidatedHistory({
+                document,
+                responseById: input.responseById,
+                updates: input.updates,
+            });
+        }
+    }
+    finally {
+        document.free();
+    }
+}
+function exactIsolationRetryExceedsBudget(input) {
+    if (input.candidates.length > MAX_EXACT_ISOLATION_CANDIDATES)
+        return true;
+    let retryBytes = 0;
+    for (const candidateIndex of input.candidates.keys()) {
+        if (input.currentSnapshot.byteLength >
+            MAX_EXACT_ISOLATION_RETRY_BYTES - retryBytes) {
+            return true;
+        }
+        retryBytes += input.currentSnapshot.byteLength;
+        for (const [updateIndex, update] of input.candidates.entries()) {
+            if (updateIndex === candidateIndex)
+                continue;
+            if (update.updateData.byteLength >
+                MAX_EXACT_ISOLATION_RETRY_BYTES - retryBytes) {
+                return true;
+            }
+            retryBytes += update.updateData.byteLength;
+        }
+    }
+    return false;
+}
+/** @internal Exported only to exercise the bounded exact-attribution policy. */
+export async function findUniqueRepairingCandidate(candidates, repairsBatch) {
+    let repairingCandidate = null;
+    let repairingCandidateCount = 0;
+    for (const [candidateIndex, candidate] of candidates.entries()) {
+        if (await repairsBatch(candidate, candidateIndex)) {
+            repairingCandidate = candidate;
+            repairingCandidateCount += 1;
+        }
+    }
+    return repairingCandidateCount === 1 ? repairingCandidate : null;
+}
+/**
+ * Proves that a decrypted response can be imported before the live document or
+ * any durable sync frontier is mutated. On failure, retries the page without
+ * each candidate so valid sibling dependencies remain in the same batch while
+ * the update whose removal repairs the batch is attributed exactly.
+ */
+export async function validateDocumentSyncUpdateImports(input) {
+    if (input.decryptedUpdates.length === 0)
+        return;
+    const duplicateUpdateId = firstDuplicateUpdateId(input.decryptedUpdates) ??
+        firstDuplicateUpdateId(input.responseUpdates ?? []);
+    if (duplicateUpdateId !== null) {
+        throw isolateDocumentSyncBatchError({
+            cause: new Error(`Document sync response update id is duplicated: ${duplicateUpdateId}`),
+            stage: "encrypted_record",
+            updateIds: (input.responseUpdates ?? input.decryptedUpdates).map((update) => update.id),
+        });
+    }
+    const currentSnapshot = exportFullHistorySnapshot(input.currentDocument);
+    const responseById = responseUpdatesById(input.responseUpdates);
+    let batchError;
+    try {
+        await validateDecryptedUpdateBatch({
+            currentSnapshot,
+            responseById,
+            updates: input.decryptedUpdates,
+        });
+        return;
+    }
+    catch (error) {
+        if (isDocumentSyncUpdateIsolationError(error))
+            throw error;
+        batchError = error;
+    }
+    // A delta can be valid but depend on a parent omitted from this response
+    // page. Removing that delta would make an empty retry succeed and falsely
+    // identify its authenticated writer as poison, so dependency gaps remain
+    // anonymous at batch scope.
+    if (batchError instanceof LoroImportUnresolvedDependenciesError) {
+        throw isolateDocumentSyncBatchError({
+            cause: batchError,
+            stage: "loro_import",
+            updateIds: input.decryptedUpdates.map((update) => update.id),
+        });
+    }
+    if (exactIsolationRetryExceedsBudget({
+        candidates: input.decryptedUpdates,
+        currentSnapshot,
+    })) {
+        throw isolateDocumentSyncBatchError({
+            cause: batchError,
+            stage: "loro_import",
+            updateIds: input.decryptedUpdates.map((update) => update.id),
+        });
+    }
+    // Rebuild from the same immutable snapshot for every candidate: a failed
+    // import may partially mutate its scratch document. Checkpoints participate
+    // alongside ordinary updates so an incompatibility between the two kinds
+    // cannot falsely blame the ordinary writer. Keeping every other update in
+    // one batch also preserves out-of-order sibling dependencies.
+    const isolatedUpdate = await findUniqueRepairingCandidate(input.decryptedUpdates, async (_update, candidateIndex) => {
+        const withoutCandidate = input.decryptedUpdates.filter((_, updateIndex) => updateIndex !== candidateIndex);
+        try {
+            await validateDecryptedUpdateBatch({
+                currentSnapshot,
+                updates: withoutCandidate,
+            });
+            return true;
+        }
+        catch {
+            // This candidate is either valid and required by a sibling, or another
+            // poison update remains. Continue without attributing it.
+            return false;
+        }
+    });
+    if (isolatedUpdate) {
+        throw isolateDocumentSyncUpdateError({
+            cause: batchError,
+            responseUpdate: responseById.get(isolatedUpdate.id),
+            stage: "loro_import",
+            updateId: isolatedUpdate.id,
+        });
+    }
+    // Multiple bad updates or a batch-level incompatibility may have zero or
+    // multiple removals that repair the page. Fail closed without falsely naming
+    // a valid writer; no live or durable state has changed.
+    throw isolateDocumentSyncBatchError({
+        cause: batchError,
+        stage: "loro_import",
+        updateIds: input.decryptedUpdates.map((update) => update.id),
+    });
+}
+//# sourceMappingURL=documentSyncUpdateIsolation.js.map

package/data/documents/shared/sync/documentSyncUpdateIsolation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"documentSyncUpdateIsolation.js","sourceRoot":"","sources":["documentSyncUpdateIsolation.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  createDocument,\n  exportFullHistorySnapshot,\n  importSnapshot,\n  importUpdates,\n  LoroImportUnresolvedDependenciesError,\n  updateMatchesDocumentHistory,\n} from \"@tearleads/loro\";\nimport type { DocumentSyncResponse } from \"@tearleads/validators/response\";\nimport type {\n  DecryptedDocumentSyncUpdate,\n  SyncRemoteDocumentResult,\n} from \"../types\";\n\ntype DocumentSyncUpdateIsolationStage =\n  | \"content_key\"\n  | \"decrypt\"\n  | \"encrypted_record\"\n  | \"loro_import\"\n  | \"loro_metadata\"\n  | \"plaintext_integrity\"\n  | \"write_header\";\n\ntype SyncResponseUpdate = DocumentSyncResponse[\"updates\"][number];\ntype SyncDocument = Awaited<ReturnType<typeof createDocument>>;\n\nconst MAX_EXACT_ISOLATION_CANDIDATES = 8;\nconst MAX_EXACT_ISOLATION_RETRY_BYTES = 8 * 1024 * 1024;\n\nexport type IncomingDocumentSyncUpdateValidator = (\n  result: Pick<SyncRemoteDocumentResult, \"decryptedUpdates\" | \"response\">,\n) => void | Promise<void>;\n\nfunction errorMessage(error: unknown): string {\n  return error instanceof Error ? error.message : String(error);\n}\n\nfunction optionalHeaderField(\n  update: SyncResponseUpdate | undefined,\n  field: string,\n): unknown {\n  const header = update?.writeHeader;\n  return header && typeof header === \"object\"\n    ? Reflect.get(header, field)\n    : undefined;\n}\n\nfunction optionalHeaderString(\n  update: SyncResponseUpdate | undefined,\n  field: string,\n): string | null {\n  const value = optionalHeaderField(update, field);\n  return typeof value === \"string\" ? value : null;\n}\n\nfunction optionalHeaderEpoch(\n  update: SyncResponseUpdate | undefined,\n): number | null {\n  const value = optionalHeaderField(update, \"contentKeyEpoch\");\n  return typeof value === \"number\" && Number.isSafeInteger(value)\n    ? value\n    : null;\n}\n\nexport class DocumentSyncUpdateIsolationError extends Error {\n  readonly attribution: \"batch\" | \"update\";\n  readonly authorFingerprint: string | null;\n  readonly batchUpdateIds: readonly string[];\n  readonly checkpointKind: \"rotate_baseline\" | null;\n  readonly ciphertextHash: string | null;\n  readonly contentKeyEpoch: number | null;\n  readonly documentId: string | null;\n  readonly metadataHash: string | null;\n  readonly stage: DocumentSyncUpdateIsolationStage;\n  readonly updateId: string | null;\n  readonly writerUserId: string | null;\n\n  constructor(input: {\n    batchUpdateIds?: readonly string[] | undefined;\n    cause: unknown;\n    responseUpdate?: SyncResponseUpdate | undefined;\n    stage: DocumentSyncUpdateIsolationStage;\n    updateId: string | null;\n  }) {\n    const causeMessage = errorMessage(input.cause);\n    const writerUserId = optionalHeaderString(\n      input.responseUpdate,\n      \"writerUserId\",\n    );\n    const author =\n      writerUserId ?? input.responseUpdate?.authorFingerprint ?? \"unknown\";\n    const fingerprint = input.responseUpdate?.authorFingerprint ?? \"unknown\";\n    const epoch = optionalHeaderEpoch(input.responseUpdate) ?? \"unknown\";\n    const batchUpdateIds =\n      input.updateId === null ? (input.batchUpdateIds ?? []) : [];\n    const subject =\n      input.updateId === null\n        ? `response batch containing ${batchUpdateIds.length} updates; exact update and writer unknown`\n        : `update ${input.updateId} from writer ${author} (fingerprint ${fingerprint}, epoch ${epoch})`;\n    super(\n      `Document sync quarantined ${subject} during ${input.stage}: ${causeMessage}`,\n      { cause: input.cause },\n    );\n    this.name = \"DocumentSyncUpdateIsolationError\";\n    this.attribution = input.updateId === null ? \"batch\" : \"update\";\n    this.authorFingerprint = input.responseUpdate?.authorFingerprint ?? null;\n    this.batchUpdateIds = [...batchUpdateIds];\n    this.checkpointKind =\n      input.responseUpdate?.checkpointKind === \"rotate_baseline\"\n        ? \"rotate_baseline\"\n        : null;\n    this.ciphertextHash = optionalHeaderString(\n      input.responseUpdate,\n      \"ciphertextHash\",\n    );\n    this.contentKeyEpoch = optionalHeaderEpoch(input.responseUpdate);\n    this.documentId = input.responseUpdate?.documentId ?? null;\n    this.metadataHash = optionalHeaderString(\n      input.responseUpdate,\n      \"metadataHash\",\n    );\n    this.stage = input.stage;\n    this.updateId = input.updateId;\n    this.writerUserId = writerUserId;\n  }\n}\n\nexport function isolateDocumentSyncBatchError(input: {\n  cause: unknown;\n  stage: DocumentSyncUpdateIsolationStage;\n  updateIds: readonly string[];\n}): DocumentSyncUpdateIsolationError {\n  return new DocumentSyncUpdateIsolationError({\n    batchUpdateIds: input.updateIds,\n    cause: input.cause,\n    stage: input.stage,\n    updateId: null,\n  });\n}\n\nexport function isolateDocumentSyncUpdateError(input: {\n  cause: unknown;\n  responseUpdate?: SyncResponseUpdate | undefined;\n  stage: DocumentSyncUpdateIsolationStage;\n  updateId: string;\n}): DocumentSyncUpdateIsolationError {\n  return input.cause instanceof DocumentSyncUpdateIsolationError\n    ? input.cause\n    : new DocumentSyncUpdateIsolationError(input);\n}\n\nexport function isDocumentSyncUpdateIsolationError(\n  error: unknown,\n): error is DocumentSyncUpdateIsolationError {\n  return error instanceof DocumentSyncUpdateIsolationError;\n}\n\nfunction responseUpdatesById(\n  updates: readonly SyncResponseUpdate[] | undefined,\n): ReadonlyMap<string, SyncResponseUpdate> {\n  return new Map((updates ?? []).map((update) => [update.id, update]));\n}\n\nfunction firstDuplicateUpdateId(\n  updates: readonly { readonly id: string }[],\n): string | null {\n  const seen = new Set<string>();\n  for (const update of updates) {\n    if (seen.has(update.id)) return update.id;\n    seen.add(update.id);\n  }\n  return null;\n}\n\nfunction assertImportedUpdatesMatchValidatedHistory(input: {\n  document: SyncDocument;\n  responseById: ReadonlyMap<string, SyncResponseUpdate>;\n  updates: readonly DecryptedDocumentSyncUpdate[];\n}): void {\n  const collisions = input.updates.filter(\n    (update) =>\n      !updateMatchesDocumentHistory(input.document, update.updateData),\n  );\n  if (collisions.length === 0) return;\n  const cause = new Error(\n    \"incoming Loro update reuses an already-covered frontier with different operations\",\n  );\n  const [collision] = collisions;\n  if (input.updates.length === 1 && collision) {\n    throw isolateDocumentSyncUpdateError({\n      cause,\n      responseUpdate: input.responseById.get(collision.id),\n      stage: \"loro_import\",\n      updateId: collision.id,\n    });\n  }\n  throw isolateDocumentSyncBatchError({\n    cause,\n    stage: \"loro_import\",\n    updateIds: input.updates.map((update) => update.id),\n  });\n}\n\nasync function createValidationDocument(snapshot: Uint8Array) {\n  const document = await createDocument(crypto.randomUUID());\n  try {\n    importSnapshot(document, snapshot);\n    return document;\n  } catch (error) {\n    document.free();\n    throw error;\n  }\n}\n\nfunction splitDocumentSyncUpdates(\n  updates: readonly DecryptedDocumentSyncUpdate[],\n): {\n  checkpoints: DecryptedDocumentSyncUpdate[];\n  ordinaryUpdates: DecryptedDocumentSyncUpdate[];\n} {\n  const checkpoints: DecryptedDocumentSyncUpdate[] = [];\n  const ordinaryUpdates: DecryptedDocumentSyncUpdate[] = [];\n  for (const update of updates) {\n    if (\n      update.checkpointKind === \"rotate_baseline\" &&\n      update.checkpointPayloadKind === \"full_history_snapshot\"\n    ) {\n      checkpoints.push(update);\n    } else {\n      ordinaryUpdates.push(update);\n    }\n  }\n  return { checkpoints, ordinaryUpdates };\n}\n\n/** Applies checkpoints with the snapshot API before batching ordinary deltas. */\nexport function importDecryptedDocumentSyncUpdates(\n  document: SyncDocument,\n  updates: readonly DecryptedDocumentSyncUpdate[],\n): void {\n  const { checkpoints, ordinaryUpdates } = splitDocumentSyncUpdates(updates);\n  for (const checkpoint of checkpoints) {\n    importSnapshot(document, checkpoint.updateData);\n  }\n  if (ordinaryUpdates.length > 0) {\n    importUpdates(\n      document,\n      ordinaryUpdates.map((update) => update.updateData),\n    );\n  }\n}\n\nasync function validateDecryptedUpdateBatch(input: {\n  currentSnapshot: Uint8Array;\n  responseById?: ReadonlyMap<string, SyncResponseUpdate> | undefined;\n  updates: readonly DecryptedDocumentSyncUpdate[];\n}): Promise<void> {\n  const document = await createValidationDocument(input.currentSnapshot);\n  try {\n    const { checkpoints, ordinaryUpdates } = splitDocumentSyncUpdates(\n      input.updates,\n    );\n    for (const checkpoint of checkpoints) {\n      importSnapshot(document, checkpoint.updateData);\n    }\n    if (ordinaryUpdates.length > 0) {\n      importUpdates(\n        document,\n        ordinaryUpdates.map((update) => update.updateData),\n      );\n    }\n    if (input.responseById) {\n      // Validate against the completed scratch history, not only the live\n      // pre-page frontier. If two updates in this page reuse one peer/counter\n      // with different operations, Loro accepts one and treats the other as a\n      // no-op; only the accepted history can match both when they are equal.\n      assertImportedUpdatesMatchValidatedHistory({\n        document,\n        responseById: input.responseById,\n        updates: input.updates,\n      });\n    }\n  } finally {\n    document.free();\n  }\n}\n\nfunction exactIsolationRetryExceedsBudget(input: {\n  candidates: readonly DecryptedDocumentSyncUpdate[];\n  currentSnapshot: Uint8Array;\n}): boolean {\n  if (input.candidates.length > MAX_EXACT_ISOLATION_CANDIDATES) return true;\n\n  let retryBytes = 0;\n  for (const candidateIndex of input.candidates.keys()) {\n    if (\n      input.currentSnapshot.byteLength >\n      MAX_EXACT_ISOLATION_RETRY_BYTES - retryBytes\n    ) {\n      return true;\n    }\n    retryBytes += input.currentSnapshot.byteLength;\n    for (const [updateIndex, update] of input.candidates.entries()) {\n      if (updateIndex === candidateIndex) continue;\n      if (\n        update.updateData.byteLength >\n        MAX_EXACT_ISOLATION_RETRY_BYTES - retryBytes\n      ) {\n        return true;\n      }\n      retryBytes += update.updateData.byteLength;\n    }\n  }\n  return false;\n}\n\n/** @internal Exported only to exercise the bounded exact-attribution policy. */\nexport async function findUniqueRepairingCandidate<T>(\n  candidates: readonly T[],\n  repairsBatch: (candidate: T, candidateIndex: number) => Promise<boolean>,\n): Promise<T | null> {\n  let repairingCandidate: T | null = null;\n  let repairingCandidateCount = 0;\n  for (const [candidateIndex, candidate] of candidates.entries()) {\n    if (await repairsBatch(candidate, candidateIndex)) {\n      repairingCandidate = candidate;\n      repairingCandidateCount += 1;\n    }\n  }\n  return repairingCandidateCount === 1 ? repairingCandidate : null;\n}\n\n/**\n * Proves that a decrypted response can be imported before the live document or\n * any durable sync frontier is mutated. On failure, retries the page without\n * each candidate so valid sibling dependencies remain in the same batch while\n * the update whose removal repairs the batch is attributed exactly.\n */\nexport async function validateDocumentSyncUpdateImports(input: {\n  currentDocument: Awaited<ReturnType<typeof createDocument>>;\n  decryptedUpdates: readonly DecryptedDocumentSyncUpdate[];\n  responseUpdates?: readonly SyncResponseUpdate[] | undefined;\n}): Promise<void> {\n  if (input.decryptedUpdates.length === 0) return;\n\n  const duplicateUpdateId =\n    firstDuplicateUpdateId(input.decryptedUpdates) ??\n    firstDuplicateUpdateId(input.responseUpdates ?? []);\n  if (duplicateUpdateId !== null) {\n    throw isolateDocumentSyncBatchError({\n      cause: new Error(\n        `Document sync response update id is duplicated: ${duplicateUpdateId}`,\n      ),\n      stage: \"encrypted_record\",\n      updateIds: (input.responseUpdates ?? input.decryptedUpdates).map(\n        (update) => update.id,\n      ),\n    });\n  }\n\n  const currentSnapshot = exportFullHistorySnapshot(input.currentDocument);\n  const responseById = responseUpdatesById(input.responseUpdates);\n  let batchError: unknown;\n  try {\n    await validateDecryptedUpdateBatch({\n      currentSnapshot,\n      responseById,\n      updates: input.decryptedUpdates,\n    });\n    return;\n  } catch (error) {\n    if (isDocumentSyncUpdateIsolationError(error)) throw error;\n    batchError = error;\n  }\n\n  // A delta can be valid but depend on a parent omitted from this response\n  // page. Removing that delta would make an empty retry succeed and falsely\n  // identify its authenticated writer as poison, so dependency gaps remain\n  // anonymous at batch scope.\n  if (batchError instanceof LoroImportUnresolvedDependenciesError) {\n    throw isolateDocumentSyncBatchError({\n      cause: batchError,\n      stage: \"loro_import\",\n      updateIds: input.decryptedUpdates.map((update) => update.id),\n    });\n  }\n\n  if (\n    exactIsolationRetryExceedsBudget({\n      candidates: input.decryptedUpdates,\n      currentSnapshot,\n    })\n  ) {\n    throw isolateDocumentSyncBatchError({\n      cause: batchError,\n      stage: \"loro_import\",\n      updateIds: input.decryptedUpdates.map((update) => update.id),\n    });\n  }\n\n  // Rebuild from the same immutable snapshot for every candidate: a failed\n  // import may partially mutate its scratch document. Checkpoints participate\n  // alongside ordinary updates so an incompatibility between the two kinds\n  // cannot falsely blame the ordinary writer. Keeping every other update in\n  // one batch also preserves out-of-order sibling dependencies.\n  const isolatedUpdate = await findUniqueRepairingCandidate(\n    input.decryptedUpdates,\n    async (_update, candidateIndex) => {\n      const withoutCandidate = input.decryptedUpdates.filter(\n        (_, updateIndex) => updateIndex !== candidateIndex,\n      );\n      try {\n        await validateDecryptedUpdateBatch({\n          currentSnapshot,\n          updates: withoutCandidate,\n        });\n        return true;\n      } catch {\n        // This candidate is either valid and required by a sibling, or another\n        // poison update remains. Continue without attributing it.\n        return false;\n      }\n    },\n  );\n  if (isolatedUpdate) {\n    throw isolateDocumentSyncUpdateError({\n      cause: batchError,\n      responseUpdate: responseById.get(isolatedUpdate.id),\n      stage: \"loro_import\",\n      updateId: isolatedUpdate.id,\n    });\n  }\n\n  // Multiple bad updates or a batch-level incompatibility may have zero or\n  // multiple removals that repair the page. Fail closed without falsely naming\n  // a valid writer; no live or durable state has changed.\n  throw isolateDocumentSyncBatchError({\n    cause: batchError,\n    stage: \"loro_import\",\n    updateIds: input.decryptedUpdates.map((update) => update.id),\n  });\n}\n"]}

package/data/documents/shared/sync/mutationAcknowledgement.js

@@ -0,0 +1,10 @@
+import { advanceLocallyAcknowledgedAccessManifestHeadsAtomically, locallyAuthoredAccessManifestHead, } from "../../../persistence/keyingCheckpoints/locallyAcknowledgedCheckpointPersistence.js";
+/** Advances a document head only after its response was matched to this plan. */
+export async function acknowledgeDocumentMutation(input) {
+    await advanceLocallyAcknowledgedAccessManifestHeadsAtomically({
+        execSql: input.execSql,
+        heads: [locallyAuthoredAccessManifestHead(input.plan)],
+        stillCurrent: input.stillCurrent,
+    });
+}
+//# sourceMappingURL=mutationAcknowledgement.js.map

package/data/documents/shared/sync/mutationAcknowledgement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutationAcknowledgement.js","sourceRoot":"","sources":["mutationAcknowledgement.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uDAAuD,EACvD,iCAAiC,GAClC,MAAM,iFAAiF,CAAC;AAGzF,iFAAiF;AACjF,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAAC,KAIjD;IACC,MAAM,uDAAuD,CAAC;QAC5D,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,KAAK,EAAE,CAAC,iCAAiC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACtD,YAAY,EAAE,KAAK,CAAC,YAAY;KACjC,CAAC,CAAC;AACL,CAAC","sourcesContent":["import {\n  advanceLocallyAcknowledgedAccessManifestHeadsAtomically,\n  locallyAuthoredAccessManifestHead,\n} from \"../../../persistence/keyingCheckpoints/locallyAcknowledgedCheckpointPersistence\";\nimport type { ExecSql } from \"../../../sqlite/sqlSchema\";\n\n/** Advances a document head only after its response was matched to this plan. */\nexport async function acknowledgeDocumentMutation(input: {\n  readonly execSql: ExecSql;\n  readonly plan: Parameters<typeof locallyAuthoredAccessManifestHead>[0];\n  readonly stillCurrent?: (() => boolean) | undefined;\n}): Promise<void> {\n  await advanceLocallyAcknowledgedAccessManifestHeadsAtomically({\n    execSql: input.execSql,\n    heads: [locallyAuthoredAccessManifestHead(input.plan)],\n    stillCurrent: input.stillCurrent,\n  });\n}\n"]}

package/data/documents/shared/sync/pullContinuation.js

@@ -0,0 +1,53 @@
+import { isWalLsnString, MAX_DOCUMENT_SYNC_PULL_CURSOR_LENGTH, } from "../../../../internal/validators/util/index.js";
+export function documentSyncPullContinuationsEqual(left, right) {
+    if (!left || !right)
+        return left == null && right == null;
+    return (left.commitLsn === right.commitLsn &&
+        left.commitLsnMode === right.commitLsnMode &&
+        left.cursor === right.cursor);
+}
+/**
+ * Non-null durable value used after the server rejects a cursor. Readers treat
+ * it like any other undecodable continuation and force page-one recovery, but
+ * ordinary saves preserve it until a successful sync settlement explicitly
+ * replaces or clears the continuation.
+ */
+export const DOCUMENT_SYNC_PULL_RECOVERY_REQUIRED = '[0,"recovery-required"]';
+function isValidCheckpoint(mode, commitLsn) {
+    return ((mode === "tracked" && commitLsn !== "0/0" && isWalLsnString(commitLsn)) ||
+        (mode === "untracked" && commitLsn === "0/0"));
+}
+/** Decode untrusted local state; malformed progress restarts from page one. */
+export function deserializeDocumentSyncPullContinuation(value) {
+    if (value === null)
+        return null;
+    try {
+        const parsed = JSON.parse(value);
+        if (!Array.isArray(parsed) || parsed.length !== 4)
+            return null;
+        const [version, commitLsnMode, commitLsn, cursor] = parsed;
+        if (version !== 1 ||
+            !isValidCheckpoint(commitLsnMode, commitLsn) ||
+            typeof commitLsn !== "string" ||
+            typeof cursor !== "string" ||
+            cursor.length === 0 ||
+            cursor.length > MAX_DOCUMENT_SYNC_PULL_CURSOR_LENGTH) {
+            return null;
+        }
+        return { commitLsn, commitLsnMode, cursor };
+    }
+    catch {
+        return null;
+    }
+}
+export function serializeDocumentSyncPullContinuation(continuation) {
+    if (continuation === null)
+        return null;
+    return JSON.stringify([
+        1,
+        continuation.commitLsnMode,
+        continuation.commitLsn,
+        continuation.cursor,
+    ]);
+}
+//# sourceMappingURL=pullContinuation.js.map

package/data/documents/shared/sync/syncPagination.d.ts

@@ -0,0 +1,20 @@
+import type { DocumentSyncResponse } from "../../../../internal/validators/response/index.js";
+import type { DocumentSyncApi, DocumentSyncPlan, DocumentSyncSubmitFailure } from "../types.js";
+import type { DocumentSyncCommitLsnMode, DocumentSyncPullContinuation } from "./pullContinuation.js";
+export type { DocumentSyncCommitLsnMode, DocumentSyncPullContinuation, } from "./pullContinuation.js";
+export { documentSyncPullContinuationsEqual } from "./pullContinuation.js";
+export declare class InvalidDocumentSyncPullContinuationError extends Error {
+    constructor(message: string);
+}
+type DocumentSyncSubmission = {
+    readonly ok: true;
+    readonly pullComplete: boolean;
+    readonly response: DocumentSyncResponse;
+} | DocumentSyncSubmitFailure | null;
+export declare function readPullContinuation(response: DocumentSyncResponse): DocumentSyncPullContinuation | null;
+export declare function resolvePullContinuationMinLsn(continuation: DocumentSyncPullContinuation | undefined, fallback: string | undefined): string | undefined;
+export declare function submitDocumentSync(input: {
+    apiClient: DocumentSyncApi;
+    expectedCommitLsnMode?: DocumentSyncCommitLsnMode | undefined;
+    plan: DocumentSyncPlan;
+}): Promise<DocumentSyncSubmission>;

package/data/documents/shared/sync/syncPagination.js

@@ -0,0 +1,109 @@
+import { parseWalLsn } from "../../../../internal/validators/util/index.js";
+export { documentSyncPullContinuationsEqual } from "./pullContinuation.js";
+export class InvalidDocumentSyncPullContinuationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InvalidDocumentSyncPullContinuationError";
+    }
+}
+export function readPullContinuation(response) {
+    const cursor = requirePullPage(response).nextCursor;
+    if (cursor === null)
+        return null;
+    if (response.commitLsn === null) {
+        throw new Error("Document sync pull continuation is missing its checkpoint");
+    }
+    return {
+        commitLsn: response.commitLsn,
+        commitLsnMode: response.commitLsnMode,
+        cursor,
+    };
+}
+export function resolvePullContinuationMinLsn(continuation, fallback) {
+    if (!continuation)
+        return fallback;
+    if (continuation.commitLsnMode === "untracked" || fallback === undefined) {
+        return continuation.commitLsn;
+    }
+    return parseWalLsn(continuation.commitLsn) >= parseWalLsn(fallback)
+        ? continuation.commitLsn
+        : fallback;
+}
+function assertPageCheckpoint(input) {
+    if (input.response.commitLsnMode === "untracked") {
+        if (input.response.commitLsn !== "0/0") {
+            throw new InvalidDocumentSyncPullContinuationError("Document sync continuation untracked LSN is invalid");
+        }
+        return;
+    }
+    if (input.response.commitLsn === null) {
+        if (input.minLsn === undefined && input.nextCursor === null)
+            return;
+        throw new InvalidDocumentSyncPullContinuationError("Document sync pull continuation is missing its checkpoint");
+    }
+    let responseLsn;
+    try {
+        responseLsn = parseWalLsn(input.response.commitLsn);
+    }
+    catch {
+        throw new InvalidDocumentSyncPullContinuationError("Document sync continuation commit LSN is invalid");
+    }
+    if (input.minLsn === undefined)
+        return;
+    let minimumLsn;
+    try {
+        minimumLsn = parseWalLsn(input.minLsn);
+    }
+    catch {
+        throw new InvalidDocumentSyncPullContinuationError("Document sync minimum commit LSN is invalid");
+    }
+    if (responseLsn < minimumLsn) {
+        throw new InvalidDocumentSyncPullContinuationError("Document sync continuation commit LSN regressed");
+    }
+}
+function requirePullPage(response) {
+    if (response.pullPage === undefined) {
+        throw new Error("Document sync response is missing pull page metadata");
+    }
+    return response.pullPage;
+}
+async function submitDocumentSyncPage(input) {
+    const page = await input.submit();
+    if (!page?.ok)
+        return page;
+    if (input.expectedCommitLsnMode !== undefined &&
+        page.response.commitLsnMode !== input.expectedCommitLsnMode) {
+        throw new InvalidDocumentSyncPullContinuationError("Document sync continuation commit LSN mode changed");
+    }
+    const nextCursor = requirePullPage(page.response).nextCursor;
+    assertPageCheckpoint({
+        minLsn: input.plan.request.minLsn,
+        nextCursor,
+        response: page.response,
+    });
+    if (nextCursor !== null && page.response.commitLsn === null) {
+        throw new InvalidDocumentSyncPullContinuationError("Document sync pull continuation is missing its checkpoint");
+    }
+    if (nextCursor !== null && nextCursor === input.plan.request.pullCursor) {
+        throw new InvalidDocumentSyncPullContinuationError("Document sync continuation cursor did not advance");
+    }
+    return {
+        ok: true,
+        pullComplete: nextCursor === null,
+        response: page.response,
+    };
+}
+export async function submitDocumentSync(input) {
+    return submitDocumentSyncPage({
+        expectedCommitLsnMode: input.expectedCommitLsnMode,
+        plan: input.plan,
+        submit: async () => {
+            const result = await input.apiClient.syncDocumentResult(input.plan.documentId, input.plan.request, {
+                expectedPaymentRequiredOrganizationId: input.plan.organizationId,
+                reportErrors: false,
+            });
+            return result.ok ? { ok: true, response: result.data } : result;
+        },
+    });
+}
+//# sourceMappingURL=syncPagination.js.map

package/data/documents/shared/sync/syncPagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncPagination.js","sourceRoot":"","sources":["syncPagination.ts"],"names":[],"mappings":"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","sourcesContent":["import type { DocumentSyncResponse } from \"@tearleads/validators/response\";\nimport { parseWalLsn } from \"@tearleads/validators/util\";\nimport type {\n  DocumentSyncApi,\n  DocumentSyncPlan,\n  DocumentSyncSubmitFailure,\n} from \"../types\";\nimport type {\n  DocumentSyncCommitLsnMode,\n  DocumentSyncPullContinuation,\n} from \"./pullContinuation\";\n\nexport type {\n  DocumentSyncCommitLsnMode,\n  DocumentSyncPullContinuation,\n} from \"./pullContinuation\";\nexport { documentSyncPullContinuationsEqual } from \"./pullContinuation\";\n\nexport class InvalidDocumentSyncPullContinuationError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"InvalidDocumentSyncPullContinuationError\";\n  }\n}\n\ntype DocumentSyncPageSubmission =\n  | {\n      readonly ok: true;\n      readonly response: DocumentSyncResponse;\n    }\n  | DocumentSyncSubmitFailure\n  | null;\n\ntype DocumentSyncSubmission =\n  | {\n      readonly ok: true;\n      readonly pullComplete: boolean;\n      readonly response: DocumentSyncResponse;\n    }\n  | DocumentSyncSubmitFailure\n  | null;\n\nexport function readPullContinuation(\n  response: DocumentSyncResponse,\n): DocumentSyncPullContinuation | null {\n  const cursor = requirePullPage(response).nextCursor;\n  if (cursor === null) return null;\n  if (response.commitLsn === null) {\n    throw new Error(\n      \"Document sync pull continuation is missing its checkpoint\",\n    );\n  }\n  return {\n    commitLsn: response.commitLsn,\n    commitLsnMode: response.commitLsnMode,\n    cursor,\n  };\n}\n\nexport function resolvePullContinuationMinLsn(\n  continuation: DocumentSyncPullContinuation | undefined,\n  fallback: string | undefined,\n): string | undefined {\n  if (!continuation) return fallback;\n  if (continuation.commitLsnMode === \"untracked\" || fallback === undefined) {\n    return continuation.commitLsn;\n  }\n  return parseWalLsn(continuation.commitLsn) >= parseWalLsn(fallback)\n    ? continuation.commitLsn\n    : fallback;\n}\n\nfunction assertPageCheckpoint(input: {\n  readonly minLsn: string | undefined;\n  readonly nextCursor: string | null;\n  readonly response: DocumentSyncResponse;\n}): void {\n  if (input.response.commitLsnMode === \"untracked\") {\n    if (input.response.commitLsn !== \"0/0\") {\n      throw new InvalidDocumentSyncPullContinuationError(\n        \"Document sync continuation untracked LSN is invalid\",\n      );\n    }\n    return;\n  }\n  if (input.response.commitLsn === null) {\n    if (input.minLsn === undefined && input.nextCursor === null) return;\n    throw new InvalidDocumentSyncPullContinuationError(\n      \"Document sync pull continuation is missing its checkpoint\",\n    );\n  }\n  let responseLsn: bigint;\n  try {\n    responseLsn = parseWalLsn(input.response.commitLsn);\n  } catch {\n    throw new InvalidDocumentSyncPullContinuationError(\n      \"Document sync continuation commit LSN is invalid\",\n    );\n  }\n  if (input.minLsn === undefined) return;\n  let minimumLsn: bigint;\n  try {\n    minimumLsn = parseWalLsn(input.minLsn);\n  } catch {\n    throw new InvalidDocumentSyncPullContinuationError(\n      \"Document sync minimum commit LSN is invalid\",\n    );\n  }\n  if (responseLsn < minimumLsn) {\n    throw new InvalidDocumentSyncPullContinuationError(\n      \"Document sync continuation commit LSN regressed\",\n    );\n  }\n}\n\nfunction requirePullPage(response: DocumentSyncResponse) {\n  if (response.pullPage === undefined) {\n    throw new Error(\"Document sync response is missing pull page metadata\");\n  }\n  return response.pullPage;\n}\n\nasync function submitDocumentSyncPage(input: {\n  readonly expectedCommitLsnMode?: DocumentSyncCommitLsnMode | undefined;\n  readonly plan: DocumentSyncPlan;\n  readonly submit: () => Promise<DocumentSyncPageSubmission>;\n}): Promise<DocumentSyncSubmission> {\n  const page = await input.submit();\n  if (!page?.ok) return page;\n  if (\n    input.expectedCommitLsnMode !== undefined &&\n    page.response.commitLsnMode !== input.expectedCommitLsnMode\n  ) {\n    throw new InvalidDocumentSyncPullContinuationError(\n      \"Document sync continuation commit LSN mode changed\",\n    );\n  }\n  const nextCursor = requirePullPage(page.response).nextCursor;\n  assertPageCheckpoint({\n    minLsn: input.plan.request.minLsn,\n    nextCursor,\n    response: page.response,\n  });\n  if (nextCursor !== null && page.response.commitLsn === null) {\n    throw new InvalidDocumentSyncPullContinuationError(\n      \"Document sync pull continuation is missing its checkpoint\",\n    );\n  }\n  if (nextCursor !== null && nextCursor === input.plan.request.pullCursor) {\n    throw new InvalidDocumentSyncPullContinuationError(\n      \"Document sync continuation cursor did not advance\",\n    );\n  }\n  return {\n    ok: true,\n    pullComplete: nextCursor === null,\n    response: page.response,\n  };\n}\n\nexport async function submitDocumentSync(input: {\n  apiClient: DocumentSyncApi;\n  expectedCommitLsnMode?: DocumentSyncCommitLsnMode | undefined;\n  plan: DocumentSyncPlan;\n}): Promise<DocumentSyncSubmission> {\n  return submitDocumentSyncPage({\n    expectedCommitLsnMode: input.expectedCommitLsnMode,\n    plan: input.plan,\n    submit: async () => {\n      const result = await input.apiClient.syncDocumentResult(\n        input.plan.documentId,\n        input.plan.request,\n        {\n          expectedPaymentRequiredOrganizationId: input.plan.organizationId,\n          reportErrors: false,\n        },\n      );\n      return result.ok ? { ok: true, response: result.data } : result;\n    },\n  });\n}\n"]}