@tearleads/client-sdk 0.0.0-stage → 0.1.13

package/stores/documents/documentStore/syncRemoteSignals.js

@@ -0,0 +1,67 @@
+import { isContainerProjectionInvalidationHint, isDocumentUpdateCreatedEvent, } from "../../../data/documents/documentSync.js";
+import { sequenceUnchanged } from "../../../workflows/documents/syncLane.js";
+import { resumeAfterAncestorRepairHint } from "./ancestorRepairPark.js";
+import { allowDocumentStoreRemoteSync, markDocumentStoreRemoteSyncPending, } from "./syncGeneration.js";
+import { invalidateDocumentWriterProjection } from "./writerProjectionGeneration.js";
+export function hasRemoteDocumentUpdateEvent(state, events) {
+    let remoteUpdateFound = false;
+    for (const event of events) {
+        if (!isDocumentUpdateCreatedEvent(event) ||
+            event.documentId !== state.record?.documentId) {
+            continue;
+        }
+        if (event.updateIds && event.updateIds.length > 0) {
+            for (const updateId of event.updateIds) {
+                if (!state.locallyAcceptedUpdateIds.has(updateId)) {
+                    remoteUpdateFound = true;
+                    continue;
+                }
+                state.locallyAcceptedUpdateIds.delete(updateId);
+            }
+            continue;
+        }
+        remoteUpdateFound = true;
+    }
+    return remoteUpdateFound;
+}
+/** Clear the remote-update signal only when its consumed sequence is unchanged.
+ * A moved sequence means a newer remote event arrived mid-pass and must survive
+ * for the coalesced re-run to avoid the convergence-stall race.
+ */
+export const canClearRemoteUpdateSignalAfterSync = sequenceUnchanged;
+export function clearConsumedRemoteUpdateSignal(state, consumedSignalSequence) {
+    // A peer event can arrive while the HTTP request is in flight. Clear only
+    // the sequence this pass consumed so the newer event survives for a re-run.
+    if (canClearRemoteUpdateSignalAfterSync(state.remoteUpdateSignalSeq, consumedSignalSequence)) {
+        state.remoteUpdateCompletedSignalSeq = consumedSignalSequence;
+        state.remoteUpdatePending = false;
+    }
+}
+export function handleDocumentRemoteEvents(state, scheduleSync) {
+    const nextEvents = state.runtime.state.events.slice(state.lastEventCount);
+    state.lastEventCount = state.runtime.state.events.length;
+    // A container the document's path cites may have moved its manifest; the
+    // store cannot tell which containers this document links into, so the held
+    // projection goes and the next mutation fetches a fresh one. This runs even
+    // before the document has a remote id: a create in flight captured the
+    // generation when it started and must not install its pre-hint projection.
+    const projectionInvalidated = nextEvents.some(isContainerProjectionInvalidationHint);
+    if (projectionInvalidated)
+        invalidateDocumentWriterProjection(state);
+    if (!state.record?.documentId)
+        return;
+    // Writes parked behind an ancestor another member must re-key: this hint is
+    // the only signal that the repair may have landed. It names no ancestor, so
+    // any one re-runs the pass, which parks again if the path is still stale.
+    if (projectionInvalidated && resumeAfterAncestorRepairHint(state)) {
+        scheduleSync();
+    }
+    if (hasRemoteDocumentUpdateEvent(state, nextEvents)) {
+        allowDocumentStoreRemoteSync(state);
+        // Let an in-flight pass distinguish this new signal from the one it
+        // consumed before its network request.
+        markDocumentStoreRemoteSyncPending(state, "independent");
+        scheduleSync();
+    }
+}
+//# sourceMappingURL=syncRemoteSignals.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"syncRemoteSignals.js","sourceRoot":"","sources":["syncRemoteSignals.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qCAAqC,EACrC,4BAA4B,GAC7B,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAC1E,OAAO,EAAE,6BAA6B,EAAE,MAAM,sBAAsB,CAAC;AAErE,OAAO,EACL,4BAA4B,EAC5B,kCAAkC,GACnC,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,kCAAkC,EAAE,MAAM,8BAA8B,CAAC;AAElF,MAAM,UAAU,4BAA4B,CAC1C,KAAyB,EACzB,MAA8B;IAE9B,IAAI,iBAAiB,GAAG,KAAK,CAAC;IAE9B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IACE,CAAC,4BAA4B,CAAC,KAAK,CAAC;YACpC,KAAK,CAAC,UAAU,KAAK,KAAK,CAAC,MAAM,EAAE,UAAU,EAC7C,CAAC;YACD,SAAS;QACX,CAAC;QAED,IAAI,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAClD,KAAK,MAAM,QAAQ,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;gBACvC,IAAI,CAAC,KAAK,CAAC,wBAAwB,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;oBAClD,iBAAiB,GAAG,IAAI,CAAC;oBACzB,SAAS;gBACX,CAAC;gBAED,KAAK,CAAC,wBAAwB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAClD,CAAC;YACD,SAAS;QACX,CAAC;QAED,iBAAiB,GAAG,IAAI,CAAC;IAC3B,CAAC;IAED,OAAO,iBAAiB,CAAC;AAC3B,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAAG,iBAAiB,CAAC;AAErE,MAAM,UAAU,+BAA+B,CAC7C,KAAyB,EACzB,sBAA8B;IAE9B,0EAA0E;IAC1E,4EAA4E;IAC5E,IACE,mCAAmC,CACjC,KAAK,CAAC,qBAAqB,EAC3B,sBAAsB,CACvB,EACD,CAAC;QACD,KAAK,CAAC,8BAA8B,GAAG,sBAAsB,CAAC;QAC9D,KAAK,CAAC,mBAAmB,GAAG,KAAK,CAAC;IACpC,CAAC;AACH,CAAC;AAED,MAAM,UAAU,0BAA0B,CACxC,KAAyB,EACzB,YAAwB;IAExB,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;IAC1E,KAAK,CAAC,cAAc,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;IAEzD,yEAAyE;IACzE,2EAA2E;IAC3E,4EAA4E;IAC5E,uEAAuE;IACvE,2EAA2E;IAC3E,MAAM,qBAAqB,GAAG,UAAU,CAAC,IAAI,CAC3C,qCAAqC,CACtC,CAAC;IACF,IAAI,qBAAqB;QAAE,kCAAkC,CAAC,KAAK,CAAC,CAAC;IAErE,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,UAAU;QAAE,OAAO;IAEtC,4EAA4E;IAC5E,4EAA4E;IAC5E,0EAA0E;IAC1E,IAAI,qBAAqB,IAAI,6BAA6B,CAAC,KAAK,CAAC,EAAE,CAAC;QAClE,YAAY,EAAE,CAAC;IACjB,CAAC;IAED,IAAI,4BAA4B,CAAC,KAAK,EAAE,UAAU,CAAC,EAAE,CAAC;QACpD,4BAA4B,CAAC,KAAK,CAAC,CAAC;QACpC,oEAAoE;QACpE,uCAAuC;QACvC,kCAAkC,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;QACzD,YAAY,EAAE,CAAC;IACjB,CAAC;AACH,CAAC","sourcesContent":["import {\n  isContainerProjectionInvalidationHint,\n  isDocumentUpdateCreatedEvent,\n} from \"../../../data/documents/documentSync\";\nimport { sequenceUnchanged } from \"../../../workflows/documents/syncLane\";\nimport { resumeAfterAncestorRepairHint } from \"./ancestorRepairPark\";\nimport type { DocumentStoreState } from \"./state\";\nimport {\n  allowDocumentStoreRemoteSync,\n  markDocumentStoreRemoteSyncPending,\n} from \"./syncGeneration\";\nimport { invalidateDocumentWriterProjection } from \"./writerProjectionGeneration\";\n\nexport function hasRemoteDocumentUpdateEvent(\n  state: DocumentStoreState,\n  events: ReadonlyArray<unknown>,\n): boolean {\n  let remoteUpdateFound = false;\n\n  for (const event of events) {\n    if (\n      !isDocumentUpdateCreatedEvent(event) ||\n      event.documentId !== state.record?.documentId\n    ) {\n      continue;\n    }\n\n    if (event.updateIds && event.updateIds.length > 0) {\n      for (const updateId of event.updateIds) {\n        if (!state.locallyAcceptedUpdateIds.has(updateId)) {\n          remoteUpdateFound = true;\n          continue;\n        }\n\n        state.locallyAcceptedUpdateIds.delete(updateId);\n      }\n      continue;\n    }\n\n    remoteUpdateFound = true;\n  }\n\n  return remoteUpdateFound;\n}\n\n/** Clear the remote-update signal only when its consumed sequence is unchanged.\n * A moved sequence means a newer remote event arrived mid-pass and must survive\n * for the coalesced re-run to avoid the convergence-stall race.\n */\nexport const canClearRemoteUpdateSignalAfterSync = sequenceUnchanged;\n\nexport function clearConsumedRemoteUpdateSignal(\n  state: DocumentStoreState,\n  consumedSignalSequence: number,\n): void {\n  // A peer event can arrive while the HTTP request is in flight. Clear only\n  // the sequence this pass consumed so the newer event survives for a re-run.\n  if (\n    canClearRemoteUpdateSignalAfterSync(\n      state.remoteUpdateSignalSeq,\n      consumedSignalSequence,\n    )\n  ) {\n    state.remoteUpdateCompletedSignalSeq = consumedSignalSequence;\n    state.remoteUpdatePending = false;\n  }\n}\n\nexport function handleDocumentRemoteEvents(\n  state: DocumentStoreState,\n  scheduleSync: () => void,\n): void {\n  const nextEvents = state.runtime.state.events.slice(state.lastEventCount);\n  state.lastEventCount = state.runtime.state.events.length;\n\n  // A container the document's path cites may have moved its manifest; the\n  // store cannot tell which containers this document links into, so the held\n  // projection goes and the next mutation fetches a fresh one. This runs even\n  // before the document has a remote id: a create in flight captured the\n  // generation when it started and must not install its pre-hint projection.\n  const projectionInvalidated = nextEvents.some(\n    isContainerProjectionInvalidationHint,\n  );\n  if (projectionInvalidated) invalidateDocumentWriterProjection(state);\n\n  if (!state.record?.documentId) return;\n\n  // Writes parked behind an ancestor another member must re-key: this hint is\n  // the only signal that the repair may have landed. It names no ancestor, so\n  // any one re-runs the pass, which parks again if the path is still stale.\n  if (projectionInvalidated && resumeAfterAncestorRepairHint(state)) {\n    scheduleSync();\n  }\n\n  if (hasRemoteDocumentUpdateEvent(state, nextEvents)) {\n    allowDocumentStoreRemoteSync(state);\n    // Let an in-flight pass distinguish this new signal from the one it\n    // consumed before its network request.\n    markDocumentStoreRemoteSyncPending(state, \"independent\");\n    scheduleSync();\n  }\n}\n"]}

