@tearleads/client-sdk 0.1.61 → 0.1.63

package/workflows/documents/sync/syncLane.js

@@ -0,0 +1,94 @@
+import { getOrCreateDomainSyncCoordinator, isDatabaseUnavailableError, } from "../../../data/sync/syncCoordinator.js";
+// Facade re-export: document stores must reach this shared sync helper
+// through this workflow boundary, not by importing data/sync directly.
+export { sequenceUnchanged } from "../../../data/sync/sequence.js";
+function getDocumentSyncLaneKey(localId) {
+    return `documents:${localId}`;
+}
+export function registerDocumentSyncLane(input) {
+    return getOrCreateDomainSyncCoordinator(input.domainScope).registerLane(getDocumentSyncLaneKey(input.localId), {
+        label: `Document ${input.localId}`,
+        onUnexpectedError: (error) => {
+            console.error(`Failed to sync document ${input.localId}:`, error);
+        },
+        phase: "document",
+        priority: input.priority,
+        // Fixed literal: the local id stays in the console line above, never in
+        // a report. The mapped stack identifies which lane body threw. Returning
+        // the host's result hands a rejection to the lane reporter's wrapper;
+        // discarding it would surface as an unhandled rejection instead.
+        reportUnexpectedError: (error) => input.logError?.("Documents: sync lane failed", error),
+        run: input.run,
+        shouldIgnoreError: isDatabaseUnavailableError,
+    });
+}
+export function requestDocumentSyncLaneAndWait(input) {
+    if (input.signal?.aborted) {
+        input.onInvalidated?.();
+        return Promise.resolve(false);
+    }
+    const coordinator = getOrCreateDomainSyncCoordinator(input.domainScope);
+    const laneKey = getDocumentSyncLaneKey(input.localId);
+    const initialLane = coordinator
+        .getSnapshot()
+        .lanes.find((lane) => lane.key === laneKey);
+    if (!initialLane) {
+        return Promise.resolve(false);
+    }
+    if (initialLane.runAbandoned) {
+        return Promise.resolve(false);
+    }
+    const baselineRunCount = initialLane.runCount;
+    return new Promise((resolve) => {
+        let settled = false;
+        let unsubscribe = () => undefined;
+        const finish = (completed) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            unsubscribe();
+            input.signal?.removeEventListener("abort", handleAbort);
+            resolve(completed);
+        };
+        const handleAbort = () => {
+            if (settled) {
+                return;
+            }
+            input.onInvalidated?.();
+            finish(false);
+        };
+        const inspect = () => {
+            if (coordinator.isDisposed()) {
+                handleAbort();
+                return;
+            }
+            const lane = coordinator
+                .getSnapshot()
+                .lanes.find((candidate) => candidate.key === laneKey);
+            if (!lane) {
+                handleAbort();
+                return;
+            }
+            if (lane.runAbandoned) {
+                handleAbort();
+                return;
+            }
+            if (lane.runCount <= baselineRunCount || lane.running || lane.requested) {
+                return;
+            }
+            if (lane.lastAction === "completed" || lane.lastAction === "failed") {
+                finish(lane.lastAction === "completed" && input.didCompleteRequest());
+            }
+        };
+        unsubscribe = coordinator.subscribe(inspect);
+        input.signal?.addEventListener("abort", handleAbort, { once: true });
+        if (input.signal?.aborted) {
+            handleAbort();
+            return;
+        }
+        input.request();
+        inspect();
+    });
+}
+//# sourceMappingURL=syncLane.js.map

