@tearleads/client-sdk 0.1.62 → 0.1.64

package/workflows/documents/syncRekeys/syncAutomaticContainerRekeys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncAutomaticContainerRekeys.js","sourceRoot":"","sources":["syncAutomaticContainerRekeys.ts"],"names":[],"mappings":"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","sourcesContent":["import { KeyingVerificationError } from \"@tearleads/crypto\";\nimport type {\n  ContainerWriterProjectionResponse,\n  DocumentWriterProjectionResponse,\n} from \"@tearleads/validators/response\";\nimport { MAX_INLINE_CONTAINER_REKEYS } from \"@tearleads/validators/util\";\nimport { ContainerAuthorAccessError } from \"../../../data/containers/shared/authorAccess\";\nimport type { MaterializedContainerRekeyPlan } from \"../../../data/containers/shared/types\";\nimport { ContainerKekRepairInaccessibleError } from \"../../../data/documents/shared/containerKekCurrency\";\nimport { ContainerKekTargetUnreachableError } from \"../../../data/documents/shared/containerKekPath\";\nimport { documentContainerProjections } from \"../../../data/keyingProjectionVerification/document/documentContainerProjections\";\nimport { assertProjectionVerificationCurrent } from \"../../../data/keyingProjectionVerification/types\";\nimport { buildMaterializedContainerRekeyPlan } from \"../../containers/child/rekey\";\nimport type { SyncRemoteDocumentInput } from \"../sync/readOnlySync\";\nimport { DocumentAncestorRepairAbandonedError } from \"../syncFailures/syncRepairAbandon\";\nimport { hasOtherLinkedWriteAccess } from \"../syncFailures/syncRepairAccess\";\nimport { applyContainerRekeyPlan } from \"./syncContainerRekeyProjection\";\n\ninterface StaleContainer {\n  /** The stale container is the one the document itself is linked into. */\n  readonly isPathTarget: boolean;\n  readonly projection: ContainerWriterProjectionResponse;\n}\n\nfunction firstStaleContainer(\n  projection: DocumentWriterProjectionResponse,\n): StaleContainer | null {\n  for (const path of documentContainerProjections(projection)) {\n    for (let index = 1; index < path.containerKeks.length; index += 1) {\n      const parent = path.containerKeks[index - 1];\n      const child = path.containerKeks[index];\n      if (!parent || !child)\n        throw new Error(\"Container KEK path is incomplete\");\n      if (child.parentContainerKeyEpochId === parent.containerKeyEpochId) {\n        continue;\n      }\n      return {\n        isPathTarget: index === path.containerKeks.length - 1,\n        projection: {\n          ...path,\n          containerId: child.containerId,\n          containerKeks: path.containerKeks.slice(0, index + 1),\n          path: path.path.slice(0, index + 1),\n        },\n      };\n    }\n  }\n  return null;\n}\n\n/**\n * The stale container is not this writer's to re-key: no wrap on the verified\n * path opens it, or the signed path grants the signer no write access there.\n * Both are judged against the path sliced at the stale container, so a grant\n * held only further down never counts — exactly the API's `container.rekey`\n * rule. Anything else (keyring damage, a forged path) stays an error.\n *\n * A target's write refusal is handled separately: another linked target may\n * still authorize the document write. Key unwrap failures on a target stay\n * errors, because this path's readable grant should open its own key.\n */\nfunction isRepairInaccessible(error: unknown, stale: StaleContainer): boolean {\n  if (stale.isPathTarget) return false;\n  return (\n    error instanceof ContainerAuthorAccessError ||\n    (error instanceof ContainerKekTargetUnreachableError &&\n      error.containerId === stale.projection.containerId)\n  );\n}\n\n/** Prepare parent-first repairs; the sync transaction commits them with the write. */\nexport async function buildAutomaticContainerRekeys(\n  sync: SyncRemoteDocumentInput,\n  initialProjection: DocumentWriterProjectionResponse,\n): Promise<{ plans: MaterializedContainerRekeyPlan[]; hasMore: boolean }> {\n  const plans: MaterializedContainerRekeyPlan[] = [];\n  const plannedIds = new Set<string>();\n  let projection = initialProjection;\n  for (;;) {\n    const stale = firstStaleContainer(projection);\n    if (!stale) return { plans, hasMore: false };\n    const previousProjection = stale.projection;\n    if (plans.length >= MAX_INLINE_CONTAINER_REKEYS) {\n      return { plans, hasMore: true };\n    }\n    // Use the shared cancellation sentinel: syncRemoteDocument converts only\n    // that to a graceful null, so a plain Error would report a routine\n    // generation flip mid-repair as a real sync failure.\n    assertProjectionVerificationCurrent(sync.stillCurrent);\n    if (plannedIds.has(previousProjection.containerId)) {\n      // Abandon like every other routine repair failure: two linked paths\n      // disagreeing about a container is a concurrent-rotation race, not a\n      // defect, and a raw Error would crash the sync lane instead.\n      throw new DocumentAncestorRepairAbandonedError(\"peer-rotation\");\n    }\n    // Assert rather than adopt: resolveRotationContext compares the verified\n    // manifest's organization against the author's, so substituting the path's\n    // own organization here would make that the only cross-org check and leave\n    // it comparing a server-supplied value with itself.\n    if (previousProjection.organizationId !== sync.author.organizationId) {\n      throw new KeyingVerificationError(\n        \"object_mismatch\",\n        \"Document ancestor repair crosses the author's organization\",\n      );\n    }\n    const planned = await buildMaterializedContainerRekeyPlan({\n      author: sync.author,\n      persistVerificationCheckpoints: false,\n      previousProjection,\n      signedAt: sync.signedAt,\n      targetSecretKey: sync.targetSecretKey,\n      resolveProjectionUserKey: sync.resolveProjectionUserKey,\n      stillCurrent: sync.stillCurrent,\n      warmReferencedPrincipalPolicies: sync.warmReferencedPrincipalPolicies,\n      execSql: sync.execSql,\n    }).catch(async (error: unknown) => {\n      if (error instanceof ContainerAuthorAccessError && stale.isPathTarget) {\n        if (\n          await hasOtherLinkedWriteAccess(\n            sync,\n            initialProjection,\n            previousProjection.containerId,\n          )\n        ) {\n          throw new ContainerKekRepairInaccessibleError(\n            previousProjection.containerId,\n          );\n        }\n        await sync.onTerminalSubmitFailure?.({\n          code: error.code,\n          message: error.message,\n          ok: false,\n          report: () => undefined,\n          status: error.status,\n        });\n        throw new DocumentAncestorRepairAbandonedError(\"refused\");\n      }\n      // Repairs run parent-first and access inherits downward, so only the\n      // first stale container can be out of reach. Retry-classified like any\n      // stale path: one refetch sees a repair a capable member already made.\n      throw isRepairInaccessible(error, stale)\n        ? new ContainerKekRepairInaccessibleError(\n            previousProjection.containerId,\n          )\n        : error;\n    });\n    plannedIds.add(previousProjection.containerId);\n    plans.push(planned);\n    projection = await applyContainerRekeyPlan(projection, planned);\n  }\n}\n"]}

