@tearleads/client-sdk 0.1.62 → 0.1.64

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