@tearleads/client-sdk 0.0.0-stage → 0.1.11

package/stores/documents/documentStore/rotation.js

@@ -0,0 +1,307 @@
+import { encodeVersionVector, versionVectorsEqual } from "../../../internal/loro/index.js";
+import { createDocumentWriterPublicKeyResolver, readPullContinuation, resolveDocumentCreateAuthor, syncRemoteDocument, validateDocumentSyncUpdateImports, } from "../../../workflows/documents/index.js";
+import { createRuntimePrincipalPolicyWarmer } from "../../../workflows/principals/runtimePolicyWarmer.js";
+import { requestDocumentStoreSync } from "../registry.js";
+import { installRebuiltDocument } from "./historyRebuild.js";
+import { chainIdentityWrite } from "./identityWriteChain.js";
+import { listPendingUpdates } from "./persistence.js";
+import { runDocumentRemoteWork } from "./remoteWork.js";
+import { assertExactDocumentHistory, importProvenOrdinaryPendingHistory, } from "./rotationProvenance.js";
+import { invalidatePullContinuationBeforeRotation, RotationPendingUpdatesChangedError, settleOrdinaryDocumentUpdatesBeforeRotation, } from "./rotationSettlement.js";
+import { createStoredDocument } from "./storedDocument.js";
+import { captureDocumentStoreAttachmentSyncGeneration, captureDocumentStoreSyncLaneGeneration, isDocumentStoreSyncGenerationCurrent, } from "./syncGeneration.js";
+import { deleteUpstreamDeletedDocument } from "./syncRequest.js";
+import { documentIncomingUpdateIsolationFailureHandler } from "./syncShared.js";
+import { importSyncedDocumentUpdates } from "./syncUpdateImport.js";
+function ordinaryRawHistoryUpdates(updates) {
+    return updates.filter((update) => update.checkpointKind === undefined);
+}
+function assertRotationRecoveryPrerequisites(state) {
+    if (state.persistence.supportsAtomicRecoveryHistoryPruning !== true) {
+        throw new Error("Rotation raw-history recovery requires an adapter with atomic local-history pruning");
+    }
+    const author = resolveDocumentCreateAuthor(state.runtime);
+    const encapsulationKeyPair = state.runtime.crypto.encapsulationKeyPair;
+    const documentId = state.record?.documentId;
+    if (!author ||
+        !encapsulationKeyPair ||
+        !documentId ||
+        !state.runtime.auth.isAuthenticated ||
+        !state.runtime.state.online) {
+        throw new Error("Rotation requires verified full-history recovery, but remote sync prerequisites are unavailable");
+    }
+    return { author, documentId, encapsulationKeyPair };
+}
+function assertRotationRecoveryGeneration(input) {
+    if (!isDocumentStoreSyncGenerationCurrent(input.state, input.generation)) {
+        throw new Error("Document changed during rotation recovery; retry key rotation");
+    }
+}
+function rotationIncomingUpdateIsolation(input) {
+    return {
+        onIncomingUpdateIsolationFailure: documentIncomingUpdateIsolationFailureHandler(input.state, input.generation),
+        validateIncomingUpdates: async (result) => {
+            await validateDocumentSyncUpdateImports({
+                currentDocument: input.currentDocument,
+                decryptedUpdates: result.decryptedUpdates,
+                responseUpdates: result.response.updates,
+            });
+            const decryptedUpdates = ordinaryRawHistoryUpdates(result.decryptedUpdates);
+            const ordinaryUpdateIds = new Set(decryptedUpdates.map((update) => update.id));
+            await validateDocumentSyncUpdateImports({
+                currentDocument: input.currentDocument,
+                decryptedUpdates,
+                responseUpdates: result.response.updates.filter((update) => ordinaryUpdateIds.has(update.id)),
+            });
+        },
+    };
+}
+async function pullVerifiedRawHistoryForRotation(input) {
+    const { author, documentId, encapsulationKeyPair } = assertRotationRecoveryPrerequisites(input.state);
+    let pullContinuation;
+    const seenPullCursors = new Set();
+    let planningRecord = input.currentRecord;
+    let writerProjection = input.state.writerProjection?.documentId === documentId
+        ? input.state.writerProjection
+        : undefined;
+    while (true) {
+        let abandonReason = null;
+        const synced = await syncRemoteDocument({
+            apiClient: input.state.runtime.apiClient,
+            author,
+            documentId,
+            execSql: input.state.runtime.infra.execSql,
+            historyMode: "raw",
+            isRemoteSyncBlocked: input.state.runtime.util.isRemoteSyncBlocked,
+            localVersionVector: null,
+            minLsn: input.currentRecord.lastCommitLsn ?? undefined,
+            onRemoteDocumentDeleted: ({ commitPurgeProof, documentId }) => deleteUpstreamDeletedDocument(input.state, input.generation, input.currentRecord, documentId, commitPurgeProof),
+            // Recorded, never parked: this pass submits no writes, so it plans no
+            // ancestor repair and cannot abandon as `inaccessible`.
+            onSyncAbandoned: (reason) => {
+                abandonReason = reason;
+            },
+            ...rotationIncomingUpdateIsolation({
+                currentDocument: input.rebuiltDocument,
+                generation: input.generation,
+                state: input.state,
+            }),
+            onSyncTrace: (line) => input.state.runtime.util.log(`Documents: ${line}`),
+            pendingUpdates: [],
+            persistedState: planningRecord,
+            pullContinuation,
+            resolveProjectionUserKey: input.state.resolveProjectionUserKey,
+            resolveWriterPublicKey: createDocumentWriterPublicKeyResolver({
+                logPrefix: "Documents",
+                runtime: input.state.runtime,
+                writerKeyLabel: "writer key",
+            }),
+            targetSecretKey: encapsulationKeyPair.secretKey,
+            warmReferencedPrincipalPolicies: createRuntimePrincipalPolicyWarmer(input.state.runtime),
+            writerProjection,
+        });
+        if (!synced) {
+            throw new Error(`Rotation raw-history recovery could not complete (${abandonReason ?? "sync did not finish"}); key rotation was not started`);
+        }
+        assertRotationRecoveryGeneration(input);
+        importSyncedDocumentUpdates(input.rebuiltDocument, ordinaryRawHistoryUpdates(synced.decryptedUpdates));
+        if (!synced.hasIncompletePull)
+            return synced;
+        const nextContinuation = readPullContinuation(synced.response);
+        if (!nextContinuation) {
+            throw new Error("Rotation raw-history recovery ended before the retained history was complete");
+        }
+        if (seenPullCursors.has(nextContinuation.cursor)) {
+            throw new Error("Rotation raw-history recovery encountered a repeated pull cursor");
+        }
+        seenPullCursors.add(nextContinuation.cursor);
+        pullContinuation = nextContinuation;
+        planningRecord = { ...planningRecord, ...synced.persistedState };
+        writerProjection = synced.writerProjection;
+    }
+}
+async function collectVerifiedRawHistoryForRotation(input) {
+    const consumedPullContinuation = input.state.pullContinuation;
+    const writerProjectionGeneration = input.state.writerProjectionGeneration;
+    const rebuiltDocument = await createStoredDocument(input.state);
+    try {
+        const synced = await pullVerifiedRawHistoryForRotation({
+            ...input,
+            rebuiltDocument,
+        });
+        return {
+            consumedPullContinuation,
+            currentRecord: input.currentRecord,
+            rebuiltDocument,
+            synced,
+            writerProjectionGeneration,
+        };
+    }
+    catch (error) {
+        rebuiltDocument.free();
+        throw error;
+    }
+}
+class RotationDocumentChangedError extends Error {
+}
+function assertCapturedDocumentCurrent(input) {
+    assertRotationRecoveryGeneration(input);
+    if (!versionVectorsEqual(encodeVersionVector(input.currentDocument), input.capturedVersion)) {
+        throw new RotationDocumentChangedError("Document changed during rotation recovery; retry key rotation");
+    }
+}
+function currentRotationRecoveryRecord(state) {
+    if (state.record)
+        return state.record;
+    throw new Error("Document changed during rotation recovery; retry key rotation");
+}
+function installRotationRecovery(input) {
+    const { capturedVersion, collection, currentDoc, generation, state } = input;
+    const installation = state.writeChain
+        .catch(() => undefined)
+        .then(() => chainIdentityWrite(state, async () => {
+        assertCapturedDocumentCurrent({
+            capturedVersion,
+            currentDocument: currentDoc,
+            generation,
+            state,
+        });
+        assertExactDocumentHistory({
+            currentDocument: currentDoc,
+            rebuiltDocument: collection.rebuiltDocument,
+        });
+        return installRebuiltDocument({
+            consumedPullContinuation: collection.consumedPullContinuation,
+            currentRecord: collection.currentRecord,
+            generation,
+            rebuiltDoc: collection.rebuiltDocument,
+            state,
+            synced: collection.synced,
+            writerProjectionGeneration: collection.writerProjectionGeneration,
+        });
+    }));
+    // Only the checked local install occupies the write queue. Network recovery
+    // uses the remote queue, so an outage cannot hold new edits hostage.
+    state.writeChain = installation.then(() => undefined, () => undefined);
+    return installation;
+}
+async function recoverFullHistoryForRotation(state, laneGeneration) {
+    assertRotationRecoveryPrerequisites(state);
+    await invalidatePullContinuationBeforeRotation(state);
+    const currentDoc = state.doc;
+    const currentRecord = state.record;
+    if (!currentDoc || !currentRecord) {
+        throw new Error("Document must finish loading before its content key can rotate");
+    }
+    // The teardown guard for the recovery's terminal-failure handler: captured
+    // before the pull so a discard (row 21) racing this preflight invalidates
+    // it, and the stale handler cannot resurrect a deleted failure row.
+    const generation = captureDocumentStoreAttachmentSyncGeneration(state, currentDoc, laneGeneration);
+    if (!generation) {
+        throw new Error("Document changed during rotation recovery; retry key rotation");
+    }
+    const capturedVersion = encodeVersionVector(currentDoc);
+    let settlementRequiresRetry = false;
+    // A raw recovery starts from an empty scratch document, bypasses untrusted
+    // rotation-baseline redirects, drains every retained page in memory, and
+    // publishes nothing until all response updates have validated. Checkpoints
+    // are authenticated and decrypted but are not reconstruction inputs: the
+    // original ordinary update stream is the source of truth in this mode.
+    let collection = await collectVerifiedRawHistoryForRotation({
+        currentRecord,
+        generation,
+        state,
+    });
+    try {
+        assertCapturedDocumentCurrent({
+            capturedVersion,
+            currentDocument: currentDoc,
+            generation,
+            state,
+        });
+        const pendingUpdates = await listPendingUpdates(state);
+        assertCapturedDocumentCurrent({
+            capturedVersion,
+            currentDocument: currentDoc,
+            generation,
+            state,
+        });
+        const verifiedOrdinaryVersion = importProvenOrdinaryPendingHistory({
+            currentDocument: currentDoc,
+            pendingUpdates,
+            rebuiltDocument: collection.rebuiltDocument,
+        });
+        if (pendingUpdates.some((update) => update.sourceVersionVector == null)) {
+            // The first raw pass proves the exact ordinary frontier before any local
+            // row can be published. Pull raw history again after settlement so the
+            // installed snapshot also includes remote work that raced that submit.
+            await settleOrdinaryDocumentUpdatesBeforeRotation(state, verifiedOrdinaryVersion, pendingUpdates, generation);
+            assertCapturedDocumentCurrent({
+                capturedVersion,
+                currentDocument: currentDoc,
+                generation,
+                state,
+            });
+            const definitiveCollection = await collectVerifiedRawHistoryForRotation({
+                currentRecord: currentRotationRecoveryRecord(state),
+                generation,
+                state,
+            });
+            collection.rebuiltDocument.free();
+            collection = definitiveCollection;
+        }
+        const installed = await installRotationRecovery({
+            capturedVersion,
+            collection,
+            currentDoc,
+            generation,
+            state,
+        });
+        settlementRequiresRetry = installed.settlementRequiresRetry;
+        if (settlementRequiresRetry) {
+            throw new Error("Rotation raw-history recovery was superseded during its atomic install; retry key rotation");
+        }
+        return installed.fullHistorySnapshot;
+    }
+    finally {
+        if (state.doc !== collection.rebuiltDocument) {
+            collection.rebuiltDocument.free();
+        }
+        if (settlementRequiresRetry) {
+            requestDocumentStoreSync(state);
+        }
+    }
+}
+/**
+ * Wait for prior local writes and serialize with other remote work. Edits can
+ * continue during the pull; the checked install rejects a changed document so
+ * a stale recovery cannot replace them. This preflight can then be retried.
+ */
+export function assertDocumentStoreCanRotateContentKey(state) {
+    const laneGeneration = captureDocumentStoreSyncLaneGeneration(state);
+    const generation = captureDocumentStoreAttachmentSyncGeneration(state, state.doc, laneGeneration);
+    return runDocumentRemoteWork(state, async () => {
+        await state.writeChain.catch(() => undefined);
+        if (!generation ||
+            !isDocumentStoreSyncGenerationCurrent(state, generation)) {
+            throw new Error("Document changed before rotation recovery; retry key rotation");
+        }
+        for (let attempt = 0;; attempt += 1) {
+            try {
+                return await recoverFullHistoryForRotation(state, laneGeneration);
+            }
+            catch (error) {
+                // Autosaves and conflict re-keying can invalidate the proven frontier.
+                // Repeat the complete proof without blocking new local edits; repeated
+                // changes remain bounded and leave the durable queue retryable.
+                if (!(error instanceof RotationPendingUpdatesChangedError ||
+                    error instanceof RotationDocumentChangedError) ||
+                    attempt >= 2 ||
+                    !isDocumentStoreSyncGenerationCurrent(state, generation)) {
+                    throw error;
+                }
+            }
+        }
+    });
+}
+//# sourceMappingURL=rotation.js.map