package/workflows/documents/syncRekeys/syncContainerRekeyPreparation.js

@@ -0,0 +1,227 @@
+import { KeyingVerificationError } from "../../../internal/crypto/index.js";
+import { MAX_CONTAINER_PATH_LENGTH } from "../../../internal/validators/util/index.js";
+import { acknowledgeContainerMutationBatch } from "../../../data/containers/shared/mutationAcknowledgement.js";
+import { assertDocumentWriterProjectionConsistent } from "../../../data/documents/shared/projection.js";
+import { projectionVerificationOptions } from "../../../data/documents/shared/types.js";
+import { requireProjectionUserKeyResolver } from "../../../data/keyingProjectionVerification/index.js";
+import { assertProjectionVerificationCurrent } from "../../../data/keyingProjectionVerification/types.js";
+import { submitContainerRotation, submitRotationCarryingDescendants, } from "../../containers/child/mutationSubmit.js";
+import { refreshSyncAttemptWriterProjection } from "../syncFailures/index.js";
+import { shouldRetrySyncWithFreshWriterProjection } from "../syncFailures/syncFailureClassification.js";
+import { DocumentAncestorRepairAbandonedError } from "../syncFailures/syncRepairAbandon.js";
+import { buildAutomaticContainerRekeys } from "./syncAutomaticContainerRekeys.js";
+/**
+ * Repairs committed during one sync pass, keyed by the pass's own input object
+ * (stable across all three attempts). The sync loop explicitly prepares each
+ * attempt, so a counter local to one call would not bound the whole pass.
+ */
+const passRepairTotals = new WeakMap();
+/**
+ * Passes whose inline repairs the server refused for stranding a level above a
+ * directly granted container. The write's flat rekey list cannot say which
+ * descendants each repair must carry; a standalone rekey can, so the rest of
+ * the pass commits every repair standalone before writing.
+ */
+const standaloneRepairPasses = new WeakSet();
+export function requiresStandaloneAncestorRepairs(sync) {
+    return standaloneRepairPasses.has(sync);
+}
+export function requireStandaloneAncestorRepairs(sync) {
+    standaloneRepairPasses.add(sync);
+}
+/** A refusal the writer cannot clear by retrying, as opposed to 5xx/offline. */
+function isTerminalRepairStatus(status) {
+    return status === 401 || status === 402 || status === 403;
+}
+/**
+ * One standalone repair. Prefers the status-bearing rekey: a permanent refusal
+ * (403 once ancestor write access is revoked, 402) must leave a durable record,
+ * while a 5xx or an offline blip must not, and plain `rekeyContainer` collapses
+ * both to null. It is also the only way to learn which descendant rekeys this
+ * repair must carry. An adapter without it still repairs; its refusals are just
+ * reported as an ordinary abandon.
+ */
+function submitStandaloneRepair(sync, plan, writerProjection) {
+    const options = {
+        expectedPaymentRequiredOrganizationId: plan.state.organizationId,
+    };
+    const { getContainerWriterProjection, rekeyContainerResult } = sync.apiClient;
+    return submitRotationCarryingDescendants({
+        carriedRekeys: getContainerWriterProjection && {
+            planning: {
+                apiClient: {
+                    getContainerWriterProjection: getContainerWriterProjection.bind(sync.apiClient),
+                },
+                author: sync.author,
+                execSql: sync.execSql,
+                resolveProjectionUserKey: requireProjectionUserKeyResolver(sync.resolveProjectionUserKey, "Document ancestor repair"),
+                stillCurrent: sync.stillCurrent,
+                targetSecretKey: sync.targetSecretKey,
+                warmReferencedPrincipalPolicies: sync.warmReferencedPrincipalPolicies,
+            },
+            rotated: async () => writerProjection,
+        },
+        stillCurrent: sync.stillCurrent,
+        submit: (carried) => {
+            const request = carried.length
+                ? { ...plan.request, containerRekeys: [...carried] }
+                : plan.request;
+            return submitContainerRotation({
+                plain: () => sync.apiClient.rekeyContainer(plan.containerId, request, options),
+                result: rekeyContainerResult
+                    ? () => rekeyContainerResult.call(sync.apiClient, plan.containerId, request, { ...options, reportErrors: false })
+                    : undefined,
+            });
+        },
+    });
+}
+async function commitRepairPrefix(input) {
+    let committed = 0;
+    for (const { plan, writerProjection } of input.plans) {
+        assertProjectionVerificationCurrent(input.sync.stillCurrent);
+        if (input.sync.isRemoteSyncBlocked?.(plan.state.organizationId)) {
+            throw new DocumentAncestorRepairAbandonedError("blocked");
+        }
+        if (input.repairedIds.has(plan.containerId)) {
+            throw new DocumentAncestorRepairAbandonedError("peer-rotation");
+        }
+        const { carriedPlans, result } = await submitStandaloneRepair(input.sync, plan, writerProjection);
+        const response = result.ok ? result.data : null;
+        // Deliberately not ContainerKekRepairRequiredError: that is classified as
+        // retryable, so a handled refusal would re-sign the whole prefix before
+        // failing again, and the retry never reaches onTerminalSubmitFailure
+        // regardless, because this throws before submission.
+        if (!response) {
+            if (!result.ok && isTerminalRepairStatus(result.status)) {
+                await input.sync.onTerminalSubmitFailure?.({
+                    code: "document_ancestor_repair_refused",
+                    message: `Ancestor repair refused for ${plan.containerId}`,
+                    ok: false,
+                    report: () => undefined,
+                    status: result.status,
+                });
+            }
+            throw new DocumentAncestorRepairAbandonedError("refused");
+        }
+        // What a repair carried committed with it, so the pins advance together.
+        const acknowledged = await acknowledgeContainerMutationBatch({
+            execSql: input.sync.execSql,
+            plans: [plan, ...carriedPlans.map((carried) => carried.plan)],
+            responses: [response, ...(response.containerRekeys ?? [])],
+            stillCurrent: input.sync.stillCurrent,
+        });
+        if (!acknowledged) {
+            // A refused guarded transaction is usually a generation flip; surface it
+            // as the shared cancellation so syncRemoteDocument returns null instead
+            // of reporting a routine flip as a sync failure.
+            assertProjectionVerificationCurrent(input.sync.stillCurrent);
+            throw new Error("Document ancestor repair was superseded");
+        }
+        input.repairedIds.add(plan.containerId);
+        for (const carried of carriedPlans) {
+            input.repairedIds.add(carried.plan.containerId);
+        }
+        committed += 1 + carriedPlans.length;
+        // The rest of this prefix was signed before the carry. A plan for a carried
+        // container extends a superseded head, and one below it pins an epoch that
+        // was never minted. Stop here; the caller refetches and re-plans.
+        if (carriedPlans.length > 0)
+            return committed;
+    }
+    return committed;
+}
+/**
+ * Large repairs commit a bounded prefix; the last batch stays atomic with content.
+ * A tighter local resource budget may be used, but never above the protocol cap.
+ */
+export async function prepareAutomaticContainerRekeys(sync, initialProjection, maxRepairs = MAX_CONTAINER_PATH_LENGTH) {
+    if (initialProjection.documentId !== sync.documentId) {
+        throw new KeyingVerificationError("object_mismatch", "Document ancestor repair projection targets another document");
+    }
+    let projection = initialProjection;
+    const repairedIds = new Set();
+    // `repairedIds` only breaks a loop within one preparation. An explicit sync
+    // retry starts another preparation with a fresh set. Bound the
+    // work by the deepest authorizing path the protocol allows, counted across
+    // the whole pass rather than per call: no honest chain needs more repairs
+    // than that, so re-entry cannot multiply the budget.
+    for (;;) {
+        const batch = await buildAutomaticContainerRekeys(sync, projection);
+        const commitsStandalone = batch.hasMore ||
+            (batch.plans.length > 0 && standaloneRepairPasses.has(sync));
+        if (!commitsStandalone)
+            return { plans: batch.plans, projection };
+        // Standalone mutations require authentic document scope before any request.
+        // Persist the verified heads here, unlike the inline path: a committed
+        // repair is acknowledged against the latest durable pin, and a repaired
+        // ancestor is always past epoch 1, so a device that has never pinned it
+        // would reject its own acknowledgement after the server already committed
+        // the rekey. The inline path needs no pin because the sync response
+        // re-verifies and pins before anything is acknowledged.
+        await assertDocumentWriterProjectionConsistent(projection, {
+            ...projectionVerificationOptions(sync),
+            persistVerificationCheckpoints: true,
+            allowStaleContentKeyBundle: true,
+        });
+        // Charge what this prefix can still commit, then settle to what it did: it
+        // stops early after a repair that carried something, and charging the plans
+        // it never submitted would spend the budget on work that did not happen.
+        const committedBefore = passRepairTotals.get(sync) ?? 0;
+        if (committedBefore + batch.plans.length >
+            Math.min(maxRepairs, MAX_CONTAINER_PATH_LENGTH)) {
+            throw new DocumentAncestorRepairAbandonedError("depth-budget");
+        }
+        passRepairTotals.set(sync, committedBefore +
+            (await commitRepairPrefix({ plans: batch.plans, repairedIds, sync })));
+        const fresh = await refreshSyncAttemptWriterProjection({
+            apiClient: sync.apiClient,
+            documentId: sync.documentId,
+            onRemoteDocumentDeleted: sync.onRemoteDocumentDeleted,
+            onSyncAbandoned: sync.onSyncAbandoned,
+            onSyncTrace: sync.onSyncTrace,
+            // Always a write-bearing pass, so a terminal projection failure (a 403
+            // after revocation mid-repair) must leave the durable record that the
+            // queued writes are blocked. onReadOnlyProjectionFailure is documented
+            // for passes without queued writes and would not apply here.
+            onTerminalFailure: sync.onTerminalSubmitFailure,
+            stillCurrent: sync.stillCurrent,
+        });
+        if (!fresh) {
+            // refreshSyncAttemptWriterProjection returns null on a generation flip.
+            assertProjectionVerificationCurrent(sync.stillCurrent);
+            // It has already called onSyncAbandoned by this point, and on a coded 404
+            // ran the verified local teardown, so a bare Error would double-signal as
+            // an abandon plus a sync-lane crash.
+            throw new DocumentAncestorRepairAbandonedError("unrefreshable");
+        }
+        // The scope check above guards the first round only; a refetched projection
+        // is server-supplied too, and nothing in the refresh path proves it names
+        // the document this repair is for.
+        if (fresh.documentId !== sync.documentId) {
+            throw new KeyingVerificationError("object_mismatch", "Document ancestor repair projection targets another document");
+        }
+        projection = fresh;
+    }
+}
+/** An explicit preparation retry may commit repairs; plan retries never do. */
+export async function prepareSyncAttemptContainerRekeys(sync, projection) {
+    try {
+        return await prepareAutomaticContainerRekeys(sync, projection);
+    }
+    catch (error) {
+        if (!sync.apiClient.evictDocumentWriterProjection ||
+            !shouldRetrySyncWithFreshWriterProjection(error))
+            throw error;
+    }
+    const fresh = await refreshSyncAttemptWriterProjection({
+        apiClient: sync.apiClient,
+        documentId: sync.documentId,
+        onRemoteDocumentDeleted: sync.onRemoteDocumentDeleted,
+        onSyncAbandoned: sync.onSyncAbandoned,
+        onSyncTrace: sync.onSyncTrace,
+        onTerminalFailure: sync.onTerminalSubmitFailure,
+        stillCurrent: sync.stillCurrent,
+    });
+    return fresh ? prepareAutomaticContainerRekeys(sync, fresh) : null;
+}
+//# sourceMappingURL=syncContainerRekeyPreparation.js.map