package/workflows/documents/sync/syncLane.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncLane.js","sourceRoot":"","sources":["syncLane.ts"],"names":[],"mappings":"AACA,OAAO,EACL,gCAAgC,EAChC,0BAA0B,GAE3B,MAAM,oCAAoC,CAAC;AAE5C,uEAAuE;AACvE,uEAAuE;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAIhE,SAAS,sBAAsB,CAAC,OAAe;IAC7C,OAAO,aAAa,OAAO,EAAE,CAAC;AAChC,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,KAOxC;IACC,OAAO,gCAAgC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,YAAY,CACrE,sBAAsB,CAAC,KAAK,CAAC,OAAO,CAAC,EACrC;QACE,KAAK,EAAE,YAAY,KAAK,CAAC,OAAO,EAAE;QAClC,iBAAiB,EAAE,CAAC,KAAK,EAAE,EAAE;YAC3B,OAAO,CAAC,KAAK,CAAC,2BAA2B,KAAK,CAAC,OAAO,GAAG,EAAE,KAAK,CAAC,CAAC;QACpE,CAAC;QACD,KAAK,EAAE,UAAU;QACjB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,wEAAwE;QACxE,yEAAyE;QACzE,sEAAsE;QACtE,iEAAiE;QACjE,qBAAqB,EAAE,CAAC,KAAK,EAAE,EAAE,CAC/B,KAAK,CAAC,QAAQ,EAAE,CAAC,6BAA6B,EAAE,KAAK,CAAC;QACxD,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,iBAAiB,EAAE,0BAA0B;KAC9C,CACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,8BAA8B,CAAC,KAO9C;IACC,IAAI,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;QAC1B,KAAK,CAAC,aAAa,EAAE,EAAE,CAAC;QACxB,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;IACD,MAAM,WAAW,GAAG,gCAAgC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IACxE,MAAM,OAAO,GAAG,sBAAsB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACtD,MAAM,WAAW,GAAG,WAAW;SAC5B,WAAW,EAAE;SACb,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,KAAK,OAAO,CAAC,CAAC;IAC9C,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;IACD,IAAI,WAAW,CAAC,YAAY,EAAE,CAAC;QAC7B,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;IACD,MAAM,gBAAgB,GAAG,WAAW,CAAC,QAAQ,CAAC;IAC9C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,IAAI,WAAW,GAAe,GAAG,EAAE,CAAC,SAAS,CAAC;QAC9C,MAAM,MAAM,GAAG,CAAC,SAAkB,EAAE,EAAE;YACpC,IAAI,OAAO,EAAE,CAAC;gBACZ,OAAO;YACT,CAAC;YACD,OAAO,GAAG,IAAI,CAAC;YACf,WAAW,EAAE,CAAC;YACd,KAAK,CAAC,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;YACxD,OAAO,CAAC,SAAS,CAAC,CAAC;QACrB,CAAC,CAAC;QACF,MAAM,WAAW,GAAG,GAAG,EAAE;YACvB,IAAI,OAAO,EAAE,CAAC;gBACZ,OAAO;YACT,CAAC;YACD,KAAK,CAAC,aAAa,EAAE,EAAE,CAAC;YACxB,MAAM,CAAC,KAAK,CAAC,CAAC;QAChB,CAAC,CAAC;QACF,MAAM,OAAO,GAAG,GAAG,EAAE;YACnB,IAAI,WAAW,CAAC,UAAU,EAAE,EAAE,CAAC;gBAC7B,WAAW,EAAE,CAAC;gBACd,OAAO;YACT,CAAC;YACD,MAAM,IAAI,GAAG,WAAW;iBACrB,WAAW,EAAE;iBACb,KAAK,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,KAAK,OAAO,CAAC,CAAC;YACxD,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,WAAW,EAAE,CAAC;gBACd,OAAO;YACT,CAAC;YACD,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;gBACtB,WAAW,EAAE,CAAC;gBACd,OAAO;YACT,CAAC;YACD,IAAI,IAAI,CAAC,QAAQ,IAAI,gBAAgB,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;gBACxE,OAAO;YACT,CAAC;YACD,IAAI,IAAI,CAAC,UAAU,KAAK,WAAW,IAAI,IAAI,CAAC,UAAU,KAAK,QAAQ,EAAE,CAAC;gBACpE,MAAM,CAAC,IAAI,CAAC,UAAU,KAAK,WAAW,IAAI,KAAK,CAAC,kBAAkB,EAAE,CAAC,CAAC;YACxE,CAAC;QACH,CAAC,CAAC;QACF,WAAW,GAAG,WAAW,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAC7C,KAAK,CAAC,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACrE,IAAI,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;YAC1B,WAAW,EAAE,CAAC;YACd,OAAO;QACT,CAAC;QACD,KAAK,CAAC,OAAO,EAAE,CAAC;QAChB,OAAO,EAAE,CAAC;IACZ,CAAC,CAAC,CAAC;AACL,CAAC","sourcesContent":["import type { DomainScope } from \"../../../data/shared/domainScope\";\nimport {\n  getOrCreateDomainSyncCoordinator,\n  isDatabaseUnavailableError,\n  type SyncLane,\n} from \"../../../data/sync/syncCoordinator\";\n\n// Facade re-export: document stores must reach this shared sync helper\n// through this workflow boundary, not by importing data/sync directly.\nexport { sequenceUnchanged } from \"../../../data/sync/sequence\";\n\nexport type DocumentSyncLane = SyncLane;\n\nfunction getDocumentSyncLaneKey(localId: string): string {\n  return `documents:${localId}`;\n}\n\nexport function registerDocumentSyncLane(input: {\n  readonly domainScope: DomainScope;\n  readonly localId: string;\n  /** Host diagnostics sink; bare runtimes do not structure errors. */\n  readonly logError?: ((message: string, error: unknown) => void) | undefined;\n  readonly run: () => Promise<void>;\n  readonly priority?: (() => number) | undefined;\n}): DocumentSyncLane {\n  return getOrCreateDomainSyncCoordinator(input.domainScope).registerLane(\n    getDocumentSyncLaneKey(input.localId),\n    {\n      label: `Document ${input.localId}`,\n      onUnexpectedError: (error) => {\n        console.error(`Failed to sync document ${input.localId}:`, error);\n      },\n      phase: \"document\",\n      priority: input.priority,\n      // Fixed literal: the local id stays in the console line above, never in\n      // a report. The mapped stack identifies which lane body threw. Returning\n      // the host's result hands a rejection to the lane reporter's wrapper;\n      // discarding it would surface as an unhandled rejection instead.\n      reportUnexpectedError: (error) =>\n        input.logError?.(\"Documents: sync lane failed\", error),\n      run: input.run,\n      shouldIgnoreError: isDatabaseUnavailableError,\n    },\n  );\n}\n\nexport function requestDocumentSyncLaneAndWait(input: {\n  readonly didCompleteRequest: () => boolean;\n  readonly domainScope: DomainScope;\n  readonly localId: string;\n  readonly onInvalidated?: (() => void) | undefined;\n  readonly request: () => void;\n  readonly signal?: AbortSignal | undefined;\n}): Promise<boolean> {\n  if (input.signal?.aborted) {\n    input.onInvalidated?.();\n    return Promise.resolve(false);\n  }\n  const coordinator = getOrCreateDomainSyncCoordinator(input.domainScope);\n  const laneKey = getDocumentSyncLaneKey(input.localId);\n  const initialLane = coordinator\n    .getSnapshot()\n    .lanes.find((lane) => lane.key === laneKey);\n  if (!initialLane) {\n    return Promise.resolve(false);\n  }\n  if (initialLane.runAbandoned) {\n    return Promise.resolve(false);\n  }\n  const baselineRunCount = initialLane.runCount;\n  return new Promise((resolve) => {\n    let settled = false;\n    let unsubscribe: () => void = () => undefined;\n    const finish = (completed: boolean) => {\n      if (settled) {\n        return;\n      }\n      settled = true;\n      unsubscribe();\n      input.signal?.removeEventListener(\"abort\", handleAbort);\n      resolve(completed);\n    };\n    const handleAbort = () => {\n      if (settled) {\n        return;\n      }\n      input.onInvalidated?.();\n      finish(false);\n    };\n    const inspect = () => {\n      if (coordinator.isDisposed()) {\n        handleAbort();\n        return;\n      }\n      const lane = coordinator\n        .getSnapshot()\n        .lanes.find((candidate) => candidate.key === laneKey);\n      if (!lane) {\n        handleAbort();\n        return;\n      }\n      if (lane.runAbandoned) {\n        handleAbort();\n        return;\n      }\n      if (lane.runCount <= baselineRunCount || lane.running || lane.requested) {\n        return;\n      }\n      if (lane.lastAction === \"completed\" || lane.lastAction === \"failed\") {\n        finish(lane.lastAction === \"completed\" && input.didCompleteRequest());\n      }\n    };\n    unsubscribe = coordinator.subscribe(inspect);\n    input.signal?.addEventListener(\"abort\", handleAbort, { once: true });\n    if (input.signal?.aborted) {\n      handleAbort();\n      return;\n    }\n    input.request();\n    inspect();\n  });\n}\n"]}

package/workflows/documents/sync/syncResponseResult.js

