@tearleads/client-sdk 0.1.61 → 0.1.63

package/workflows/documents/syncFailures/index.js

@@ -0,0 +1,252 @@
+import { DOCUMENT_SYNC_ERROR_CODES, } from "../../../internal/validators/response/index.js";
+import { isUpstreamDeletedDocumentSyncFailure, submitDocumentSync, } from "../../../data/documents/shared/responses.js";
+import { InvalidDocumentSyncPullContinuationError, } from "../../../data/documents/shared/syncPagination.js";
+import { traceProjectionFailed, traceSubmitFailed, } from "../sync/syncTrace.js";
+import { canRecoverDocumentUpdateIdConflict, canRetryDocumentSyncConflict, handleUpstreamDeletedDocumentSyncFailure, isCheckpointCoverageConflict, shouldRetrySyncWithFreshWriterProjection, } from "./syncFailureClassification.js";
+import { recoverDocumentSyncPolicyRepair } from "./syncPolicyRepair.js";
+const REMOTE_DOCUMENT_DELETED = Symbol("remoteDocumentDeleted");
+export function assertRawContinuationCanRetry(historyMode, pullContinuation) {
+    if (historyMode === "raw" && pullContinuation !== undefined) {
+        throw new InvalidDocumentSyncPullContinuationError("Document raw-history continuation became stale");
+    }
+}
+async function resolveFailedDocumentSyncAction(input) {
+    const action = await classifyFailedDocumentSyncAction(input);
+    traceSubmitFailed(input.onSyncTrace, {
+        action: action === "retry" || action === "stop"
+            ? action
+            : action.kind === "recover_update_id_conflict"
+                ? "recover-update-ids"
+                : "regenerate-checkpoints",
+        code: input.failure.code,
+        documentId: input.documentId,
+        status: input.failure.status,
+    });
+    return action;
+}
+async function classifyFailedDocumentSyncAction(input) {
+    if (await handleUpstreamDeletedDocumentSyncFailure({
+        documentId: input.documentId,
+        failure: input.failure,
+        onRemoteDocumentDeleted: input.onRemoteDocumentDeleted,
+    })) {
+        return "stop";
+    }
+    if (canRetryDocumentSyncConflict({
+        attempt: input.attempt,
+        failure: input.failure,
+        maxAttempts: input.maxAttempts,
+    })) {
+        return "retry";
+    }
+    // The write rolled back whole. Its inline repairs would have stranded a
+    // level above a directly granted container, and a flat rekey list cannot say
+    // what each must carry: the retry commits them standalone instead.
+    if (input.attempt < input.maxAttempts &&
+        input.onInlineRepairRefused &&
+        input.failure.code === DOCUMENT_SYNC_ERROR_CODES.descendantRekeysRequired) {
+        input.onInlineRepairRefused();
+        return "retry";
+    }
+    if (canRecoverDocumentUpdateIdConflict({
+        attempt: input.attempt,
+        failure: input.failure,
+        maxAttempts: input.maxAttempts,
+        pendingUpdateCount: input.pendingUpdates.length,
+    })) {
+        return {
+            kind: "recover_update_id_conflict",
+            recoveryPendingUpdatesById: new Map(input.pendingUpdates.map((update) => [update.id, update])),
+        };
+    }
+    if (input.attempt < input.maxAttempts &&
+        input.canRegenerateQueuedCheckpoints === true &&
+        isCheckpointCoverageConflict(input.failure)) {
+        return { kind: "regenerate_queued_checkpoints" };
+    }
+    input.failure.report();
+    await input.onTerminalSubmitFailure?.(input.failure);
+    return "stop";
+}
+async function submitDocumentSyncAttempt(input) {
+    if (input.stillCurrent?.() === false)
+        return "cancelled";
+    const submitted = await submitDocumentSync({
+        apiClient: input.apiClient,
+        expectedCommitLsnMode: input.expectedCommitLsnMode,
+        plan: input.plan,
+    });
+    if (input.stillCurrent?.() === false)
+        return "cancelled";
+    if (!submitted) {
+        return "stop";
+    }
+    if (submitted.ok) {
+        return {
+            kind: "completed",
+            pullComplete: submitted.pullComplete,
+            response: submitted.response,
+        };
+    }
+    await recoverDocumentSyncPolicyRepair({
+        failure: submitted,
+        plan: input.plan,
+        stillCurrent: input.stillCurrent,
+        warmReferencedPrincipalPolicies: input.warmReferencedPrincipalPolicies,
+    });
+    if (input.stillCurrent?.() === false)
+        return "cancelled";
+    return resolveFailedDocumentSyncAction({
+        attempt: input.attempt,
+        canRegenerateQueuedCheckpoints: input.canRegenerateQueuedCheckpoints,
+        documentId: input.documentId,
+        failure: submitted,
+        maxAttempts: input.maxAttempts,
+        onInlineRepairRefused: input.onInlineRepairRefused,
+        onRemoteDocumentDeleted: input.onRemoteDocumentDeleted,
+        onSyncTrace: input.onSyncTrace,
+        onTerminalSubmitFailure: input.onTerminalSubmitFailure,
+        pendingUpdates: input.pendingUpdates,
+    });
+}
+export async function submitDocumentSyncAttemptIfAllowed(input) {
+    const { failureBlocksQueuedWrites, isRemoteSyncBlocked, onOutgoingUpdatesMaterialized, ...submissionInput } = input;
+    const hasRemoteWrites = input.plan.request.outgoingUpdates.length > 0 ||
+        (input.plan.request.containerRekeys?.length ?? 0) > 0;
+    if (hasRemoteWrites && isRemoteSyncBlocked?.(input.plan.organizationId)) {
+        return "blocked";
+    }
+    if (input.stillCurrent?.() === false)
+        return "cancelled";
+    onOutgoingUpdatesMaterialized?.(input.plan.request.outgoingUpdates.map(({ id }) => id));
+    return submitDocumentSyncAttempt({
+        ...submissionInput,
+        // A read-only pass carries no writes, so a terminal failure describes a
+        // pull, not queued local data — recording it would flag the next local
+        // edit as failed before it was ever attempted. A cursor continuation and
+        // update-id recovery both submit an empty request while durable rows still
+        // exist; a terminal 403 there IS what blocks the queued edits.
+        onTerminalSubmitFailure: hasRemoteWrites || failureBlocksQueuedWrites
+            ? submissionInput.onTerminalSubmitFailure
+            : undefined,
+    });
+}
+async function resolveDocumentSyncWriterProjection(input) {
+    if (input.stillCurrent?.() === false)
+        return null;
+    if (input.reusableWriterProjection) {
+        return input.reusableWriterProjection;
+    }
+    const result = await input.apiClient.getDocumentWriterProjectionResult(input.documentId, { reportErrors: false });
+    if (input.stillCurrent?.() === false)
+        return null;
+    if (result.ok) {
+        return result.data;
+    }
+    if (isUpstreamDeletedDocumentSyncFailure(result)) {
+        return REMOTE_DOCUMENT_DELETED;
+    }
+    traceProjectionFailed(input.onSyncTrace, {
+        code: result.code,
+        documentId: input.documentId,
+        status: result.status,
+    });
+    result.report();
+    await input.onTerminalFailure?.(result);
+    return null;
+}
+export async function retrySyncPlan(input) {
+    try {
+        return [
+            await input.buildWithProjection(input.writerProjection),
+            input.writerProjection,
+        ];
+    }
+    catch (error) {
+        if (!input.apiClient.evictDocumentWriterProjection ||
+            !shouldRetrySyncWithFreshWriterProjection(error)) {
+            throw error;
+        }
+    }
+    if (input.stillCurrent?.() === false)
+        return null;
+    // Only this document's projection was stale; evict just it so unrelated
+    // documents keep their warm cache instead of a global wipe.
+    input.apiClient.evictDocumentWriterProjection?.(input.documentId);
+    const writerProjection = await resolveDocumentSyncWriterProjection({
+        apiClient: input.apiClient,
+        documentId: input.documentId,
+        onSyncTrace: input.onSyncTrace,
+        onTerminalFailure: input.onTerminalFailure,
+        reusableWriterProjection: null,
+        stillCurrent: input.stillCurrent,
+    });
+    if (input.stillCurrent?.() === false)
+        return null;
+    if (writerProjection === REMOTE_DOCUMENT_DELETED) {
+        await input.onRemoteDocumentDeleted?.({ documentId: input.documentId });
+        return null;
+    }
+    if (!writerProjection) {
+        return null;
+    }
+    return [await input.buildWithProjection(writerProjection), writerProjection];
+}
+/**
+ * Resolves the writer projection for one sync attempt, converting the two
+ * unrecoverable outcomes into an abandoned (null) result with a named reason
+ * so callers that turn a null sync into their own error can surface the real
+ * cause.
+ */
+export async function resolveSyncAttemptWriterProjection(input) {
+    const writerProjection = await resolveDocumentSyncWriterProjection(input);
+    if (input.stillCurrent?.() === false)
+        return null;
+    if (writerProjection === REMOTE_DOCUMENT_DELETED) {
+        await input.onRemoteDocumentDeleted?.({ documentId: input.documentId });
+        if (input.stillCurrent?.() !== false) {
+            input.onSyncAbandoned?.("the remote document was deleted");
+        }
+        return null;
+    }
+    if (!writerProjection) {
+        input.onSyncAbandoned?.("the document writer projection could not be fetched");
+        return null;
+    }
+    return writerProjection;
+}
+export async function refreshSyncAttemptWriterProjection(input) {
+    const { onRemoteDocumentDeleted, unavailableError, ...resolutionInput } = input;
+    if (input.stillCurrent?.() === false)
+        return null;
+    if (input.apiClient.evictDocumentWriterProjection) {
+        input.apiClient.evictDocumentWriterProjection(input.documentId);
+    }
+    else {
+        input.apiClient.clearWriterProjectionCaches?.();
+    }
+    let remoteDocumentDeleted = false;
+    const writerProjection = await resolveSyncAttemptWriterProjection({
+        ...resolutionInput,
+        onRemoteDocumentDeleted: async (deleted) => {
+            remoteDocumentDeleted = true;
+            await onRemoteDocumentDeleted?.(deleted);
+        },
+        reusableWriterProjection: null,
+    });
+    if (!writerProjection &&
+        unavailableError !== undefined &&
+        !remoteDocumentDeleted &&
+        input.stillCurrent?.() !== false) {
+        throw unavailableError;
+    }
+    return writerProjection;
+}
+export async function retrySyncPlanOrAbandon(input) {
+    const planned = await retrySyncPlan(input);
+    if (!planned && input.stillCurrent?.() !== false) {
+        input.onSyncAbandoned?.("a sync plan could not be built against the current projection");
+    }
+    return planned;
+}
+//# sourceMappingURL=index.js.map