package/workflows/documents/syncRekeys/syncContainerRekeyPreparation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncContainerRekeyPreparation.js","sourceRoot":"","sources":["syncContainerRekeyPreparation.ts"],"names":[],"mappings":"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","sourcesContent":["import { KeyingVerificationError } from \"@tearleads/crypto\";\nimport type { DocumentWriterProjectionResponse } from \"@tearleads/validators/response\";\nimport { MAX_CONTAINER_PATH_LENGTH } from \"@tearleads/validators/util\";\nimport { acknowledgeContainerMutationBatch } from \"../../../data/containers/shared/mutationAcknowledgement\";\nimport type { MaterializedContainerRekeyPlan } from \"../../../data/containers/shared/types\";\nimport { assertDocumentWriterProjectionConsistent } from \"../../../data/documents/shared/projection\";\nimport { projectionVerificationOptions } from \"../../../data/documents/shared/types\";\nimport { requireProjectionUserKeyResolver } from \"../../../data/keyingProjectionVerification\";\nimport { assertProjectionVerificationCurrent } from \"../../../data/keyingProjectionVerification/types\";\nimport {\n  submitContainerRotation,\n  submitRotationCarryingDescendants,\n} from \"../../containers/child/mutationSubmit\";\nimport type { SyncRemoteDocumentInput } from \"../sync/readOnlySync\";\nimport { refreshSyncAttemptWriterProjection } from \"../syncFailures\";\nimport { shouldRetrySyncWithFreshWriterProjection } from \"../syncFailures/syncFailureClassification\";\nimport { DocumentAncestorRepairAbandonedError } from \"../syncFailures/syncRepairAbandon\";\nimport { buildAutomaticContainerRekeys } from \"./syncAutomaticContainerRekeys\";\n\n/**\n * Repairs committed during one sync pass, keyed by the pass's own input object\n * (stable across all three attempts). The sync loop explicitly prepares each\n * attempt, so a counter local to one call would not bound the whole pass.\n */\nconst passRepairTotals = new WeakMap<SyncRemoteDocumentInput, number>();\n\n/**\n * Passes whose inline repairs the server refused for stranding a level above a\n * directly granted container. The write's flat rekey list cannot say which\n * descendants each repair must carry; a standalone rekey can, so the rest of\n * the pass commits every repair standalone before writing.\n */\nconst standaloneRepairPasses = new WeakSet<SyncRemoteDocumentInput>();\n\nexport function requiresStandaloneAncestorRepairs(\n  sync: SyncRemoteDocumentInput,\n): boolean {\n  return standaloneRepairPasses.has(sync);\n}\n\nexport function requireStandaloneAncestorRepairs(\n  sync: SyncRemoteDocumentInput,\n): void {\n  standaloneRepairPasses.add(sync);\n}\n\n/** A refusal the writer cannot clear by retrying, as opposed to 5xx/offline. */\nfunction isTerminalRepairStatus(status: number | null): boolean {\n  return status === 401 || status === 402 || status === 403;\n}\n\n/**\n * One standalone repair. Prefers the status-bearing rekey: a permanent refusal\n * (403 once ancestor write access is revoked, 402) must leave a durable record,\n * while a 5xx or an offline blip must not, and plain `rekeyContainer` collapses\n * both to null. It is also the only way to learn which descendant rekeys this\n * repair must carry. An adapter without it still repairs; its refusals are just\n * reported as an ordinary abandon.\n */\nfunction submitStandaloneRepair(\n  sync: SyncRemoteDocumentInput,\n  plan: MaterializedContainerRekeyPlan[\"plan\"],\n  writerProjection: MaterializedContainerRekeyPlan[\"writerProjection\"],\n) {\n  const options = {\n    expectedPaymentRequiredOrganizationId: plan.state.organizationId,\n  };\n  const { getContainerWriterProjection, rekeyContainerResult } = sync.apiClient;\n  return submitRotationCarryingDescendants({\n    carriedRekeys: getContainerWriterProjection && {\n      planning: {\n        apiClient: {\n          getContainerWriterProjection: getContainerWriterProjection.bind(\n            sync.apiClient,\n          ),\n        },\n        author: sync.author,\n        execSql: sync.execSql,\n        resolveProjectionUserKey: requireProjectionUserKeyResolver(\n          sync.resolveProjectionUserKey,\n          \"Document ancestor repair\",\n        ),\n        stillCurrent: sync.stillCurrent,\n        targetSecretKey: sync.targetSecretKey,\n        warmReferencedPrincipalPolicies: sync.warmReferencedPrincipalPolicies,\n      },\n      rotated: async () => writerProjection,\n    },\n    stillCurrent: sync.stillCurrent,\n    submit: (carried) => {\n      const request = carried.length\n        ? { ...plan.request, containerRekeys: [...carried] }\n        : plan.request;\n      return submitContainerRotation({\n        plain: () =>\n          sync.apiClient.rekeyContainer(plan.containerId, request, options),\n        result: rekeyContainerResult\n          ? () =>\n              rekeyContainerResult.call(\n                sync.apiClient,\n                plan.containerId,\n                request,\n                { ...options, reportErrors: false },\n              )\n          : undefined,\n      });\n    },\n  });\n}\n\nasync function commitRepairPrefix(input: {\n  plans: readonly MaterializedContainerRekeyPlan[];\n  repairedIds: Set<string>;\n  sync: SyncRemoteDocumentInput;\n}): Promise<number> {\n  let committed = 0;\n  for (const { plan, writerProjection } of input.plans) {\n    assertProjectionVerificationCurrent(input.sync.stillCurrent);\n    if (input.sync.isRemoteSyncBlocked?.(plan.state.organizationId)) {\n      throw new DocumentAncestorRepairAbandonedError(\"blocked\");\n    }\n    if (input.repairedIds.has(plan.containerId)) {\n      throw new DocumentAncestorRepairAbandonedError(\"peer-rotation\");\n    }\n    const { carriedPlans, result } = await submitStandaloneRepair(\n      input.sync,\n      plan,\n      writerProjection,\n    );\n    const response = result.ok ? result.data : null;\n    // Deliberately not ContainerKekRepairRequiredError: that is classified as\n    // retryable, so a handled refusal would re-sign the whole prefix before\n    // failing again, and the retry never reaches onTerminalSubmitFailure\n    // regardless, because this throws before submission.\n    if (!response) {\n      if (!result.ok && isTerminalRepairStatus(result.status)) {\n        await input.sync.onTerminalSubmitFailure?.({\n          code: \"document_ancestor_repair_refused\",\n          message: `Ancestor repair refused for ${plan.containerId}`,\n          ok: false,\n          report: () => undefined,\n          status: result.status,\n        });\n      }\n      throw new DocumentAncestorRepairAbandonedError(\"refused\");\n    }\n    // What a repair carried committed with it, so the pins advance together.\n    const acknowledged = await acknowledgeContainerMutationBatch({\n      execSql: input.sync.execSql,\n      plans: [plan, ...carriedPlans.map((carried) => carried.plan)],\n      responses: [response, ...(response.containerRekeys ?? [])],\n      stillCurrent: input.sync.stillCurrent,\n    });\n    if (!acknowledged) {\n      // A refused guarded transaction is usually a generation flip; surface it\n      // as the shared cancellation so syncRemoteDocument returns null instead\n      // of reporting a routine flip as a sync failure.\n      assertProjectionVerificationCurrent(input.sync.stillCurrent);\n      throw new Error(\"Document ancestor repair was superseded\");\n    }\n    input.repairedIds.add(plan.containerId);\n    for (const carried of carriedPlans) {\n      input.repairedIds.add(carried.plan.containerId);\n    }\n    committed += 1 + carriedPlans.length;\n    // The rest of this prefix was signed before the carry. A plan for a carried\n    // container extends a superseded head, and one below it pins an epoch that\n    // was never minted. Stop here; the caller refetches and re-plans.\n    if (carriedPlans.length > 0) return committed;\n  }\n  return committed;\n}\n\n/**\n * Large repairs commit a bounded prefix; the last batch stays atomic with content.\n * A tighter local resource budget may be used, but never above the protocol cap.\n */\nexport async function prepareAutomaticContainerRekeys(\n  sync: SyncRemoteDocumentInput,\n  initialProjection: DocumentWriterProjectionResponse,\n  maxRepairs = MAX_CONTAINER_PATH_LENGTH,\n): Promise<{\n  plans: readonly MaterializedContainerRekeyPlan[];\n  projection: DocumentWriterProjectionResponse;\n}> {\n  if (initialProjection.documentId !== sync.documentId) {\n    throw new KeyingVerificationError(\n      \"object_mismatch\",\n      \"Document ancestor repair projection targets another document\",\n    );\n  }\n  let projection = initialProjection;\n  const repairedIds = new Set<string>();\n  // `repairedIds` only breaks a loop within one preparation. An explicit sync\n  // retry starts another preparation with a fresh set. Bound the\n  // work by the deepest authorizing path the protocol allows, counted across\n  // the whole pass rather than per call: no honest chain needs more repairs\n  // than that, so re-entry cannot multiply the budget.\n  for (;;) {\n    const batch = await buildAutomaticContainerRekeys(sync, projection);\n    const commitsStandalone =\n      batch.hasMore ||\n      (batch.plans.length > 0 && standaloneRepairPasses.has(sync));\n    if (!commitsStandalone) return { plans: batch.plans, projection };\n    // Standalone mutations require authentic document scope before any request.\n    // Persist the verified heads here, unlike the inline path: a committed\n    // repair is acknowledged against the latest durable pin, and a repaired\n    // ancestor is always past epoch 1, so a device that has never pinned it\n    // would reject its own acknowledgement after the server already committed\n    // the rekey. The inline path needs no pin because the sync response\n    // re-verifies and pins before anything is acknowledged.\n    await assertDocumentWriterProjectionConsistent(projection, {\n      ...projectionVerificationOptions(sync),\n      persistVerificationCheckpoints: true,\n      allowStaleContentKeyBundle: true,\n    });\n    // Charge what this prefix can still commit, then settle to what it did: it\n    // stops early after a repair that carried something, and charging the plans\n    // it never submitted would spend the budget on work that did not happen.\n    const committedBefore = passRepairTotals.get(sync) ?? 0;\n    if (\n      committedBefore + batch.plans.length >\n      Math.min(maxRepairs, MAX_CONTAINER_PATH_LENGTH)\n    ) {\n      throw new DocumentAncestorRepairAbandonedError(\"depth-budget\");\n    }\n    passRepairTotals.set(\n      sync,\n      committedBefore +\n        (await commitRepairPrefix({ plans: batch.plans, repairedIds, sync })),\n    );\n    const fresh = await refreshSyncAttemptWriterProjection({\n      apiClient: sync.apiClient,\n      documentId: sync.documentId,\n      onRemoteDocumentDeleted: sync.onRemoteDocumentDeleted,\n      onSyncAbandoned: sync.onSyncAbandoned,\n      onSyncTrace: sync.onSyncTrace,\n      // Always a write-bearing pass, so a terminal projection failure (a 403\n      // after revocation mid-repair) must leave the durable record that the\n      // queued writes are blocked. onReadOnlyProjectionFailure is documented\n      // for passes without queued writes and would not apply here.\n      onTerminalFailure: sync.onTerminalSubmitFailure,\n      stillCurrent: sync.stillCurrent,\n    });\n    if (!fresh) {\n      // refreshSyncAttemptWriterProjection returns null on a generation flip.\n      assertProjectionVerificationCurrent(sync.stillCurrent);\n      // It has already called onSyncAbandoned by this point, and on a coded 404\n      // ran the verified local teardown, so a bare Error would double-signal as\n      // an abandon plus a sync-lane crash.\n      throw new DocumentAncestorRepairAbandonedError(\"unrefreshable\");\n    }\n    // The scope check above guards the first round only; a refetched projection\n    // is server-supplied too, and nothing in the refresh path proves it names\n    // the document this repair is for.\n    if (fresh.documentId !== sync.documentId) {\n      throw new KeyingVerificationError(\n        \"object_mismatch\",\n        \"Document ancestor repair projection targets another document\",\n      );\n    }\n    projection = fresh;\n  }\n}\n\n/** An explicit preparation retry may commit repairs; plan retries never do. */\nexport async function prepareSyncAttemptContainerRekeys(\n  sync: SyncRemoteDocumentInput,\n  projection: DocumentWriterProjectionResponse,\n) {\n  try {\n    return await prepareAutomaticContainerRekeys(sync, projection);\n  } catch (error) {\n    if (\n      !sync.apiClient.evictDocumentWriterProjection ||\n      !shouldRetrySyncWithFreshWriterProjection(error)\n    )\n      throw error;\n  }\n  const fresh = await refreshSyncAttemptWriterProjection({\n    apiClient: sync.apiClient,\n    documentId: sync.documentId,\n    onRemoteDocumentDeleted: sync.onRemoteDocumentDeleted,\n    onSyncAbandoned: sync.onSyncAbandoned,\n    onSyncTrace: sync.onSyncTrace,\n    onTerminalFailure: sync.onTerminalSubmitFailure,\n    stillCurrent: sync.stillCurrent,\n  });\n  return fresh ? prepareAutomaticContainerRekeys(sync, fresh) : null;\n}\n"]}

