@tearleads/client-sdk 0.1.62 → 0.1.64

package/stores/documents/documentStore/attachments/index.js

@@ -0,0 +1,241 @@
+import { encodeVersionVector, exportFullHistorySnapshot, } from "../../../../internal/loro/index.js";
+import { addDocumentAttachments } from "../../../../data/documents/documentContent.js";
+import { requestDocumentStoreSync } from "../../registry.js";
+import { deleteUnreferencedStagedAttachmentBytes, installPendingAttachmentRows, stagePendingAttachments, } from "../attachmentUpload/attachmentStaging.js";
+import { ensureDocumentStoreReady } from "../initialization/index.js";
+import { settleDeferredInitialUpdate } from "../initialization/deferredInitialUpdate.js";
+import { advancePendingBaseVersion, pendingDeltaSinceBase, } from "../persistence.js";
+import { reportDocumentStoreWriteFailure } from "../reportWriteFailure.js";
+import { canAttachFiles, canWriteDocument, } from "../state.js";
+import { captureDocumentStoreSyncGeneration } from "../sync/syncGeneration.js";
+import { buildAttachmentIntent, buildPendingAttachments, } from "./attachmentIntents.js";
+import { persistStagedAttachmentMutation, restoreFailedAttachmentMutation, } from "./attachmentMutationPersistence.js";
+import { captureAttachmentWriteGeneration, isAttachmentWriteGenerationCurrent, shouldAbortAttachmentPersistFollowup, } from "./attachmentWriteGeneration.js";
+// Fixed literal: a reported message must never carry file names or slot ids.
+export const ATTACHMENT_FAILURE_MESSAGE = "Documents: attachment mutation failed";
+function logAttachedFiles(state, count) {
+    state.runtime.util.log(state.runtime.state.online && state.runtime.auth.isAuthenticated
+        ? `Attached ${count} file${count === 1 ? "" : "s"} to document ${state.localId}.`
+        : `Stored ${count} attachment${count === 1 ? "" : "s"} locally for document ${state.localId}.`);
+}
+async function persistAttachedFiles(state, files, writeGeneration) {
+    if (!isAttachmentWriteGenerationCurrent(state, writeGeneration))
+        return;
+    const currentDoc = state.doc;
+    if (!currentDoc || !canAttachFiles(state)) {
+        state.runtime.util.log("Documents: attachments require a local key package.");
+        return;
+    }
+    const generation = captureDocumentStoreSyncGeneration(state, currentDoc);
+    if (!generation) {
+        return;
+    }
+    const { nextAttachments, nextPendingAttachments } = await buildPendingAttachments(state.localId, files);
+    if (!isAttachmentWriteGenerationCurrent(state, writeGeneration) ||
+        state.doc !== currentDoc)
+        return;
+    const rollbackSnapshot = exportFullHistorySnapshot(currentDoc).slice();
+    addDocumentAttachments(currentDoc, nextAttachments);
+    const attachmentUpdate = pendingDeltaSinceBase(state, currentDoc);
+    // Captured at delta time: the enqueued row proves coverage up to exactly
+    // this version, so it is the frontier the persist below may publish.
+    const coveredVersion = encodeVersionVector(currentDoc);
+    let staged;
+    try {
+        staged = await stagePendingAttachments({
+            files,
+            generation,
+            pendingAttachments: nextPendingAttachments,
+            state,
+        });
+    }
+    catch (error) {
+        await restoreFailedAttachmentMutation({
+            generation,
+            rollbackSnapshot,
+            state,
+        });
+        throw error;
+    }
+    if (!staged) {
+        await restoreFailedAttachmentMutation({
+            generation,
+            rollbackSnapshot,
+            state,
+        });
+        return;
+    }
+    // This persist changes attachments, not prose. setReadySnapshot always
+    // re-derives attachments from the doc, but preserve the text/structured
+    // fields so an attach that overlaps an in-flight keystroke does not republish
+    // a stale doc read over the live optimistic editor value.
+    const persisted = await persistStagedAttachmentMutation({
+        attachmentUpdate,
+        coveredVersion,
+        currentDoc,
+        generation,
+        rollbackSnapshot,
+        staged,
+        state,
+    });
+    if (shouldAbortAttachmentPersistFollowup(state, writeGeneration, generation, persisted)) {
+        await deleteUnreferencedStagedAttachmentBytes({
+            generation,
+            pendingAttachments: staged.pendingAttachments,
+            state,
+        });
+        return;
+    }
+    installPendingAttachmentRows({ ...staged, state });
+    advancePendingBaseVersion(state, currentDoc);
+    logAttachedFiles(state, files.length);
+    requestDocumentStoreSync(state);
+}
+async function persistSlotAttachmentFile(state, slotId, file, writeGeneration) {
+    if (!isAttachmentWriteGenerationCurrent(state, writeGeneration))
+        return;
+    const currentDoc = state.doc;
+    if (!currentDoc || !canAttachFiles(state)) {
+        state.runtime.util.log("Documents: slot attachments require a local key package.");
+        return;
+    }
+    const generation = captureDocumentStoreSyncGeneration(state, currentDoc);
+    if (!generation) {
+        return;
+    }
+    const replacementAttachment = await buildAttachmentIntent(slotId, file);
+    if (!isAttachmentWriteGenerationCurrent(state, writeGeneration) ||
+        state.doc !== currentDoc)
+        return;
+    const rollbackSnapshot = exportFullHistorySnapshot(currentDoc).slice();
+    addDocumentAttachments(currentDoc, [replacementAttachment]);
+    const attachmentUpdate = pendingDeltaSinceBase(state, currentDoc);
+    const coveredVersion = encodeVersionVector(currentDoc);
+    const storageKey = `${state.localId}-${slotId}-${crypto.randomUUID()}`;
+    const pendingAttachment = {
+        byteLength: replacementAttachment.byteLength,
+        contentSha256: replacementAttachment.contentSha256,
+        localId: state.localId,
+        mimeType: replacementAttachment.mimeType,
+        name: replacementAttachment.name,
+        slotId,
+        storageKey,
+    };
+    let staged;
+    try {
+        staged = await stagePendingAttachments({
+            files: [file],
+            generation,
+            pendingAttachments: [pendingAttachment],
+            state,
+        });
+    }
+    catch (error) {
+        await restoreFailedAttachmentMutation({
+            generation,
+            rollbackSnapshot,
+            state,
+        });
+        throw error;
+    }
+    if (!staged) {
+        await restoreFailedAttachmentMutation({
+            generation,
+            rollbackSnapshot,
+            state,
+        });
+        return;
+    }
+    // Preserve the optimistic text/structured fields (see persistAttachedFiles):
+    // a slot replacement overlapping a keystroke must not regress the editor.
+    const persisted = await persistStagedAttachmentMutation({
+        attachmentUpdate,
+        coveredVersion,
+        currentDoc,
+        generation,
+        rollbackSnapshot,
+        staged,
+        state,
+    });
+    if (shouldAbortAttachmentPersistFollowup(state, writeGeneration, generation, persisted)) {
+        await deleteUnreferencedStagedAttachmentBytes({
+            generation,
+            pendingAttachments: staged.pendingAttachments,
+            state,
+        });
+        return;
+    }
+    installPendingAttachmentRows({ ...staged, state });
+    advancePendingBaseVersion(state, currentDoc);
+    state.runtime.util.log(`Queued attachment ${file.name} for slot ${slotId}.`);
+    requestDocumentStoreSync(state);
+}
+async function captureReadyAttachWrite(state, scheduleSync, callGeneration) {
+    let ready;
+    try {
+        ready = await ensureDocumentStoreReady(state, scheduleSync);
+    }
+    catch (error) {
+        reportDocumentStoreWriteFailure(state, ATTACHMENT_FAILURE_MESSAGE, error);
+        return null;
+    }
+    if (!ready || !state.doc || !canWriteDocument(state))
+        return null;
+    // A reset or relink while this call waited owns the replacement document.
+    if (callGeneration &&
+        !isAttachmentWriteGenerationCurrent(state, callGeneration)) {
+        return null;
+    }
+    return captureAttachmentWriteGeneration(state);
+}
+async function attachThenSettle(state, scheduleSync, files, callGeneration) {
+    const writeGeneration = files.length === 0
+        ? null
+        : await captureReadyAttachWrite(state, scheduleSync, callGeneration);
+    try {
+        if (writeGeneration) {
+            await persistAttachedFiles(state, files, writeGeneration);
+        }
+    }
+    finally {
+        await settleDeferredInitialUpdate(state, writeGeneration);
+    }
+}
+export async function attachFilesToDocumentStore(state, scheduleSync, files) {
+    // Join the chain before awaiting readiness so settlements keep call order,
+    // and settle even when nothing attaches: a deferred birth's sync hold lifts
+    // only behind every earlier attach, never while one is still staging. The
+    // caller's document is captured now (a cold store captures once ready).
+    const callGeneration = captureAttachmentWriteGeneration(state);
+    state.writeChain = state.writeChain
+        .catch(() => undefined)
+        .then(async () => attachThenSettle(state, scheduleSync, files, callGeneration))
+        .catch((error) => {
+        reportDocumentStoreWriteFailure(state, ATTACHMENT_FAILURE_MESSAGE, error);
+    });
+    return state.writeChain;
+}
+export async function replaceAttachmentInDocumentStore(state, scheduleSync, slotId, file) {
+    let ready;
+    try {
+        ready = await ensureDocumentStoreReady(state, scheduleSync);
+    }
+    catch (error) {
+        reportDocumentStoreWriteFailure(state, ATTACHMENT_FAILURE_MESSAGE, error);
+        return;
+    }
+    if (!ready || !state.doc || !canWriteDocument(state)) {
+        return;
+    }
+    const writeGeneration = captureAttachmentWriteGeneration(state);
+    if (!writeGeneration)
+        return;
+    state.writeChain = state.writeChain
+        .catch(() => undefined)
+        .then(async () => persistSlotAttachmentFile(state, slotId, file, writeGeneration))
+        .catch((error) => {
+        reportDocumentStoreWriteFailure(state, ATTACHMENT_FAILURE_MESSAGE, error);
+    });
+    return state.writeChain;
+}
+//# sourceMappingURL=index.js.map