package/stores/documents/documentStore/rotation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rotation.js","sourceRoot":"","sources":["rotation.ts"],"names":[],"mappings":"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","sourcesContent":["import { encodeVersionVector, versionVectorsEqual } from \"@tearleads/loro\";\nimport {\n  createDocumentWriterPublicKeyResolver,\n  type DocumentSyncPullContinuation,\n  readPullContinuation,\n  resolveDocumentCreateAuthor,\n  syncRemoteDocument,\n  validateDocumentSyncUpdateImports,\n} from \"../../../workflows/documents\";\nimport { createRuntimePrincipalPolicyWarmer } from \"../../../workflows/principals/runtimePolicyWarmer\";\nimport { requestDocumentStoreSync } from \"../registry\";\nimport { installRebuiltDocument } from \"./historyRebuild\";\nimport { chainIdentityWrite } from \"./identityWriteChain\";\nimport { listPendingUpdates } from \"./persistence\";\nimport { runDocumentRemoteWork } from \"./remoteWork\";\nimport {\n  assertExactDocumentHistory,\n  importProvenOrdinaryPendingHistory,\n} from \"./rotationProvenance\";\nimport {\n  invalidatePullContinuationBeforeRotation,\n  RotationPendingUpdatesChangedError,\n  settleOrdinaryDocumentUpdatesBeforeRotation,\n} from \"./rotationSettlement\";\nimport type { DocumentState, DocumentStoreState } from \"./state\";\nimport { createStoredDocument } from \"./storedDocument\";\nimport {\n  captureDocumentStoreAttachmentSyncGeneration,\n  captureDocumentStoreSyncLaneGeneration,\n  type DocumentStoreSyncGeneration,\n  type DocumentStoreSyncLaneGeneration,\n  isDocumentStoreSyncGenerationCurrent,\n} from \"./syncGeneration\";\nimport { deleteUpstreamDeletedDocument } from \"./syncRequest\";\nimport { documentIncomingUpdateIsolationFailureHandler } from \"./syncShared\";\nimport { importSyncedDocumentUpdates } from \"./syncUpdateImport\";\n\nfunction ordinaryRawHistoryUpdates<T extends { checkpointKind?: string }>(\n  updates: readonly T[],\n): T[] {\n  return updates.filter((update) => update.checkpointKind === undefined);\n}\n\nfunction assertRotationRecoveryPrerequisites(state: DocumentStoreState) {\n  if (state.persistence.supportsAtomicRecoveryHistoryPruning !== true) {\n    throw new Error(\n      \"Rotation raw-history recovery requires an adapter with atomic local-history pruning\",\n    );\n  }\n  const author = resolveDocumentCreateAuthor(state.runtime);\n  const encapsulationKeyPair = state.runtime.crypto.encapsulationKeyPair;\n  const documentId = state.record?.documentId;\n  if (\n    !author ||\n    !encapsulationKeyPair ||\n    !documentId ||\n    !state.runtime.auth.isAuthenticated ||\n    !state.runtime.state.online\n  ) {\n    throw new Error(\n      \"Rotation requires verified full-history recovery, but remote sync prerequisites are unavailable\",\n    );\n  }\n  return { author, documentId, encapsulationKeyPair };\n}\n\nfunction assertRotationRecoveryGeneration(input: {\n  generation: DocumentStoreSyncGeneration;\n  state: DocumentStoreState;\n}): void {\n  if (!isDocumentStoreSyncGenerationCurrent(input.state, input.generation)) {\n    throw new Error(\n      \"Document changed during rotation recovery; retry key rotation\",\n    );\n  }\n}\n\nfunction rotationIncomingUpdateIsolation(input: {\n  currentDocument: DocumentState;\n  generation: DocumentStoreSyncGeneration;\n  state: DocumentStoreState;\n}) {\n  return {\n    onIncomingUpdateIsolationFailure:\n      documentIncomingUpdateIsolationFailureHandler(\n        input.state,\n        input.generation,\n      ),\n    validateIncomingUpdates: async (\n      result: Pick<\n        NonNullable<Awaited<ReturnType<typeof syncRemoteDocument>>>,\n        \"decryptedUpdates\" | \"response\"\n      >,\n    ) => {\n      await validateDocumentSyncUpdateImports({\n        currentDocument: input.currentDocument,\n        decryptedUpdates: result.decryptedUpdates,\n        responseUpdates: result.response.updates,\n      });\n      const decryptedUpdates = ordinaryRawHistoryUpdates(\n        result.decryptedUpdates,\n      );\n      const ordinaryUpdateIds = new Set(\n        decryptedUpdates.map((update) => update.id),\n      );\n      await validateDocumentSyncUpdateImports({\n        currentDocument: input.currentDocument,\n        decryptedUpdates,\n        responseUpdates: result.response.updates.filter((update) =>\n          ordinaryUpdateIds.has(update.id),\n        ),\n      });\n    },\n  };\n}\n\nasync function pullVerifiedRawHistoryForRotation(input: {\n  currentRecord: NonNullable<DocumentStoreState[\"record\"]>;\n  generation: DocumentStoreSyncGeneration;\n  rebuiltDocument: DocumentState;\n  state: DocumentStoreState;\n}) {\n  const { author, documentId, encapsulationKeyPair } =\n    assertRotationRecoveryPrerequisites(input.state);\n  let pullContinuation: DocumentSyncPullContinuation | undefined;\n  const seenPullCursors = new Set<string>();\n  let planningRecord = input.currentRecord;\n  let writerProjection =\n    input.state.writerProjection?.documentId === documentId\n      ? input.state.writerProjection\n      : undefined;\n\n  while (true) {\n    let abandonReason: string | null = null;\n    const synced = await syncRemoteDocument({\n      apiClient: input.state.runtime.apiClient,\n      author,\n      documentId,\n      execSql: input.state.runtime.infra.execSql,\n      historyMode: \"raw\",\n      isRemoteSyncBlocked: input.state.runtime.util.isRemoteSyncBlocked,\n      localVersionVector: null,\n      minLsn: input.currentRecord.lastCommitLsn ?? undefined,\n      onRemoteDocumentDeleted: ({ commitPurgeProof, documentId }) =>\n        deleteUpstreamDeletedDocument(\n          input.state,\n          input.generation,\n          input.currentRecord,\n          documentId,\n          commitPurgeProof,\n        ),\n      // Recorded, never parked: this pass submits no writes, so it plans no\n      // ancestor repair and cannot abandon as `inaccessible`.\n      onSyncAbandoned: (reason) => {\n        abandonReason = reason;\n      },\n      ...rotationIncomingUpdateIsolation({\n        currentDocument: input.rebuiltDocument,\n        generation: input.generation,\n        state: input.state,\n      }),\n      onSyncTrace: (line) => input.state.runtime.util.log(`Documents: ${line}`),\n      pendingUpdates: [],\n      persistedState: planningRecord,\n      pullContinuation,\n      resolveProjectionUserKey: input.state.resolveProjectionUserKey,\n      resolveWriterPublicKey: createDocumentWriterPublicKeyResolver({\n        logPrefix: \"Documents\",\n        runtime: input.state.runtime,\n        writerKeyLabel: \"writer key\",\n      }),\n      targetSecretKey: encapsulationKeyPair.secretKey,\n      warmReferencedPrincipalPolicies: createRuntimePrincipalPolicyWarmer(\n        input.state.runtime,\n      ),\n      writerProjection,\n    });\n    if (!synced) {\n      throw new Error(\n        `Rotation raw-history recovery could not complete (${abandonReason ?? \"sync did not finish\"}); key rotation was not started`,\n      );\n    }\n\n    assertRotationRecoveryGeneration(input);\n\n    importSyncedDocumentUpdates(\n      input.rebuiltDocument,\n      ordinaryRawHistoryUpdates(synced.decryptedUpdates),\n    );\n    if (!synced.hasIncompletePull) return synced;\n\n    const nextContinuation = readPullContinuation(synced.response);\n    if (!nextContinuation) {\n      throw new Error(\n        \"Rotation raw-history recovery ended before the retained history was complete\",\n      );\n    }\n    if (seenPullCursors.has(nextContinuation.cursor)) {\n      throw new Error(\n        \"Rotation raw-history recovery encountered a repeated pull cursor\",\n      );\n    }\n    seenPullCursors.add(nextContinuation.cursor);\n    pullContinuation = nextContinuation;\n    planningRecord = { ...planningRecord, ...synced.persistedState };\n    writerProjection = synced.writerProjection;\n  }\n}\n\nasync function collectVerifiedRawHistoryForRotation(input: {\n  currentRecord: NonNullable<DocumentStoreState[\"record\"]>;\n  generation: DocumentStoreSyncGeneration;\n  state: DocumentStoreState;\n}) {\n  const consumedPullContinuation = input.state.pullContinuation;\n  const writerProjectionGeneration = input.state.writerProjectionGeneration;\n  const rebuiltDocument = await createStoredDocument(input.state);\n  try {\n    const synced = await pullVerifiedRawHistoryForRotation({\n      ...input,\n      rebuiltDocument,\n    });\n    return {\n      consumedPullContinuation,\n      currentRecord: input.currentRecord,\n      rebuiltDocument,\n      synced,\n      writerProjectionGeneration,\n    };\n  } catch (error) {\n    rebuiltDocument.free();\n    throw error;\n  }\n}\n\nclass RotationDocumentChangedError extends Error {}\n\nfunction assertCapturedDocumentCurrent(input: {\n  capturedVersion: string;\n  currentDocument: DocumentState;\n  generation: DocumentStoreSyncGeneration;\n  state: DocumentStoreState;\n}): void {\n  assertRotationRecoveryGeneration(input);\n  if (\n    !versionVectorsEqual(\n      encodeVersionVector(input.currentDocument),\n      input.capturedVersion,\n    )\n  ) {\n    throw new RotationDocumentChangedError(\n      \"Document changed during rotation recovery; retry key rotation\",\n    );\n  }\n}\n\nfunction currentRotationRecoveryRecord(\n  state: DocumentStoreState,\n): NonNullable<DocumentStoreState[\"record\"]> {\n  if (state.record) return state.record;\n  throw new Error(\n    \"Document changed during rotation recovery; retry key rotation\",\n  );\n}\n\nfunction installRotationRecovery(input: {\n  capturedVersion: string;\n  collection: Awaited<ReturnType<typeof collectVerifiedRawHistoryForRotation>>;\n  currentDoc: DocumentState;\n  generation: DocumentStoreSyncGeneration;\n  state: DocumentStoreState;\n}) {\n  const { capturedVersion, collection, currentDoc, generation, state } = input;\n  const installation = state.writeChain\n    .catch(() => undefined)\n    .then(() =>\n      chainIdentityWrite(state, async () => {\n        assertCapturedDocumentCurrent({\n          capturedVersion,\n          currentDocument: currentDoc,\n          generation,\n          state,\n        });\n        assertExactDocumentHistory({\n          currentDocument: currentDoc,\n          rebuiltDocument: collection.rebuiltDocument,\n        });\n        return installRebuiltDocument({\n          consumedPullContinuation: collection.consumedPullContinuation,\n          currentRecord: collection.currentRecord,\n          generation,\n          rebuiltDoc: collection.rebuiltDocument,\n          state,\n          synced: collection.synced,\n          writerProjectionGeneration: collection.writerProjectionGeneration,\n        });\n      }),\n    );\n  // Only the checked local install occupies the write queue. Network recovery\n  // uses the remote queue, so an outage cannot hold new edits hostage.\n  state.writeChain = installation.then(\n    () => undefined,\n    () => undefined,\n  );\n  return installation;\n}\n\nasync function recoverFullHistoryForRotation(\n  state: DocumentStoreState,\n  laneGeneration: DocumentStoreSyncLaneGeneration,\n): Promise<Uint8Array> {\n  assertRotationRecoveryPrerequisites(state);\n  await invalidatePullContinuationBeforeRotation(state);\n  const currentDoc = state.doc;\n  const currentRecord = state.record;\n  if (!currentDoc || !currentRecord) {\n    throw new Error(\n      \"Document must finish loading before its content key can rotate\",\n    );\n  }\n  // The teardown guard for the recovery's terminal-failure handler: captured\n  // before the pull so a discard (row 21) racing this preflight invalidates\n  // it, and the stale handler cannot resurrect a deleted failure row.\n  const generation = captureDocumentStoreAttachmentSyncGeneration(\n    state,\n    currentDoc,\n    laneGeneration,\n  );\n  if (!generation) {\n    throw new Error(\n      \"Document changed during rotation recovery; retry key rotation\",\n    );\n  }\n\n  const capturedVersion = encodeVersionVector(currentDoc);\n  let settlementRequiresRetry = false;\n\n  // A raw recovery starts from an empty scratch document, bypasses untrusted\n  // rotation-baseline redirects, drains every retained page in memory, and\n  // publishes nothing until all response updates have validated. Checkpoints\n  // are authenticated and decrypted but are not reconstruction inputs: the\n  // original ordinary update stream is the source of truth in this mode.\n  let collection = await collectVerifiedRawHistoryForRotation({\n    currentRecord,\n    generation,\n    state,\n  });\n\n  try {\n    assertCapturedDocumentCurrent({\n      capturedVersion,\n      currentDocument: currentDoc,\n      generation,\n      state,\n    });\n    const pendingUpdates = await listPendingUpdates(state);\n    assertCapturedDocumentCurrent({\n      capturedVersion,\n      currentDocument: currentDoc,\n      generation,\n      state,\n    });\n    const verifiedOrdinaryVersion = importProvenOrdinaryPendingHistory({\n      currentDocument: currentDoc,\n      pendingUpdates,\n      rebuiltDocument: collection.rebuiltDocument,\n    });\n    if (pendingUpdates.some((update) => update.sourceVersionVector == null)) {\n      // The first raw pass proves the exact ordinary frontier before any local\n      // row can be published. Pull raw history again after settlement so the\n      // installed snapshot also includes remote work that raced that submit.\n      await settleOrdinaryDocumentUpdatesBeforeRotation(\n        state,\n        verifiedOrdinaryVersion,\n        pendingUpdates,\n        generation,\n      );\n      assertCapturedDocumentCurrent({\n        capturedVersion,\n        currentDocument: currentDoc,\n        generation,\n        state,\n      });\n      const definitiveCollection = await collectVerifiedRawHistoryForRotation({\n        currentRecord: currentRotationRecoveryRecord(state),\n        generation,\n        state,\n      });\n      collection.rebuiltDocument.free();\n      collection = definitiveCollection;\n    }\n    const installed = await installRotationRecovery({\n      capturedVersion,\n      collection,\n      currentDoc,\n      generation,\n      state,\n    });\n    settlementRequiresRetry = installed.settlementRequiresRetry;\n    if (settlementRequiresRetry) {\n      throw new Error(\n        \"Rotation raw-history recovery was superseded during its atomic install; retry key rotation\",\n      );\n    }\n    return installed.fullHistorySnapshot;\n  } finally {\n    if (state.doc !== collection.rebuiltDocument) {\n      collection.rebuiltDocument.free();\n    }\n    if (settlementRequiresRetry) {\n      requestDocumentStoreSync(state);\n    }\n  }\n}\n\n/**\n * Wait for prior local writes and serialize with other remote work. Edits can\n * continue during the pull; the checked install rejects a changed document so\n * a stale recovery cannot replace them. This preflight can then be retried.\n */\nexport function assertDocumentStoreCanRotateContentKey(\n  state: DocumentStoreState,\n): Promise<Uint8Array> {\n  const laneGeneration = captureDocumentStoreSyncLaneGeneration(state);\n  const generation = captureDocumentStoreAttachmentSyncGeneration(\n    state,\n    state.doc,\n    laneGeneration,\n  );\n  return runDocumentRemoteWork(state, async () => {\n    await state.writeChain.catch(() => undefined);\n    if (\n      !generation ||\n      !isDocumentStoreSyncGenerationCurrent(state, generation)\n    ) {\n      throw new Error(\n        \"Document changed before rotation recovery; retry key rotation\",\n      );\n    }\n    for (let attempt = 0; ; attempt += 1) {\n      try {\n        return await recoverFullHistoryForRotation(state, laneGeneration);\n      } catch (error) {\n        // Autosaves and conflict re-keying can invalidate the proven frontier.\n        // Repeat the complete proof without blocking new local edits; repeated\n        // changes remain bounded and leave the durable queue retryable.\n        if (\n          !(\n            error instanceof RotationPendingUpdatesChangedError ||\n            error instanceof RotationDocumentChangedError\n          ) ||\n          attempt >= 2 ||\n          !isDocumentStoreSyncGenerationCurrent(state, generation)\n        ) {\n          throw error;\n        }\n      }\n    }\n  });\n}\n"]}