package/workflows/documents/syncRekeys/syncContainerRekeyProjection.js

@@ -0,0 +1,79 @@
+import { computeDocumentContentKeyTargetHash } from "../../../internal/crypto/index.js";
+import { normalizeDocumentKekTargetResponse, readManifestContainerId, } from "../../../data/documents/shared/readers.js";
+function replaceRekeyedPathNode(input) {
+    const index = input.projection.path.findIndex((bundle) => readManifestContainerId(bundle) === input.plan.plan.containerId);
+    if (index < 0)
+        return { projection: input.projection, replaced: false };
+    const previousManifest = input.projection.path[index];
+    const previousKek = input.projection.containerKeks[index];
+    const nextManifest = input.plan.writerProjection.path.at(-1);
+    const nextKek = input.plan.writerProjection.containerKeks.at(-1);
+    if (!previousManifest ||
+        !previousKek ||
+        !nextManifest ||
+        !nextKek ||
+        previousManifest.manifestHash !==
+            input.plan.plan.previousManifest.manifestHash ||
+        previousKek.accessManifestHash !== previousManifest.manifestHash) {
+        throw new Error("Document inline rekey projection predecessor mismatch");
+    }
+    const path = [...input.projection.path];
+    const containerKeks = [...input.projection.containerKeks];
+    path[index] = nextManifest;
+    containerKeks[index] = nextKek;
+    return {
+        projection: { ...input.projection, containerKeks, path },
+        replaced: true,
+    };
+}
+export async function applyContainerRekeyPlan(writerProjection, plan) {
+    let replacedPath = false;
+    const authorizingContainerPaths = writerProjection.authorizingContainerPaths.map((projection) => {
+        const replaced = replaceRekeyedPathNode({ plan, projection });
+        replacedPath ||= replaced.replaced;
+        return replaced.projection;
+    });
+    const nextKek = plan.writerProjection.containerKeks.at(-1);
+    const nextManifest = plan.writerProjection.path.at(-1);
+    if (!nextKek || !nextManifest) {
+        throw new Error("Document inline rekey projection is empty");
+    }
+    let replacedTarget = false;
+    const targets = normalizeDocumentKekTargetResponse(writerProjection.documentKekTargets).map((target) => {
+        if (target.containerId !== plan.plan.containerId)
+            return target;
+        replacedTarget = true;
+        return {
+            ...target,
+            containerKeyEpoch: nextKek.containerKeyEpoch,
+            containerKeyEpochId: nextKek.containerKeyEpochId,
+            containerManifestHash: nextManifest.manifestHash,
+        };
+    });
+    if (!replacedPath && !replacedTarget) {
+        throw new Error("Document inline rekey does not belong to its writer projection");
+    }
+    const documentKeyTargetHash = await computeDocumentContentKeyTargetHash(targets);
+    return {
+        ...writerProjection,
+        authorizingContainerPaths,
+        ...(documentKeyTargetHash === writerProjection.contentKeyBundle.targetHash
+            ? {}
+            : { contentKeyBundleStale: true }),
+        documentKekTargets: {
+            ...writerProjection.documentKekTargets,
+            documentKeyTargetHash,
+            linkedContainerKeyEpochIds: targets.map((target) => target.containerKeyEpochId),
+            linkedContainerManifestHashes: targets.map((target) => target.containerManifestHash),
+            targets: targets.map((target) => ({ ...target })),
+        },
+    };
+}
+export async function applyDocumentSyncContainerRekeys(input) {
+    let projection = input.writerProjection;
+    for (const plan of input.plans) {
+        projection = await applyContainerRekeyPlan(projection, plan);
+    }
+    return projection;
+}
+//# sourceMappingURL=syncContainerRekeyProjection.js.map