package/stores/documents/documentStore/attachments/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  encodeVersionVector,\n  exportFullHistorySnapshot,\n} from \"@tearleads/loro\";\nimport { addDocumentAttachments } from \"../../../../data/documents/documentContent\";\nimport type { PendingAttachmentRecord } from \"../../../../workflows/documents\";\nimport { requestDocumentStoreSync } from \"../../registry\";\nimport type { DocumentAttachmentUpload } from \"../../types\";\nimport {\n  deleteUnreferencedStagedAttachmentBytes,\n  installPendingAttachmentRows,\n  stagePendingAttachments,\n} from \"../attachmentUpload/attachmentStaging\";\nimport { ensureDocumentStoreReady } from \"../initialization\";\nimport { settleDeferredInitialUpdate } from \"../initialization/deferredInitialUpdate\";\nimport {\n  advancePendingBaseVersion,\n  pendingDeltaSinceBase,\n} from \"../persistence\";\nimport { reportDocumentStoreWriteFailure } from \"../reportWriteFailure\";\nimport {\n  canAttachFiles,\n  canWriteDocument,\n  type DocumentStoreState,\n} from \"../state\";\nimport { captureDocumentStoreSyncGeneration } from \"../sync/syncGeneration\";\nimport {\n  buildAttachmentIntent,\n  buildPendingAttachments,\n} from \"./attachmentIntents\";\nimport {\n  persistStagedAttachmentMutation,\n  restoreFailedAttachmentMutation,\n} from \"./attachmentMutationPersistence\";\nimport {\n  type AttachmentWriteGeneration,\n  captureAttachmentWriteGeneration,\n  isAttachmentWriteGenerationCurrent,\n  shouldAbortAttachmentPersistFollowup,\n} from \"./attachmentWriteGeneration\";\n\n// Fixed literal: a reported message must never carry file names or slot ids.\nexport const ATTACHMENT_FAILURE_MESSAGE =\n  \"Documents: attachment mutation failed\";\n\nfunction logAttachedFiles(state: DocumentStoreState, count: number) {\n  state.runtime.util.log(\n    state.runtime.state.online && state.runtime.auth.isAuthenticated\n      ? `Attached ${count} file${count === 1 ? \"\" : \"s\"} to document ${state.localId}.`\n      : `Stored ${count} attachment${count === 1 ? \"\" : \"s\"} locally for document ${state.localId}.`,\n  );\n}\n\nasync function persistAttachedFiles(\n  state: DocumentStoreState,\n  files: ReadonlyArray<DocumentAttachmentUpload>,\n  writeGeneration: AttachmentWriteGeneration,\n) {\n  if (!isAttachmentWriteGenerationCurrent(state, writeGeneration)) return;\n  const currentDoc = state.doc;\n\n  if (!currentDoc || !canAttachFiles(state)) {\n    state.runtime.util.log(\n      \"Documents: attachments require a local key package.\",\n    );\n    return;\n  }\n  const generation = captureDocumentStoreSyncGeneration(state, currentDoc);\n  if (!generation) {\n    return;\n  }\n\n  const { nextAttachments, nextPendingAttachments } =\n    await buildPendingAttachments(state.localId, files);\n  if (\n    !isAttachmentWriteGenerationCurrent(state, writeGeneration) ||\n    state.doc !== currentDoc\n  )\n    return;\n  const rollbackSnapshot = exportFullHistorySnapshot(currentDoc).slice();\n  addDocumentAttachments(currentDoc, nextAttachments);\n  const attachmentUpdate = pendingDeltaSinceBase(state, currentDoc);\n  // Captured at delta time: the enqueued row proves coverage up to exactly\n  // this version, so it is the frontier the persist below may publish.\n  const coveredVersion = encodeVersionVector(currentDoc);\n\n  let staged: Awaited<ReturnType<typeof stagePendingAttachments>>;\n  try {\n    staged = await stagePendingAttachments({\n      files,\n      generation,\n      pendingAttachments: nextPendingAttachments,\n      state,\n    });\n  } catch (error) {\n    await restoreFailedAttachmentMutation({\n      generation,\n      rollbackSnapshot,\n      state,\n    });\n    throw error;\n  }\n  if (!staged) {\n    await restoreFailedAttachmentMutation({\n      generation,\n      rollbackSnapshot,\n      state,\n    });\n    return;\n  }\n  // This persist changes attachments, not prose. setReadySnapshot always\n  // re-derives attachments from the doc, but preserve the text/structured\n  // fields so an attach that overlaps an in-flight keystroke does not republish\n  // a stale doc read over the live optimistic editor value.\n  const persisted = await persistStagedAttachmentMutation({\n    attachmentUpdate,\n    coveredVersion,\n    currentDoc,\n    generation,\n    rollbackSnapshot,\n    staged,\n    state,\n  });\n  if (\n    shouldAbortAttachmentPersistFollowup(\n      state,\n      writeGeneration,\n      generation,\n      persisted,\n    )\n  ) {\n    await deleteUnreferencedStagedAttachmentBytes({\n      generation,\n      pendingAttachments: staged.pendingAttachments,\n      state,\n    });\n    return;\n  }\n  installPendingAttachmentRows({ ...staged, state });\n  advancePendingBaseVersion(state, currentDoc);\n  logAttachedFiles(state, files.length);\n  requestDocumentStoreSync(state);\n}\n\nasync function persistSlotAttachmentFile(\n  state: DocumentStoreState,\n  slotId: string,\n  file: DocumentAttachmentUpload,\n  writeGeneration: AttachmentWriteGeneration,\n) {\n  if (!isAttachmentWriteGenerationCurrent(state, writeGeneration)) return;\n  const currentDoc = state.doc;\n\n  if (!currentDoc || !canAttachFiles(state)) {\n    state.runtime.util.log(\n      \"Documents: slot attachments require a local key package.\",\n    );\n    return;\n  }\n  const generation = captureDocumentStoreSyncGeneration(state, currentDoc);\n  if (!generation) {\n    return;\n  }\n\n  const replacementAttachment = await buildAttachmentIntent(slotId, file);\n  if (\n    !isAttachmentWriteGenerationCurrent(state, writeGeneration) ||\n    state.doc !== currentDoc\n  )\n    return;\n  const rollbackSnapshot = exportFullHistorySnapshot(currentDoc).slice();\n  addDocumentAttachments(currentDoc, [replacementAttachment]);\n  const attachmentUpdate = pendingDeltaSinceBase(state, currentDoc);\n  const coveredVersion = encodeVersionVector(currentDoc);\n\n  const storageKey = `${state.localId}-${slotId}-${crypto.randomUUID()}`;\n  const pendingAttachment: PendingAttachmentRecord = {\n    byteLength: replacementAttachment.byteLength,\n    contentSha256: replacementAttachment.contentSha256,\n    localId: state.localId,\n    mimeType: replacementAttachment.mimeType,\n    name: replacementAttachment.name,\n    slotId,\n    storageKey,\n  };\n  let staged: Awaited<ReturnType<typeof stagePendingAttachments>>;\n  try {\n    staged = await stagePendingAttachments({\n      files: [file],\n      generation,\n      pendingAttachments: [pendingAttachment],\n      state,\n    });\n  } catch (error) {\n    await restoreFailedAttachmentMutation({\n      generation,\n      rollbackSnapshot,\n      state,\n    });\n    throw error;\n  }\n  if (!staged) {\n    await restoreFailedAttachmentMutation({\n      generation,\n      rollbackSnapshot,\n      state,\n    });\n    return;\n  }\n  // Preserve the optimistic text/structured fields (see persistAttachedFiles):\n  // a slot replacement overlapping a keystroke must not regress the editor.\n  const persisted = await persistStagedAttachmentMutation({\n    attachmentUpdate,\n    coveredVersion,\n    currentDoc,\n    generation,\n    rollbackSnapshot,\n    staged,\n    state,\n  });\n  if (\n    shouldAbortAttachmentPersistFollowup(\n      state,\n      writeGeneration,\n      generation,\n      persisted,\n    )\n  ) {\n    await deleteUnreferencedStagedAttachmentBytes({\n      generation,\n      pendingAttachments: staged.pendingAttachments,\n      state,\n    });\n    return;\n  }\n  installPendingAttachmentRows({ ...staged, state });\n  advancePendingBaseVersion(state, currentDoc);\n  state.runtime.util.log(`Queued attachment ${file.name} for slot ${slotId}.`);\n  requestDocumentStoreSync(state);\n}\n\nasync function captureReadyAttachWrite(\n  state: DocumentStoreState,\n  scheduleSync: () => void,\n  callGeneration: AttachmentWriteGeneration | null,\n) {\n  let ready: boolean;\n  try {\n    ready = await ensureDocumentStoreReady(state, scheduleSync);\n  } catch (error) {\n    reportDocumentStoreWriteFailure(state, ATTACHMENT_FAILURE_MESSAGE, error);\n    return null;\n  }\n  if (!ready || !state.doc || !canWriteDocument(state)) return null;\n  // A reset or relink while this call waited owns the replacement document.\n  if (\n    callGeneration &&\n    !isAttachmentWriteGenerationCurrent(state, callGeneration)\n  ) {\n    return null;\n  }\n  return captureAttachmentWriteGeneration(state);\n}\n\nasync function attachThenSettle(\n  state: DocumentStoreState,\n  scheduleSync: () => void,\n  files: ReadonlyArray<DocumentAttachmentUpload>,\n  callGeneration: AttachmentWriteGeneration | null,\n) {\n  const writeGeneration =\n    files.length === 0\n      ? null\n      : await captureReadyAttachWrite(state, scheduleSync, callGeneration);\n  try {\n    if (writeGeneration) {\n      await persistAttachedFiles(state, files, writeGeneration);\n    }\n  } finally {\n    await settleDeferredInitialUpdate(state, writeGeneration);\n  }\n}\n\nexport async function attachFilesToDocumentStore(\n  state: DocumentStoreState,\n  scheduleSync: () => void,\n  files: ReadonlyArray<DocumentAttachmentUpload>,\n) {\n  // Join the chain before awaiting readiness so settlements keep call order,\n  // and settle even when nothing attaches: a deferred birth's sync hold lifts\n  // only behind every earlier attach, never while one is still staging. The\n  // caller's document is captured now (a cold store captures once ready).\n  const callGeneration = captureAttachmentWriteGeneration(state);\n  state.writeChain = state.writeChain\n    .catch(() => undefined)\n    .then(async () =>\n      attachThenSettle(state, scheduleSync, files, callGeneration),\n    )\n    .catch((error: unknown) => {\n      reportDocumentStoreWriteFailure(state, ATTACHMENT_FAILURE_MESSAGE, error);\n    });\n  return state.writeChain;\n}\n\nexport async function replaceAttachmentInDocumentStore(\n  state: DocumentStoreState,\n  scheduleSync: () => void,\n  slotId: string,\n  file: DocumentAttachmentUpload,\n) {\n  let ready: boolean;\n  try {\n    ready = await ensureDocumentStoreReady(state, scheduleSync);\n  } catch (error) {\n    reportDocumentStoreWriteFailure(state, ATTACHMENT_FAILURE_MESSAGE, error);\n    return;\n  }\n\n  if (!ready || !state.doc || !canWriteDocument(state)) {\n    return;\n  }\n\n  const writeGeneration = captureAttachmentWriteGeneration(state);\n  if (!writeGeneration) return;\n  state.writeChain = state.writeChain\n    .catch(() => undefined)\n    .then(async () =>\n      persistSlotAttachmentFile(state, slotId, file, writeGeneration),\n    )\n    .catch((error: unknown) => {\n      reportDocumentStoreWriteFailure(state, ATTACHMENT_FAILURE_MESSAGE, error);\n    });\n  return state.writeChain;\n}\n"]}