package/workflows/documents/syncFailures/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  DOCUMENT_SYNC_ERROR_CODES,\n  type DocumentSyncResponse,\n  type DocumentWriterProjectionResponse,\n} from \"@tearleads/validators/response\";\nimport {\n  isUpstreamDeletedDocumentSyncFailure,\n  submitDocumentSync,\n} from \"../../../data/documents/shared/responses\";\nimport {\n  type DocumentSyncCommitLsnMode,\n  type DocumentSyncPullContinuation,\n  InvalidDocumentSyncPullContinuationError,\n} from \"../../../data/documents/shared/syncPagination\";\nimport type {\n  DocumentSyncApi,\n  DocumentSyncPlan,\n  DocumentSyncSubmitFailure,\n  MaterializedDocumentSyncPlan,\n} from \"../../../data/documents/shared/types\";\nimport type { ReferencedPrincipalPolicyWarmer } from \"../../../data/keyingProjectionVerification\";\nimport type { PendingUpdateRecord } from \"../../../data/sqlite/documentPersistence\";\nimport {\n  type DocumentSyncTraceEmitter,\n  traceProjectionFailed,\n  traceSubmitFailed,\n} from \"../sync/syncTrace\";\nimport {\n  canRecoverDocumentUpdateIdConflict,\n  canRetryDocumentSyncConflict,\n  handleUpstreamDeletedDocumentSyncFailure,\n  isCheckpointCoverageConflict,\n  type RemoteDocumentDeletionHandler,\n  shouldRetrySyncWithFreshWriterProjection,\n  type TerminalSubmitFailureHandler,\n} from \"./syncFailureClassification\";\nimport { recoverDocumentSyncPolicyRepair } from \"./syncPolicyRepair\";\n\nconst REMOTE_DOCUMENT_DELETED = Symbol(\"remoteDocumentDeleted\");\n\nexport function assertRawContinuationCanRetry(\n  historyMode: \"raw\" | undefined,\n  pullContinuation: DocumentSyncPullContinuation | undefined,\n): void {\n  if (historyMode === \"raw\" && pullContinuation !== undefined) {\n    throw new InvalidDocumentSyncPullContinuationError(\n      \"Document raw-history continuation became stale\",\n    );\n  }\n}\n\ntype DocumentWriterProjectionResolution =\n  | DocumentWriterProjectionResponse\n  | typeof REMOTE_DOCUMENT_DELETED\n  | null;\n\ntype FailedDocumentSyncAction =\n  | \"retry\"\n  | \"stop\"\n  | {\n      readonly kind: \"recover_update_id_conflict\";\n      readonly recoveryPendingUpdatesById: Map<string, PendingUpdateRecord>;\n    }\n  | { readonly kind: \"regenerate_queued_checkpoints\" };\n\ntype DocumentSyncAttemptSubmission =\n  | {\n      readonly kind: \"completed\";\n      readonly pullComplete: boolean;\n      readonly response: DocumentSyncResponse;\n    }\n  | FailedDocumentSyncAction\n  | \"cancelled\"\n  | \"blocked\";\n\nasync function resolveFailedDocumentSyncAction(input: {\n  attempt: number;\n  canRegenerateQueuedCheckpoints?: boolean | undefined;\n  documentId: string;\n  failure: DocumentSyncSubmitFailure;\n  maxAttempts: number;\n  onInlineRepairRefused?: (() => void) | undefined;\n  onRemoteDocumentDeleted?: RemoteDocumentDeletionHandler | undefined;\n  onSyncTrace?: DocumentSyncTraceEmitter | undefined;\n  onTerminalSubmitFailure?: TerminalSubmitFailureHandler | undefined;\n  pendingUpdates: readonly PendingUpdateRecord[];\n}): Promise<FailedDocumentSyncAction> {\n  const action = await classifyFailedDocumentSyncAction(input);\n  traceSubmitFailed(input.onSyncTrace, {\n    action:\n      action === \"retry\" || action === \"stop\"\n        ? action\n        : action.kind === \"recover_update_id_conflict\"\n          ? \"recover-update-ids\"\n          : \"regenerate-checkpoints\",\n    code: input.failure.code,\n    documentId: input.documentId,\n    status: input.failure.status,\n  });\n  return action;\n}\n\nasync function classifyFailedDocumentSyncAction(input: {\n  attempt: number;\n  canRegenerateQueuedCheckpoints?: boolean | undefined;\n  documentId: string;\n  failure: DocumentSyncSubmitFailure;\n  maxAttempts: number;\n  onInlineRepairRefused?: (() => void) | undefined;\n  onRemoteDocumentDeleted?: RemoteDocumentDeletionHandler | undefined;\n  onTerminalSubmitFailure?: TerminalSubmitFailureHandler | undefined;\n  pendingUpdates: readonly PendingUpdateRecord[];\n}): Promise<FailedDocumentSyncAction> {\n  if (\n    await handleUpstreamDeletedDocumentSyncFailure({\n      documentId: input.documentId,\n      failure: input.failure,\n      onRemoteDocumentDeleted: input.onRemoteDocumentDeleted,\n    })\n  ) {\n    return \"stop\";\n  }\n\n  if (\n    canRetryDocumentSyncConflict({\n      attempt: input.attempt,\n      failure: input.failure,\n      maxAttempts: input.maxAttempts,\n    })\n  ) {\n    return \"retry\";\n  }\n\n  // The write rolled back whole. Its inline repairs would have stranded a\n  // level above a directly granted container, and a flat rekey list cannot say\n  // what each must carry: the retry commits them standalone instead.\n  if (\n    input.attempt < input.maxAttempts &&\n    input.onInlineRepairRefused &&\n    input.failure.code === DOCUMENT_SYNC_ERROR_CODES.descendantRekeysRequired\n  ) {\n    input.onInlineRepairRefused();\n    return \"retry\";\n  }\n\n  if (\n    canRecoverDocumentUpdateIdConflict({\n      attempt: input.attempt,\n      failure: input.failure,\n      maxAttempts: input.maxAttempts,\n      pendingUpdateCount: input.pendingUpdates.length,\n    })\n  ) {\n    return {\n      kind: \"recover_update_id_conflict\",\n      recoveryPendingUpdatesById: new Map(\n        input.pendingUpdates.map((update) => [update.id, update]),\n      ),\n    };\n  }\n\n  if (\n    input.attempt < input.maxAttempts &&\n    input.canRegenerateQueuedCheckpoints === true &&\n    isCheckpointCoverageConflict(input.failure)\n  ) {\n    return { kind: \"regenerate_queued_checkpoints\" };\n  }\n\n  input.failure.report();\n  await input.onTerminalSubmitFailure?.(input.failure);\n  return \"stop\";\n}\n\nasync function submitDocumentSyncAttempt(input: {\n  apiClient: DocumentSyncApi;\n  attempt: number;\n  canRegenerateQueuedCheckpoints?: boolean | undefined;\n  documentId: string;\n  expectedCommitLsnMode?: DocumentSyncCommitLsnMode | undefined;\n  maxAttempts: number;\n  onInlineRepairRefused?: (() => void) | undefined;\n  onRemoteDocumentDeleted?: RemoteDocumentDeletionHandler | undefined;\n  onSyncTrace?: DocumentSyncTraceEmitter | undefined;\n  onTerminalSubmitFailure?: TerminalSubmitFailureHandler | undefined;\n  pendingUpdates: readonly PendingUpdateRecord[];\n  plan: DocumentSyncPlan;\n  stillCurrent?: (() => boolean) | undefined;\n  warmReferencedPrincipalPolicies?: ReferencedPrincipalPolicyWarmer | undefined;\n}): Promise<DocumentSyncAttemptSubmission> {\n  if (input.stillCurrent?.() === false) return \"cancelled\";\n  const submitted = await submitDocumentSync({\n    apiClient: input.apiClient,\n    expectedCommitLsnMode: input.expectedCommitLsnMode,\n    plan: input.plan,\n  });\n  if (input.stillCurrent?.() === false) return \"cancelled\";\n  if (!submitted) {\n    return \"stop\";\n  }\n  if (submitted.ok) {\n    return {\n      kind: \"completed\",\n      pullComplete: submitted.pullComplete,\n      response: submitted.response,\n    };\n  }\n\n  await recoverDocumentSyncPolicyRepair({\n    failure: submitted,\n    plan: input.plan,\n    stillCurrent: input.stillCurrent,\n    warmReferencedPrincipalPolicies: input.warmReferencedPrincipalPolicies,\n  });\n  if (input.stillCurrent?.() === false) return \"cancelled\";\n\n  return resolveFailedDocumentSyncAction({\n    attempt: input.attempt,\n    canRegenerateQueuedCheckpoints: input.canRegenerateQueuedCheckpoints,\n    documentId: input.documentId,\n    failure: submitted,\n    maxAttempts: input.maxAttempts,\n    onInlineRepairRefused: input.onInlineRepairRefused,\n    onRemoteDocumentDeleted: input.onRemoteDocumentDeleted,\n    onSyncTrace: input.onSyncTrace,\n    onTerminalSubmitFailure: input.onTerminalSubmitFailure,\n    pendingUpdates: input.pendingUpdates,\n  });\n}\n\nexport async function submitDocumentSyncAttemptIfAllowed(\n  input: Parameters<typeof submitDocumentSyncAttempt>[0] & {\n    isRemoteSyncBlocked?: ((organizationId: string) => boolean) | undefined;\n    onOutgoingUpdatesMaterialized?:\n      | ((updateIds: readonly string[]) => void)\n      | undefined;\n    failureBlocksQueuedWrites?: boolean | undefined;\n  },\n): Promise<DocumentSyncAttemptSubmission> {\n  const {\n    failureBlocksQueuedWrites,\n    isRemoteSyncBlocked,\n    onOutgoingUpdatesMaterialized,\n    ...submissionInput\n  } = input;\n  const hasRemoteWrites =\n    input.plan.request.outgoingUpdates.length > 0 ||\n    (input.plan.request.containerRekeys?.length ?? 0) > 0;\n  if (hasRemoteWrites && isRemoteSyncBlocked?.(input.plan.organizationId)) {\n    return \"blocked\";\n  }\n  if (input.stillCurrent?.() === false) return \"cancelled\";\n\n  onOutgoingUpdatesMaterialized?.(\n    input.plan.request.outgoingUpdates.map(({ id }) => id),\n  );\n\n  return submitDocumentSyncAttempt({\n    ...submissionInput,\n    // A read-only pass carries no writes, so a terminal failure describes a\n    // pull, not queued local data — recording it would flag the next local\n    // edit as failed before it was ever attempted. A cursor continuation and\n    // update-id recovery both submit an empty request while durable rows still\n    // exist; a terminal 403 there IS what blocks the queued edits.\n    onTerminalSubmitFailure:\n      hasRemoteWrites || failureBlocksQueuedWrites\n        ? submissionInput.onTerminalSubmitFailure\n        : undefined,\n  });\n}\n\nasync function resolveDocumentSyncWriterProjection(input: {\n  apiClient: DocumentSyncApi;\n  documentId: string;\n  onSyncTrace?: DocumentSyncTraceEmitter | undefined;\n  /**\n   * Invoked when the projection fetch fails terminally. Write-bearing sync\n   * passes persist this: without a writer projection their queued writes can\n   * never submit, so the failure (e.g. a 403 after access revocation) is what\n   * the write queue should surface.\n   */\n  onTerminalFailure?: TerminalSubmitFailureHandler | undefined;\n  reusableWriterProjection: DocumentWriterProjectionResponse | null;\n  stillCurrent?: (() => boolean) | undefined;\n}): Promise<DocumentWriterProjectionResolution> {\n  if (input.stillCurrent?.() === false) return null;\n  if (input.reusableWriterProjection) {\n    return input.reusableWriterProjection;\n  }\n\n  const result = await input.apiClient.getDocumentWriterProjectionResult(\n    input.documentId,\n    { reportErrors: false },\n  );\n  if (input.stillCurrent?.() === false) return null;\n  if (result.ok) {\n    return result.data;\n  }\n  if (isUpstreamDeletedDocumentSyncFailure(result)) {\n    return REMOTE_DOCUMENT_DELETED;\n  }\n  traceProjectionFailed(input.onSyncTrace, {\n    code: result.code,\n    documentId: input.documentId,\n    status: result.status,\n  });\n  result.report();\n  await input.onTerminalFailure?.(result);\n  return null;\n}\n\nexport async function retrySyncPlan(input: {\n  apiClient: DocumentSyncApi;\n  buildWithProjection: (\n    projection: DocumentWriterProjectionResponse,\n  ) => Promise<MaterializedDocumentSyncPlan>;\n  documentId: string;\n  onRemoteDocumentDeleted?: RemoteDocumentDeletionHandler | undefined;\n  onSyncTrace?: DocumentSyncTraceEmitter | undefined;\n  onTerminalFailure?: TerminalSubmitFailureHandler | undefined;\n  stillCurrent?: (() => boolean) | undefined;\n  writerProjection: DocumentWriterProjectionResponse;\n}): Promise<\n  | readonly [MaterializedDocumentSyncPlan, DocumentWriterProjectionResponse]\n  | null\n> {\n  try {\n    return [\n      await input.buildWithProjection(input.writerProjection),\n      input.writerProjection,\n    ];\n  } catch (error) {\n    if (\n      !input.apiClient.evictDocumentWriterProjection ||\n      !shouldRetrySyncWithFreshWriterProjection(error)\n    ) {\n      throw error;\n    }\n  }\n  if (input.stillCurrent?.() === false) return null;\n\n  // Only this document's projection was stale; evict just it so unrelated\n  // documents keep their warm cache instead of a global wipe.\n  input.apiClient.evictDocumentWriterProjection?.(input.documentId);\n  const writerProjection = await resolveDocumentSyncWriterProjection({\n    apiClient: input.apiClient,\n    documentId: input.documentId,\n    onSyncTrace: input.onSyncTrace,\n    onTerminalFailure: input.onTerminalFailure,\n    reusableWriterProjection: null,\n    stillCurrent: input.stillCurrent,\n  });\n  if (input.stillCurrent?.() === false) return null;\n  if (writerProjection === REMOTE_DOCUMENT_DELETED) {\n    await input.onRemoteDocumentDeleted?.({ documentId: input.documentId });\n    return null;\n  }\n  if (!writerProjection) {\n    return null;\n  }\n\n  return [await input.buildWithProjection(writerProjection), writerProjection];\n}\n\n/**\n * Resolves the writer projection for one sync attempt, converting the two\n * unrecoverable outcomes into an abandoned (null) result with a named reason\n * so callers that turn a null sync into their own error can surface the real\n * cause.\n */\nexport async function resolveSyncAttemptWriterProjection(input: {\n  apiClient: DocumentSyncApi;\n  documentId: string;\n  onRemoteDocumentDeleted?: RemoteDocumentDeletionHandler | undefined;\n  onSyncAbandoned?: ((reason: string) => void) | undefined;\n  onSyncTrace?: DocumentSyncTraceEmitter | undefined;\n  onTerminalFailure?: TerminalSubmitFailureHandler | undefined;\n  reusableWriterProjection: DocumentWriterProjectionResponse | null;\n  stillCurrent?: (() => boolean) | undefined;\n}): Promise<DocumentWriterProjectionResponse | null> {\n  const writerProjection = await resolveDocumentSyncWriterProjection(input);\n  if (input.stillCurrent?.() === false) return null;\n  if (writerProjection === REMOTE_DOCUMENT_DELETED) {\n    await input.onRemoteDocumentDeleted?.({ documentId: input.documentId });\n    if (input.stillCurrent?.() !== false) {\n      input.onSyncAbandoned?.(\"the remote document was deleted\");\n    }\n    return null;\n  }\n  if (!writerProjection) {\n    input.onSyncAbandoned?.(\n      \"the document writer projection could not be fetched\",\n    );\n    return null;\n  }\n  return writerProjection;\n}\n\nexport async function refreshSyncAttemptWriterProjection(\n  input: Omit<\n    Parameters<typeof resolveSyncAttemptWriterProjection>[0],\n    \"reusableWriterProjection\"\n  > & { unavailableError?: unknown },\n): Promise<DocumentWriterProjectionResponse | null> {\n  const { onRemoteDocumentDeleted, unavailableError, ...resolutionInput } =\n    input;\n  if (input.stillCurrent?.() === false) return null;\n  if (input.apiClient.evictDocumentWriterProjection) {\n    input.apiClient.evictDocumentWriterProjection(input.documentId);\n  } else {\n    input.apiClient.clearWriterProjectionCaches?.();\n  }\n  let remoteDocumentDeleted = false;\n  const writerProjection = await resolveSyncAttemptWriterProjection({\n    ...resolutionInput,\n    onRemoteDocumentDeleted: async (deleted) => {\n      remoteDocumentDeleted = true;\n      await onRemoteDocumentDeleted?.(deleted);\n    },\n    reusableWriterProjection: null,\n  });\n  if (\n    !writerProjection &&\n    unavailableError !== undefined &&\n    !remoteDocumentDeleted &&\n    input.stillCurrent?.() !== false\n  ) {\n    throw unavailableError;\n  }\n  return writerProjection;\n}\n\nexport async function retrySyncPlanOrAbandon(input: {\n  apiClient: DocumentSyncApi;\n  buildWithProjection: (\n    projection: DocumentWriterProjectionResponse,\n  ) => Promise<MaterializedDocumentSyncPlan>;\n  documentId: string;\n  onRemoteDocumentDeleted?: RemoteDocumentDeletionHandler | undefined;\n  onSyncAbandoned?: ((reason: string) => void) | undefined;\n  onSyncTrace?: DocumentSyncTraceEmitter | undefined;\n  onTerminalFailure?: TerminalSubmitFailureHandler | undefined;\n  stillCurrent?: (() => boolean) | undefined;\n  writerProjection: DocumentWriterProjectionResponse;\n}): Promise<\n  | readonly [MaterializedDocumentSyncPlan, DocumentWriterProjectionResponse]\n  | null\n> {\n  const planned = await retrySyncPlan(input);\n  if (!planned && input.stillCurrent?.() !== false) {\n    input.onSyncAbandoned?.(\n      \"a sync plan could not be built against the current projection\",\n    );\n  }\n  return planned;\n}\n"]}