package/workflows/documents/syncRekeys/syncContainerRekeyProjection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncContainerRekeyProjection.js","sourceRoot":"","sources":["syncContainerRekeyProjection.ts"],"names":[],"mappings":"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","sourcesContent":["import { computeDocumentContentKeyTargetHash } from \"@tearleads/crypto\";\nimport type { DocumentWriterProjectionResponse } from \"@tearleads/validators/response\";\nimport type { MaterializedContainerRekeyPlan } from \"../../../data/containers/shared/types\";\nimport {\n  normalizeDocumentKekTargetResponse,\n  readManifestContainerId,\n} from \"../../../data/documents/shared/readers\";\n\nfunction replaceRekeyedPathNode(input: {\n  plan: MaterializedContainerRekeyPlan;\n  projection: DocumentWriterProjectionResponse[\"authorizingContainerPaths\"][number];\n}) {\n  const index = input.projection.path.findIndex(\n    (bundle) => readManifestContainerId(bundle) === input.plan.plan.containerId,\n  );\n  if (index < 0) return { projection: input.projection, replaced: false };\n  const previousManifest = input.projection.path[index];\n  const previousKek = input.projection.containerKeks[index];\n  const nextManifest = input.plan.writerProjection.path.at(-1);\n  const nextKek = input.plan.writerProjection.containerKeks.at(-1);\n  if (\n    !previousManifest ||\n    !previousKek ||\n    !nextManifest ||\n    !nextKek ||\n    previousManifest.manifestHash !==\n      input.plan.plan.previousManifest.manifestHash ||\n    previousKek.accessManifestHash !== previousManifest.manifestHash\n  ) {\n    throw new Error(\"Document inline rekey projection predecessor mismatch\");\n  }\n  const path = [...input.projection.path];\n  const containerKeks = [...input.projection.containerKeks];\n  path[index] = nextManifest;\n  containerKeks[index] = nextKek;\n  return {\n    projection: { ...input.projection, containerKeks, path },\n    replaced: true,\n  };\n}\n\nexport async function applyContainerRekeyPlan(\n  writerProjection: DocumentWriterProjectionResponse,\n  plan: MaterializedContainerRekeyPlan,\n): Promise<DocumentWriterProjectionResponse> {\n  let replacedPath = false;\n  const authorizingContainerPaths =\n    writerProjection.authorizingContainerPaths.map((projection) => {\n      const replaced = replaceRekeyedPathNode({ plan, projection });\n      replacedPath ||= replaced.replaced;\n      return replaced.projection;\n    });\n  const nextKek = plan.writerProjection.containerKeks.at(-1);\n  const nextManifest = plan.writerProjection.path.at(-1);\n  if (!nextKek || !nextManifest) {\n    throw new Error(\"Document inline rekey projection is empty\");\n  }\n  let replacedTarget = false;\n  const targets = normalizeDocumentKekTargetResponse(\n    writerProjection.documentKekTargets,\n  ).map((target) => {\n    if (target.containerId !== plan.plan.containerId) return target;\n    replacedTarget = true;\n    return {\n      ...target,\n      containerKeyEpoch: nextKek.containerKeyEpoch,\n      containerKeyEpochId: nextKek.containerKeyEpochId,\n      containerManifestHash: nextManifest.manifestHash,\n    };\n  });\n  if (!replacedPath && !replacedTarget) {\n    throw new Error(\n      \"Document inline rekey does not belong to its writer projection\",\n    );\n  }\n  const documentKeyTargetHash =\n    await computeDocumentContentKeyTargetHash(targets);\n  return {\n    ...writerProjection,\n    authorizingContainerPaths,\n    ...(documentKeyTargetHash === writerProjection.contentKeyBundle.targetHash\n      ? {}\n      : { contentKeyBundleStale: true as const }),\n    documentKekTargets: {\n      ...writerProjection.documentKekTargets,\n      documentKeyTargetHash,\n      linkedContainerKeyEpochIds: targets.map(\n        (target) => target.containerKeyEpochId,\n      ),\n      linkedContainerManifestHashes: targets.map(\n        (target) => target.containerManifestHash,\n      ),\n      targets: targets.map((target) => ({ ...target })),\n    },\n  };\n}\n\nexport async function applyDocumentSyncContainerRekeys(input: {\n  plans: readonly MaterializedContainerRekeyPlan[];\n  writerProjection: DocumentWriterProjectionResponse;\n}): Promise<DocumentWriterProjectionResponse> {\n  let projection = input.writerProjection;\n  for (const plan of input.plans) {\n    projection = await applyContainerRekeyPlan(projection, plan);\n  }\n  return projection;\n}\n"]}