package/stores/documents/documentStore/syncRequest.js

@@ -0,0 +1,158 @@
+import { encodeVersionVector, exportFullHistorySnapshot, } from "../../../internal/loro/index.js";
+import { createDocumentWriterPublicKeyResolver, defaultDocumentsPersistence, deletePersistedDocument, reclaimDocumentOrphanBlobs, resolveDocumentCreateAuthor, syncRemoteDocument, validateDocumentSyncUpdateImports, } from "../../../workflows/documents/index.js";
+import { createRuntimePrincipalPolicyWarmer } from "../../../workflows/principals/runtimePolicyWarmer.js";
+import { requestDocumentStoreSync } from "../registry.js";
+import { parkForAncestorRepair } from "./ancestorRepairPark.js";
+import { chainIdentityWrite } from "./identityWriteChain.js";
+import { invalidateDocumentStorePullContinuation } from "./pullContinuationInvalidation.js";
+import { markDocumentStoreRemoved, } from "./state.js";
+import { isDocumentStoreSyncGenerationCurrent, } from "./syncGeneration.js";
+import { documentIncomingUpdateIsolationFailureHandler, documentRevalidationFailureHandler, documentTerminalSubmitFailureHandler, } from "./syncShared.js";
+import { documentSyncContextMatches } from "./syncUpdateImport.js";
+/**
+ * Destroying queued local edits here is settled policy, not an oversight
+ * (docs/sync-edge-cases.md row 1): deletion is a privacy operation, so an
+ * authoritative remote delete removes the document and its unsynced edits
+ * everywhere with no preservation copy. Quarantine/export were rejected —
+ * they retain or re-upload content the user deliberately destroyed.
+ */
+export async function deleteUpstreamDeletedDocument(state, generation, requestRecord, remoteDocumentId, commitPurgeProof) {
+    await chainIdentityWrite(state, async () => {
+        if (!isDocumentStoreSyncGenerationCurrent(state, generation) ||
+            !documentSyncContextMatches(state.record, requestRecord, remoteDocumentId)) {
+            return;
+        }
+        const canDeleteCapturedDocument = () => isDocumentStoreSyncGenerationCurrent(state, generation) &&
+            documentSyncContextMatches(state.record, requestRecord, remoteDocumentId);
+        let removedInMutation = false;
+        const deletionStarted = await deletePersistedDocument({
+            beforeDeleteInTransaction: commitPurgeProof,
+            canStartDurableMutation: canDeleteCapturedDocument,
+            documentProjectors: state.runtime.infra.documentProjectors,
+            execSql: generation.execSql,
+            expectedRecord: requestRecord,
+            localId: requestRecord.id,
+            // Invalidate the store generation INSIDE the deletion mutation: a
+            // terminal failure handler queued behind it then observes the stale
+            // generation and cannot resurrect a failure row the deletes removed.
+            onDeletedInMutation: () => {
+                if (canDeleteCapturedDocument()) {
+                    markDocumentStoreRemoved(state);
+                    removedInMutation = true;
+                }
+            },
+            persistence: state.persistence,
+        });
+        if (!deletionStarted || !removedInMutation) {
+            return;
+        }
+        if (state.persistence === defaultDocumentsPersistence) {
+            void reclaimDocumentOrphanBlobs(state.runtime);
+        }
+        state.runtime.util.log(`Documents: removed local document ${state.localId} after remote deletion.`);
+    });
+}
+function createDocumentSyncAttempt(input) {
+    return {
+        consumedPullContinuation: input.synced.plan.request.pullCursor === undefined
+            ? null
+            : input.requestedPullContinuation,
+        outgoingUpdateCount: input.outgoingUpdateCount,
+        requestRecord: input.currentRecord,
+        synced: input.synced,
+        writerProjectionGeneration: input.writerProjectionGeneration,
+    };
+}
+function runRemoteDocumentSync(input, author, documentId, requestedPullContinuation) {
+    const { currentDoc, currentRecord, generation, pendingUpdates, state } = input;
+    const runtime = state.runtime;
+    const writerProjectionGenerationAtStart = state.writerProjectionGeneration;
+    state.awaitingAncestorRepair = false;
+    return syncRemoteDocument({
+        apiClient: runtime.apiClient,
+        author,
+        // Heal a stale content-key bundle from this full-history snapshot. Rotation
+        // settlement disables this: it may submit only the ordinary local stream.
+        ...(input.allowRecoveryBaseline === false
+            ? {}
+            : {
+                buildRotationSnapshot: async () => exportFullHistorySnapshot(currentDoc),
+            }),
+        documentId,
+        execSql: runtime.infra.execSql,
+        isRemoteSyncBlocked: runtime.util.isRemoteSyncBlocked,
+        localVersionVector: encodeVersionVector(currentDoc),
+        minLsn: currentRecord.lastCommitLsn ?? undefined,
+        onRemoteDocumentDeleted: ({ commitPurgeProof, documentId }) => deleteUpstreamDeletedDocument(state, generation, currentRecord, documentId, commitPurgeProof),
+        onSyncAbandoned: (reason) => {
+            if (!isDocumentStoreSyncGenerationCurrent(state, generation))
+                return;
+            const hintLandedMidPass = parkForAncestorRepair(state, reason, writerProjectionGenerationAtStart);
+            if (hintLandedMidPass)
+                requestDocumentStoreSync(state);
+        },
+        onSyncTrace: (line) => runtime.util.log(`Documents: ${line}`),
+        onReadOnlyProjectionFailure: documentRevalidationFailureHandler(state, generation),
+        onIncomingUpdateIsolationFailure: documentIncomingUpdateIsolationFailureHandler(state, generation),
+        onOutgoingUpdatesMaterialized: input.onOutgoingUpdatesMaterialized,
+        onPullContinuationInvalidated: (continuation) => invalidateDocumentStorePullContinuation({
+            continuation,
+            currentRecord,
+            generation,
+            state,
+        }),
+        onTerminalSubmitFailure: documentTerminalSubmitFailureHandler(state, generation),
+        pendingUpdates,
+        persistedState: currentRecord,
+        pullContinuation: requestedPullContinuation ?? undefined,
+        rekeyPendingUpdate: state.persistence.rekeyPendingUpdate,
+        resolveProjectionUserKey: state.resolveProjectionUserKey,
+        resolveWriterPublicKey: createDocumentWriterPublicKeyResolver({
+            logPrefix: "Documents",
+            runtime,
+            writerKeyLabel: "writer key",
+        }),
+        stillCurrent: () => isDocumentStoreSyncGenerationCurrent(state, generation),
+        targetSecretKey: input.encapsulationKeyPair.secretKey,
+        validateIncomingUpdates: (result) => validateDocumentSyncUpdateImports({
+            currentDocument: currentDoc,
+            decryptedUpdates: result.decryptedUpdates,
+            responseUpdates: result.response.updates,
+        }),
+        warmReferencedPrincipalPolicies: createRuntimePrincipalPolicyWarmer(runtime),
+        writerProjection: state.writerProjection?.documentId === currentRecord.documentId
+            ? state.writerProjection
+            : undefined,
+    });
+}
+export async function requestRemoteDocumentSync(input) {
+    const { currentRecord, generation, pendingUpdates, state, unavailableWriterLogMessage, } = input;
+    if (!isDocumentStoreSyncGenerationCurrent(state, generation))
+        return null;
+    // Captured before the network round trip: a hint that lands meanwhile
+    // must keep the response's projection out of the cache.
+    const writerProjectionGeneration = state.writerProjectionGeneration;
+    const runtime = state.runtime;
+    if (!currentRecord.documentId)
+        return null;
+    const requestedPullContinuation = state.pullContinuation;
+    const author = resolveDocumentCreateAuthor(runtime);
+    if (!author) {
+        runtime.util.log(unavailableWriterLogMessage);
+        return null;
+    }
+    const synced = await runRemoteDocumentSync(input, author, currentRecord.documentId, requestedPullContinuation);
+    if (!isDocumentStoreSyncGenerationCurrent(state, generation))
+        return null;
+    if (!synced)
+        return null;
+    const outgoingUpdateCount = input.queuedUpdateCount ?? pendingUpdates.length;
+    return createDocumentSyncAttempt({
+        currentRecord,
+        outgoingUpdateCount,
+        requestedPullContinuation,
+        synced,
+        writerProjectionGeneration,
+    });
+}
+//# sourceMappingURL=syncRequest.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"syncRequest.js","sourceRoot":"","sources":["syncRequest.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,qCAAqC,EAErC,2BAA2B,EAC3B,uBAAuB,EAGvB,0BAA0B,EAC1B,2BAA2B,EAC3B,kBAAkB,EAClB,iCAAiC,GAClC,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,kCAAkC,EAAE,MAAM,mDAAmD,CAAC;AACvG,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,uCAAuC,EAAE,MAAM,gCAAgC,CAAC;AACzF,OAAO,EAKL,wBAAwB,GACzB,MAAM,SAAS,CAAC;AACjB,OAAO,EAEL,oCAAoC,GACrC,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,6CAA6C,EAC7C,kCAAkC,EAClC,oCAAoC,GACrC,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAEhE;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,6BAA6B,CACjD,KAAyB,EACzB,UAAuC,EACvC,aAA6B,EAC7B,gBAAwB,EACxB,gBAAiE;IAEjE,MAAM,kBAAkB,CAAC,KAAK,EAAE,KAAK,IAAI,EAAE;QACzC,IACE,CAAC,oCAAoC,CAAC,KAAK,EAAE,UAAU,CAAC;YACxD,CAAC,0BAA0B,CAAC,KAAK,CAAC,MAAM,EAAE,aAAa,EAAE,gBAAgB,CAAC,EAC1E,CAAC;YACD,OAAO;QACT,CAAC;QAED,MAAM,yBAAyB,GAAG,GAAG,EAAE,CACrC,oCAAoC,CAAC,KAAK,EAAE,UAAU,CAAC;YACvD,0BAA0B,CAAC,KAAK,CAAC,MAAM,EAAE,aAAa,EAAE,gBAAgB,CAAC,CAAC;QAC5E,IAAI,iBAAiB,GAAG,KAAK,CAAC;QAC9B,MAAM,eAAe,GAAG,MAAM,uBAAuB,CAAC;YACpD,yBAAyB,EAAE,gBAAgB;YAC3C,uBAAuB,EAAE,yBAAyB;YAClD,kBAAkB,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,kBAAkB;YAC1D,OAAO,EAAE,UAAU,CAAC,OAAO;YAC3B,cAAc,EAAE,aAAa;YAC7B,OAAO,EAAE,aAAa,CAAC,EAAE;YACzB,kEAAkE;YAClE,oEAAoE;YACpE,qEAAqE;YACrE,mBAAmB,EAAE,GAAG,EAAE;gBACxB,IAAI,yBAAyB,EAAE,EAAE,CAAC;oBAChC,wBAAwB,CAAC,KAAK,CAAC,CAAC;oBAChC,iBAAiB,GAAG,IAAI,CAAC;gBAC3B,CAAC;YACH,CAAC;YACD,WAAW,EAAE,KAAK,CAAC,WAAW;SAC/B,CAAC,CAAC;QACH,IAAI,CAAC,eAAe,IAAI,CAAC,iBAAiB,EAAE,CAAC;YAC3C,OAAO;QACT,CAAC;QACD,IAAI,KAAK,CAAC,WAAW,KAAK,2BAA2B,EAAE,CAAC;YACtD,KAAK,0BAA0B,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACjD,CAAC;QACD,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CACpB,qCAAqC,KAAK,CAAC,OAAO,yBAAyB,CAC5E,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,yBAAyB,CAAC,KAMlC;IACC,OAAO;QACL,wBAAwB,EACtB,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,KAAK,SAAS;YAChD,CAAC,CAAC,IAAI;YACN,CAAC,CAAC,KAAK,CAAC,yBAAyB;QACrC,mBAAmB,EAAE,KAAK,CAAC,mBAAmB;QAC9C,aAAa,EAAE,KAAK,CAAC,aAAa;QAClC,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,0BAA0B,EAAE,KAAK,CAAC,0BAA0B;KAC7D,CAAC;AACJ,CAAC;AAiBD,SAAS,qBAAqB,CAC5B,KAAqC,EACrC,MAAmE,EACnE,UAAkB,EAClB,yBAAiE;IAEjE,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,cAAc,EAAE,KAAK,EAAE,GACpE,KAAK,CAAC;IACR,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC9B,MAAM,iCAAiC,GAAG,KAAK,CAAC,0BAA0B,CAAC;IAC3E,KAAK,CAAC,sBAAsB,GAAG,KAAK,CAAC;IACrC,OAAO,kBAAkB,CAAC;QACxB,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,MAAM;QACN,4EAA4E;QAC5E,0EAA0E;QAC1E,GAAG,CAAC,KAAK,CAAC,qBAAqB,KAAK,KAAK;YACvC,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC;gBACE,qBAAqB,EAAE,KAAK,IAAI,EAAE,CAChC,yBAAyB,CAAC,UAAU,CAAC;aACxC,CAAC;QACN,UAAU;QACV,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,OAAO;QAC9B,mBAAmB,EAAE,OAAO,CAAC,IAAI,CAAC,mBAAmB;QACrD,kBAAkB,EAAE,mBAAmB,CAAC,UAAU,CAAC;QACnD,MAAM,EAAE,aAAa,CAAC,aAAa,IAAI,SAAS;QAChD,uBAAuB,EAAE,CAAC,EAAE,gBAAgB,EAAE,UAAU,EAAE,EAAE,EAAE,CAC5D,6BAA6B,CAC3B,KAAK,EACL,UAAU,EACV,aAAa,EACb,UAAU,EACV,gBAAgB,CACjB;QACH,eAAe,EAAE,CAAC,MAAM,EAAE,EAAE;YAC1B,IAAI,CAAC,oCAAoC,CAAC,KAAK,EAAE,UAAU,CAAC;gBAAE,OAAO;YACrE,MAAM,iBAAiB,GAAG,qBAAqB,CAC7C,KAAK,EACL,MAAM,EACN,iCAAiC,CAClC,CAAC;YACF,IAAI,iBAAiB;gBAAE,wBAAwB,CAAC,KAAK,CAAC,CAAC;QACzD,CAAC;QACD,WAAW,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,cAAc,IAAI,EAAE,CAAC;QAC7D,2BAA2B,EAAE,kCAAkC,CAC7D,KAAK,EACL,UAAU,CACX;QACD,gCAAgC,EAC9B,6CAA6C,CAAC,KAAK,EAAE,UAAU,CAAC;QAClE,6BAA6B,EAAE,KAAK,CAAC,6BAA6B;QAClE,6BAA6B,EAAE,CAAC,YAAY,EAAE,EAAE,CAC9C,uCAAuC,CAAC;YACtC,YAAY;YACZ,aAAa;YACb,UAAU;YACV,KAAK;SACN,CAAC;QACJ,uBAAuB,EAAE,oCAAoC,CAC3D,KAAK,EACL,UAAU,CACX;QACD,cAAc;QACd,cAAc,EAAE,aAAa;QAC7B,gBAAgB,EAAE,yBAAyB,IAAI,SAAS;QACxD,kBAAkB,EAAE,KAAK,CAAC,WAAW,CAAC,kBAAkB;QACxD,wBAAwB,EAAE,KAAK,CAAC,wBAAwB;QACxD,sBAAsB,EAAE,qCAAqC,CAAC;YAC5D,SAAS,EAAE,WAAW;YACtB,OAAO;YACP,cAAc,EAAE,YAAY;SAC7B,CAAC;QACF,YAAY,EAAE,GAAG,EAAE,CAAC,oCAAoC,CAAC,KAAK,EAAE,UAAU,CAAC;QAC3E,eAAe,EAAE,KAAK,CAAC,oBAAoB,CAAC,SAAS;QACrD,uBAAuB,EAAE,CAAC,MAAM,EAAE,EAAE,CAClC,iCAAiC,CAAC;YAChC,eAAe,EAAE,UAAU;YAC3B,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;YACzC,eAAe,EAAE,MAAM,CAAC,QAAQ,CAAC,OAAO;SACzC,CAAC;QACJ,+BAA+B,EAC7B,kCAAkC,CAAC,OAAO,CAAC;QAC7C,gBAAgB,EACd,KAAK,CAAC,gBAAgB,EAAE,UAAU,KAAK,aAAa,CAAC,UAAU;YAC7D,CAAC,CAAC,KAAK,CAAC,gBAAgB;YACxB,CAAC,CAAC,SAAS;KAChB,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,KAAqC;IAErC,MAAM,EACJ,aAAa,EACb,UAAU,EACV,cAAc,EACd,KAAK,EACL,2BAA2B,GAC5B,GAAG,KAAK,CAAC;IACV,IAAI,CAAC,oCAAoC,CAAC,KAAK,EAAE,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1E,sEAAsE;IACtE,wDAAwD;IACxD,MAAM,0BAA0B,GAAG,KAAK,CAAC,0BAA0B,CAAC;IAEpE,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC9B,IAAI,CAAC,aAAa,CAAC,UAAU;QAAE,OAAO,IAAI,CAAC;IAE3C,MAAM,yBAAyB,GAAG,KAAK,CAAC,gBAAgB,CAAC;IAEzD,MAAM,MAAM,GAAG,2BAA2B,CAAC,OAAO,CAAC,CAAC;IACpD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;QAC9C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,qBAAqB,CACxC,KAAK,EACL,MAAM,EACN,aAAa,CAAC,UAAU,EACxB,yBAAyB,CAC1B,CAAC;IACF,IAAI,CAAC,oCAAoC,CAAC,KAAK,EAAE,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1E,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IAEzB,MAAM,mBAAmB,GAAG,KAAK,CAAC,iBAAiB,IAAI,cAAc,CAAC,MAAM,CAAC;IAC7E,OAAO,yBAAyB,CAAC;QAC/B,aAAa;QACb,mBAAmB;QACnB,yBAAyB;QACzB,MAAM;QACN,0BAA0B;KAC3B,CAAC,CAAC;AACL,CAAC","sourcesContent":["import {\n  encodeVersionVector,\n  exportFullHistorySnapshot,\n} from \"@tearleads/loro\";\nimport {\n  createDocumentWriterPublicKeyResolver,\n  type DocumentRecord,\n  defaultDocumentsPersistence,\n  deletePersistedDocument,\n  type ExecSql,\n  type PendingUpdateRecord,\n  reclaimDocumentOrphanBlobs,\n  resolveDocumentCreateAuthor,\n  syncRemoteDocument,\n  validateDocumentSyncUpdateImports,\n} from \"../../../workflows/documents\";\nimport { createRuntimePrincipalPolicyWarmer } from \"../../../workflows/principals/runtimePolicyWarmer\";\nimport { requestDocumentStoreSync } from \"../registry\";\nimport { parkForAncestorRepair } from \"./ancestorRepairPark\";\nimport { chainIdentityWrite } from \"./identityWriteChain\";\nimport { invalidateDocumentStorePullContinuation } from \"./pullContinuationInvalidation\";\nimport {\n  type DocumentState,\n  type DocumentStoreState,\n  type DocumentSyncAttempt,\n  type EncapsulationKeyPair,\n  markDocumentStoreRemoved,\n} from \"./state\";\nimport {\n  type DocumentStoreSyncGeneration,\n  isDocumentStoreSyncGenerationCurrent,\n} from \"./syncGeneration\";\nimport {\n  documentIncomingUpdateIsolationFailureHandler,\n  documentRevalidationFailureHandler,\n  documentTerminalSubmitFailureHandler,\n} from \"./syncShared\";\nimport { documentSyncContextMatches } from \"./syncUpdateImport\";\n\n/**\n * Destroying queued local edits here is settled policy, not an oversight\n * (docs/sync-edge-cases.md row 1): deletion is a privacy operation, so an\n * authoritative remote delete removes the document and its unsynced edits\n * everywhere with no preservation copy. Quarantine/export were rejected —\n * they retain or re-upload content the user deliberately destroyed.\n */\nexport async function deleteUpstreamDeletedDocument(\n  state: DocumentStoreState,\n  generation: DocumentStoreSyncGeneration,\n  requestRecord: DocumentRecord,\n  remoteDocumentId: string,\n  commitPurgeProof?: (transactionExecSql: ExecSql) => Promise<void>,\n) {\n  await chainIdentityWrite(state, async () => {\n    if (\n      !isDocumentStoreSyncGenerationCurrent(state, generation) ||\n      !documentSyncContextMatches(state.record, requestRecord, remoteDocumentId)\n    ) {\n      return;\n    }\n\n    const canDeleteCapturedDocument = () =>\n      isDocumentStoreSyncGenerationCurrent(state, generation) &&\n      documentSyncContextMatches(state.record, requestRecord, remoteDocumentId);\n    let removedInMutation = false;\n    const deletionStarted = await deletePersistedDocument({\n      beforeDeleteInTransaction: commitPurgeProof,\n      canStartDurableMutation: canDeleteCapturedDocument,\n      documentProjectors: state.runtime.infra.documentProjectors,\n      execSql: generation.execSql,\n      expectedRecord: requestRecord,\n      localId: requestRecord.id,\n      // Invalidate the store generation INSIDE the deletion mutation: a\n      // terminal failure handler queued behind it then observes the stale\n      // generation and cannot resurrect a failure row the deletes removed.\n      onDeletedInMutation: () => {\n        if (canDeleteCapturedDocument()) {\n          markDocumentStoreRemoved(state);\n          removedInMutation = true;\n        }\n      },\n      persistence: state.persistence,\n    });\n    if (!deletionStarted || !removedInMutation) {\n      return;\n    }\n    if (state.persistence === defaultDocumentsPersistence) {\n      void reclaimDocumentOrphanBlobs(state.runtime);\n    }\n    state.runtime.util.log(\n      `Documents: removed local document ${state.localId} after remote deletion.`,\n    );\n  });\n}\n\nfunction createDocumentSyncAttempt(input: {\n  currentRecord: DocumentRecord;\n  outgoingUpdateCount: number;\n  requestedPullContinuation: DocumentStoreState[\"pullContinuation\"];\n  synced: DocumentSyncAttempt[\"synced\"];\n  writerProjectionGeneration: number;\n}): DocumentSyncAttempt {\n  return {\n    consumedPullContinuation:\n      input.synced.plan.request.pullCursor === undefined\n        ? null\n        : input.requestedPullContinuation,\n    outgoingUpdateCount: input.outgoingUpdateCount,\n    requestRecord: input.currentRecord,\n    synced: input.synced,\n    writerProjectionGeneration: input.writerProjectionGeneration,\n  };\n}\n\ninterface RequestRemoteDocumentSyncInput {\n  allowRecoveryBaseline?: boolean | undefined;\n  currentDoc: DocumentState;\n  currentRecord: DocumentRecord;\n  encapsulationKeyPair: EncapsulationKeyPair;\n  generation: DocumentStoreSyncGeneration;\n  onOutgoingUpdatesMaterialized?:\n    | ((updateIds: readonly string[]) => void)\n    | undefined;\n  pendingUpdates: PendingUpdateRecord[];\n  queuedUpdateCount?: number | undefined;\n  state: DocumentStoreState;\n  unavailableWriterLogMessage: string;\n}\n\nfunction runRemoteDocumentSync(\n  input: RequestRemoteDocumentSyncInput,\n  author: NonNullable<ReturnType<typeof resolveDocumentCreateAuthor>>,\n  documentId: string,\n  requestedPullContinuation: DocumentStoreState[\"pullContinuation\"],\n) {\n  const { currentDoc, currentRecord, generation, pendingUpdates, state } =\n    input;\n  const runtime = state.runtime;\n  const writerProjectionGenerationAtStart = state.writerProjectionGeneration;\n  state.awaitingAncestorRepair = false;\n  return syncRemoteDocument({\n    apiClient: runtime.apiClient,\n    author,\n    // Heal a stale content-key bundle from this full-history snapshot. Rotation\n    // settlement disables this: it may submit only the ordinary local stream.\n    ...(input.allowRecoveryBaseline === false\n      ? {}\n      : {\n          buildRotationSnapshot: async () =>\n            exportFullHistorySnapshot(currentDoc),\n        }),\n    documentId,\n    execSql: runtime.infra.execSql,\n    isRemoteSyncBlocked: runtime.util.isRemoteSyncBlocked,\n    localVersionVector: encodeVersionVector(currentDoc),\n    minLsn: currentRecord.lastCommitLsn ?? undefined,\n    onRemoteDocumentDeleted: ({ commitPurgeProof, documentId }) =>\n      deleteUpstreamDeletedDocument(\n        state,\n        generation,\n        currentRecord,\n        documentId,\n        commitPurgeProof,\n      ),\n    onSyncAbandoned: (reason) => {\n      if (!isDocumentStoreSyncGenerationCurrent(state, generation)) return;\n      const hintLandedMidPass = parkForAncestorRepair(\n        state,\n        reason,\n        writerProjectionGenerationAtStart,\n      );\n      if (hintLandedMidPass) requestDocumentStoreSync(state);\n    },\n    onSyncTrace: (line) => runtime.util.log(`Documents: ${line}`),\n    onReadOnlyProjectionFailure: documentRevalidationFailureHandler(\n      state,\n      generation,\n    ),\n    onIncomingUpdateIsolationFailure:\n      documentIncomingUpdateIsolationFailureHandler(state, generation),\n    onOutgoingUpdatesMaterialized: input.onOutgoingUpdatesMaterialized,\n    onPullContinuationInvalidated: (continuation) =>\n      invalidateDocumentStorePullContinuation({\n        continuation,\n        currentRecord,\n        generation,\n        state,\n      }),\n    onTerminalSubmitFailure: documentTerminalSubmitFailureHandler(\n      state,\n      generation,\n    ),\n    pendingUpdates,\n    persistedState: currentRecord,\n    pullContinuation: requestedPullContinuation ?? undefined,\n    rekeyPendingUpdate: state.persistence.rekeyPendingUpdate,\n    resolveProjectionUserKey: state.resolveProjectionUserKey,\n    resolveWriterPublicKey: createDocumentWriterPublicKeyResolver({\n      logPrefix: \"Documents\",\n      runtime,\n      writerKeyLabel: \"writer key\",\n    }),\n    stillCurrent: () => isDocumentStoreSyncGenerationCurrent(state, generation),\n    targetSecretKey: input.encapsulationKeyPair.secretKey,\n    validateIncomingUpdates: (result) =>\n      validateDocumentSyncUpdateImports({\n        currentDocument: currentDoc,\n        decryptedUpdates: result.decryptedUpdates,\n        responseUpdates: result.response.updates,\n      }),\n    warmReferencedPrincipalPolicies:\n      createRuntimePrincipalPolicyWarmer(runtime),\n    writerProjection:\n      state.writerProjection?.documentId === currentRecord.documentId\n        ? state.writerProjection\n        : undefined,\n  });\n}\n\nexport async function requestRemoteDocumentSync(\n  input: RequestRemoteDocumentSyncInput,\n): Promise<DocumentSyncAttempt | null> {\n  const {\n    currentRecord,\n    generation,\n    pendingUpdates,\n    state,\n    unavailableWriterLogMessage,\n  } = input;\n  if (!isDocumentStoreSyncGenerationCurrent(state, generation)) return null;\n  // Captured before the network round trip: a hint that lands meanwhile\n  // must keep the response's projection out of the cache.\n  const writerProjectionGeneration = state.writerProjectionGeneration;\n\n  const runtime = state.runtime;\n  if (!currentRecord.documentId) return null;\n\n  const requestedPullContinuation = state.pullContinuation;\n\n  const author = resolveDocumentCreateAuthor(runtime);\n  if (!author) {\n    runtime.util.log(unavailableWriterLogMessage);\n    return null;\n  }\n\n  const synced = await runRemoteDocumentSync(\n    input,\n    author,\n    currentRecord.documentId,\n    requestedPullContinuation,\n  );\n  if (!isDocumentStoreSyncGenerationCurrent(state, generation)) return null;\n  if (!synced) return null;\n\n  const outgoingUpdateCount = input.queuedUpdateCount ?? pendingUpdates.length;\n  return createDocumentSyncAttempt({\n    currentRecord,\n    outgoingUpdateCount,\n    requestedPullContinuation,\n    synced,\n    writerProjectionGeneration,\n  });\n}\n"]}