@@ -0,0 +1,134 @@
+import { KeyingVerificationError } from "../../../internal/crypto/index.js";
+import { decryptDocumentSyncUpdatesByEpoch } from "../../../data/documents/shared/crypto.js";
+import { isolateDocumentSyncBatchError, } from "../../../data/documents/shared/documentSyncUpdateIsolation.js";
+import { assertDocumentWriterProjectionConsistent } from "../../../data/documents/shared/projection.js";
+import { DocumentSyncResponseUpdateContentKeyError, persistedDocumentSyncStateFromResponse, } from "../../../data/documents/shared/responses.js";
+import { projectionVerificationOptions } from "../../../data/documents/shared/types.js";
+import { unwrapDocumentSyncResponseContentKeys } from "../syncPlan/syncContentKeys.js";
+import { acceptedHeldBackPendingUpdateIds, responseAcceptedRecoveryBaseline, } from "../syncPlan/syncPlanRequestBounds.js";
+import { rekeyAndReportUnsettledRecoveryPendingUpdates, settledPendingUpdateIdsFromSync, } from "../syncRekeys/syncRecoveryRekey.js";
+function isolateContentKeyResponseFailure(error, response) {
+    if (!(error instanceof DocumentSyncResponseUpdateContentKeyError) ||
+        response.updates.length === 0) {
+        throw error;
+    }
+    throw isolateDocumentSyncBatchError({
+        cause: new KeyingVerificationError("invalid_shape", error.message),
+        stage: "content_key",
+        updateIds: response.updates.map((update) => update.id),
+    });
+}
+/** @internal Exercises poison precedence for the decryptable subset of a raw page. */
+export async function validateDecryptableRawHistorySiblings(input) {
+    if (input.updates.length === 0)
+        return;
+    const decryptedUpdates = await decryptDocumentSyncUpdatesByEpoch({
+        contentKeysByEpoch: input.contentKeysByEpoch,
+        documentId: input.documentId,
+        organizationId: input.organizationId,
+        updates: input.updates,
+    });
+    // The current wire contract authenticates each update's operation range but
+    // not its exact dependency set. An unresolved import therefore cannot prove
+    // that the missing parent belongs to an unavailable sibling; preserve the
+    // isolation failure instead of downgrading unrelated poison to availability.
+    await input.validateIncomingUpdates({
+        decryptedUpdates,
+        response: { ...input.response, updates: [...input.updates] },
+    });
+}
+async function resolveVerifiedResponseState(input) {
+    const { plan } = input.materializedPlan;
+    let persistedState;
+    try {
+        persistedState = await persistedDocumentSyncStateFromResponse(plan, input.response, {
+            resolveWriterPublicKey: input.resolveWriterPublicKey,
+        });
+    }
+    catch (error) {
+        // Missing or future bundles are response-integrity failures. They must be
+        // poison-isolated before key availability is considered, because the
+        // referenced update has not yet authenticated against a bundle.
+        isolateContentKeyResponseFailure(error, input.response);
+    }
+    if ((plan.request.containerRekeys?.length ?? 0) > 0) {
+        await assertDocumentWriterProjectionConsistent(input.writerProjection, {
+            allowStaleContentKeyBundle: true,
+            execSql: input.execSql,
+            stillCurrent: input.stillCurrent,
+            ...projectionVerificationOptions(input),
+        });
+    }
+    const contentKeysByEpoch = await unwrapDocumentSyncResponseContentKeys({
+        currentContentKey: input.materializedPlan.contentKey,
+        currentContentKeyEpoch: plan.contentKeyEpoch,
+        execSql: input.execSql,
+        historyMode: plan.request.historyMode,
+        onRawHistoryUnavailable: async ({ contentKeysByEpoch, updates }) => validateDecryptableRawHistorySiblings({
+            contentKeysByEpoch,
+            documentId: plan.documentId,
+            organizationId: plan.organizationId,
+            response: input.response,
+            updates,
+            validateIncomingUpdates: input.validateIncomingUpdates,
+        }),
+        response: input.response,
+        targetSecretKey: input.targetSecretKey,
+        writerProjection: input.writerProjection,
+        ...projectionVerificationOptions(input),
+    });
+    return { contentKeysByEpoch, persistedState };
+}
+export async function syncRemoteDocumentResultFromResponse(input) {
+    const { plan } = input.materializedPlan;
+    const { contentKeysByEpoch, persistedState } = await resolveVerifiedResponseState(input);
+    const decryptedUpdates = await decryptDocumentSyncUpdatesByEpoch({
+        contentKeysByEpoch,
+        documentId: plan.documentId,
+        organizationId: plan.organizationId,
+        updates: input.response.updates,
+    });
+    await input.validateIncomingUpdates({
+        decryptedUpdates,
+        response: input.response,
+    });
+    const recoveryBaselineId = input.materializedPlan.staleRecoveryBaselineUpdateId;
+    const acceptedRecoveryBaseline = responseAcceptedRecoveryBaseline(input.materializedPlan, input.response);
+    // Two heal-specific corrections: the synthetic heal baseline matches no
+    // pending-queue row, so its ack must not count as a settled pending update;
+    // and checkpoints the heal held back ARE settled by it — the committed
+    // covering baseline subsumes their full-history content, and resubmitting
+    // them post-heal could become the LATEST baseline at the healed epoch and
+    // shrink the redirect's coverage below the pre-heal frontier.
+    const settledPendingUpdateIds = [
+        ...settledPendingUpdateIdsFromSync({
+            decryptedUpdates,
+            recoveryPendingUpdatesById: input.recoveryPendingUpdatesById,
+            response: input.response,
+        }).filter((updateId) => updateId !== recoveryBaselineId),
+        ...acceptedHeldBackPendingUpdateIds(input.materializedPlan, input.response),
+    ];
+    const { exhaustedPendingUpdateCount, rekeyedPendingUpdateIds } = await rekeyAndReportUnsettledRecoveryPendingUpdates({
+        execSql: input.execSql,
+        onTerminalSubmitFailure: input.onTerminalSubmitFailure,
+        recoveryPendingUpdatesById: input.recoveryPendingUpdatesById,
+        rekeyPendingUpdate: input.rekeyPendingUpdate,
+        settledPendingUpdateIds,
+        stillCurrent: input.stillCurrent,
+    });
+    return {
+        exhaustedPendingUpdateCount,
+        contentKey: input.materializedPlan.contentKey,
+        decryptedUpdates,
+        hasDeferredPendingUpdates: false,
+        hasIncompletePull: false,
+        persistedState,
+        plan,
+        rekeyedPendingUpdateIds,
+        response: input.response,
+        settledPendingUpdateIds,
+        acceptedRecoveryBaseline,
+        writerProjection: input.writerProjection,
+    };
+}
+//# sourceMappingURL=syncResponseResult.js.map