package/workflows/documents/syncRekeys/syncContainerRekeys.js

@@ -0,0 +1,72 @@
+import { projectionVerificationOptions } from "../../../data/documents/shared/types.js";
+import { DocumentSyncPreparationRequiredError } from "../syncFailures/syncRepairAbandon.js";
+import { buildMaterializedDocumentSyncPlan } from "../syncPlan/syncPlanMaterial.js";
+import { buildAutomaticContainerRekeys } from "./syncAutomaticContainerRekeys.js";
+import { requiresStandaloneAncestorRepairs } from "./syncContainerRekeyPreparation.js";
+import { applyDocumentSyncContainerRekeys } from "./syncContainerRekeyProjection.js";
+import { computeInlineRekeyCommitId } from "./syncRekeyCommit.js";
+/** Plan only: standalone server repairs belong to the outer sync attempt. */
+export async function buildRemoteDocumentSyncPlan(input) {
+    // Repairing this document's own container moves its key target hash, which
+    // marks the content-key bundle stale. Only a pass that can build a rotation
+    // snapshot is able to heal that; rotation settlement deliberately cannot
+    // (`syncRequest.ts` omits the builder for `allowRecoveryBaseline: false`), so
+    // repairing there would trade a classified "ancestor repair required" failure
+    // for an unhealable bundle — after a standalone prefix may already have been
+    // committed. Such a pass is left to fail as it did before automatic repair.
+    const canHealStaleBundle = input.sync.buildRotationSnapshot !== undefined;
+    let automaticPlans = input.preparedRekeys;
+    if (input.pendingUpdates.length &&
+        !input.sync.buildContainerRekeys &&
+        canHealStaleBundle &&
+        automaticPlans === undefined) {
+        const batch = await buildAutomaticContainerRekeys(input.sync, input.projection);
+        if (batch.hasMore ||
+            (batch.plans.length > 0 && requiresStandaloneAncestorRepairs(input.sync))) {
+            throw new DocumentSyncPreparationRequiredError();
+        }
+        automaticPlans = batch.plans;
+    }
+    const rekeyPlans = input.pendingUpdates.length && input.sync.buildContainerRekeys
+        ? await input.sync.buildContainerRekeys(input.projection, {
+            persistVerificationCheckpoints: false,
+        })
+        : automaticPlans;
+    const writerProjection = rekeyPlans?.length
+        ? await applyDocumentSyncContainerRekeys({
+            plans: rekeyPlans,
+            writerProjection: input.projection,
+        })
+        : input.projection;
+    let inlineRekeyCommitId;
+    if (rekeyPlans?.length) {
+        const headPendingUpdate = input.pendingUpdates[0];
+        if (!headPendingUpdate) {
+            throw new Error("Document inline rekey pending queue is empty");
+        }
+        inlineRekeyCommitId = await computeInlineRekeyCommitId({
+            headPendingUpdateId: headPendingUpdate.id,
+            projection: input.projection,
+        });
+    }
+    return buildMaterializedDocumentSyncPlan({
+        author: input.sync.author,
+        buildRotationSnapshot: input.sync.buildRotationSnapshot,
+        containerRekeys: rekeyPlans?.map(({ plan }) => plan.request),
+        execSql: input.sync.execSql,
+        historyMode: input.sync.historyMode,
+        inlineRekeyCommitId,
+        localVersionVector: input.sync.localVersionVector,
+        minLsn: input.minLsn,
+        onSyncTrace: input.sync.onSyncTrace,
+        pendingUpdates: input.pendingUpdates,
+        persistVerificationCheckpoints: rekeyPlans?.length ? false : undefined,
+        pullCursor: input.pullCursor,
+        regenerateQueuedCheckpoints: input.regenerateQueuedCheckpoints,
+        signedAt: input.sync.signedAt,
+        targetSecretKey: input.sync.targetSecretKey,
+        writerProjection,
+        ...projectionVerificationOptions(input.sync),
+    });
+}
+//# sourceMappingURL=syncContainerRekeys.js.map