package/stores/documents/documentStore/rotationProvenance.js

@@ -0,0 +1,52 @@
+import { base64ToBytes } from "../../../internal/encoding/index.js";
+import { encodeVersionVector, exportFullHistoryIdentity, getImportBlobMetadata, importUpdates, satisfiesVersionVector, updateMatchesDocumentHistory, versionVectorsEqual, } from "../../../internal/loro/index.js";
+function unverifiedLocalHistory(cause) {
+    return new Error("Rotation raw-history recovery found unverified local history; key rotation was not started", cause === undefined ? undefined : { cause });
+}
+function ordinaryPendingUpdateBytes(input) {
+    return input.pendingUpdates.flatMap((update) => {
+        if (update.sourceVersionVector != null)
+            return [];
+        const bytes = base64ToBytes(update.updateData);
+        const metadata = getImportBlobMetadata(bytes);
+        if (metadata.mode !== "update" ||
+            !versionVectorsEqual(metadata.partialStartVersionVector, update.partialStartVersionVector) ||
+            !versionVectorsEqual(metadata.partialEndVersionVector, update.partialEndVersionVector) ||
+            !updateMatchesDocumentHistory(input.currentDocument, bytes)) {
+            throw new Error("Ordinary pending-update provenance is inconsistent");
+        }
+        return [bytes];
+    });
+}
+export function assertExactDocumentHistory(input) {
+    const currentVersion = encodeVersionVector(input.currentDocument);
+    if (!satisfiesVersionVector(encodeVersionVector(input.rebuiltDocument), currentVersion) ||
+        exportFullHistoryIdentity(input.currentDocument) !==
+            exportFullHistoryIdentity(input.rebuiltDocument, currentVersion)) {
+        throw unverifiedLocalHistory();
+    }
+}
+/**
+ * Prove that the live history is exactly raw remote history plus queued local
+ * ordinary deltas. Deterministic operation-log comparison detects checkpoint
+ * substitutions that reuse the genuine operations' version-vector identities.
+ */
+export function importProvenOrdinaryPendingHistory(input) {
+    try {
+        const updates = ordinaryPendingUpdateBytes({
+            currentDocument: input.currentDocument,
+            pendingUpdates: input.pendingUpdates,
+        });
+        if (updates.length > 0)
+            importUpdates(input.rebuiltDocument, updates);
+        assertExactDocumentHistory(input);
+        return encodeVersionVector(input.currentDocument);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.includes("unverified local")) {
+            throw error;
+        }
+        throw unverifiedLocalHistory(error);
+    }
+}
+//# sourceMappingURL=rotationProvenance.js.map