package/workflows/documents/sync/syncResponseResult.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncResponseResult.js","sourceRoot":"","sources":["syncResponseResult.ts"],"names":[],"mappings":"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","sourcesContent":["import { KeyingVerificationError } from \"@tearleads/crypto\";\nimport type {\n  DocumentSyncResponse,\n  DocumentWriterProjectionResponse,\n} from \"@tearleads/validators/response\";\nimport { decryptDocumentSyncUpdatesByEpoch } from \"../../../data/documents/shared/crypto\";\nimport {\n  type IncomingDocumentSyncUpdateValidator,\n  isolateDocumentSyncBatchError,\n} from \"../../../data/documents/shared/documentSyncUpdateIsolation\";\nimport { assertDocumentWriterProjectionConsistent } from \"../../../data/documents/shared/projection\";\nimport {\n  DocumentSyncResponseUpdateContentKeyError,\n  persistedDocumentSyncStateFromResponse,\n} from \"../../../data/documents/shared/responses\";\nimport type {\n  DocumentWriterPublicKeyResolver,\n  MaterializedDocumentSyncPlan,\n  SyncRemoteDocumentResult,\n} from \"../../../data/documents/shared/types\";\nimport { projectionVerificationOptions } from \"../../../data/documents/shared/types\";\nimport type {\n  ProjectionUserKeyResolver,\n  ReferencedPrincipalPolicyWarmer,\n} from \"../../../data/keyingProjectionVerification\";\nimport type { PendingUpdateRecord } from \"../../../data/sqlite/documentPersistence\";\nimport type { ExecSql } from \"../../../data/sqlite/sqlSchema\";\nimport type { TerminalSubmitFailureHandler } from \"../syncFailures/syncFailureClassification\";\nimport { unwrapDocumentSyncResponseContentKeys } from \"../syncPlan/syncContentKeys\";\nimport {\n  acceptedHeldBackPendingUpdateIds,\n  responseAcceptedRecoveryBaseline,\n} from \"../syncPlan/syncPlanRequestBounds\";\nimport {\n  type RekeyPendingUpdate,\n  rekeyAndReportUnsettledRecoveryPendingUpdates,\n  settledPendingUpdateIdsFromSync,\n} from \"../syncRekeys/syncRecoveryRekey\";\n\nfunction isolateContentKeyResponseFailure(\n  error: unknown,\n  response: DocumentSyncResponse,\n): never {\n  if (\n    !(error instanceof DocumentSyncResponseUpdateContentKeyError) ||\n    response.updates.length === 0\n  ) {\n    throw error;\n  }\n  throw isolateDocumentSyncBatchError({\n    cause: new KeyingVerificationError(\"invalid_shape\", error.message),\n    stage: \"content_key\",\n    updateIds: response.updates.map((update) => update.id),\n  });\n}\n\ntype SyncRemoteDocumentResultInput = {\n  execSql: ExecSql;\n  materializedPlan: MaterializedDocumentSyncPlan;\n  onTerminalSubmitFailure?: TerminalSubmitFailureHandler | undefined;\n  recoveryPendingUpdatesById: ReadonlyMap<string, PendingUpdateRecord>;\n  rekeyPendingUpdate?: RekeyPendingUpdate | undefined;\n  resolveProjectionUserKey: ProjectionUserKeyResolver;\n  warmReferencedPrincipalPolicies?: ReferencedPrincipalPolicyWarmer | undefined;\n  resolveWriterPublicKey: DocumentWriterPublicKeyResolver;\n  response: DocumentSyncResponse;\n  stillCurrent?: (() => boolean) | undefined;\n  targetSecretKey: Uint8Array;\n  validateIncomingUpdates: IncomingDocumentSyncUpdateValidator;\n  writerProjection: DocumentWriterProjectionResponse;\n};\n\n/** @internal Exercises poison precedence for the decryptable subset of a raw page. */\nexport async function validateDecryptableRawHistorySiblings(input: {\n  contentKeysByEpoch: ReadonlyMap<number, Uint8Array>;\n  documentId: string;\n  organizationId: string;\n  response: DocumentSyncResponse;\n  updates: readonly DocumentSyncResponse[\"updates\"][number][];\n  validateIncomingUpdates: IncomingDocumentSyncUpdateValidator;\n}): Promise<void> {\n  if (input.updates.length === 0) return;\n  const decryptedUpdates = await decryptDocumentSyncUpdatesByEpoch({\n    contentKeysByEpoch: input.contentKeysByEpoch,\n    documentId: input.documentId,\n    organizationId: input.organizationId,\n    updates: input.updates,\n  });\n  // The current wire contract authenticates each update's operation range but\n  // not its exact dependency set. An unresolved import therefore cannot prove\n  // that the missing parent belongs to an unavailable sibling; preserve the\n  // isolation failure instead of downgrading unrelated poison to availability.\n  await input.validateIncomingUpdates({\n    decryptedUpdates,\n    response: { ...input.response, updates: [...input.updates] },\n  });\n}\n\nasync function resolveVerifiedResponseState(\n  input: SyncRemoteDocumentResultInput,\n) {\n  const { plan } = input.materializedPlan;\n  let persistedState: Awaited<\n    ReturnType<typeof persistedDocumentSyncStateFromResponse>\n  >;\n  try {\n    persistedState = await persistedDocumentSyncStateFromResponse(\n      plan,\n      input.response,\n      {\n        resolveWriterPublicKey: input.resolveWriterPublicKey,\n      },\n    );\n  } catch (error) {\n    // Missing or future bundles are response-integrity failures. They must be\n    // poison-isolated before key availability is considered, because the\n    // referenced update has not yet authenticated against a bundle.\n    isolateContentKeyResponseFailure(error, input.response);\n  }\n  if ((plan.request.containerRekeys?.length ?? 0) > 0) {\n    await assertDocumentWriterProjectionConsistent(input.writerProjection, {\n      allowStaleContentKeyBundle: true,\n      execSql: input.execSql,\n      stillCurrent: input.stillCurrent,\n      ...projectionVerificationOptions(input),\n    });\n  }\n  const contentKeysByEpoch = await unwrapDocumentSyncResponseContentKeys({\n    currentContentKey: input.materializedPlan.contentKey,\n    currentContentKeyEpoch: plan.contentKeyEpoch,\n    execSql: input.execSql,\n    historyMode: plan.request.historyMode,\n    onRawHistoryUnavailable: async ({ contentKeysByEpoch, updates }) =>\n      validateDecryptableRawHistorySiblings({\n        contentKeysByEpoch,\n        documentId: plan.documentId,\n        organizationId: plan.organizationId,\n        response: input.response,\n        updates,\n        validateIncomingUpdates: input.validateIncomingUpdates,\n      }),\n    response: input.response,\n    targetSecretKey: input.targetSecretKey,\n    writerProjection: input.writerProjection,\n    ...projectionVerificationOptions(input),\n  });\n  return { contentKeysByEpoch, persistedState };\n}\n\nexport async function syncRemoteDocumentResultFromResponse(\n  input: SyncRemoteDocumentResultInput,\n): Promise<SyncRemoteDocumentResult> {\n  const { plan } = input.materializedPlan;\n  const { contentKeysByEpoch, persistedState } =\n    await resolveVerifiedResponseState(input);\n  const decryptedUpdates = await decryptDocumentSyncUpdatesByEpoch({\n    contentKeysByEpoch,\n    documentId: plan.documentId,\n    organizationId: plan.organizationId,\n    updates: input.response.updates,\n  });\n  await input.validateIncomingUpdates({\n    decryptedUpdates,\n    response: input.response,\n  });\n  const recoveryBaselineId =\n    input.materializedPlan.staleRecoveryBaselineUpdateId;\n  const acceptedRecoveryBaseline = responseAcceptedRecoveryBaseline(\n    input.materializedPlan,\n    input.response,\n  );\n  // Two heal-specific corrections: the synthetic heal baseline matches no\n  // pending-queue row, so its ack must not count as a settled pending update;\n  // and checkpoints the heal held back ARE settled by it — the committed\n  // covering baseline subsumes their full-history content, and resubmitting\n  // them post-heal could become the LATEST baseline at the healed epoch and\n  // shrink the redirect's coverage below the pre-heal frontier.\n  const settledPendingUpdateIds = [\n    ...settledPendingUpdateIdsFromSync({\n      decryptedUpdates,\n      recoveryPendingUpdatesById: input.recoveryPendingUpdatesById,\n      response: input.response,\n    }).filter((updateId) => updateId !== recoveryBaselineId),\n    ...acceptedHeldBackPendingUpdateIds(input.materializedPlan, input.response),\n  ];\n  const { exhaustedPendingUpdateCount, rekeyedPendingUpdateIds } =\n    await rekeyAndReportUnsettledRecoveryPendingUpdates({\n      execSql: input.execSql,\n      onTerminalSubmitFailure: input.onTerminalSubmitFailure,\n      recoveryPendingUpdatesById: input.recoveryPendingUpdatesById,\n      rekeyPendingUpdate: input.rekeyPendingUpdate,\n      settledPendingUpdateIds,\n      stillCurrent: input.stillCurrent,\n    });\n\n  return {\n    exhaustedPendingUpdateCount,\n    contentKey: input.materializedPlan.contentKey,\n    decryptedUpdates,\n    hasDeferredPendingUpdates: false,\n    hasIncompletePull: false,\n    persistedState,\n    plan,\n    rekeyedPendingUpdateIds,\n    response: input.response,\n    settledPendingUpdateIds,\n    acceptedRecoveryBaseline,\n    writerProjection: input.writerProjection,\n  };\n}\n"]}