package/stores/documents/documentStore/syncShared.js

@@ -0,0 +1,211 @@
+import { deriveStableDocumentId } from "../../../data/documents/shared/stableDocumentId.js";
+import { createRemoteDocument, DOCUMENTS_APP_KIND, describeDocumentRevalidationFailure, describeDocumentSyncSubmitFailure, recordDocumentSyncFailure, resolveDocumentCreateAuthor, runSerializedSqlMutation, } from "../../../workflows/documents/index.js";
+import { reportDocumentSyncQuarantine } from "../../../workflows/documents/reportDocumentSyncQuarantine.js";
+import { createRuntimePrincipalPolicyWarmer } from "../../../workflows/principals/runtimePolicyWarmer.js";
+import { chainIdentityWrite } from "./identityWriteChain.js";
+import { persistDocument } from "./persistence.js";
+import { markDocumentStoreRemoved, } from "./state.js";
+import { isDocumentStoreSyncGenerationCurrent, } from "./syncGeneration.js";
+import { installDocumentWriterProjection } from "./writerProjectionGeneration.js";
+/**
+ * Record a refused read-only revalidation on this document's failure row, so
+ * a document that can never refresh stops failing silently (edge-case row
+ * 13). 403s stay suppressed on purpose — a read-only 403 must never flag
+ * unattempted local edits (row 9) — and the row clears on the next clean
+ * pass like every other sync failure.
+ */
+export function documentRevalidationFailureHandler(state, generation) {
+    return documentSyncFailureHandler({
+        describeFailure: describeDocumentRevalidationFailure,
+        generation,
+        state,
+        suppressForbidden: true,
+    });
+}
+/**
+ * Record a terminal submit failure on this document's write-queue row. Shared
+ * by every store pass that can submit queued writes (create and sync), so
+ * re-key exhaustion and denial failures surface no matter which pass hits
+ * them first.
+ */
+export function documentTerminalSubmitFailureHandler(state, generation) {
+    return documentSyncFailureHandler({
+        describeFailure: describeDocumentSyncSubmitFailure,
+        generation,
+        state,
+    });
+}
+/** Persist quarantine and report its Error through the host's diagnostics. */
+export function documentIncomingUpdateIsolationFailureHandler(state, generation) {
+    const recordFailure = documentSyncFailureHandler({
+        describeFailure: (failure) => failure.message,
+        generation,
+        state,
+    });
+    return async (failure) => {
+        await recordFailure({ message: failure.message, status: null });
+        if (generation && !isDocumentStoreSyncGenerationCurrent(state, generation))
+            return;
+        reportDocumentSyncQuarantine(generation?.currentDoc ?? state.doc ?? state, state.runtime.util.logError, failure);
+    };
+}
+/**
+ * The generation recheck runs INSIDE the serialized mutation (like the
+ * attachment failure path): a teardown (discard/reset) that wins the ordering
+ * deletes this document's rows first and invalidates the generation, so a
+ * stale handler can never resurrect a deleted or orphan failure row
+ * afterwards.
+ */
+function documentSyncFailureHandler(input) {
+    const { generation, state } = input;
+    return async (failure) => {
+        if (input.suppressForbidden && failure.status === 403) {
+            return;
+        }
+        await runSerializedSqlMutation(generation?.execSql ?? state.runtime.infra.execSql, async (lockedExecSql) => {
+            if (generation &&
+                !isDocumentStoreSyncGenerationCurrent(state, generation)) {
+                return;
+            }
+            await recordDocumentSyncFailure(lockedExecSql, { appKind: DOCUMENTS_APP_KIND, localId: state.localId }, {
+                attemptedAt: new Date().toISOString(),
+                message: input.describeFailure(failure),
+                status: failure.status,
+            });
+        });
+    };
+}
+function hasPersistedRemoteDocumentSyncState(record) {
+    return (record.lastCommitLsn !== null &&
+        record.contentKeyBundle !== null &&
+        record.documentKekTargets !== null &&
+        record.documentManifestBundle !== null);
+}
+export function shouldSkipCleanScheduledDocumentSync(input) {
+    return (input.pendingUpdates.length === 0 &&
+        input.state.pendingAttachments.length === 0 &&
+        input.state.pullContinuation === null &&
+        !input.currentRecord.pullContinuationRecoveryRequired &&
+        !input.state.remoteUpdatePending &&
+        hasPersistedRemoteDocumentSyncState(input.currentRecord));
+}
+/**
+ * True when the store's container exists locally but has not been created on
+ * the server yet (its own create intent is still pending). Creating a document
+ * inside it would 404 on the container writer projection and surface a
+ * spurious sync error; the container-contents lane re-arms document sync once
+ * the container lands. An unknown or unqueryable container resolves false so
+ * store-level consumers without container persistence keep creating eagerly.
+ */
+export async function isContainerAwaitingRemoteCreate(state) {
+    const containerId = state.runtime.state.containerId;
+    if (!containerId) {
+        return false;
+    }
+    try {
+        const rows = await state.runtime.infra.execSql("SELECT server_created_at FROM containers WHERE id = :containerId", { ":containerId": containerId });
+        const row = rows[0];
+        return row !== undefined && Reflect.get(row, "server_created_at") == null;
+    }
+    catch {
+        return false;
+    }
+}
+async function hasDurableDocumentForCreate(state, isCurrent) {
+    // A bulk import can leave this store queued long after trash purged its
+    // durable row. The persistence guard runs too late to prevent an orphaned
+    // remote create, so check existence before beginning the network work.
+    const record = await state.persistence.loadDocument(state.runtime.infra.execSql, state.localId);
+    if (!isCurrent())
+        return false;
+    if (record)
+        return true;
+    markDocumentStoreRemoved(state);
+    return false;
+}
+export async function ensureRemoteDocument(state, currentDoc, nextRecord, encapsulationKeyPair, generation) {
+    const generationIsCurrent = () => !generation || isDocumentStoreSyncGenerationCurrent(state, generation);
+    if (!generationIsCurrent())
+        return state.record ?? nextRecord;
+    if (nextRecord?.documentId) {
+        return nextRecord;
+    }
+    const runtime = state.runtime;
+    if (!runtime.state.containerId) {
+        runtime.util.log("Documents: cannot create a remote document without a container.");
+        // A local-only document with no container scope (e.g. a last-link orphan
+        // from a tombstone cascade, docs/sync-edge-cases.md row 3) can never
+        // create; record the stuck state durably so the write queue surfaces it
+        // instead of this lane going silent on every trigger.
+        await documentTerminalSubmitFailureHandler(state, generation)({
+            message: "Local document has no container for its remote create",
+            status: null,
+        });
+        return nextRecord;
+    }
+    const author = resolveDocumentCreateAuthor(runtime);
+    if (!author) {
+        runtime.util.log("Documents: skipped remote create because the writer context is unavailable.");
+        return nextRecord;
+    }
+    const documentId = nextRecord?.recoveryDocumentId ??
+        (await deriveStableDocumentId(state.localId));
+    if (!generationIsCurrent())
+        return state.record ?? nextRecord;
+    if (!(await hasDurableDocumentForCreate(state, generationIsCurrent)))
+        return state.record;
+    const writerProjectionGeneration = state.writerProjectionGeneration;
+    const created = await createRemoteDocument({
+        apiClient: runtime.apiClient,
+        author,
+        containerId: runtime.state.containerId,
+        // Derive the remote id from the stable local id so a retry after a lost
+        // create response re-sends the same id and adopts the existing remote
+        // document instead of creating a duplicate.
+        documentId,
+        execSql: runtime.infra.execSql,
+        isRemoteSyncBlocked: runtime.util.isRemoteSyncBlocked,
+        onTerminalSubmitFailure: documentTerminalSubmitFailureHandler(state, generation),
+        resolveProjectionUserKey: state.resolveProjectionUserKey,
+        stillCurrent: generationIsCurrent,
+        targetSecretKey: encapsulationKeyPair.secretKey,
+        warmReferencedPrincipalPolicies: createRuntimePrincipalPolicyWarmer(runtime),
+    });
+    if (!generationIsCurrent())
+        return state.record ?? nextRecord;
+    if (!created) {
+        return nextRecord;
+    }
+    return chainIdentityWrite(state, async () => {
+        if (!generationIsCurrent())
+            return state.record ?? nextRecord;
+        // A concurrent relink (e.g. live duplicate-facade resolution) may have
+        // assigned this store a different remote identity while the create round
+        // trip was in flight. That identity wins: persisting the created one here
+        // would clobber the relink. The just-created remote document is left an
+        // orphan, the same benign outcome as a lost create response.
+        const liveDocumentId = state.record?.documentId;
+        if (liveDocumentId && liveDocumentId !== created.documentId) {
+            return state.record;
+        }
+        runtime.util.log(`Created document: ${created.documentId}`);
+        installDocumentWriterProjection(state, created.writerProjection, writerProjectionGeneration);
+        // This persist is a remote-identity write (documentId + content keys), not a
+        // content change. It runs after a network round trip, during which the user
+        // may have kept typing into a brand-new note. The Loro doc is mutated
+        // asynchronously on the write chain, so it can lag the optimistic snapshot;
+        // re-deriving text/structured fields from the doc here would republish that
+        // stale read over the live editor value and drop the just-typed characters
+        // (the new-note "type immediately" race). Preserve the optimistic snapshot —
+        // documentId/keys still propagate via state.record, independent of the
+        // snapshot text — matching finalizeDocumentSync and the keystroke writes.
+        const persistPatch = { ...created.persistedState };
+        const persistOptions = {
+            preserveSnapshotStructuredFields: true,
+            preserveSnapshotText: true,
+        };
+        const persisted = await persistDocument(state, currentDoc, persistPatch, persistOptions, generation);
+        return persisted?.record ?? state.record ?? nextRecord;
+    });
+}
+//# sourceMappingURL=syncShared.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"syncShared.js","sourceRoot":"","sources":["syncShared.ts"],"names":[],"mappings":"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","sourcesContent":["import { deriveStableDocumentId } from \"../../../data/documents/shared/stableDocumentId\";\nimport {\n  createRemoteDocument,\n  DOCUMENTS_APP_KIND,\n  type DocumentRecord,\n  type DocumentSyncUpdateIsolationError,\n  describeDocumentRevalidationFailure,\n  describeDocumentSyncSubmitFailure,\n  type PendingUpdateRecord,\n  recordDocumentSyncFailure,\n  resolveDocumentCreateAuthor,\n  runSerializedSqlMutation,\n} from \"../../../workflows/documents\";\nimport { reportDocumentSyncQuarantine } from \"../../../workflows/documents/reportDocumentSyncQuarantine\";\nimport { createRuntimePrincipalPolicyWarmer } from \"../../../workflows/principals/runtimePolicyWarmer\";\nimport { chainIdentityWrite } from \"./identityWriteChain\";\nimport { persistDocument } from \"./persistence\";\nimport {\n  type DocumentState,\n  type DocumentStoreState,\n  type EncapsulationKeyPair,\n  markDocumentStoreRemoved,\n} from \"./state\";\nimport {\n  type DocumentStoreSyncGeneration,\n  isDocumentStoreSyncGenerationCurrent,\n} from \"./syncGeneration\";\nimport { installDocumentWriterProjection } from \"./writerProjectionGeneration\";\n\n/**\n * Record a refused read-only revalidation on this document's failure row, so\n * a document that can never refresh stops failing silently (edge-case row\n * 13). 403s stay suppressed on purpose — a read-only 403 must never flag\n * unattempted local edits (row 9) — and the row clears on the next clean\n * pass like every other sync failure.\n */\nexport function documentRevalidationFailureHandler(\n  state: DocumentStoreState,\n  generation?: DocumentStoreSyncGeneration,\n) {\n  return documentSyncFailureHandler({\n    describeFailure: describeDocumentRevalidationFailure,\n    generation,\n    state,\n    suppressForbidden: true,\n  });\n}\n\n/**\n * Record a terminal submit failure on this document's write-queue row. Shared\n * by every store pass that can submit queued writes (create and sync), so\n * re-key exhaustion and denial failures surface no matter which pass hits\n * them first.\n */\nexport function documentTerminalSubmitFailureHandler(\n  state: DocumentStoreState,\n  generation?: DocumentStoreSyncGeneration,\n) {\n  return documentSyncFailureHandler({\n    describeFailure: describeDocumentSyncSubmitFailure,\n    generation,\n    state,\n  });\n}\n\n/** Persist quarantine and report its Error through the host's diagnostics. */\nexport function documentIncomingUpdateIsolationFailureHandler(\n  state: DocumentStoreState,\n  generation?: DocumentStoreSyncGeneration,\n) {\n  const recordFailure = documentSyncFailureHandler({\n    describeFailure: (failure) => failure.message,\n    generation,\n    state,\n  });\n  return async (failure: DocumentSyncUpdateIsolationError) => {\n    await recordFailure({ message: failure.message, status: null });\n    if (generation && !isDocumentStoreSyncGenerationCurrent(state, generation))\n      return;\n    reportDocumentSyncQuarantine(\n      generation?.currentDoc ?? state.doc ?? state,\n      state.runtime.util.logError,\n      failure,\n    );\n  };\n}\n\n/**\n * The generation recheck runs INSIDE the serialized mutation (like the\n * attachment failure path): a teardown (discard/reset) that wins the ordering\n * deletes this document's rows first and invalidates the generation, so a\n * stale handler can never resurrect a deleted or orphan failure row\n * afterwards.\n */\nfunction documentSyncFailureHandler(input: {\n  describeFailure: (failure: {\n    readonly message: string;\n    readonly status: number | null;\n  }) => string;\n  generation: DocumentStoreSyncGeneration | undefined;\n  state: DocumentStoreState;\n  suppressForbidden?: boolean;\n}) {\n  const { generation, state } = input;\n  return async (failure: {\n    readonly message: string;\n    readonly status: number | null;\n  }) => {\n    if (input.suppressForbidden && failure.status === 403) {\n      return;\n    }\n\n    await runSerializedSqlMutation(\n      generation?.execSql ?? state.runtime.infra.execSql,\n      async (lockedExecSql) => {\n        if (\n          generation &&\n          !isDocumentStoreSyncGenerationCurrent(state, generation)\n        ) {\n          return;\n        }\n        await recordDocumentSyncFailure(\n          lockedExecSql,\n          { appKind: DOCUMENTS_APP_KIND, localId: state.localId },\n          {\n            attemptedAt: new Date().toISOString(),\n            message: input.describeFailure(failure),\n            status: failure.status,\n          },\n        );\n      },\n    );\n  };\n}\n\nfunction hasPersistedRemoteDocumentSyncState(record: DocumentRecord): boolean {\n  return (\n    record.lastCommitLsn !== null &&\n    record.contentKeyBundle !== null &&\n    record.documentKekTargets !== null &&\n    record.documentManifestBundle !== null\n  );\n}\n\nexport function shouldSkipCleanScheduledDocumentSync(input: {\n  currentRecord: DocumentRecord;\n  pendingUpdates: readonly PendingUpdateRecord[];\n  state: DocumentStoreState;\n}): boolean {\n  return (\n    input.pendingUpdates.length === 0 &&\n    input.state.pendingAttachments.length === 0 &&\n    input.state.pullContinuation === null &&\n    !input.currentRecord.pullContinuationRecoveryRequired &&\n    !input.state.remoteUpdatePending &&\n    hasPersistedRemoteDocumentSyncState(input.currentRecord)\n  );\n}\n\n/**\n * True when the store's container exists locally but has not been created on\n * the server yet (its own create intent is still pending). Creating a document\n * inside it would 404 on the container writer projection and surface a\n * spurious sync error; the container-contents lane re-arms document sync once\n * the container lands. An unknown or unqueryable container resolves false so\n * store-level consumers without container persistence keep creating eagerly.\n */\nexport async function isContainerAwaitingRemoteCreate(\n  state: DocumentStoreState,\n): Promise<boolean> {\n  const containerId = state.runtime.state.containerId;\n  if (!containerId) {\n    return false;\n  }\n\n  try {\n    const rows = await state.runtime.infra.execSql(\n      \"SELECT server_created_at FROM containers WHERE id = :containerId\",\n      { \":containerId\": containerId },\n    );\n    const row = rows[0];\n    return row !== undefined && Reflect.get(row, \"server_created_at\") == null;\n  } catch {\n    return false;\n  }\n}\n\nasync function hasDurableDocumentForCreate(\n  state: DocumentStoreState,\n  isCurrent: () => boolean,\n): Promise<boolean> {\n  // A bulk import can leave this store queued long after trash purged its\n  // durable row. The persistence guard runs too late to prevent an orphaned\n  // remote create, so check existence before beginning the network work.\n  const record = await state.persistence.loadDocument(\n    state.runtime.infra.execSql,\n    state.localId,\n  );\n  if (!isCurrent()) return false;\n  if (record) return true;\n  markDocumentStoreRemoved(state);\n  return false;\n}\n\nexport async function ensureRemoteDocument(\n  state: DocumentStoreState,\n  currentDoc: DocumentState,\n  nextRecord: DocumentRecord | null,\n  encapsulationKeyPair: EncapsulationKeyPair,\n  generation?: DocumentStoreSyncGeneration,\n): Promise<DocumentRecord | null> {\n  const generationIsCurrent = () =>\n    !generation || isDocumentStoreSyncGenerationCurrent(state, generation);\n  if (!generationIsCurrent()) return state.record ?? nextRecord;\n\n  if (nextRecord?.documentId) {\n    return nextRecord;\n  }\n\n  const runtime = state.runtime;\n  if (!runtime.state.containerId) {\n    runtime.util.log(\n      \"Documents: cannot create a remote document without a container.\",\n    );\n    // A local-only document with no container scope (e.g. a last-link orphan\n    // from a tombstone cascade, docs/sync-edge-cases.md row 3) can never\n    // create; record the stuck state durably so the write queue surfaces it\n    // instead of this lane going silent on every trigger.\n    await documentTerminalSubmitFailureHandler(\n      state,\n      generation,\n    )({\n      message: \"Local document has no container for its remote create\",\n      status: null,\n    });\n    return nextRecord;\n  }\n\n  const author = resolveDocumentCreateAuthor(runtime);\n  if (!author) {\n    runtime.util.log(\n      \"Documents: skipped remote create because the writer context is unavailable.\",\n    );\n    return nextRecord;\n  }\n\n  const documentId =\n    nextRecord?.recoveryDocumentId ??\n    (await deriveStableDocumentId(state.localId));\n  if (!generationIsCurrent()) return state.record ?? nextRecord;\n\n  if (!(await hasDurableDocumentForCreate(state, generationIsCurrent)))\n    return state.record;\n\n  const writerProjectionGeneration = state.writerProjectionGeneration;\n  const created = await createRemoteDocument({\n    apiClient: runtime.apiClient,\n    author,\n    containerId: runtime.state.containerId,\n    // Derive the remote id from the stable local id so a retry after a lost\n    // create response re-sends the same id and adopts the existing remote\n    // document instead of creating a duplicate.\n    documentId,\n    execSql: runtime.infra.execSql,\n    isRemoteSyncBlocked: runtime.util.isRemoteSyncBlocked,\n    onTerminalSubmitFailure: documentTerminalSubmitFailureHandler(\n      state,\n      generation,\n    ),\n    resolveProjectionUserKey: state.resolveProjectionUserKey,\n    stillCurrent: generationIsCurrent,\n    targetSecretKey: encapsulationKeyPair.secretKey,\n    warmReferencedPrincipalPolicies:\n      createRuntimePrincipalPolicyWarmer(runtime),\n  });\n  if (!generationIsCurrent()) return state.record ?? nextRecord;\n  if (!created) {\n    return nextRecord;\n  }\n\n  return chainIdentityWrite(state, async () => {\n    if (!generationIsCurrent()) return state.record ?? nextRecord;\n\n    // A concurrent relink (e.g. live duplicate-facade resolution) may have\n    // assigned this store a different remote identity while the create round\n    // trip was in flight. That identity wins: persisting the created one here\n    // would clobber the relink. The just-created remote document is left an\n    // orphan, the same benign outcome as a lost create response.\n    const liveDocumentId = state.record?.documentId;\n    if (liveDocumentId && liveDocumentId !== created.documentId) {\n      return state.record;\n    }\n\n    runtime.util.log(`Created document: ${created.documentId}`);\n    installDocumentWriterProjection(\n      state,\n      created.writerProjection,\n      writerProjectionGeneration,\n    );\n\n    // This persist is a remote-identity write (documentId + content keys), not a\n    // content change. It runs after a network round trip, during which the user\n    // may have kept typing into a brand-new note. The Loro doc is mutated\n    // asynchronously on the write chain, so it can lag the optimistic snapshot;\n    // re-deriving text/structured fields from the doc here would republish that\n    // stale read over the live editor value and drop the just-typed characters\n    // (the new-note \"type immediately\" race). Preserve the optimistic snapshot —\n    // documentId/keys still propagate via state.record, independent of the\n    // snapshot text — matching finalizeDocumentSync and the keystroke writes.\n    const persistPatch = { ...created.persistedState };\n    const persistOptions = {\n      preserveSnapshotStructuredFields: true,\n      preserveSnapshotText: true,\n    };\n    const persisted = await persistDocument(\n      state,\n      currentDoc,\n      persistPatch,\n      persistOptions,\n      generation,\n    );\n    return persisted?.record ?? state.record ?? nextRecord;\n  });\n}\n"]}