package/stores/documents/documentStore/history/documentHistoryCompaction.js

@@ -0,0 +1,67 @@
+import { base64ToBytes, bytesToBase64 } from "../../../../internal/encoding/index.js";
+import { encodeVersionVector, exportFullHistorySnapshot, updateMatchesDocumentHistory, } from "../../../../internal/loro/index.js";
+import { DOCUMENT_HISTORY_COMPACTION_MAX_BYTES, DOCUMENT_HISTORY_COMPACTION_MAX_ROWS, } from "../../../../workflows/documents/index.js";
+import { captureDocumentStoreSyncGeneration, isDocumentStoreSyncGenerationCurrent as isSyncGenerationCurrent, } from "../sync/syncGeneration.js";
+/**
+ * Refresh the durable full-history checkpoint when the tail has grown past
+ * the compaction thresholds, or seed the first checkpoint as soon as the
+ * document can export full history (a freshly created or rebuilt document is
+ * cheap to export; waiting for the threshold would leave restarts without
+ * history until then). The snapshot comes from the LIVE document, which has
+ * every tail update imported, so clearing the tail loses nothing.
+ */
+export async function maybeCompactDocumentHistory(state, currentDoc, stillCurrent) {
+    const { persistence } = state;
+    // Bind this compaction to the store context it started under: a store
+    // reset or runtime swap mid-compaction must not let the OLD document's
+    // checkpoint overwrite the replacement generation's history (or land in a
+    // newly selected database).
+    const generation = captureDocumentStoreSyncGeneration(state, currentDoc);
+    if (!generation || stillCurrent?.() === false) {
+        return;
+    }
+    const execSql = state.runtime.infra.execSql;
+    const tail = await persistence.readHistoryTailSize(execSql, state.localId);
+    if (tail.hasCheckpoint &&
+        tail.rowCount < DOCUMENT_HISTORY_COMPACTION_MAX_ROWS &&
+        tail.byteLength < DOCUMENT_HISTORY_COMPACTION_MAX_BYTES) {
+        return;
+    }
+    // Capture the tail BEFORE exporting, then prove coverage per row: another
+    // pane can append ops this pane's document has not merged, so blanket
+    // deletion would discard the only durable copy. Unproven rows survive for
+    // a later compaction by whichever pane holds their ops.
+    const tailEntries = await persistence.listHistoryTailEntries(execSql, state.localId);
+    const snapshot = exportFullHistorySnapshot(currentDoc);
+    if (!isSyncGenerationCurrent(state, generation) ||
+        stillCurrent?.() === false) {
+        return;
+    }
+    const endVersionVector = encodeVersionVector(currentDoc);
+    await persistence.replaceHistoryCheckpoint(execSql, {
+        coveredTailIds: coveredHistoryTailIds(tailEntries, currentDoc),
+        endVersionVector,
+        localId: state.localId,
+        snapshot: bytesToBase64(snapshot),
+        stillCurrent: () => isSyncGenerationCurrent(state, generation) && stillCurrent?.() !== false,
+    });
+}
+/**
+ * Tail rows whose exact operations already belong to the checkpoint document.
+ * Version-vector dominance is insufficient: a same-frontier fork has the same
+ * declared range, and malformed rows must survive so recovery fails closed
+ * instead of compaction deleting the evidence before provenance validation.
+ */
+function coveredHistoryTailIds(tailEntries, document) {
+    return tailEntries.flatMap((entry) => {
+        try {
+            return updateMatchesDocumentHistory(document, base64ToBytes(entry.updateData))
+                ? [entry.id]
+                : [];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+//# sourceMappingURL=documentHistoryCompaction.js.map

package/stores/documents/documentStore/history/documentHistoryCompaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"documentHistoryCompaction.js","sourceRoot":"","sources":["documentHistoryCompaction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACnE,OAAO,EACL,mBAAmB,EACnB,yBAAyB,EACzB,4BAA4B,GAC7B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,qCAAqC,EACrC,oCAAoC,GACrC,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EACL,kCAAkC,EAClC,oCAAoC,IAAI,uBAAuB,GAChE,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,KAAyB,EACzB,UAAyB,EACzB,YAA0C;IAE1C,MAAM,EAAE,WAAW,EAAE,GAAG,KAAK,CAAC;IAC9B,sEAAsE;IACtE,uEAAuE;IACvE,0EAA0E;IAC1E,4BAA4B;IAC5B,MAAM,UAAU,GAAG,kCAAkC,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;IACzE,IAAI,CAAC,UAAU,IAAI,YAAY,EAAE,EAAE,KAAK,KAAK,EAAE,CAAC;QAC9C,OAAO;IACT,CAAC;IACD,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC;IAC5C,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IAC3E,IACE,IAAI,CAAC,aAAa;QAClB,IAAI,CAAC,QAAQ,GAAG,oCAAoC;QACpD,IAAI,CAAC,UAAU,GAAG,qCAAqC,EACvD,CAAC;QACD,OAAO;IACT,CAAC;IAED,0EAA0E;IAC1E,sEAAsE;IACtE,0EAA0E;IAC1E,wDAAwD;IACxD,MAAM,WAAW,GAAG,MAAM,WAAW,CAAC,sBAAsB,CAC1D,OAAO,EACP,KAAK,CAAC,OAAO,CACd,CAAC;IACF,MAAM,QAAQ,GAAG,yBAAyB,CAAC,UAAU,CAAC,CAAC;IACvD,IACE,CAAC,uBAAuB,CAAC,KAAK,EAAE,UAAU,CAAC;QAC3C,YAAY,EAAE,EAAE,KAAK,KAAK,EAC1B,CAAC;QACD,OAAO;IACT,CAAC;IACD,MAAM,gBAAgB,GAAG,mBAAmB,CAAC,UAAU,CAAC,CAAC;IACzD,MAAM,WAAW,CAAC,wBAAwB,CAAC,OAAO,EAAE;QAClD,cAAc,EAAE,qBAAqB,CAAC,WAAW,EAAE,UAAU,CAAC;QAC9D,gBAAgB;QAChB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,QAAQ,EAAE,aAAa,CAAC,QAAQ,CAAC;QACjC,YAAY,EAAE,GAAG,EAAE,CACjB,uBAAuB,CAAC,KAAK,EAAE,UAAU,CAAC,IAAI,YAAY,EAAE,EAAE,KAAK,KAAK;KAC3E,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,SAAS,qBAAqB,CAC5B,WAA0D,EAC1D,QAAuB;IAEvB,OAAO,WAAW,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE;QACnC,IAAI,CAAC;YACH,OAAO,4BAA4B,CACjC,QAAQ,EACR,aAAa,CAAC,KAAK,CAAC,UAAU,CAAC,CAChC;gBACC,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;gBACZ,CAAC,CAAC,EAAE,CAAC;QACT,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC","sourcesContent":["import { base64ToBytes, bytesToBase64 } from \"@tearleads/encoding\";\nimport {\n  encodeVersionVector,\n  exportFullHistorySnapshot,\n  updateMatchesDocumentHistory,\n} from \"@tearleads/loro\";\nimport {\n  DOCUMENT_HISTORY_COMPACTION_MAX_BYTES,\n  DOCUMENT_HISTORY_COMPACTION_MAX_ROWS,\n} from \"../../../../workflows/documents\";\nimport type { DocumentState, DocumentStoreState } from \"../state\";\nimport {\n  captureDocumentStoreSyncGeneration,\n  isDocumentStoreSyncGenerationCurrent as isSyncGenerationCurrent,\n} from \"../sync/syncGeneration\";\n\n/**\n * Refresh the durable full-history checkpoint when the tail has grown past\n * the compaction thresholds, or seed the first checkpoint as soon as the\n * document can export full history (a freshly created or rebuilt document is\n * cheap to export; waiting for the threshold would leave restarts without\n * history until then). The snapshot comes from the LIVE document, which has\n * every tail update imported, so clearing the tail loses nothing.\n */\nexport async function maybeCompactDocumentHistory(\n  state: DocumentStoreState,\n  currentDoc: DocumentState,\n  stillCurrent?: (() => boolean) | undefined,\n): Promise<void> {\n  const { persistence } = state;\n  // Bind this compaction to the store context it started under: a store\n  // reset or runtime swap mid-compaction must not let the OLD document's\n  // checkpoint overwrite the replacement generation's history (or land in a\n  // newly selected database).\n  const generation = captureDocumentStoreSyncGeneration(state, currentDoc);\n  if (!generation || stillCurrent?.() === false) {\n    return;\n  }\n  const execSql = state.runtime.infra.execSql;\n  const tail = await persistence.readHistoryTailSize(execSql, state.localId);\n  if (\n    tail.hasCheckpoint &&\n    tail.rowCount < DOCUMENT_HISTORY_COMPACTION_MAX_ROWS &&\n    tail.byteLength < DOCUMENT_HISTORY_COMPACTION_MAX_BYTES\n  ) {\n    return;\n  }\n\n  // Capture the tail BEFORE exporting, then prove coverage per row: another\n  // pane can append ops this pane's document has not merged, so blanket\n  // deletion would discard the only durable copy. Unproven rows survive for\n  // a later compaction by whichever pane holds their ops.\n  const tailEntries = await persistence.listHistoryTailEntries(\n    execSql,\n    state.localId,\n  );\n  const snapshot = exportFullHistorySnapshot(currentDoc);\n  if (\n    !isSyncGenerationCurrent(state, generation) ||\n    stillCurrent?.() === false\n  ) {\n    return;\n  }\n  const endVersionVector = encodeVersionVector(currentDoc);\n  await persistence.replaceHistoryCheckpoint(execSql, {\n    coveredTailIds: coveredHistoryTailIds(tailEntries, currentDoc),\n    endVersionVector,\n    localId: state.localId,\n    snapshot: bytesToBase64(snapshot),\n    stillCurrent: () =>\n      isSyncGenerationCurrent(state, generation) && stillCurrent?.() !== false,\n  });\n}\n\n/**\n * Tail rows whose exact operations already belong to the checkpoint document.\n * Version-vector dominance is insufficient: a same-frontier fork has the same\n * declared range, and malformed rows must survive so recovery fails closed\n * instead of compaction deleting the evidence before provenance validation.\n */\nfunction coveredHistoryTailIds(\n  tailEntries: readonly { id: string; updateData: string }[],\n  document: DocumentState,\n): string[] {\n  return tailEntries.flatMap((entry) => {\n    try {\n      return updateMatchesDocumentHistory(\n        document,\n        base64ToBytes(entry.updateData),\n      )\n        ? [entry.id]\n        : [];\n    } catch {\n      return [];\n    }\n  });\n}\n"]}

package/stores/documents/documentStore/history/durableDocumentReload.js

@@ -0,0 +1,79 @@
+import { base64ToBytes } from "../../../../internal/encoding/index.js";
+import { importSnapshot } from "../../../../internal/loro/index.js";
+import { importDocumentHistoryTailUpdates, runSerializedSqlMutation, } from "../../../../workflows/documents/index.js";
+import { markDocumentStoreRemoved, setReadySnapshot, } from "../state.js";
+import { createFreshPeerStoredDocument } from "../storedDocument.js";
+import { isDocumentStoreSyncGenerationCurrent, } from "../sync/syncGeneration.js";
+export function importDurableDocumentHistory(replacementDoc, history) {
+    if (history?.snapshot) {
+        importSnapshot(replacementDoc, base64ToBytes(history.snapshot));
+    }
+    if (history) {
+        importDocumentHistoryTailUpdates(replacementDoc, history.tailUpdates.map((update) => update.updateData));
+    }
+}
+export function installDurableDocumentReload(input) {
+    const { durableRecord, replacementDoc, state } = input;
+    const previousDocumentId = input.previousDocumentId === undefined
+        ? (state.record?.documentId ?? null)
+        : input.previousDocumentId;
+    const identityChanged = previousDocumentId !== durableRecord.documentId;
+    const preserveQueuedWrites = input.preserveQueuedWritesWhenIdentityMatches && !identityChanged;
+    if (!preserveQueuedWrites) {
+        state.localWriteGeneration += 1;
+        state.pendingLocalWrites = 0;
+    }
+    state.record = durableRecord;
+    state.pullContinuation = durableRecord.pullContinuation ?? null;
+    state.pendingBaseVersion =
+        durableRecord.pendingBaseVersion ??
+            (durableRecord.snapshotEndVersion.length > 0
+                ? durableRecord.snapshotEndVersion
+                : null);
+    state.doc = replacementDoc;
+    state.writerProjection = null;
+    if (identityChanged && input.registerIdentityChange !== false) {
+        state.effects.registerDocumentIdentity(state.runtime.state.domainScope, durableRecord.id, durableRecord.documentId);
+    }
+    const preserveOptimisticProjection = preserveQueuedWrites && state.pendingLocalWrites > 0;
+    setReadySnapshot(state, replacementDoc, state.snapshot.syncing, preserveOptimisticProjection ? state.snapshot.text : undefined, preserveOptimisticProjection ? state.snapshot.structuredFields : undefined);
+}
+export async function reloadDocumentFromDurableHistory(input) {
+    const { expectedGeneration, state } = input;
+    if (!isDocumentStoreSyncGenerationCurrent(state, expectedGeneration)) {
+        return false;
+    }
+    const replacementDoc = await createFreshPeerStoredDocument();
+    return runSerializedSqlMutation(state.runtime.infra.execSql, async (lockedExecSql) => {
+        if (!isDocumentStoreSyncGenerationCurrent(state, expectedGeneration)) {
+            return false;
+        }
+        const { document: durableRecord, historyRestoreState } = await state.persistence.loadDocumentWithHistoryRestoreState(lockedExecSql, state.localId);
+        if (!durableRecord) {
+            markDocumentStoreRemoved(state);
+            return false;
+        }
+        const canRestoreCapturedSnapshot = Boolean(input.sameIdentitySnapshot &&
+            (state.record?.documentId ?? null) === durableRecord.documentId);
+        if (canRestoreCapturedSnapshot && input.sameIdentitySnapshot) {
+            importSnapshot(replacementDoc, input.sameIdentitySnapshot);
+        }
+        // The captured snapshot removes the failed in-memory mutation, but it
+        // cannot replace the durable source of truth: another pane may have
+        // advanced history and the record frontier while attachment staging was
+        // in flight. Merge the latest checkpoint and tail in both paths before
+        // installing that record/frontier beside the rebuilt CRDT.
+        importDurableDocumentHistory(replacementDoc, historyRestoreState);
+        if (!isDocumentStoreSyncGenerationCurrent(state, expectedGeneration)) {
+            return false;
+        }
+        installDurableDocumentReload({
+            durableRecord,
+            preserveQueuedWritesWhenIdentityMatches: input.preserveQueuedWritesWhenIdentityMatches,
+            replacementDoc,
+            state,
+        });
+        return true;
+    });
+}
+//# sourceMappingURL=durableDocumentReload.js.map

package/stores/documents/documentStore/history/durableDocumentReload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"durableDocumentReload.js","sourceRoot":"","sources":["durableDocumentReload.ts"],"names":[],"mappings":"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","sourcesContent":["import { base64ToBytes } from \"@tearleads/encoding\";\nimport { importSnapshot } from \"@tearleads/loro\";\nimport {\n  importDocumentHistoryTailUpdates,\n  runSerializedSqlMutation,\n} from \"../../../../workflows/documents\";\nimport {\n  type DocumentState,\n  type DocumentStoreState,\n  markDocumentStoreRemoved,\n  setReadySnapshot,\n} from \"../state\";\nimport { createFreshPeerStoredDocument } from \"../storedDocument\";\nimport {\n  type DocumentStoreSyncGeneration,\n  isDocumentStoreSyncGenerationCurrent,\n} from \"../sync/syncGeneration\";\n\ntype DurableDocumentRecord = NonNullable<\n  Awaited<ReturnType<DocumentStoreState[\"persistence\"][\"loadDocument\"]>>\n>;\ntype DurableHistory = Awaited<\n  ReturnType<DocumentStoreState[\"persistence\"][\"loadHistoryRestoreState\"]>\n>;\n\nexport function importDurableDocumentHistory(\n  replacementDoc: DocumentState,\n  history: DurableHistory,\n): void {\n  if (history?.snapshot) {\n    importSnapshot(replacementDoc, base64ToBytes(history.snapshot));\n  }\n  if (history) {\n    importDocumentHistoryTailUpdates(\n      replacementDoc,\n      history.tailUpdates.map((update) => update.updateData),\n    );\n  }\n}\n\nexport function installDurableDocumentReload(input: {\n  durableRecord: DurableDocumentRecord;\n  previousDocumentId?: string | null | undefined;\n  preserveQueuedWritesWhenIdentityMatches: boolean;\n  registerIdentityChange?: boolean | undefined;\n  replacementDoc: DocumentState;\n  state: DocumentStoreState;\n}): void {\n  const { durableRecord, replacementDoc, state } = input;\n  const previousDocumentId =\n    input.previousDocumentId === undefined\n      ? (state.record?.documentId ?? null)\n      : input.previousDocumentId;\n  const identityChanged = previousDocumentId !== durableRecord.documentId;\n  const preserveQueuedWrites =\n    input.preserveQueuedWritesWhenIdentityMatches && !identityChanged;\n  if (!preserveQueuedWrites) {\n    state.localWriteGeneration += 1;\n    state.pendingLocalWrites = 0;\n  }\n  state.record = durableRecord;\n  state.pullContinuation = durableRecord.pullContinuation ?? null;\n  state.pendingBaseVersion =\n    durableRecord.pendingBaseVersion ??\n    (durableRecord.snapshotEndVersion.length > 0\n      ? durableRecord.snapshotEndVersion\n      : null);\n  state.doc = replacementDoc;\n  state.writerProjection = null;\n  if (identityChanged && input.registerIdentityChange !== false) {\n    state.effects.registerDocumentIdentity(\n      state.runtime.state.domainScope,\n      durableRecord.id,\n      durableRecord.documentId,\n    );\n  }\n  const preserveOptimisticProjection =\n    preserveQueuedWrites && state.pendingLocalWrites > 0;\n  setReadySnapshot(\n    state,\n    replacementDoc,\n    state.snapshot.syncing,\n    preserveOptimisticProjection ? state.snapshot.text : undefined,\n    preserveOptimisticProjection ? state.snapshot.structuredFields : undefined,\n  );\n}\n\nexport async function reloadDocumentFromDurableHistory(input: {\n  expectedGeneration: DocumentStoreSyncGeneration;\n  preserveQueuedWritesWhenIdentityMatches: boolean;\n  sameIdentitySnapshot?: Uint8Array | undefined;\n  state: DocumentStoreState;\n}): Promise<boolean> {\n  const { expectedGeneration, state } = input;\n  if (!isDocumentStoreSyncGenerationCurrent(state, expectedGeneration)) {\n    return false;\n  }\n\n  const replacementDoc = await createFreshPeerStoredDocument();\n  return runSerializedSqlMutation(\n    state.runtime.infra.execSql,\n    async (lockedExecSql) => {\n      if (!isDocumentStoreSyncGenerationCurrent(state, expectedGeneration)) {\n        return false;\n      }\n      const { document: durableRecord, historyRestoreState } =\n        await state.persistence.loadDocumentWithHistoryRestoreState(\n          lockedExecSql,\n          state.localId,\n        );\n      if (!durableRecord) {\n        markDocumentStoreRemoved(state);\n        return false;\n      }\n      const canRestoreCapturedSnapshot = Boolean(\n        input.sameIdentitySnapshot &&\n          (state.record?.documentId ?? null) === durableRecord.documentId,\n      );\n      if (canRestoreCapturedSnapshot && input.sameIdentitySnapshot) {\n        importSnapshot(replacementDoc, input.sameIdentitySnapshot);\n      }\n      // The captured snapshot removes the failed in-memory mutation, but it\n      // cannot replace the durable source of truth: another pane may have\n      // advanced history and the record frontier while attachment staging was\n      // in flight. Merge the latest checkpoint and tail in both paths before\n      // installing that record/frontier beside the rebuilt CRDT.\n      importDurableDocumentHistory(replacementDoc, historyRestoreState);\n      if (!isDocumentStoreSyncGenerationCurrent(state, expectedGeneration)) {\n        return false;\n      }\n\n      installDurableDocumentReload({\n        durableRecord,\n        preserveQueuedWritesWhenIdentityMatches:\n          input.preserveQueuedWritesWhenIdentityMatches,\n        replacementDoc,\n        state,\n      });\n      return true;\n    },\n  );\n}\n"]}

package/stores/documents/documentStore/history/historyRebuild.js

@@ -0,0 +1,75 @@
+import { bytesToBase64 } from "../../../../internal/encoding/index.js";
+import { encodeVersionVector, exportFullHistorySnapshot, } from "../../../../internal/loro/index.js";
+import { readPullContinuation } from "../../../../data/documents/shared/syncPagination.js";
+import { persistDocument } from "../persistence.js";
+import { isDocumentStoreSyncGenerationCurrent, } from "../sync/syncGeneration.js";
+import { installDocumentWriterProjection } from "../writerProjectionGeneration.js";
+/**
+ * Machinery for reconstructing a full-history document from a verified remote
+ * pull. Used by the rotation preflight (rotation.ts): it pulls the remote op
+ * log, replays it into a fresh document alongside the durable local queue,
+ * and installs the rebuilt document — preserving op identity end to end.
+ */
+export async function installRebuiltDocument(input) {
+    // The guarded persist makes the recovered history durable BEFORE publishing
+    // the newer record. Checkpoint-ahead is the safe crash direction: restore
+    // reads the checkpoint and the record catches up on the next persist.
+    const fullHistorySnapshot = exportFullHistorySnapshot(input.rebuiltDoc);
+    const rebuiltEndVersion = encodeVersionVector(input.rebuiltDoc);
+    const persisted = await persistDocument(input.state, input.rebuiltDoc, {
+        ...input.synced.persistedState,
+        lastCommitLsn: input.synced.response.commitLsn ??
+            input.currentRecord.lastCommitLsn ??
+            null,
+        pullContinuation: readPullContinuation(input.synced.response),
+        recoveryGeneration: (input.currentRecord.recoveryGeneration ?? 0) + 1,
+        // The guarded checkpoint below covers exactly this frontier.
+        snapshotEndVersion: rebuiltEndVersion,
+    }, {
+        acceptedPendingUpdateIds: input.synced.settledPendingUpdateIds,
+        expectedSyncState: {
+            pullContinuation: input.consumedPullContinuation,
+            record: input.currentRecord,
+        },
+        historyCheckpoint: {
+            coveredTailIds: [],
+            endVersionVector: rebuiltEndVersion,
+            pruneCoveredLocalState: true,
+            snapshot: bytesToBase64(fullHistorySnapshot),
+        },
+        pendingBaseVersionOverride: rebuiltEndVersion,
+        preserveSnapshotStructuredFields: input.state.pendingLocalWrites > 0,
+        preserveSnapshotText: input.state.pendingLocalWrites > 0,
+    }, input.generation);
+    if (!persisted) {
+        if (!isDocumentStoreSyncGenerationCurrent(input.state, input.generation)) {
+            throw new Error("Document changed during rotation recovery; retry key rotation");
+        }
+        // The resurrect guard refused: another subsystem deleted this document
+        // while the rebuild was in flight, and saveDocumentRecord cleared the
+        // zombie store — pendingBaseVersion included. Restoring the rebuilt doc,
+        // projection, or the captured base version here would resurrect state
+        // over that clearing.
+        throw new Error("Document was deleted while its history rebuild was in flight");
+    }
+    if (!persisted.pullContinuationSuperseded &&
+        !persisted.syncIdentitySuperseded) {
+        input.state.pendingBaseVersion = rebuiltEndVersion;
+        input.state.doc = input.rebuiltDoc;
+    }
+    if (persisted.pullContinuationSuperseded)
+        input.state.writerProjection = null;
+    else
+        installDocumentWriterProjection(input.state, input.synced.writerProjection ?? input.state.writerProjection, input.writerProjectionGeneration);
+    const installedDoc = input.state.doc ?? input.rebuiltDoc;
+    return {
+        fullHistorySnapshot: persisted.pullContinuationSuperseded
+            ? exportFullHistorySnapshot(installedDoc)
+            : fullHistorySnapshot,
+        settlementRequiresRetry: persisted.pullContinuationSuperseded === true ||
+            persisted.syncIdentitySuperseded === true ||
+            persisted.record.pullContinuation != null ||
+            persisted.record.pullContinuationRecoveryRequired === true,
+    };
+}
+//# sourceMappingURL=historyRebuild.js.map

package/stores/documents/documentStore/history/historyRebuild.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"historyRebuild.js","sourceRoot":"","sources":["historyRebuild.ts"],"names":[],"mappings":"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","sourcesContent":["import { bytesToBase64 } from \"@tearleads/encoding\";\nimport {\n  encodeVersionVector,\n  exportFullHistorySnapshot,\n} from \"@tearleads/loro\";\nimport { readPullContinuation } from \"../../../../data/documents/shared/syncPagination\";\nimport type {\n  DocumentSyncPullContinuation,\n  syncRemoteDocument,\n} from \"../../../../workflows/documents\";\nimport { persistDocument } from \"../persistence\";\nimport type { DocumentState, DocumentStoreState } from \"../state\";\nimport {\n  type DocumentStoreSyncGeneration,\n  isDocumentStoreSyncGenerationCurrent,\n} from \"../sync/syncGeneration\";\nimport { installDocumentWriterProjection } from \"../writerProjectionGeneration\";\n\n/**\n * Machinery for reconstructing a full-history document from a verified remote\n * pull. Used by the rotation preflight (rotation.ts): it pulls the remote op\n * log, replays it into a fresh document alongside the durable local queue,\n * and installs the rebuilt document — preserving op identity end to end.\n */\n\nexport async function installRebuiltDocument(input: {\n  consumedPullContinuation: DocumentSyncPullContinuation | null;\n  currentRecord: NonNullable<DocumentStoreState[\"record\"]>;\n  generation: DocumentStoreSyncGeneration;\n  rebuiltDoc: DocumentState;\n  state: DocumentStoreState;\n  synced: NonNullable<Awaited<ReturnType<typeof syncRemoteDocument>>>;\n  /** `state.writerProjectionGeneration` when the recovery pull started. */\n  writerProjectionGeneration: number;\n}): Promise<{\n  fullHistorySnapshot: Uint8Array;\n  settlementRequiresRetry: boolean;\n}> {\n  // The guarded persist makes the recovered history durable BEFORE publishing\n  // the newer record. Checkpoint-ahead is the safe crash direction: restore\n  // reads the checkpoint and the record catches up on the next persist.\n  const fullHistorySnapshot = exportFullHistorySnapshot(input.rebuiltDoc);\n  const rebuiltEndVersion = encodeVersionVector(input.rebuiltDoc);\n  const persisted = await persistDocument(\n    input.state,\n    input.rebuiltDoc,\n    {\n      ...input.synced.persistedState,\n      lastCommitLsn:\n        input.synced.response.commitLsn ??\n        input.currentRecord.lastCommitLsn ??\n        null,\n      pullContinuation: readPullContinuation(input.synced.response),\n      recoveryGeneration: (input.currentRecord.recoveryGeneration ?? 0) + 1,\n      // The guarded checkpoint below covers exactly this frontier.\n      snapshotEndVersion: rebuiltEndVersion,\n    },\n    {\n      acceptedPendingUpdateIds: input.synced.settledPendingUpdateIds,\n      expectedSyncState: {\n        pullContinuation: input.consumedPullContinuation,\n        record: input.currentRecord,\n      },\n      historyCheckpoint: {\n        coveredTailIds: [],\n        endVersionVector: rebuiltEndVersion,\n        pruneCoveredLocalState: true,\n        snapshot: bytesToBase64(fullHistorySnapshot),\n      },\n      pendingBaseVersionOverride: rebuiltEndVersion,\n      preserveSnapshotStructuredFields: input.state.pendingLocalWrites > 0,\n      preserveSnapshotText: input.state.pendingLocalWrites > 0,\n    },\n    input.generation,\n  );\n  if (!persisted) {\n    if (!isDocumentStoreSyncGenerationCurrent(input.state, input.generation)) {\n      throw new Error(\n        \"Document changed during rotation recovery; retry key rotation\",\n      );\n    }\n    // The resurrect guard refused: another subsystem deleted this document\n    // while the rebuild was in flight, and saveDocumentRecord cleared the\n    // zombie store — pendingBaseVersion included. Restoring the rebuilt doc,\n    // projection, or the captured base version here would resurrect state\n    // over that clearing.\n    throw new Error(\n      \"Document was deleted while its history rebuild was in flight\",\n    );\n  }\n  if (\n    !persisted.pullContinuationSuperseded &&\n    !persisted.syncIdentitySuperseded\n  ) {\n    input.state.pendingBaseVersion = rebuiltEndVersion;\n    input.state.doc = input.rebuiltDoc;\n  }\n  if (persisted.pullContinuationSuperseded) input.state.writerProjection = null;\n  else\n    installDocumentWriterProjection(\n      input.state,\n      input.synced.writerProjection ?? input.state.writerProjection,\n      input.writerProjectionGeneration,\n    );\n  const installedDoc = input.state.doc ?? input.rebuiltDoc;\n  return {\n    fullHistorySnapshot: persisted.pullContinuationSuperseded\n      ? exportFullHistorySnapshot(installedDoc)\n      : fullHistorySnapshot,\n    settlementRequiresRetry:\n      persisted.pullContinuationSuperseded === true ||\n      persisted.syncIdentitySuperseded === true ||\n      persisted.record.pullContinuation != null ||\n      persisted.record.pullContinuationRecoveryRequired === true,\n  };\n}\n"]}

package/stores/documents/documentStore/index.d.ts

@@ -0,0 +1,8 @@
+import type { StoredDocumentKind } from "../../../data/documents/documentKinds.js";
+import type { DomainScope } from "../../../data/shared/domainScope.js";
+import { type DocumentsPersistence } from "../../../workflows/documents/index.js";
+import type { DocumentStore, DocumentStoreFacade, DocumentStoreOpenOptions, DocumentsRuntime } from "../types.js";
+export { discardRegisteredDocumentLocalState, requestDomainDocumentSync, subscribeToPersistedDocuments, } from "../registry.js";
+export declare function createDocumentStore(localId: string, initialRuntime: DocumentsRuntime, persistence?: DocumentsPersistence, initialDocumentId?: string | null, initialText?: string, initialDocumentKind?: StoredDocumentKind, options?: DocumentStoreOpenOptions): DocumentStoreFacade;
+export declare function getOrCreateDocumentStore(domainScope: DomainScope, localId: string, runtime: DocumentsRuntime, initialDocumentId?: string | null, initialText?: string, initialDocumentKind?: StoredDocumentKind, options?: DocumentStoreOpenOptions): DocumentStore;
+export declare function openDocumentStore(domainScope: DomainScope, localId: string, runtime: DocumentsRuntime, initialDocumentId?: string | null, initialText?: string, initialDocumentKind?: StoredDocumentKind, options?: DocumentStoreOpenOptions): DocumentStore;