package/stores/documents/documentStore/rotationProvenance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rotationProvenance.js","sourceRoot":"","sources":["rotationProvenance.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EACL,mBAAmB,EACnB,yBAAyB,EACzB,qBAAqB,EACrB,aAAa,EACb,sBAAsB,EACtB,4BAA4B,EAC5B,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AAIzB,SAAS,sBAAsB,CAAC,KAAe;IAC7C,OAAO,IAAI,KAAK,CACd,4FAA4F,EAC5F,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAC5C,CAAC;AACJ,CAAC;AAED,SAAS,0BAA0B,CAAC,KAGnC;IACC,OAAO,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE;QAC7C,IAAI,MAAM,CAAC,mBAAmB,IAAI,IAAI;YAAE,OAAO,EAAE,CAAC;QAClD,MAAM,KAAK,GAAG,aAAa,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAC/C,MAAM,QAAQ,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAC;QAC9C,IACE,QAAQ,CAAC,IAAI,KAAK,QAAQ;YAC1B,CAAC,mBAAmB,CAClB,QAAQ,CAAC,yBAAyB,EAClC,MAAM,CAAC,yBAAyB,CACjC;YACD,CAAC,mBAAmB,CAClB,QAAQ,CAAC,uBAAuB,EAChC,MAAM,CAAC,uBAAuB,CAC/B;YACD,CAAC,4BAA4B,CAAC,KAAK,CAAC,eAAe,EAAE,KAAK,CAAC,EAC3D,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;QACxE,CAAC;QACD,OAAO,CAAC,KAAK,CAAC,CAAC;IACjB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,0BAA0B,CAAC,KAG1C;IACC,MAAM,cAAc,GAAG,mBAAmB,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;IAClE,IACE,CAAC,sBAAsB,CACrB,mBAAmB,CAAC,KAAK,CAAC,eAAe,CAAC,EAC1C,cAAc,CACf;QACD,yBAAyB,CAAC,KAAK,CAAC,eAAe,CAAC;YAC9C,yBAAyB,CAAC,KAAK,CAAC,eAAe,EAAE,cAAc,CAAC,EAClE,CAAC;QACD,MAAM,sBAAsB,EAAE,CAAC;IACjC,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kCAAkC,CAAC,KAIlD;IACC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,0BAA0B,CAAC;YACzC,eAAe,EAAE,KAAK,CAAC,eAAe;YACtC,cAAc,EAAE,KAAK,CAAC,cAAc;SACrC,CAAC,CAAC;QACH,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;YAAE,aAAa,CAAC,KAAK,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;QACtE,0BAA0B,CAAC,KAAK,CAAC,CAAC;QAClC,OAAO,mBAAmB,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;IACpD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC;YACzE,MAAM,KAAK,CAAC;QACd,CAAC;QACD,MAAM,sBAAsB,CAAC,KAAK,CAAC,CAAC;IACtC,CAAC;AACH,CAAC","sourcesContent":["import { base64ToBytes } from \"@tearleads/encoding\";\nimport {\n  encodeVersionVector,\n  exportFullHistoryIdentity,\n  getImportBlobMetadata,\n  importUpdates,\n  satisfiesVersionVector,\n  updateMatchesDocumentHistory,\n  versionVectorsEqual,\n} from \"@tearleads/loro\";\nimport type { PendingUpdateRecord } from \"../../../workflows/documents\";\nimport type { DocumentState } from \"./state\";\n\nfunction unverifiedLocalHistory(cause?: unknown): Error {\n  return new Error(\n    \"Rotation raw-history recovery found unverified local history; key rotation was not started\",\n    cause === undefined ? undefined : { cause },\n  );\n}\n\nfunction ordinaryPendingUpdateBytes(input: {\n  currentDocument: DocumentState;\n  pendingUpdates: readonly PendingUpdateRecord[];\n}): Uint8Array[] {\n  return input.pendingUpdates.flatMap((update) => {\n    if (update.sourceVersionVector != null) return [];\n    const bytes = base64ToBytes(update.updateData);\n    const metadata = getImportBlobMetadata(bytes);\n    if (\n      metadata.mode !== \"update\" ||\n      !versionVectorsEqual(\n        metadata.partialStartVersionVector,\n        update.partialStartVersionVector,\n      ) ||\n      !versionVectorsEqual(\n        metadata.partialEndVersionVector,\n        update.partialEndVersionVector,\n      ) ||\n      !updateMatchesDocumentHistory(input.currentDocument, bytes)\n    ) {\n      throw new Error(\"Ordinary pending-update provenance is inconsistent\");\n    }\n    return [bytes];\n  });\n}\n\nexport function assertExactDocumentHistory(input: {\n  currentDocument: DocumentState;\n  rebuiltDocument: DocumentState;\n}): void {\n  const currentVersion = encodeVersionVector(input.currentDocument);\n  if (\n    !satisfiesVersionVector(\n      encodeVersionVector(input.rebuiltDocument),\n      currentVersion,\n    ) ||\n    exportFullHistoryIdentity(input.currentDocument) !==\n      exportFullHistoryIdentity(input.rebuiltDocument, currentVersion)\n  ) {\n    throw unverifiedLocalHistory();\n  }\n}\n\n/**\n * Prove that the live history is exactly raw remote history plus queued local\n * ordinary deltas. Deterministic operation-log comparison detects checkpoint\n * substitutions that reuse the genuine operations' version-vector identities.\n */\nexport function importProvenOrdinaryPendingHistory(input: {\n  currentDocument: DocumentState;\n  pendingUpdates: readonly PendingUpdateRecord[];\n  rebuiltDocument: DocumentState;\n}): string {\n  try {\n    const updates = ordinaryPendingUpdateBytes({\n      currentDocument: input.currentDocument,\n      pendingUpdates: input.pendingUpdates,\n    });\n    if (updates.length > 0) importUpdates(input.rebuiltDocument, updates);\n    assertExactDocumentHistory(input);\n    return encodeVersionVector(input.currentDocument);\n  } catch (error) {\n    if (error instanceof Error && error.message.includes(\"unverified local\")) {\n      throw error;\n    }\n    throw unverifiedLocalHistory(error);\n  }\n}\n"]}