package/workflows/documents/sync/syncSubmittedResult.js

@@ -0,0 +1,119 @@
+import { projectionVerificationOptions } from "../../../data/documents/shared/types.js";
+import { verifyDocumentWriterProjectionAuthorization, } from "../../../data/keyingProjectionVerification/index.js";
+import { isKeyingVerificationError } from "../../../data/keyingProjectionVerification/error.js";
+import { refreshSyncAttemptWriterProjection } from "../syncFailures/index.js";
+import { DocumentRawHistoryUnavailableError } from "../syncPlan/syncContentKeys.js";
+import { hasDeferredPendingUpdatesAfterSubmit, responseAcceptedRecoveryBaseline, } from "../syncPlan/syncPlanRequestBounds.js";
+import { syncRemoteDocumentResultFromResponse } from "./syncResponseResult.js";
+import { traceHealed } from "./syncTrace.js";
+/** @internal Applies post-verification heal effects under the sync generation. */
+export function applyAcceptedHealSideEffects(input) {
+    if (!input.materializedPlan.healedStaleContentKeyBundle ||
+        !responseAcceptedRecoveryBaseline(input.materializedPlan, input.response) ||
+        input.stillCurrent?.() === false) {
+        return;
+    }
+    input.evictWriterProjection?.(input.documentId);
+    if (input.stillCurrent?.() === false) {
+        return;
+    }
+    traceHealed(input.onSyncTrace, {
+        accepted: input.response.acceptedOutgoingUpdateIds.length,
+        documentId: input.materializedPlan.plan.documentId,
+        epoch: input.materializedPlan.plan.contentKeyEpoch,
+    });
+}
+async function submittedDocumentSyncResult(input) {
+    const result = await syncRemoteDocumentResultFromResponse({
+        ...projectionVerificationOptions(input.sync),
+        execSql: input.sync.execSql,
+        materializedPlan: input.materializedPlan,
+        onTerminalSubmitFailure: input.sync.onTerminalSubmitFailure,
+        recoveryPendingUpdatesById: input.recoveryPendingUpdatesById,
+        rekeyPendingUpdate: input.sync.rekeyPendingUpdate,
+        resolveWriterPublicKey: input.sync.resolveWriterPublicKey,
+        response: input.response,
+        stillCurrent: input.sync.stillCurrent,
+        targetSecretKey: input.sync.targetSecretKey,
+        validateIncomingUpdates: input.sync.validateIncomingUpdates,
+        writerProjection: input.writerProjection,
+        resolveProjectionUserKey: input.resolveProjectionUserKey,
+    });
+    if ((input.materializedPlan.plan.request.containerRekeys?.length ?? 0) > 0 &&
+        input.sync.stillCurrent?.() !== false) {
+        input.sync.apiClient.clearWriterProjectionCaches?.();
+    }
+    applyAcceptedHealSideEffects({
+        documentId: input.sync.documentId,
+        evictWriterProjection: input.sync.apiClient.evictDocumentWriterProjection?.bind(input.sync.apiClient),
+        materializedPlan: input.materializedPlan,
+        onSyncTrace: input.sync.onSyncTrace,
+        response: input.response,
+        stillCurrent: input.sync.stillCurrent,
+    });
+    return {
+        ...result,
+        hasDeferredPendingUpdates: (input.materializedPlan.plan.request.pullCursor !== undefined &&
+            input.pendingUpdateIds.length > 0 &&
+            result.exhaustedPendingUpdateCount === 0) ||
+            hasDeferredPendingUpdatesAfterSubmit({
+                acceptedRecoveryBaseline: result.acceptedRecoveryBaseline,
+                exhaustedPendingUpdateCount: result.exhaustedPendingUpdateCount,
+                pendingUpdateIds: input.pendingUpdateIds,
+                rekeyedPendingUpdateIds: result.rekeyedPendingUpdateIds,
+                settledPendingUpdateIds: result.settledPendingUpdateIds,
+            }),
+        hasIncompletePull: !input.pullComplete,
+    };
+}
+async function retrySubmittedResponseWithFreshProjection(input, unavailableError, refreshAuthorization) {
+    const writerProjection = await refreshSyncAttemptWriterProjection({
+        apiClient: input.sync.apiClient,
+        documentId: input.sync.documentId,
+        onRemoteDocumentDeleted: input.sync.onRemoteDocumentDeleted,
+        onSyncAbandoned: input.sync.onSyncAbandoned,
+        onSyncTrace: input.sync.onSyncTrace,
+        onTerminalFailure: input.sync.onReadOnlyProjectionFailure,
+        stillCurrent: input.sync.stillCurrent,
+        unavailableError,
+    });
+    if (!writerProjection)
+        return null;
+    const materializedPlan = refreshAuthorization
+        ? {
+            ...input.materializedPlan,
+            plan: {
+                ...input.materializedPlan.plan,
+                documentWriterAuthorization: await verifyDocumentWriterProjectionAuthorization({
+                    execSql: input.sync.execSql,
+                    projection: writerProjection,
+                    resolveUserKey: input.resolveProjectionUserKey,
+                    stillCurrent: input.sync.stillCurrent,
+                    warmReferencedPrincipalPolicies: input.sync.warmReferencedPrincipalPolicies,
+                }),
+            },
+        }
+        : input.materializedPlan;
+    // Keep the submitted request, keys, and response frozen. Only refreshed,
+    // verified evidence may be added; this retry never resubmits outgoing edits.
+    return submittedDocumentSyncResult({
+        ...input,
+        materializedPlan,
+        writerProjection,
+    });
+}
+export async function resolveSubmittedDocumentSyncResult(input) {
+    try {
+        return await submittedDocumentSyncResult(input);
+    }
+    catch (error) {
+        const missingDependency = isKeyingVerificationError(error) && error.code === "missing_dependency";
+        if (!missingDependency &&
+            (input.sync.historyMode !== "raw" ||
+                !(error instanceof DocumentRawHistoryUnavailableError))) {
+            throw error;
+        }
+        return retrySubmittedResponseWithFreshProjection(input, error, missingDependency);
+    }
+}
+//# sourceMappingURL=syncSubmittedResult.js.map