package/stores/documents/documentStore/syncUpdateImport.js

@@ -0,0 +1,62 @@
+import { encodeVersionVector } from "../../../internal/loro/index.js";
+import { importDecryptedDocumentSyncUpdates } from "../../../data/documents/shared/documentSyncUpdateIsolation.js";
+import { setReadySnapshot, } from "./state.js";
+import { isDocumentStoreSyncGenerationCurrent, } from "./syncGeneration.js";
+import { extendDocumentVersionCoverage } from "./versionCoverage.js";
+function sameNullableValue(left, right) {
+    return (left ?? null) === (right ?? null);
+}
+/**
+ * A response may mutate document content only while the identity and access
+ * context used to create its request are still live. Local content fields and
+ * the pending marker are deliberately excluded because edits may advance them
+ * while the request is in flight.
+ */
+export function documentSyncContextMatches(liveRecord, requestRecord, responseDocumentId) {
+    return (liveRecord !== null &&
+        liveRecord.id === requestRecord.id &&
+        liveRecord.documentId === requestRecord.documentId &&
+        liveRecord.documentId === responseDocumentId &&
+        liveRecord.containerId === requestRecord.containerId &&
+        liveRecord.accessEpoch === requestRecord.accessEpoch &&
+        sameNullableValue(liveRecord.accessStateHash, requestRecord.accessStateHash) &&
+        (liveRecord.effectiveAccessLevel ?? null) ===
+            (requestRecord.effectiveAccessLevel ?? null) &&
+        sameNullableValue(liveRecord.contentKeyBundle, requestRecord.contentKeyBundle) &&
+        sameNullableValue(liveRecord.documentKekTargets, requestRecord.documentKekTargets) &&
+        sameNullableValue(liveRecord.documentManifestBundle, requestRecord.documentManifestBundle));
+}
+export function importSyncedDocumentUpdates(currentDoc, updates) {
+    importDecryptedDocumentSyncUpdates(currentDoc, updates);
+    return currentDoc;
+}
+export function applyIncomingSyncedUpdates(state, currentDoc, requestRecord, syncAttempt, expectedGeneration) {
+    if ((expectedGeneration &&
+        !isDocumentStoreSyncGenerationCurrent(state, expectedGeneration)) ||
+        !documentSyncContextMatches(state.record, requestRecord, syncAttempt.synced.plan.documentId)) {
+        return currentDoc;
+    }
+    const updates = syncAttempt.synced.decryptedUpdates;
+    if (updates.length === 0)
+        return currentDoc;
+    const mergedDoc = importSyncedDocumentUpdates(currentDoc, updates);
+    const baseVersion = state.pendingBaseVersion;
+    if (baseVersion === null) {
+        throw new Error("Document sync requires an initialized pending base");
+    }
+    // Promote only through update spans proven to be remote. Advancing to the
+    // whole merged document would also cross a concurrent deferRemoteSync edit
+    // and could permanently classify that local-only operation as synced.
+    state.pendingBaseVersion = extendDocumentVersionCoverage({
+        baseVersion,
+        documentVersion: encodeVersionVector(mergedDoc),
+        spans: updates,
+    });
+    if (state.pendingLocalWrites > 0) {
+        setReadySnapshot(state, mergedDoc, true, state.snapshot.text, state.snapshot.structuredFields);
+        return mergedDoc;
+    }
+    setReadySnapshot(state, mergedDoc, true);
+    return mergedDoc;
+}
+//# sourceMappingURL=syncUpdateImport.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"syncUpdateImport.js","sourceRoot":"","sources":["syncUpdateImport.ts"],"names":[],"mappings":"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","sourcesContent":["import { encodeVersionVector } from \"@tearleads/loro\";\nimport { importDecryptedDocumentSyncUpdates } from \"../../../data/documents/shared/documentSyncUpdateIsolation\";\nimport type { DecryptedDocumentSyncUpdate } from \"../../../data/documents/shared/types\";\nimport type { DocumentRecord } from \"../../../workflows/documents\";\nimport type { DocumentSyncAttempt } from \"./state\";\nimport {\n  type DocumentState,\n  type DocumentStoreState,\n  setReadySnapshot,\n} from \"./state\";\nimport {\n  type DocumentStoreSyncGeneration,\n  isDocumentStoreSyncGenerationCurrent,\n} from \"./syncGeneration\";\nimport { extendDocumentVersionCoverage } from \"./versionCoverage\";\n\nfunction sameNullableValue(\n  left: string | null | undefined,\n  right: string | null | undefined,\n): boolean {\n  return (left ?? null) === (right ?? null);\n}\n\n/**\n * A response may mutate document content only while the identity and access\n * context used to create its request are still live. Local content fields and\n * the pending marker are deliberately excluded because edits may advance them\n * while the request is in flight.\n */\nexport function documentSyncContextMatches(\n  liveRecord: DocumentRecord | null,\n  requestRecord: DocumentRecord,\n  responseDocumentId: string | null,\n): boolean {\n  return (\n    liveRecord !== null &&\n    liveRecord.id === requestRecord.id &&\n    liveRecord.documentId === requestRecord.documentId &&\n    liveRecord.documentId === responseDocumentId &&\n    liveRecord.containerId === requestRecord.containerId &&\n    liveRecord.accessEpoch === requestRecord.accessEpoch &&\n    sameNullableValue(\n      liveRecord.accessStateHash,\n      requestRecord.accessStateHash,\n    ) &&\n    (liveRecord.effectiveAccessLevel ?? null) ===\n      (requestRecord.effectiveAccessLevel ?? null) &&\n    sameNullableValue(\n      liveRecord.contentKeyBundle,\n      requestRecord.contentKeyBundle,\n    ) &&\n    sameNullableValue(\n      liveRecord.documentKekTargets,\n      requestRecord.documentKekTargets,\n    ) &&\n    sameNullableValue(\n      liveRecord.documentManifestBundle,\n      requestRecord.documentManifestBundle,\n    )\n  );\n}\n\nexport function importSyncedDocumentUpdates(\n  currentDoc: DocumentState,\n  updates: readonly DecryptedDocumentSyncUpdate[],\n): DocumentState {\n  importDecryptedDocumentSyncUpdates(currentDoc, updates);\n  return currentDoc;\n}\n\nexport function applyIncomingSyncedUpdates(\n  state: DocumentStoreState,\n  currentDoc: DocumentState,\n  requestRecord: DocumentRecord,\n  syncAttempt: DocumentSyncAttempt,\n  expectedGeneration?: DocumentStoreSyncGeneration,\n): DocumentState {\n  if (\n    (expectedGeneration &&\n      !isDocumentStoreSyncGenerationCurrent(state, expectedGeneration)) ||\n    !documentSyncContextMatches(\n      state.record,\n      requestRecord,\n      syncAttempt.synced.plan.documentId,\n    )\n  ) {\n    return currentDoc;\n  }\n\n  const updates = syncAttempt.synced.decryptedUpdates;\n  if (updates.length === 0) return currentDoc;\n\n  const mergedDoc = importSyncedDocumentUpdates(currentDoc, updates);\n  const baseVersion = state.pendingBaseVersion;\n  if (baseVersion === null) {\n    throw new Error(\"Document sync requires an initialized pending base\");\n  }\n  // Promote only through update spans proven to be remote. Advancing to the\n  // whole merged document would also cross a concurrent deferRemoteSync edit\n  // and could permanently classify that local-only operation as synced.\n  state.pendingBaseVersion = extendDocumentVersionCoverage({\n    baseVersion,\n    documentVersion: encodeVersionVector(mergedDoc),\n    spans: updates,\n  });\n\n  if (state.pendingLocalWrites > 0) {\n    setReadySnapshot(\n      state,\n      mergedDoc,\n      true,\n      state.snapshot.text,\n      state.snapshot.structuredFields,\n    );\n    return mergedDoc;\n  }\n\n  setReadySnapshot(state, mergedDoc, true);\n  return mergedDoc;\n}\n"]}