package/workflows/documents/syncFailures/syncAbandon.js

@@ -0,0 +1,51 @@
+import { traceAncestorRepairAbandoned } from "../sync/syncTrace.js";
+import { DocumentAncestorRepairAbandonedError } from "./syncRepairAbandon.js";
+export function abandonBlockedSync(input) {
+    input.onSyncTrace?.(`document sync blocked document=${input.documentId}`);
+    input.onSyncAbandoned?.("blocked");
+    return null;
+}
+export function abandonAncestorRepair(input, error) {
+    // Trace as well as abandon: the store's onSyncAbandoned only parks the
+    // document, and this path may already have issued server-side rekeys, so
+    // abandoning untraced would leave a retrying loop with no way to see it.
+    traceAncestorRepairAbandoned(input.onSyncTrace, {
+        documentId: input.documentId,
+        reason: error.reason,
+    });
+    input.onSyncAbandoned?.(error.reason);
+    return null;
+}
+/**
+ * The stale ancestor is one this writer can neither re-key nor be given the
+ * key for, and one refetch has already confirmed nobody repaired it yet. The
+ * writes stay queued; the durable row tells the write queue why, and the
+ * dependent-path hint that follows the repair re-arms the pass.
+ */
+export async function abandonInaccessibleAncestorRepair(input, error) {
+    await input.onTerminalSubmitFailure?.({
+        code: "document_ancestor_repair_inaccessible",
+        message: error.message,
+        ok: false,
+        report: () => undefined,
+        status: null,
+    });
+    return abandonAncestorRepair(input, new DocumentAncestorRepairAbandonedError("inaccessible"));
+}
+export function abandonAfterRetryableConflicts(input) {
+    input.onSyncAbandoned?.("every sync attempt hit a retryable conflict");
+    return null;
+}
+export async function abandonOversizedSyncPlan(input, error) {
+    const failure = {
+        code: "document_sync_request_too_large",
+        message: error.message,
+        ok: false,
+        report: () => undefined,
+        status: null,
+    };
+    await input.onTerminalSubmitFailure?.(failure);
+    input.onSyncAbandoned?.("a queued update cannot fit within the document sync request limit");
+    return null;
+}
+//# sourceMappingURL=syncAbandon.js.map