package/stores/documents/documentStore/rotationSettlement.js

@@ -0,0 +1,222 @@
+import { encodeVersionVector, satisfiesVersionVector } from "../../../internal/loro/index.js";
+import { chainIdentityWrite } from "./identityWriteChain.js";
+import { listPendingUpdates, persistDocument } from "./persistence.js";
+import { invalidateDocumentStorePullContinuation } from "./pullContinuationInvalidation.js";
+import { cleanupPreRegisteredUpdateIdsOnFailure, discardUnacceptedPreRegisteredUpdateIds, preRegisterMaterializedDocumentSyncUpdateIds, } from "./syncAcceptedUpdateIds.js";
+import { captureDocumentStoreSyncGeneration, isDocumentStoreSyncGenerationCurrent, } from "./syncGeneration.js";
+import { prepareDocumentOutgoingCoverage } from "./syncOutgoingCoverage.js";
+import { requestRemoteDocumentSync } from "./syncRequest.js";
+import { extendDocumentVersionCoverage } from "./versionCoverage.js";
+export class RotationPendingUpdatesChangedError extends Error {
+}
+function ordinaryPendingUpdates(pendingUpdates) {
+    return pendingUpdates.filter((pendingUpdate) => pendingUpdate.sourceVersionVector == null);
+}
+function pendingUpdateSetKey(pendingUpdates) {
+    return pendingUpdates
+        .map((pendingUpdate) => pendingUpdate.id)
+        .sort()
+        .join("\n");
+}
+function pendingUpdateMatchesProvenRow(pendingUpdate, provenUpdate) {
+    return (pendingUpdate.id === provenUpdate.id &&
+        pendingUpdate.updateData === provenUpdate.updateData &&
+        pendingUpdate.partialStartVersionVector ===
+            provenUpdate.partialStartVersionVector &&
+        pendingUpdate.partialEndVersionVector ===
+            provenUpdate.partialEndVersionVector &&
+        pendingUpdate.sourceVersionVector === provenUpdate.sourceVersionVector);
+}
+function assertOrdinaryRowsWereProven(input) {
+    for (const pendingUpdate of ordinaryPendingUpdates(input.pendingUpdates)) {
+        const provenUpdate = input.provenUpdatesById.get(pendingUpdate.id);
+        if (!provenUpdate ||
+            !pendingUpdateMatchesProvenRow(pendingUpdate, provenUpdate)) {
+            throw new RotationPendingUpdatesChangedError("Document local updates changed after rotation provenance verification");
+        }
+    }
+}
+function ordinaryPendingUpdatesWithProvenCoverage(input) {
+    const ordinaryUpdates = ordinaryPendingUpdates(input.pendingUpdates);
+    const documentVersion = encodeVersionVector(input.currentDocument);
+    const ordinaryCoverage = extendDocumentVersionCoverage({
+        baseVersion: input.verifiedBaseVersion,
+        documentVersion,
+        spans: ordinaryUpdates,
+    });
+    if (!satisfiesVersionVector(ordinaryCoverage, documentVersion)) {
+        throw new Error("Document rotation cannot settle uncovered local history because it may be checkpoint-derived");
+    }
+    return { coverage: ordinaryCoverage, pendingUpdates: ordinaryUpdates };
+}
+export async function invalidatePullContinuationBeforeRotation(state) {
+    const continuation = state.pullContinuation;
+    if (!continuation)
+        return;
+    const currentDoc = state.doc;
+    const currentRecord = state.record;
+    if (!currentDoc || !currentRecord) {
+        throw new Error("Document changed while its pull continuation was invalidated for key rotation");
+    }
+    const generation = captureDocumentStoreSyncGeneration(state, currentDoc);
+    if (!generation) {
+        throw new Error("Document changed while its pull continuation was invalidated for key rotation");
+    }
+    await invalidateDocumentStorePullContinuation({
+        continuation,
+        currentRecord,
+        generation,
+        state,
+    });
+    if (state.pullContinuation !== null ||
+        !isDocumentStoreSyncGenerationCurrent(state, generation)) {
+        throw new Error("Document pull continuation could not be invalidated before key rotation");
+    }
+}
+async function persistStagedSettlement(input) {
+    const { state, syncAttempt } = input;
+    discardUnacceptedPreRegisteredUpdateIds(state, input.sentUpdateIds, syncAttempt.synced.response.acceptedOutgoingUpdateIds);
+    const persisted = await persistDocument(state, input.currentDocument, {
+        lastCommitLsn: syncAttempt.synced.response.commitLsn ??
+            input.preparedRecord.lastCommitLsn ??
+            null,
+        pullContinuation: null,
+    }, {
+        acceptedPendingUpdateIds: syncAttempt.synced.settledPendingUpdateIds,
+        expectedSyncState: {
+            pullContinuation: syncAttempt.consumedPullContinuation,
+            record: syncAttempt.requestRecord,
+        },
+        preserveSnapshotStructuredFields: true,
+        preserveSnapshotText: true,
+    }, input.generation);
+    if (!persisted ||
+        persisted.pullContinuationSuperseded ||
+        persisted.syncIdentitySuperseded ||
+        !isDocumentStoreSyncGenerationCurrent(state, input.generation)) {
+        throw new Error("Document changed while local updates were settling for key rotation");
+    }
+}
+function settledOrdinaryCoverage(input) {
+    const settled = new Set(input.settledUpdateIds);
+    return extendDocumentVersionCoverage({
+        baseVersion: input.verifiedBaseVersion,
+        documentVersion: encodeVersionVector(input.currentDocument),
+        spans: input.pendingUpdates.filter((update) => settled.has(update.id)),
+    });
+}
+async function persistStagedSettlementOnIdentityChain(input) {
+    return chainIdentityWrite(input.state, async () => {
+        if (!isDocumentStoreSyncGenerationCurrent(input.state, input.generation)) {
+            throw new Error("Document changed while local updates were settling for key rotation");
+        }
+        await persistStagedSettlement(input);
+        return settledOrdinaryCoverage({
+            currentDocument: input.currentDocument,
+            pendingUpdates: input.pendingUpdates,
+            settledUpdateIds: input.syncAttempt.synced.settledPendingUpdateIds,
+            verifiedBaseVersion: input.verifiedBaseVersion,
+        });
+    });
+}
+async function settleOrdinaryUpdatePass(input) {
+    const { state } = input;
+    const currentDoc = state.doc;
+    const currentRecord = state.record;
+    const encapsulationKeyPair = state.runtime.crypto.encapsulationKeyPair;
+    if (!currentDoc || !currentRecord || !encapsulationKeyPair) {
+        throw new Error("Document changed while local updates were settling for key rotation");
+    }
+    const generation = input.generation;
+    if (!isDocumentStoreSyncGenerationCurrent(state, generation)) {
+        throw new Error("Document changed while local updates were settling for key rotation");
+    }
+    const proven = ordinaryPendingUpdatesWithProvenCoverage({
+        currentDocument: currentDoc,
+        pendingUpdates: input.pendingUpdates,
+        verifiedBaseVersion: input.verifiedBaseVersion,
+    });
+    const prepared = await prepareDocumentOutgoingCoverage({
+        coverageBaseVersion: input.verifiedBaseVersion,
+        currentDoc,
+        generation,
+        pendingUpdates: proven.pendingUpdates,
+        state,
+    });
+    if (!prepared || !isDocumentStoreSyncGenerationCurrent(state, generation)) {
+        throw new Error("Document changed while local updates were settling for key rotation");
+    }
+    const preparedPendingUpdates = ordinaryPendingUpdates(prepared.pendingUpdates);
+    if (preparedPendingUpdates.length === 0)
+        return proven.coverage;
+    const sentUpdateIds = [];
+    return cleanupPreRegisteredUpdateIdsOnFailure(state, sentUpdateIds, async () => {
+        const syncAttempt = await requestRemoteDocumentSync({
+            allowRecoveryBaseline: false,
+            currentDoc,
+            currentRecord: prepared.record,
+            encapsulationKeyPair,
+            generation,
+            onOutgoingUpdatesMaterialized: (updateIds) => preRegisterMaterializedDocumentSyncUpdateIds(state, sentUpdateIds, updateIds),
+            pendingUpdates: preparedPendingUpdates,
+            queuedUpdateCount: preparedPendingUpdates.length,
+            state,
+            unavailableWriterLogMessage: "Documents: rotation could not settle local updates because the writer context is unavailable.",
+        });
+        if (!syncAttempt ||
+            !isDocumentStoreSyncGenerationCurrent(state, generation)) {
+            throw new Error("Document local updates could not be committed before key rotation");
+        }
+        return persistStagedSettlementOnIdentityChain({
+            currentDocument: currentDoc,
+            generation,
+            pendingUpdates: preparedPendingUpdates,
+            preparedRecord: prepared.record,
+            sentUpdateIds,
+            state,
+            syncAttempt,
+            verifiedBaseVersion: input.verifiedBaseVersion,
+        });
+    });
+}
+/**
+ * Commit only ordinary local rows before rotation. Server-returned updates are
+ * authenticated and decrypted by the workflow but deliberately not imported
+ * or persisted; the subsequent raw rebuild owns that all-or-nothing install.
+ */
+export async function settleOrdinaryDocumentUpdatesBeforeRotation(state, verifiedBaseVersion, provenPendingUpdates, generation) {
+    const stalledQueueStates = new Set();
+    let verifiedCoverage = verifiedBaseVersion;
+    const provenUpdatesById = new Map(ordinaryPendingUpdates(provenPendingUpdates).map((update) => [
+        update.id,
+        update,
+    ]));
+    while (true) {
+        const currentDoc = state.doc;
+        if (!currentDoc) {
+            throw new Error("Document rotation requires an initialized document");
+        }
+        const allPendingUpdates = await listPendingUpdates(state);
+        assertOrdinaryRowsWereProven({
+            pendingUpdates: allPendingUpdates,
+            provenUpdatesById,
+        });
+        const pendingUpdates = ordinaryPendingUpdates(allPendingUpdates);
+        if (pendingUpdates.length === 0 &&
+            satisfiesVersionVector(verifiedCoverage, encodeVersionVector(currentDoc))) {
+            return;
+        }
+        const queueState = `${verifiedCoverage}\n${pendingUpdateSetKey(pendingUpdates)}`;
+        if (stalledQueueStates.has(queueState)) {
+            throw new Error("Document local updates could not be committed before key rotation");
+        }
+        stalledQueueStates.add(queueState);
+        verifiedCoverage = await settleOrdinaryUpdatePass({
+            generation,
+            pendingUpdates: allPendingUpdates,
+            state,
+            verifiedBaseVersion: verifiedCoverage,
+        });
+    }
+}
+//# sourceMappingURL=rotationSettlement.js.map