package/workflows/documents/sync/syncSubmittedResult.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncSubmittedResult.js","sourceRoot":"","sources":["syncSubmittedResult.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  DocumentSyncResponse,\n  DocumentWriterProjectionResponse,\n} from \"@tearleads/validators/response\";\nimport type {\n  MaterializedDocumentSyncPlan,\n  SyncRemoteDocumentResult,\n} from \"../../../data/documents/shared/types\";\nimport { projectionVerificationOptions } from \"../../../data/documents/shared/types\";\nimport {\n  type ProjectionUserKeyResolver,\n  verifyDocumentWriterProjectionAuthorization,\n} from \"../../../data/keyingProjectionVerification\";\nimport { isKeyingVerificationError } from \"../../../data/keyingProjectionVerification/error\";\nimport type { PendingUpdateRecord } from \"../../../data/sqlite/documentPersistence\";\nimport { refreshSyncAttemptWriterProjection } from \"../syncFailures\";\nimport { DocumentRawHistoryUnavailableError } from \"../syncPlan/syncContentKeys\";\nimport {\n  hasDeferredPendingUpdatesAfterSubmit,\n  responseAcceptedRecoveryBaseline,\n} from \"../syncPlan/syncPlanRequestBounds\";\nimport type { SyncRemoteDocumentInput } from \"./readOnlySync\";\nimport { syncRemoteDocumentResultFromResponse } from \"./syncResponseResult\";\nimport { traceHealed } from \"./syncTrace\";\n\ntype SubmittedDocumentSyncResultInput = {\n  materializedPlan: MaterializedDocumentSyncPlan;\n  pendingUpdateIds: readonly string[];\n  pullComplete: boolean;\n  recoveryPendingUpdatesById: ReadonlyMap<string, PendingUpdateRecord>;\n  resolveProjectionUserKey: ProjectionUserKeyResolver;\n  response: DocumentSyncResponse;\n  sync: SyncRemoteDocumentInput;\n  writerProjection: DocumentWriterProjectionResponse;\n};\n\n/** @internal Applies post-verification heal effects under the sync generation. */\nexport function applyAcceptedHealSideEffects(input: {\n  documentId: string;\n  evictWriterProjection?: ((documentId: string) => void) | undefined;\n  materializedPlan: MaterializedDocumentSyncPlan;\n  onSyncTrace: SyncRemoteDocumentInput[\"onSyncTrace\"];\n  response: DocumentSyncResponse;\n  stillCurrent: SyncRemoteDocumentInput[\"stillCurrent\"];\n}): void {\n  if (\n    !input.materializedPlan.healedStaleContentKeyBundle ||\n    !responseAcceptedRecoveryBaseline(input.materializedPlan, input.response) ||\n    input.stillCurrent?.() === false\n  ) {\n    return;\n  }\n  input.evictWriterProjection?.(input.documentId);\n  if (input.stillCurrent?.() === false) {\n    return;\n  }\n  traceHealed(input.onSyncTrace, {\n    accepted: input.response.acceptedOutgoingUpdateIds.length,\n    documentId: input.materializedPlan.plan.documentId,\n    epoch: input.materializedPlan.plan.contentKeyEpoch,\n  });\n}\n\nasync function submittedDocumentSyncResult(\n  input: SubmittedDocumentSyncResultInput,\n): Promise<SyncRemoteDocumentResult> {\n  const result = await syncRemoteDocumentResultFromResponse({\n    ...projectionVerificationOptions(input.sync),\n    execSql: input.sync.execSql,\n    materializedPlan: input.materializedPlan,\n    onTerminalSubmitFailure: input.sync.onTerminalSubmitFailure,\n    recoveryPendingUpdatesById: input.recoveryPendingUpdatesById,\n    rekeyPendingUpdate: input.sync.rekeyPendingUpdate,\n    resolveWriterPublicKey: input.sync.resolveWriterPublicKey,\n    response: input.response,\n    stillCurrent: input.sync.stillCurrent,\n    targetSecretKey: input.sync.targetSecretKey,\n    validateIncomingUpdates: input.sync.validateIncomingUpdates,\n    writerProjection: input.writerProjection,\n    resolveProjectionUserKey: input.resolveProjectionUserKey,\n  });\n  if (\n    (input.materializedPlan.plan.request.containerRekeys?.length ?? 0) > 0 &&\n    input.sync.stillCurrent?.() !== false\n  ) {\n    input.sync.apiClient.clearWriterProjectionCaches?.();\n  }\n  applyAcceptedHealSideEffects({\n    documentId: input.sync.documentId,\n    evictWriterProjection:\n      input.sync.apiClient.evictDocumentWriterProjection?.bind(\n        input.sync.apiClient,\n      ),\n    materializedPlan: input.materializedPlan,\n    onSyncTrace: input.sync.onSyncTrace,\n    response: input.response,\n    stillCurrent: input.sync.stillCurrent,\n  });\n  return {\n    ...result,\n    hasDeferredPendingUpdates:\n      (input.materializedPlan.plan.request.pullCursor !== undefined &&\n        input.pendingUpdateIds.length > 0 &&\n        result.exhaustedPendingUpdateCount === 0) ||\n      hasDeferredPendingUpdatesAfterSubmit({\n        acceptedRecoveryBaseline: result.acceptedRecoveryBaseline,\n        exhaustedPendingUpdateCount: result.exhaustedPendingUpdateCount,\n        pendingUpdateIds: input.pendingUpdateIds,\n        rekeyedPendingUpdateIds: result.rekeyedPendingUpdateIds,\n        settledPendingUpdateIds: result.settledPendingUpdateIds,\n      }),\n    hasIncompletePull: !input.pullComplete,\n  };\n}\n\nasync function retrySubmittedResponseWithFreshProjection(\n  input: SubmittedDocumentSyncResultInput,\n  unavailableError: unknown,\n  refreshAuthorization: boolean,\n): Promise<SyncRemoteDocumentResult | null> {\n  const writerProjection = await refreshSyncAttemptWriterProjection({\n    apiClient: input.sync.apiClient,\n    documentId: input.sync.documentId,\n    onRemoteDocumentDeleted: input.sync.onRemoteDocumentDeleted,\n    onSyncAbandoned: input.sync.onSyncAbandoned,\n    onSyncTrace: input.sync.onSyncTrace,\n    onTerminalFailure: input.sync.onReadOnlyProjectionFailure,\n    stillCurrent: input.sync.stillCurrent,\n    unavailableError,\n  });\n  if (!writerProjection) return null;\n  const materializedPlan = refreshAuthorization\n    ? {\n        ...input.materializedPlan,\n        plan: {\n          ...input.materializedPlan.plan,\n          documentWriterAuthorization:\n            await verifyDocumentWriterProjectionAuthorization({\n              execSql: input.sync.execSql,\n              projection: writerProjection,\n              resolveUserKey: input.resolveProjectionUserKey,\n              stillCurrent: input.sync.stillCurrent,\n              warmReferencedPrincipalPolicies:\n                input.sync.warmReferencedPrincipalPolicies,\n            }),\n        },\n      }\n    : input.materializedPlan;\n  // Keep the submitted request, keys, and response frozen. Only refreshed,\n  // verified evidence may be added; this retry never resubmits outgoing edits.\n  return submittedDocumentSyncResult({\n    ...input,\n    materializedPlan,\n    writerProjection,\n  });\n}\n\nexport async function resolveSubmittedDocumentSyncResult(\n  input: SubmittedDocumentSyncResultInput,\n): Promise<SyncRemoteDocumentResult | null> {\n  try {\n    return await submittedDocumentSyncResult(input);\n  } catch (error) {\n    const missingDependency =\n      isKeyingVerificationError(error) && error.code === \"missing_dependency\";\n    if (\n      !missingDependency &&\n      (input.sync.historyMode !== \"raw\" ||\n        !(error instanceof DocumentRawHistoryUnavailableError))\n    ) {\n      throw error;\n    }\n    return retrySubmittedResponseWithFreshProjection(\n      input,\n      error,\n      missingDependency,\n    );\n  }\n}\n"]}