package/workflows/documents/syncFailures/syncAbandon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncAbandon.js","sourceRoot":"","sources":["syncAbandon.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,4BAA4B,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,EAAE,oCAAoC,EAAE,MAAM,qBAAqB,CAAC;AAQ3E,MAAM,UAAU,kBAAkB,CAAC,KAAyB;IAC1D,KAAK,CAAC,WAAW,EAAE,CAAC,kCAAkC,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC;IAC1E,KAAK,CAAC,eAAe,EAAE,CAAC,SAAS,CAAC,CAAC;IACnC,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,KAAyB,EACzB,KAA2C;IAE3C,uEAAuE;IACvE,yEAAyE;IACzE,yEAAyE;IACzE,4BAA4B,CAAC,KAAK,CAAC,WAAW,EAAE;QAC9C,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,MAAM,EAAE,KAAK,CAAC,MAAM;KACrB,CAAC,CAAC;IACH,KAAK,CAAC,eAAe,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACtC,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,iCAAiC,CACrD,KAAyB,EACzB,KAA0C;IAE1C,MAAM,KAAK,CAAC,uBAAuB,EAAE,CAAC;QACpC,IAAI,EAAE,uCAAuC;QAC7C,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,EAAE,EAAE,KAAK;QACT,MAAM,EAAE,GAAG,EAAE,CAAC,SAAS;QACvB,MAAM,EAAE,IAAI;KACb,CAAC,CAAC;IACH,OAAO,qBAAqB,CAC1B,KAAK,EACL,IAAI,oCAAoC,CAAC,cAAc,CAAC,CACzD,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,8BAA8B,CAC5C,KAAyB;IAEzB,KAAK,CAAC,eAAe,EAAE,CAAC,6CAA6C,CAAC,CAAC;IACvE,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,KAAyB,EACzB,KAAY;IAEZ,MAAM,OAAO,GAA8B;QACzC,IAAI,EAAE,iCAAiC;QACvC,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,EAAE,EAAE,KAAK;QACT,MAAM,EAAE,GAAG,EAAE,CAAC,SAAS;QACvB,MAAM,EAAE,IAAI;KACb,CAAC;IACF,MAAM,KAAK,CAAC,uBAAuB,EAAE,CAAC,OAAO,CAAC,CAAC;IAC/C,KAAK,CAAC,eAAe,EAAE,CACrB,mEAAmE,CACpE,CAAC;IACF,OAAO,IAAI,CAAC;AACd,CAAC","sourcesContent":["import type { ContainerKekRepairInaccessibleError } from \"../../../data/documents/shared/containerKekCurrency\";\nimport type { DocumentSyncSubmitFailure } from \"../../../data/documents/shared/types\";\nimport type { SyncRemoteDocumentInput } from \"../sync/readOnlySync\";\nimport { traceAncestorRepairAbandoned } from \"../sync/syncTrace\";\nimport { DocumentAncestorRepairAbandonedError } from \"./syncRepairAbandon\";\n\n/** The ways a sync pass gives up without failing: writes stay queued. */\ntype AbandonedSyncInput = Pick<\n  SyncRemoteDocumentInput,\n  \"documentId\" | \"onSyncAbandoned\" | \"onSyncTrace\" | \"onTerminalSubmitFailure\"\n>;\n\nexport function abandonBlockedSync(input: AbandonedSyncInput): null {\n  input.onSyncTrace?.(`document sync blocked document=${input.documentId}`);\n  input.onSyncAbandoned?.(\"blocked\");\n  return null;\n}\n\nexport function abandonAncestorRepair(\n  input: AbandonedSyncInput,\n  error: DocumentAncestorRepairAbandonedError,\n): null {\n  // Trace as well as abandon: the store's onSyncAbandoned only parks the\n  // document, and this path may already have issued server-side rekeys, so\n  // abandoning untraced would leave a retrying loop with no way to see it.\n  traceAncestorRepairAbandoned(input.onSyncTrace, {\n    documentId: input.documentId,\n    reason: error.reason,\n  });\n  input.onSyncAbandoned?.(error.reason);\n  return null;\n}\n\n/**\n * The stale ancestor is one this writer can neither re-key nor be given the\n * key for, and one refetch has already confirmed nobody repaired it yet. The\n * writes stay queued; the durable row tells the write queue why, and the\n * dependent-path hint that follows the repair re-arms the pass.\n */\nexport async function abandonInaccessibleAncestorRepair(\n  input: AbandonedSyncInput,\n  error: ContainerKekRepairInaccessibleError,\n): Promise<null> {\n  await input.onTerminalSubmitFailure?.({\n    code: \"document_ancestor_repair_inaccessible\",\n    message: error.message,\n    ok: false,\n    report: () => undefined,\n    status: null,\n  });\n  return abandonAncestorRepair(\n    input,\n    new DocumentAncestorRepairAbandonedError(\"inaccessible\"),\n  );\n}\n\nexport function abandonAfterRetryableConflicts(\n  input: AbandonedSyncInput,\n): null {\n  input.onSyncAbandoned?.(\"every sync attempt hit a retryable conflict\");\n  return null;\n}\n\nexport async function abandonOversizedSyncPlan(\n  input: AbandonedSyncInput,\n  error: Error,\n): Promise<null> {\n  const failure: DocumentSyncSubmitFailure = {\n    code: \"document_sync_request_too_large\",\n    message: error.message,\n    ok: false,\n    report: () => undefined,\n    status: null,\n  };\n  await input.onTerminalSubmitFailure?.(failure);\n  input.onSyncAbandoned?.(\n    \"a queued update cannot fit within the document sync request limit\",\n  );\n  return null;\n}\n"]}