package/workflows/documents/syncRekeys/syncContainerRekeys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncContainerRekeys.js","sourceRoot":"","sources":["syncContainerRekeys.ts"],"names":[],"mappings":"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","sourcesContent":["import type { DocumentWriterProjectionResponse } from \"@tearleads/validators/response\";\nimport type { MaterializedContainerRekeyPlan } from \"../../../data/containers/shared/types\";\nimport { projectionVerificationOptions } from \"../../../data/documents/shared/types\";\nimport type { PendingUpdateRecord } from \"../../../data/sqlite/documentPersistence\";\nimport type { SyncRemoteDocumentInput } from \"../sync/readOnlySync\";\nimport { DocumentSyncPreparationRequiredError } from \"../syncFailures/syncRepairAbandon\";\nimport { buildMaterializedDocumentSyncPlan } from \"../syncPlan/syncPlanMaterial\";\nimport { buildAutomaticContainerRekeys } from \"./syncAutomaticContainerRekeys\";\nimport { requiresStandaloneAncestorRepairs } from \"./syncContainerRekeyPreparation\";\nimport { applyDocumentSyncContainerRekeys } from \"./syncContainerRekeyProjection\";\nimport { computeInlineRekeyCommitId } from \"./syncRekeyCommit\";\n\n/** Plan only: standalone server repairs belong to the outer sync attempt. */\nexport async function buildRemoteDocumentSyncPlan(input: {\n  preparedRekeys?: readonly MaterializedContainerRekeyPlan[] | undefined;\n  minLsn?: string | undefined;\n  pendingUpdates: readonly PendingUpdateRecord[];\n  pullCursor?: string | undefined;\n  projection: DocumentWriterProjectionResponse;\n  regenerateQueuedCheckpoints: boolean;\n  sync: SyncRemoteDocumentInput;\n}) {\n  // Repairing this document's own container moves its key target hash, which\n  // marks the content-key bundle stale. Only a pass that can build a rotation\n  // snapshot is able to heal that; rotation settlement deliberately cannot\n  // (`syncRequest.ts` omits the builder for `allowRecoveryBaseline: false`), so\n  // repairing there would trade a classified \"ancestor repair required\" failure\n  // for an unhealable bundle — after a standalone prefix may already have been\n  // committed. Such a pass is left to fail as it did before automatic repair.\n  const canHealStaleBundle = input.sync.buildRotationSnapshot !== undefined;\n  let automaticPlans = input.preparedRekeys;\n  if (\n    input.pendingUpdates.length &&\n    !input.sync.buildContainerRekeys &&\n    canHealStaleBundle &&\n    automaticPlans === undefined\n  ) {\n    const batch = await buildAutomaticContainerRekeys(\n      input.sync,\n      input.projection,\n    );\n    if (\n      batch.hasMore ||\n      (batch.plans.length > 0 && requiresStandaloneAncestorRepairs(input.sync))\n    ) {\n      throw new DocumentSyncPreparationRequiredError();\n    }\n    automaticPlans = batch.plans;\n  }\n  const rekeyPlans =\n    input.pendingUpdates.length && input.sync.buildContainerRekeys\n      ? await input.sync.buildContainerRekeys(input.projection, {\n          persistVerificationCheckpoints: false,\n        })\n      : automaticPlans;\n  const writerProjection = rekeyPlans?.length\n    ? await applyDocumentSyncContainerRekeys({\n        plans: rekeyPlans,\n        writerProjection: input.projection,\n      })\n    : input.projection;\n  let inlineRekeyCommitId: string | undefined;\n  if (rekeyPlans?.length) {\n    const headPendingUpdate = input.pendingUpdates[0];\n    if (!headPendingUpdate) {\n      throw new Error(\"Document inline rekey pending queue is empty\");\n    }\n    inlineRekeyCommitId = await computeInlineRekeyCommitId({\n      headPendingUpdateId: headPendingUpdate.id,\n      projection: input.projection,\n    });\n  }\n  return buildMaterializedDocumentSyncPlan({\n    author: input.sync.author,\n    buildRotationSnapshot: input.sync.buildRotationSnapshot,\n    containerRekeys: rekeyPlans?.map(({ plan }) => plan.request),\n    execSql: input.sync.execSql,\n    historyMode: input.sync.historyMode,\n    inlineRekeyCommitId,\n    localVersionVector: input.sync.localVersionVector,\n    minLsn: input.minLsn,\n    onSyncTrace: input.sync.onSyncTrace,\n    pendingUpdates: input.pendingUpdates,\n    persistVerificationCheckpoints: rekeyPlans?.length ? false : undefined,\n    pullCursor: input.pullCursor,\n    regenerateQueuedCheckpoints: input.regenerateQueuedCheckpoints,\n    signedAt: input.sync.signedAt,\n    targetSecretKey: input.sync.targetSecretKey,\n    writerProjection,\n    ...projectionVerificationOptions(input.sync),\n  });\n}\n"]}