package/workflows/documents/sync/syncTrace.js

@@ -0,0 +1,148 @@
+/**
+ * Production-safe trace lines for the document sync workflow.
+ *
+ * Every line is assembled here from a CLOSED vocabulary — strict document
+ * UUIDs, integers, and enumerated reason/action/code values that appear as
+ * literal alternatives in the pattern below. No decrypted content, names,
+ * key material, or free-form error text can enter a line, and because the
+ * System Monitor validates LINES (it cannot know their emitter), the pattern
+ * itself rejects any token outside that vocabulary rather than trusting
+ * emitter-side sanitization. The format tests assert emitter output and
+ * pattern stay in lockstep, including that leaks fail closed.
+ */
+import { DOCUMENT_NOT_FOUND_ERROR_CODE, DOCUMENT_PROJECTION_ERROR_CODES, DOCUMENT_SYNC_ERROR_CODES, } from "../../../internal/validators/response/index.js";
+/**
+ * Enumerated, clipboard-safe reasons an ancestor repair abandons a pass. The
+ * emitter maps to these rather than passing the error's prose through, so the
+ * line stays inside the closed vocabulary the System Monitor validates.
+ */
+export const ANCESTOR_REPAIR_ABANDON_REASONS = [
+    "blocked",
+    "depth-budget",
+    "inaccessible",
+    "peer-rotation",
+    "refused",
+    "unrefreshable",
+];
+/** Fixed thrown messages mapped to enumerated, clipboard-safe reasons. */
+const HEAL_BLOCKED_REASONS = [
+    [
+        "Document content-key bundle is stale and no rotation snapshot is available",
+        "snapshot-unavailable",
+    ],
+    [
+        "Document stale-bundle recovery requires a full-history rotation snapshot",
+        "snapshot-not-full-history",
+    ],
+    ["Document stale-bundle recovery snapshot is empty", "snapshot-empty"],
+    [
+        "Document stale-bundle recovery snapshot does not cover a queued rotation checkpoint",
+        "checkpoint-uncovered",
+    ],
+    ["Document content-key re-wrap KEK is unavailable", "rewrap-kek-unavailable"],
+    [
+        "Document stale bundle manifest is missing from the projection history",
+        "stale-manifest-missing",
+    ],
+    ["Document content key could not be unwrapped", "content-key-unwrap-failed"],
+];
+/**
+ * Only the protocol's own coded values are copied; any other server-provided
+ * string — even one that happens to look like a code — is collapsed to
+ * "other" so a hostile or buggy server can never smuggle text into a report.
+ */
+const SAFE_FAILURE_CODES = new Set([
+    ...Object.values(DOCUMENT_SYNC_ERROR_CODES),
+    ...Object.values(DOCUMENT_PROJECTION_ERROR_CODES),
+    DOCUMENT_NOT_FOUND_ERROR_CODE,
+]);
+const TRACE_ACTIONS = [
+    "recover-update-ids",
+    "regenerate-checkpoints",
+    "retry",
+    "stop",
+];
+// Every vocabulary below is enumerated into the pattern as literals; the only
+// open-ended slots are a strict UUID and decimal counts.
+const UUID_FRAGMENT = "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}";
+const REASON_FRAGMENT = HEAL_BLOCKED_REASONS.map(([, reason]) => reason).join("|");
+const ABANDON_REASON_FRAGMENT = ANCESTOR_REPAIR_ABANDON_REASONS.join("|");
+const ACTION_FRAGMENT = TRACE_ACTIONS.join("|");
+const CODE_FRAGMENT = [...SAFE_FAILURE_CODES, "none", "other"].join("|");
+/**
+ * Unanchored alternatives for composition into a larger allowlist (the
+ * System Monitor wraps this in its own prefix/suffix anchors). Use
+ * DOCUMENT_SYNC_TRACE_PATTERN to validate a complete line.
+ */
+export const DOCUMENT_SYNC_TRACE_FRAGMENT = [
+    `document sync blocked document=${UUID_FRAGMENT}`,
+    `document sync stale bundle document=${UUID_FRAGMENT} epoch=\\d+ pending=\\d+`,
+    `document sync heal planned document=${UUID_FRAGMENT} fromEpoch=\\d+ toEpoch=\\d+ updates=\\d+ heldBack=\\d+`,
+    `document sync stale read document=${UUID_FRAGMENT} epoch=\\d+`,
+    `document sync checkpoint regeneration document=${UUID_FRAGMENT} checkpoints=\\d+ updates=\\d+`,
+    `document sync heal blocked document=${UUID_FRAGMENT} reason=(?:${REASON_FRAGMENT})`,
+    `document sync submit failed document=${UUID_FRAGMENT} status=(?:\\d+|none) code=(?:${CODE_FRAGMENT}) action=(?:${ACTION_FRAGMENT})`,
+    `document sync projection failed document=${UUID_FRAGMENT} status=(?:\\d+|none) code=(?:${CODE_FRAGMENT})`,
+    `document sync ancestor repair abandoned document=${UUID_FRAGMENT} reason=(?:${ABANDON_REASON_FRAGMENT})`,
+    `document sync healed document=${UUID_FRAGMENT} epoch=\\d+ accepted=\\d+`,
+]
+    .map((alternative) => `(?:${alternative})`)
+    .join("|");
+/** Anchored validator: a string is a trace line in full, or not at all. */
+export const DOCUMENT_SYNC_TRACE_PATTERN = new RegExp(`^(?:${DOCUMENT_SYNC_TRACE_FRAGMENT})$`, "u");
+/**
+ * Classifies a plan-build failure into an enumerated reason, or null when the
+ * message is not one of the fixed protocol strings — unknown errors fail
+ * closed and emit nothing rather than leaking free text.
+ */
+function classifyHealBlockedReason(error) {
+    const message = error instanceof Error ? error.message : "";
+    for (const [prefix, reason] of HEAL_BLOCKED_REASONS) {
+        if (message.startsWith(prefix)) {
+            return reason;
+        }
+    }
+    return null;
+}
+function safeCode(code) {
+    if (code === undefined) {
+        return "none";
+    }
+    return SAFE_FAILURE_CODES.has(code) ? code : "other";
+}
+function safeStatus(status) {
+    return status !== null && Number.isInteger(status) && status >= 0
+        ? String(status)
+        : "none";
+}
+export function traceStaleBundle(emit, input) {
+    emit?.(`document sync stale bundle document=${input.documentId} epoch=${input.epoch} pending=${input.pending}`);
+}
+export function traceHealPlanned(emit, input) {
+    emit?.(`document sync heal planned document=${input.documentId} fromEpoch=${input.fromEpoch} toEpoch=${input.toEpoch} updates=${input.updates} heldBack=${input.heldBack}`);
+}
+export function traceStaleRead(emit, input) {
+    emit?.(`document sync stale read document=${input.documentId} epoch=${input.epoch}`);
+}
+export function traceCheckpointRegeneration(emit, input) {
+    emit?.(`document sync checkpoint regeneration document=${input.documentId} checkpoints=${input.checkpoints} updates=${input.updates}`);
+}
+export function traceHealBlocked(emit, input) {
+    const reason = classifyHealBlockedReason(input.error);
+    if (reason !== null) {
+        emit?.(`document sync heal blocked document=${input.documentId} reason=${reason}`);
+    }
+}
+export function traceSubmitFailed(emit, input) {
+    emit?.(`document sync submit failed document=${input.documentId} status=${safeStatus(input.status)} code=${safeCode(input.code)} action=${input.action}`);
+}
+export function traceAncestorRepairAbandoned(emit, input) {
+    emit?.(`document sync ancestor repair abandoned document=${input.documentId} reason=${input.reason}`);
+}
+export function traceProjectionFailed(emit, input) {
+    emit?.(`document sync projection failed document=${input.documentId} status=${safeStatus(input.status)} code=${safeCode(input.code)}`);
+}
+export function traceHealed(emit, input) {
+    emit?.(`document sync healed document=${input.documentId} epoch=${input.epoch} accepted=${input.accepted}`);
+}
+//# sourceMappingURL=syncTrace.js.map