package/workflows/documents/syncFailures/syncFailureClassification.d.ts

@@ -0,0 +1,74 @@
+import type { DocumentSyncSubmitFailure } from "../../../data/documents/shared/types.js";
+import type { ExecSql } from "../../../data/sqlite/sqlSchema.js";
+export type RemoteDocumentDeletionHandler = (input: {
+    /** Present only after the SDK has verified the signed terminal purge proof. */
+    readonly commitPurgeProof?: ((transactionExecSql: ExecSql) => Promise<void>) | undefined;
+    readonly documentId: string;
+}) => Promise<void> | void;
+/**
+ * Invoked when a submission fails terminally — the failure is neither a
+ * retryable conflict nor a recoverable update-id conflict, so the sync pass
+ * stops and the pending writes stay queued (e.g. a 403 after write access was
+ * revoked). Callers persist the failure so the write queue can surface it.
+ */
+export type TerminalSubmitFailureHandler = (failure: DocumentSyncSubmitFailure) => Promise<void> | void;
+/**
+ * Read-only counterpart to describeDocumentSyncSubmitFailure: names a refused
+ * revalidation without implying a blocked write. 403s never reach this — a
+ * read-only 403 is deliberately suppressed (edge-case row 9) so unattempted
+ * local edits are never flagged.
+ */
+export declare function describeDocumentRevalidationFailure(failure: Pick<DocumentSyncSubmitFailure, "message" | "status">): string;
+/** Human-readable description of a terminal submit failure for queue display. */
+export declare function describeDocumentSyncSubmitFailure(failure: Pick<DocumentSyncSubmitFailure, "message" | "status">): string;
+type ProjectionIntegrityErrorCode = "equivocation" | "rollback" | "stale_predecessor";
+export declare function projectionIntegrityErrorCode(error: unknown): ProjectionIntegrityErrorCode | null;
+/**
+ * Shared shell for the stale-projection retry classifiers. A cached
+ * projection older than a checkpoint we already recorded ("rollback") —
+ * typical right after a peer shared/rotated a linked container — is resolved
+ * by refetching the current projection. The refetch is safe: it cannot
+ * bypass the anti-rollback check, because a genuinely rolled-back server
+ * response re-throws on the rebuilt plan. Any other keying-verification
+ * failure is terminal; anything else defers to the caller's message
+ * predicate for its unwrap-failure shape.
+ */
+export declare function shouldRetryWithFreshProjection(error: unknown, messageMatches: (message: string) => boolean): boolean;
+export declare function shouldRetrySyncWithFreshWriterProjection(error: unknown): boolean;
+export declare function isRecoverableDocumentUpdateIdConflict(failure: DocumentSyncSubmitFailure): boolean;
+/**
+ * The server's covering-baseline gate refused a queued rotation checkpoint
+ * (e.g. a leftover from an interrupted recovery or a lost heal ack) because
+ * it no longer covers the committed frontier. The pass can repair itself by
+ * regenerating a fresh covering baseline from the live document instead of
+ * resubmitting the stale payload — which would fail terminally forever.
+ */
+export declare function isCheckpointCoverageConflict(failure: DocumentSyncSubmitFailure): boolean;
+/**
+ * A create submitted with a stable documentId whose first attempt already
+ * committed server-side comes back as this 409 (see the server's
+ * `assertCreateCanAdvanceDocumentHead`). It is not a failure — the caller adopts
+ * the existing remote document instead of creating a duplicate.
+ */
+export declare function isDocumentManifestAlreadyExistsConflict(failure: {
+    readonly code?: string | undefined;
+    readonly message: string;
+    readonly status: number | null;
+}): boolean;
+export declare function canRetryDocumentSyncConflict(input: {
+    attempt: number;
+    failure: DocumentSyncSubmitFailure;
+    maxAttempts: number;
+}): boolean;
+export declare function canRecoverDocumentUpdateIdConflict(input: {
+    attempt: number;
+    failure: DocumentSyncSubmitFailure;
+    maxAttempts: number;
+    pendingUpdateCount: number;
+}): boolean;
+export declare function handleUpstreamDeletedDocumentSyncFailure(input: {
+    documentId: string;
+    failure: DocumentSyncSubmitFailure;
+    onRemoteDocumentDeleted?: RemoteDocumentDeletionHandler | undefined;
+}): Promise<boolean>;
+export {};