package/workflows/documents/syncRekeys/syncRecoveryRekey.d.ts

@@ -0,0 +1,70 @@
+import type { DocumentSyncResponse } from "../../../internal/validators/response/index.js";
+import type { DocumentSyncSubmitFailure } from "../../../data/documents/shared/types.js";
+import { type PendingUpdateRecord } from "../../../data/sqlite/documentPersistence.js";
+import { type ExecSql } from "../../../data/sqlite/sqlSchema.js";
+export type RekeyPendingUpdate = (execSql: ExecSql, id: string) => Promise<string | null>;
+interface DecryptedSyncUpdate {
+    id: string;
+    partialEndVersionVector: string;
+    partialStartVersionVector: string;
+    updateData: Uint8Array;
+}
+export declare function settledPendingUpdateIdsFromSync(input: {
+    decryptedUpdates: readonly DecryptedSyncUpdate[];
+    recoveryPendingUpdatesById: ReadonlyMap<string, PendingUpdateRecord>;
+    response: DocumentSyncResponse;
+}): string[];
+/**
+ * A read-only recovery sync settles a conflicted pending update only when the
+ * response carries it — but the server's frontier filter omits spans the
+ * request's localVersionVector already covers, which a locally-applied
+ * pending update always is. Left alone, the conflicted id is resubmitted (and
+ * 409s the whole outgoing batch) forever: a lost ack leaves the server
+ * holding the original ciphertext, and every rebuild encrypts with a fresh
+ * IV, so a byte-identical retry can never be reproduced. Re-key what
+ * recovery could not settle so the next sync pass submits the same ops under
+ * a conflict-free id; the server-side copy stays harmless because CRDT
+ * update import is idempotent.
+ *
+ * Re-keying goes through the caller's persistence implementation when given
+ * (defaulting to the built-in pending-update table) and reports only ids
+ * whose row actually changed, so a record living in some other queue never
+ * counts as progress. Returns the fresh ids so callers can treat re-keying
+ * as settlement-like progress and schedule the pass that submits them.
+ *
+ * A row whose persisted rekeyCount has reached the bound is not re-keyed
+ * again: it is reported as exhausted so the caller can surface a terminal
+ * failure instead of feeding an unbounded conflict loop that survives
+ * restarts (each session's in-memory lane cap resets, this bound does not).
+ */
+export declare function rekeyUnsettledRecoveryPendingUpdates(input: {
+    execSql: ExecSql;
+    recoveryPendingUpdatesById: ReadonlyMap<string, PendingUpdateRecord>;
+    rekeyPendingUpdate?: RekeyPendingUpdate | undefined;
+    settledPendingUpdateIds: readonly string[];
+    stillCurrent?: (() => boolean) | undefined;
+}): Promise<{
+    exhaustedPendingUpdateIds: string[];
+    rekeyedPendingUpdateIds: string[];
+}>;
+/**
+ * Re-key what recovery could not settle and surface exhausted rows through
+ * the caller's terminal-failure handler. The exhausted count is also
+ * returned so the sync result can carry it: a pass that recorded this
+ * failure must not read as clean to callers that clear recorded failures
+ * on success.
+ */
+export declare function rekeyAndReportUnsettledRecoveryPendingUpdates(input: Parameters<typeof rekeyUnsettledRecoveryPendingUpdates>[0] & {
+    onTerminalSubmitFailure?: ((failure: DocumentSyncSubmitFailure) => Promise<void> | void) | undefined;
+}): Promise<{
+    exhaustedPendingUpdateCount: number;
+    rekeyedPendingUpdateIds: string[];
+}>;
+/**
+ * Terminal failure recorded when conflict recovery gives up on pending
+ * updates whose persisted re-key bound is exhausted. Shaped like a submit
+ * failure so the existing write-queue surface (recordDocumentSyncFailure via
+ * onTerminalSubmitFailure) explains the stuck write without new plumbing.
+ */
+export declare function rekeyLimitSubmitFailure(exhaustedCount: number): DocumentSyncSubmitFailure;
+export {};