package/workflows/documents/syncFailures/syncFailureClassification.js

@@ -0,0 +1,122 @@
+import { KeyingVerificationError } from "../../../internal/crypto/index.js";
+import { DOCUMENT_MUTATION_ERROR_CODES, DOCUMENT_SYNC_ERROR_CODES, } from "../../../internal/validators/response/index.js";
+import { ContainerKekRepairRequiredError } from "../../../data/documents/shared/containerKekCurrency.js";
+import { isRetryableDocumentSyncConflict, isUpstreamDeletedDocumentSyncFailure, } from "../../../data/documents/shared/responses.js";
+import { ProjectionDependencyUnavailableError } from "../../../data/keyingProjectionVerification/dependencyUnavailable.js";
+import { isKeyingVerificationError } from "../../../data/keyingProjectionVerification/error.js";
+/**
+ * Read-only counterpart to describeDocumentSyncSubmitFailure: names a refused
+ * revalidation without implying a blocked write. 403s never reach this — a
+ * read-only 403 is deliberately suppressed (edge-case row 9) so unattempted
+ * local edits are never flagged.
+ */
+export function describeDocumentRevalidationFailure(failure) {
+    const detail = failure.message.trim().length > 0
+        ? failure.message.trim()
+        : "the server refused the read";
+    const suffix = failure.status === null ? "" : ` (${failure.status})`;
+    return `Remote revalidation failed: ${detail}${suffix}`;
+}
+/** Human-readable description of a terminal submit failure for queue display. */
+export function describeDocumentSyncSubmitFailure(failure) {
+    if (failure.status === 403) {
+        return "Write access denied by the server (403)";
+    }
+    const message = failure.message.trim().length > 0 ? failure.message.trim() : "Sync failed";
+    return failure.status === null ? message : `${message} (${failure.status})`;
+}
+function keyingVerificationErrorCode(error) {
+    if (!isKeyingVerificationError(error) || !(error instanceof Error)) {
+        return null;
+    }
+    const code = Reflect.get(error, "code");
+    return typeof code === "string" ? code : null;
+}
+export function projectionIntegrityErrorCode(error) {
+    if (!(error instanceof KeyingVerificationError) &&
+        !(error instanceof Error && error.name === "KeyingVerificationError")) {
+        return null;
+    }
+    const code = keyingVerificationErrorCode(error);
+    return code === "rollback" ||
+        code === "equivocation" ||
+        code === "stale_predecessor"
+        ? code
+        : null;
+}
+/**
+ * Shared shell for the stale-projection retry classifiers. A cached
+ * projection older than a checkpoint we already recorded ("rollback") —
+ * typical right after a peer shared/rotated a linked container — is resolved
+ * by refetching the current projection. The refetch is safe: it cannot
+ * bypass the anti-rollback check, because a genuinely rolled-back server
+ * response re-throws on the rebuilt plan. Any other keying-verification
+ * failure is terminal; anything else defers to the caller's message
+ * predicate for its unwrap-failure shape.
+ */
+export function shouldRetryWithFreshProjection(error, messageMatches) {
+    // A peer may already have repaired the chain. Refetch once; the same guard
+    // rejects a still-stale response before any new ciphertext is produced.
+    if (error instanceof ContainerKekRepairRequiredError ||
+        error instanceof ProjectionDependencyUnavailableError)
+        return true;
+    const integrityErrorCode = projectionIntegrityErrorCode(error);
+    if (integrityErrorCode) {
+        return integrityErrorCode === "rollback";
+    }
+    if (keyingVerificationErrorCode(error) === "invalid_shape") {
+        // Verification boundaries normalize malformed/stale projection data to a
+        // terminal error. One cache eviction is still safe: a dishonest or broken
+        // fresh response fails again outside this retry boundary.
+        return true;
+    }
+    if (isKeyingVerificationError(error)) {
+        return false;
+    }
+    return error instanceof Error && messageMatches(error.message);
+}
+export function shouldRetrySyncWithFreshWriterProjection(error) {
+    return shouldRetryWithFreshProjection(error, (message) => message.startsWith("Document authorizing container KEK path could not be unwrapped") && message.includes("Container writer projection KEK"));
+}
+export function isRecoverableDocumentUpdateIdConflict(failure) {
+    return (failure.status === 409 &&
+        failure.code === DOCUMENT_SYNC_ERROR_CODES.updateIdConflict);
+}
+/**
+ * The server's covering-baseline gate refused a queued rotation checkpoint
+ * (e.g. a leftover from an interrupted recovery or a lost heal ack) because
+ * it no longer covers the committed frontier. The pass can repair itself by
+ * regenerating a fresh covering baseline from the live document instead of
+ * resubmitting the stale payload — which would fail terminally forever.
+ */
+export function isCheckpointCoverageConflict(failure) {
+    return (failure.status === 409 &&
+        failure.code === DOCUMENT_SYNC_ERROR_CODES.checkpointCoverageConflict);
+}
+/**
+ * A create submitted with a stable documentId whose first attempt already
+ * committed server-side comes back as this 409 (see the server's
+ * `assertCreateCanAdvanceDocumentHead`). It is not a failure — the caller adopts
+ * the existing remote document instead of creating a duplicate.
+ */
+export function isDocumentManifestAlreadyExistsConflict(failure) {
+    return (failure.status === 409 &&
+        failure.code === DOCUMENT_MUTATION_ERROR_CODES.manifestAlreadyExists);
+}
+export function canRetryDocumentSyncConflict(input) {
+    return (input.attempt < input.maxAttempts &&
+        isRetryableDocumentSyncConflict(input.failure));
+}
+export function canRecoverDocumentUpdateIdConflict(input) {
+    return (input.attempt < input.maxAttempts &&
+        input.pendingUpdateCount > 0 &&
+        isRecoverableDocumentUpdateIdConflict(input.failure));
+}
+export async function handleUpstreamDeletedDocumentSyncFailure(input) {
+    if (!isUpstreamDeletedDocumentSyncFailure(input.failure)) {
+        return false;
+    }
+    await input.onRemoteDocumentDeleted?.({ documentId: input.documentId });
+    return true;
+}
+//# sourceMappingURL=syncFailureClassification.js.map

package/workflows/documents/syncFailures/syncFailureClassification.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncFailureClassification.js","sourceRoot":"","sources":["syncFailureClassification.ts"],"names":[],"mappings":"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","sourcesContent":["import { KeyingVerificationError } from \"@tearleads/crypto\";\nimport {\n  DOCUMENT_MUTATION_ERROR_CODES,\n  DOCUMENT_SYNC_ERROR_CODES,\n} from \"@tearleads/validators/response\";\nimport { ContainerKekRepairRequiredError } from \"../../../data/documents/shared/containerKekCurrency\";\nimport {\n  isRetryableDocumentSyncConflict,\n  isUpstreamDeletedDocumentSyncFailure,\n} from \"../../../data/documents/shared/responses\";\nimport type { DocumentSyncSubmitFailure } from \"../../../data/documents/shared/types\";\nimport { ProjectionDependencyUnavailableError } from \"../../../data/keyingProjectionVerification/dependencyUnavailable\";\nimport { isKeyingVerificationError } from \"../../../data/keyingProjectionVerification/error\";\nimport type { ExecSql } from \"../../../data/sqlite/sqlSchema\";\n\nexport type RemoteDocumentDeletionHandler = (input: {\n  /** Present only after the SDK has verified the signed terminal purge proof. */\n  readonly commitPurgeProof?:\n    | ((transactionExecSql: ExecSql) => Promise<void>)\n    | undefined;\n  readonly documentId: string;\n}) => Promise<void> | void;\n\n/**\n * Invoked when a submission fails terminally — the failure is neither a\n * retryable conflict nor a recoverable update-id conflict, so the sync pass\n * stops and the pending writes stay queued (e.g. a 403 after write access was\n * revoked). Callers persist the failure so the write queue can surface it.\n */\nexport type TerminalSubmitFailureHandler = (\n  failure: DocumentSyncSubmitFailure,\n) => Promise<void> | void;\n\n/**\n * Read-only counterpart to describeDocumentSyncSubmitFailure: names a refused\n * revalidation without implying a blocked write. 403s never reach this — a\n * read-only 403 is deliberately suppressed (edge-case row 9) so unattempted\n * local edits are never flagged.\n */\nexport function describeDocumentRevalidationFailure(\n  failure: Pick<DocumentSyncSubmitFailure, \"message\" | \"status\">,\n): string {\n  const detail =\n    failure.message.trim().length > 0\n      ? failure.message.trim()\n      : \"the server refused the read\";\n  const suffix = failure.status === null ? \"\" : ` (${failure.status})`;\n  return `Remote revalidation failed: ${detail}${suffix}`;\n}\n\n/** Human-readable description of a terminal submit failure for queue display. */\nexport function describeDocumentSyncSubmitFailure(\n  failure: Pick<DocumentSyncSubmitFailure, \"message\" | \"status\">,\n): string {\n  if (failure.status === 403) {\n    return \"Write access denied by the server (403)\";\n  }\n  const message =\n    failure.message.trim().length > 0 ? failure.message.trim() : \"Sync failed\";\n  return failure.status === null ? message : `${message} (${failure.status})`;\n}\n\ntype ProjectionIntegrityErrorCode =\n  | \"equivocation\"\n  | \"rollback\"\n  | \"stale_predecessor\";\n\nfunction keyingVerificationErrorCode(error: unknown): string | null {\n  if (!isKeyingVerificationError(error) || !(error instanceof Error)) {\n    return null;\n  }\n  const code = Reflect.get(error, \"code\");\n  return typeof code === \"string\" ? code : null;\n}\n\nexport function projectionIntegrityErrorCode(\n  error: unknown,\n): ProjectionIntegrityErrorCode | null {\n  if (\n    !(error instanceof KeyingVerificationError) &&\n    !(error instanceof Error && error.name === \"KeyingVerificationError\")\n  ) {\n    return null;\n  }\n\n  const code = keyingVerificationErrorCode(error);\n  return code === \"rollback\" ||\n    code === \"equivocation\" ||\n    code === \"stale_predecessor\"\n    ? code\n    : null;\n}\n\n/**\n * Shared shell for the stale-projection retry classifiers. A cached\n * projection older than a checkpoint we already recorded (\"rollback\") —\n * typical right after a peer shared/rotated a linked container — is resolved\n * by refetching the current projection. The refetch is safe: it cannot\n * bypass the anti-rollback check, because a genuinely rolled-back server\n * response re-throws on the rebuilt plan. Any other keying-verification\n * failure is terminal; anything else defers to the caller's message\n * predicate for its unwrap-failure shape.\n */\nexport function shouldRetryWithFreshProjection(\n  error: unknown,\n  messageMatches: (message: string) => boolean,\n): boolean {\n  // A peer may already have repaired the chain. Refetch once; the same guard\n  // rejects a still-stale response before any new ciphertext is produced.\n  if (\n    error instanceof ContainerKekRepairRequiredError ||\n    error instanceof ProjectionDependencyUnavailableError\n  )\n    return true;\n  const integrityErrorCode = projectionIntegrityErrorCode(error);\n  if (integrityErrorCode) {\n    return integrityErrorCode === \"rollback\";\n  }\n  if (keyingVerificationErrorCode(error) === \"invalid_shape\") {\n    // Verification boundaries normalize malformed/stale projection data to a\n    // terminal error. One cache eviction is still safe: a dishonest or broken\n    // fresh response fails again outside this retry boundary.\n    return true;\n  }\n  if (isKeyingVerificationError(error)) {\n    return false;\n  }\n\n  return error instanceof Error && messageMatches(error.message);\n}\n\nexport function shouldRetrySyncWithFreshWriterProjection(\n  error: unknown,\n): boolean {\n  return shouldRetryWithFreshProjection(\n    error,\n    (message) =>\n      message.startsWith(\n        \"Document authorizing container KEK path could not be unwrapped\",\n      ) && message.includes(\"Container writer projection KEK\"),\n  );\n}\n\nexport function isRecoverableDocumentUpdateIdConflict(\n  failure: DocumentSyncSubmitFailure,\n): boolean {\n  return (\n    failure.status === 409 &&\n    failure.code === DOCUMENT_SYNC_ERROR_CODES.updateIdConflict\n  );\n}\n\n/**\n * The server's covering-baseline gate refused a queued rotation checkpoint\n * (e.g. a leftover from an interrupted recovery or a lost heal ack) because\n * it no longer covers the committed frontier. The pass can repair itself by\n * regenerating a fresh covering baseline from the live document instead of\n * resubmitting the stale payload — which would fail terminally forever.\n */\nexport function isCheckpointCoverageConflict(\n  failure: DocumentSyncSubmitFailure,\n): boolean {\n  return (\n    failure.status === 409 &&\n    failure.code === DOCUMENT_SYNC_ERROR_CODES.checkpointCoverageConflict\n  );\n}\n\n/**\n * A create submitted with a stable documentId whose first attempt already\n * committed server-side comes back as this 409 (see the server's\n * `assertCreateCanAdvanceDocumentHead`). It is not a failure — the caller adopts\n * the existing remote document instead of creating a duplicate.\n */\nexport function isDocumentManifestAlreadyExistsConflict(failure: {\n  readonly code?: string | undefined;\n  readonly message: string;\n  readonly status: number | null;\n}): boolean {\n  return (\n    failure.status === 409 &&\n    failure.code === DOCUMENT_MUTATION_ERROR_CODES.manifestAlreadyExists\n  );\n}\n\nexport function canRetryDocumentSyncConflict(input: {\n  attempt: number;\n  failure: DocumentSyncSubmitFailure;\n  maxAttempts: number;\n}): boolean {\n  return (\n    input.attempt < input.maxAttempts &&\n    isRetryableDocumentSyncConflict(input.failure)\n  );\n}\n\nexport function canRecoverDocumentUpdateIdConflict(input: {\n  attempt: number;\n  failure: DocumentSyncSubmitFailure;\n  maxAttempts: number;\n  pendingUpdateCount: number;\n}): boolean {\n  return (\n    input.attempt < input.maxAttempts &&\n    input.pendingUpdateCount > 0 &&\n    isRecoverableDocumentUpdateIdConflict(input.failure)\n  );\n}\n\nexport async function handleUpstreamDeletedDocumentSyncFailure(input: {\n  documentId: string;\n  failure: DocumentSyncSubmitFailure;\n  onRemoteDocumentDeleted?: RemoteDocumentDeletionHandler | undefined;\n}): Promise<boolean> {\n  if (!isUpstreamDeletedDocumentSyncFailure(input.failure)) {\n    return false;\n  }\n\n  await input.onRemoteDocumentDeleted?.({ documentId: input.documentId });\n  return true;\n}\n"]}

package/workflows/documents/syncFailures/syncPolicyRepair.js

@@ -0,0 +1,50 @@
+import { KeyingVerificationError } from "../../../internal/crypto/index.js";
+import { isRetryableDocumentSyncConflict } from "../../../data/documents/shared/responses.js";
+import { recoverPrincipalPolicyRepair } from "../../principals/policyRepair.js";
+function principalIdentityKey(principalType, principalId) {
+    return `${principalType}:${principalId}`;
+}
+function requestedRepairPrincipalIdentities(plan) {
+    const identities = new Set();
+    for (const rekey of plan.request.containerRekeys ?? []) {
+        for (const policy of rekey.principalPolicies) {
+            const principalType = Reflect.get(policy, "principalType");
+            const principalId = Reflect.get(policy, "principalId");
+            if ((principalType === "group" || principalType === "organization") &&
+                typeof principalId === "string" &&
+                principalId.length > 0) {
+                identities.add(principalIdentityKey(principalType, principalId));
+            }
+        }
+    }
+    return identities;
+}
+function assertDocumentSyncPolicyRepairHeadsRequested(input) {
+    const requested = requestedRepairPrincipalIdentities(input.plan);
+    for (const head of input.heads) {
+        const { principalId, principalType } = head;
+        if (!requested.has(principalIdentityKey(principalType, principalId))) {
+            throw new KeyingVerificationError("object_mismatch", "Document sync policy repair head principal was not requested");
+        }
+    }
+}
+export async function recoverDocumentSyncPolicyRepair(input) {
+    const heads = input.failure.stalePrincipalHeads;
+    const resolve = input.warmReferencedPrincipalPolicies?.resolveReference;
+    if (!isRetryableDocumentSyncConflict(input.failure) ||
+        (input.plan.request.containerRekeys?.length ?? 0) === 0 ||
+        !heads ||
+        heads.length === 0 ||
+        !resolve ||
+        input.stillCurrent?.() === false) {
+        return;
+    }
+    assertDocumentSyncPolicyRepairHeadsRequested({ heads, plan: input.plan });
+    await recoverPrincipalPolicyRepair({
+        heads,
+        warmReferencedPrincipalPolicies: input.warmReferencedPrincipalPolicies,
+        organizationId: input.plan.organizationId,
+        stillCurrent: input.stillCurrent,
+    });
+}
+//# sourceMappingURL=syncPolicyRepair.js.map