@tearleads/client-sdk 0.0.0-stage → 0.1.13

package/workflows/documents/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 {};

package/workflows/documents/syncRecoveryRekey.js

@@ -0,0 +1,120 @@
+import { base64ToBytes } from "../../internal/encoding/index.js";
+import { MAX_PENDING_UPDATE_REKEYS, rekeyDocumentPendingUpdate, } from "../../data/sqlite/documentPersistence.js";
+import { getClientSQLitePersistenceRuntime } from "../../data/sqlite/sqlitePersistenceRuntime.js";
+import { runSerializedSqlMutation, } from "../../data/sqlite/sqlSchema.js";
+function bytesEqual(left, right) {
+    return (left.byteLength === right.byteLength &&
+        left.every((value, index) => value === right[index]));
+}
+function pendingUpdateMatchesDecryptedUpdate(pendingUpdate, decryptedUpdate) {
+    if (pendingUpdate.partialStartVersionVector !==
+        decryptedUpdate.partialStartVersionVector ||
+        pendingUpdate.partialEndVersionVector !==
+            decryptedUpdate.partialEndVersionVector) {
+        return false;
+    }
+    return bytesEqual(base64ToBytes(pendingUpdate.updateData), decryptedUpdate.updateData);
+}
+export function settledPendingUpdateIdsFromSync(input) {
+    const settled = new Set(input.response.acceptedOutgoingUpdateIds);
+    for (const update of input.decryptedUpdates) {
+        const pendingUpdate = input.recoveryPendingUpdatesById.get(update.id);
+        if (pendingUpdate &&
+            pendingUpdateMatchesDecryptedUpdate(pendingUpdate, update)) {
+            settled.add(update.id);
+        }
+    }
+    return [...settled];
+}
+/**
+ * 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 async function rekeyUnsettledRecoveryPendingUpdates(input) {
+    const rekeyPendingUpdate = input.rekeyPendingUpdate ?? rekeyDocumentPendingUpdate;
+    const settled = new Set(input.settledPendingUpdateIds);
+    const rekeyedPendingUpdateIds = [];
+    const exhaustedPendingUpdateIds = [];
+    for (const [pendingUpdateId, record] of input.recoveryPendingUpdatesById) {
+        if (input.stillCurrent?.() === false)
+            break;
+        if (settled.has(pendingUpdateId)) {
+            continue;
+        }
+        // Known multi-tab limitation: the count is the row as loaded at pass
+        // start, so a sibling tab that settle-deleted the row can make this
+        // record a failure for work that no longer exists. The stale failure is
+        // transient — the document's next clean pass clears it.
+        if ((record.rekeyCount ?? 0) >= MAX_PENDING_UPDATE_REKEYS) {
+            exhaustedPendingUpdateIds.push(pendingUpdateId);
+            continue;
+        }
+        const outcome = await runSerializedSqlMutation(input.execSql, (lockedExecSql) => getClientSQLitePersistenceRuntime(lockedExecSql).guardedTransaction(async () => input.stillCurrent?.() === false
+            ? null
+            : rekeyPendingUpdate(lockedExecSql, pendingUpdateId), () => input.stillCurrent?.() !== false));
+        if (!outcome.committed)
+            break;
+        const nextId = outcome.result;
+        if (nextId !== null) {
+            rekeyedPendingUpdateIds.push(nextId);
+        }
+    }
+    if (input.stillCurrent?.() === false) {
+        return { exhaustedPendingUpdateIds: [], rekeyedPendingUpdateIds: [] };
+    }
+    return { exhaustedPendingUpdateIds, rekeyedPendingUpdateIds };
+}
+/**
+ * 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 async function rekeyAndReportUnsettledRecoveryPendingUpdates(input) {
+    const { exhaustedPendingUpdateIds, rekeyedPendingUpdateIds } = await rekeyUnsettledRecoveryPendingUpdates(input);
+    if (input.stillCurrent?.() === false) {
+        return { exhaustedPendingUpdateCount: 0, rekeyedPendingUpdateIds: [] };
+    }
+    if (exhaustedPendingUpdateIds.length > 0) {
+        await input.onTerminalSubmitFailure?.(rekeyLimitSubmitFailure(exhaustedPendingUpdateIds.length));
+    }
+    return {
+        exhaustedPendingUpdateCount: exhaustedPendingUpdateIds.length,
+        rekeyedPendingUpdateIds,
+    };
+}
+/**
+ * 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 function rekeyLimitSubmitFailure(exhaustedCount) {
+    return {
+        message: `Update conflict recovery gave up after ${MAX_PENDING_UPDATE_REKEYS} re-key attempts (${exhaustedCount} update${exhaustedCount === 1 ? "" : "s"})`,
+        ok: false,
+        report: () => { },
+        status: null,
+    };
+}
+//# sourceMappingURL=syncRecoveryRekey.js.map

package/workflows/documents/syncRecoveryRekey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncRecoveryRekey.js","sourceRoot":"","sources":["syncRecoveryRekey.ts"],"names":[],"mappings":"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","sourcesContent":["import { base64ToBytes } from \"@tearleads/encoding\";\nimport type { DocumentSyncResponse } from \"@tearleads/validators/response\";\nimport type { DocumentSyncSubmitFailure } from \"../../data/documents/shared/types\";\nimport {\n  MAX_PENDING_UPDATE_REKEYS,\n  type PendingUpdateRecord,\n  rekeyDocumentPendingUpdate,\n} from \"../../data/sqlite/documentPersistence\";\nimport { getClientSQLitePersistenceRuntime } from \"../../data/sqlite/sqlitePersistenceRuntime\";\nimport {\n  type ExecSql,\n  runSerializedSqlMutation,\n} from \"../../data/sqlite/sqlSchema\";\n\nexport type RekeyPendingUpdate = (\n  execSql: ExecSql,\n  id: string,\n) => Promise<string | null>;\n\ninterface DecryptedSyncUpdate {\n  id: string;\n  partialEndVersionVector: string;\n  partialStartVersionVector: string;\n  updateData: Uint8Array;\n}\n\nfunction bytesEqual(left: Uint8Array, right: Uint8Array): boolean {\n  return (\n    left.byteLength === right.byteLength &&\n    left.every((value, index) => value === right[index])\n  );\n}\n\nfunction pendingUpdateMatchesDecryptedUpdate(\n  pendingUpdate: PendingUpdateRecord,\n  decryptedUpdate: Omit<DecryptedSyncUpdate, \"id\">,\n): boolean {\n  if (\n    pendingUpdate.partialStartVersionVector !==\n      decryptedUpdate.partialStartVersionVector ||\n    pendingUpdate.partialEndVersionVector !==\n      decryptedUpdate.partialEndVersionVector\n  ) {\n    return false;\n  }\n\n  return bytesEqual(\n    base64ToBytes(pendingUpdate.updateData),\n    decryptedUpdate.updateData,\n  );\n}\n\nexport function settledPendingUpdateIdsFromSync(input: {\n  decryptedUpdates: readonly DecryptedSyncUpdate[];\n  recoveryPendingUpdatesById: ReadonlyMap<string, PendingUpdateRecord>;\n  response: DocumentSyncResponse;\n}): string[] {\n  const settled = new Set(input.response.acceptedOutgoingUpdateIds);\n\n  for (const update of input.decryptedUpdates) {\n    const pendingUpdate = input.recoveryPendingUpdatesById.get(update.id);\n    if (\n      pendingUpdate &&\n      pendingUpdateMatchesDecryptedUpdate(pendingUpdate, update)\n    ) {\n      settled.add(update.id);\n    }\n  }\n\n  return [...settled];\n}\n\n/**\n * A read-only recovery sync settles a conflicted pending update only when the\n * response carries it — but the server's frontier filter omits spans the\n * request's localVersionVector already covers, which a locally-applied\n * pending update always is. Left alone, the conflicted id is resubmitted (and\n * 409s the whole outgoing batch) forever: a lost ack leaves the server\n * holding the original ciphertext, and every rebuild encrypts with a fresh\n * IV, so a byte-identical retry can never be reproduced. Re-key what\n * recovery could not settle so the next sync pass submits the same ops under\n * a conflict-free id; the server-side copy stays harmless because CRDT\n * update import is idempotent.\n *\n * Re-keying goes through the caller's persistence implementation when given\n * (defaulting to the built-in pending-update table) and reports only ids\n * whose row actually changed, so a record living in some other queue never\n * counts as progress. Returns the fresh ids so callers can treat re-keying\n * as settlement-like progress and schedule the pass that submits them.\n *\n * A row whose persisted rekeyCount has reached the bound is not re-keyed\n * again: it is reported as exhausted so the caller can surface a terminal\n * failure instead of feeding an unbounded conflict loop that survives\n * restarts (each session's in-memory lane cap resets, this bound does not).\n */\nexport async function rekeyUnsettledRecoveryPendingUpdates(input: {\n  execSql: ExecSql;\n  recoveryPendingUpdatesById: ReadonlyMap<string, PendingUpdateRecord>;\n  rekeyPendingUpdate?: RekeyPendingUpdate | undefined;\n  settledPendingUpdateIds: readonly string[];\n  stillCurrent?: (() => boolean) | undefined;\n}): Promise<{\n  exhaustedPendingUpdateIds: string[];\n  rekeyedPendingUpdateIds: string[];\n}> {\n  const rekeyPendingUpdate =\n    input.rekeyPendingUpdate ?? rekeyDocumentPendingUpdate;\n  const settled = new Set(input.settledPendingUpdateIds);\n  const rekeyedPendingUpdateIds: string[] = [];\n  const exhaustedPendingUpdateIds: string[] = [];\n  for (const [pendingUpdateId, record] of input.recoveryPendingUpdatesById) {\n    if (input.stillCurrent?.() === false) break;\n    if (settled.has(pendingUpdateId)) {\n      continue;\n    }\n    // Known multi-tab limitation: the count is the row as loaded at pass\n    // start, so a sibling tab that settle-deleted the row can make this\n    // record a failure for work that no longer exists. The stale failure is\n    // transient — the document's next clean pass clears it.\n    if ((record.rekeyCount ?? 0) >= MAX_PENDING_UPDATE_REKEYS) {\n      exhaustedPendingUpdateIds.push(pendingUpdateId);\n      continue;\n    }\n    const outcome = await runSerializedSqlMutation(\n      input.execSql,\n      (lockedExecSql) =>\n        getClientSQLitePersistenceRuntime(lockedExecSql).guardedTransaction(\n          async () =>\n            input.stillCurrent?.() === false\n              ? null\n              : rekeyPendingUpdate(lockedExecSql, pendingUpdateId),\n          () => input.stillCurrent?.() !== false,\n        ),\n    );\n    if (!outcome.committed) break;\n    const nextId = outcome.result;\n    if (nextId !== null) {\n      rekeyedPendingUpdateIds.push(nextId);\n    }\n  }\n  if (input.stillCurrent?.() === false) {\n    return { exhaustedPendingUpdateIds: [], rekeyedPendingUpdateIds: [] };\n  }\n  return { exhaustedPendingUpdateIds, rekeyedPendingUpdateIds };\n}\n\n/**\n * Re-key what recovery could not settle and surface exhausted rows through\n * the caller's terminal-failure handler. The exhausted count is also\n * returned so the sync result can carry it: a pass that recorded this\n * failure must not read as clean to callers that clear recorded failures\n * on success.\n */\nexport async function rekeyAndReportUnsettledRecoveryPendingUpdates(\n  input: Parameters<typeof rekeyUnsettledRecoveryPendingUpdates>[0] & {\n    onTerminalSubmitFailure?:\n      | ((failure: DocumentSyncSubmitFailure) => Promise<void> | void)\n      | undefined;\n  },\n): Promise<{\n  exhaustedPendingUpdateCount: number;\n  rekeyedPendingUpdateIds: string[];\n}> {\n  const { exhaustedPendingUpdateIds, rekeyedPendingUpdateIds } =\n    await rekeyUnsettledRecoveryPendingUpdates(input);\n  if (input.stillCurrent?.() === false) {\n    return { exhaustedPendingUpdateCount: 0, rekeyedPendingUpdateIds: [] };\n  }\n  if (exhaustedPendingUpdateIds.length > 0) {\n    await input.onTerminalSubmitFailure?.(\n      rekeyLimitSubmitFailure(exhaustedPendingUpdateIds.length),\n    );\n  }\n  return {\n    exhaustedPendingUpdateCount: exhaustedPendingUpdateIds.length,\n    rekeyedPendingUpdateIds,\n  };\n}\n\n/**\n * Terminal failure recorded when conflict recovery gives up on pending\n * updates whose persisted re-key bound is exhausted. Shaped like a submit\n * failure so the existing write-queue surface (recordDocumentSyncFailure via\n * onTerminalSubmitFailure) explains the stuck write without new plumbing.\n */\nexport function rekeyLimitSubmitFailure(\n  exhaustedCount: number,\n): DocumentSyncSubmitFailure {\n  return {\n    message: `Update conflict recovery gave up after ${MAX_PENDING_UPDATE_REKEYS} re-key attempts (${exhaustedCount} update${exhaustedCount === 1 ? \"\" : \"s\"})`,\n    ok: false,\n    report: () => {},\n    status: null,\n  };\n}\n"]}

package/workflows/documents/syncRekeyCommit.js

@@ -0,0 +1,18 @@
+import { serializeKeyingCanonicalJson, toFingerprint } from "../../internal/crypto/index.js";
+const textEncoder = new TextEncoder();
+/**
+ * Identifies one logical inline-rekey flush across plan rematerialization.
+ * Rotation baselines and signed rekey events can be freshly randomized on a
+ * retry. The durable FIFO head and pre-rekey projection stay stable even when
+ * a new local edit is appended to the queue after a response is lost.
+ */
+export async function computeInlineRekeyCommitId(input) {
+    return toFingerprint(textEncoder.encode(serializeKeyingCanonicalJson({
+        domain: "tearleads.document-sync.inline-rekey-commit",
+        documentId: input.projection.documentId,
+        headPendingUpdateId: input.headPendingUpdateId,
+        predecessorTargetHash: input.projection.documentKekTargets.documentKeyTargetHash,
+        version: 1,
+    })));
+}
+//# sourceMappingURL=syncRekeyCommit.js.map

package/workflows/documents/syncRekeyCommit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncRekeyCommit.js","sourceRoot":"","sources":["syncRekeyCommit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,4BAA4B,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGhF,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC;AAEtC;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAAC,KAGhD;IACC,OAAO,aAAa,CAClB,WAAW,CAAC,MAAM,CAChB,4BAA4B,CAAC;QAC3B,MAAM,EAAE,6CAA6C;QACrD,UAAU,EAAE,KAAK,CAAC,UAAU,CAAC,UAAU;QACvC,mBAAmB,EAAE,KAAK,CAAC,mBAAmB;QAC9C,qBAAqB,EACnB,KAAK,CAAC,UAAU,CAAC,kBAAkB,CAAC,qBAAqB;QAC3D,OAAO,EAAE,CAAC;KACX,CAAC,CACH,CACF,CAAC;AACJ,CAAC","sourcesContent":["import { serializeKeyingCanonicalJson, toFingerprint } from \"@tearleads/crypto\";\nimport type { DocumentWriterProjectionResponse } from \"@tearleads/validators/response\";\n\nconst textEncoder = new TextEncoder();\n\n/**\n * Identifies one logical inline-rekey flush across plan rematerialization.\n * Rotation baselines and signed rekey events can be freshly randomized on a\n * retry. The durable FIFO head and pre-rekey projection stay stable even when\n * a new local edit is appended to the queue after a response is lost.\n */\nexport async function computeInlineRekeyCommitId(input: {\n  readonly headPendingUpdateId: string;\n  readonly projection: DocumentWriterProjectionResponse;\n}): Promise<string> {\n  return toFingerprint(\n    textEncoder.encode(\n      serializeKeyingCanonicalJson({\n        domain: \"tearleads.document-sync.inline-rekey-commit\",\n        documentId: input.projection.documentId,\n        headPendingUpdateId: input.headPendingUpdateId,\n        predecessorTargetHash:\n          input.projection.documentKekTargets.documentKeyTargetHash,\n        version: 1,\n      }),\n    ),\n  );\n}\n"]}

package/workflows/documents/syncRepairAbandon.js

@@ -0,0 +1,27 @@
+/**
+ * A repair that cannot proceed for a routine reason: the organization's writes
+ * are gated, the server refused the rekey, a peer rotated an ancestor mid-pass,
+ * the refreshed projection was unavailable, or the pass exhausted its repair
+ * budget. None is a defect, so the sync lane abandons the attempt rather than
+ * reporting a failed run; the next trigger re-plans from a fresh projection.
+ *
+ * Lives apart from both the planner and the preparation loop: each throws it,
+ * and preparation already imports the planner, so declaring it in either would
+ * close a dependency cycle.
+ */
+export class DocumentAncestorRepairAbandonedError extends Error {
+    reason;
+    constructor(reason) {
+        super(`Document ancestor repair abandoned: ${reason}`);
+        this.reason = reason;
+        this.name = "DocumentAncestorRepairAbandonedError";
+    }
+}
+/** A refreshed projection needs durable preparation before another pure plan. */
+export class DocumentSyncPreparationRequiredError extends Error {
+    constructor() {
+        super("Document sync requires a new ancestor preparation step");
+        this.name = "DocumentSyncPreparationRequiredError";
+    }
+}
+//# sourceMappingURL=syncRepairAbandon.js.map

package/workflows/documents/syncRepairAbandon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncRepairAbandon.js","sourceRoot":"","sources":["syncRepairAbandon.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,MAAM,OAAO,oCAAqC,SAAQ,KAAK;IACxC;IAArB,YAAqB,MAAmC;QACtD,KAAK,CAAC,uCAAuC,MAAM,EAAE,CAAC,CAAC;QADpC,WAAM,GAAN,MAAM,CAA6B;QAEtD,IAAI,CAAC,IAAI,GAAG,sCAAsC,CAAC;IACrD,CAAC;CACF;AAED,iFAAiF;AACjF,MAAM,OAAO,oCAAqC,SAAQ,KAAK;IAC7D;QACE,KAAK,CAAC,wDAAwD,CAAC,CAAC;QAChE,IAAI,CAAC,IAAI,GAAG,sCAAsC,CAAC;IACrD,CAAC;CACF","sourcesContent":["import type { AncestorRepairAbandonReason } from \"./syncTrace\";\n\n/**\n * A repair that cannot proceed for a routine reason: the organization's writes\n * are gated, the server refused the rekey, a peer rotated an ancestor mid-pass,\n * the refreshed projection was unavailable, or the pass exhausted its repair\n * budget. None is a defect, so the sync lane abandons the attempt rather than\n * reporting a failed run; the next trigger re-plans from a fresh projection.\n *\n * Lives apart from both the planner and the preparation loop: each throws it,\n * and preparation already imports the planner, so declaring it in either would\n * close a dependency cycle.\n */\nexport class DocumentAncestorRepairAbandonedError extends Error {\n  constructor(readonly reason: AncestorRepairAbandonReason) {\n    super(`Document ancestor repair abandoned: ${reason}`);\n    this.name = \"DocumentAncestorRepairAbandonedError\";\n  }\n}\n\n/** A refreshed projection needs durable preparation before another pure plan. */\nexport class DocumentSyncPreparationRequiredError extends Error {\n  constructor() {\n    super(\"Document sync requires a new ancestor preparation step\");\n    this.name = \"DocumentSyncPreparationRequiredError\";\n  }\n}\n"]}

package/workflows/documents/syncRepairAccess.js

@@ -0,0 +1,42 @@
+import { resolveContainerPathUserAccessLevel } from "../../internal/crypto/index.js";
+import { requireProjectionUserKeyResolver, verifyDocumentWriterProjectionAuthorization, } from "../../data/keyingProjectionVerification.js";
+/** A repair refusal on one link does not revoke write access through another. */
+export async function hasOtherLinkedWriteAccess(sync, projection, inaccessibleContainerId) {
+    if (projection.authorizingContainerPaths.length < 2)
+        return false;
+    const verified = await verifyDocumentWriterProjectionAuthorization({
+        execSql: sync.execSql,
+        persistVerificationCheckpoints: false,
+        projection,
+        resolveUserKey: requireProjectionUserKeyResolver(sync.resolveProjectionUserKey, "Document linked repair access"),
+        stillCurrent: sync.stillCurrent,
+        warmReferencedPrincipalPolicies: sync.warmReferencedPrincipalPolicies,
+    });
+    const document = verified.documentManifestByHash.get(projection.documentManifest.manifestHash);
+    if (!document ||
+        document.state.documentId !== sync.documentId ||
+        document.state.organizationId !== sync.author.organizationId)
+        return false;
+    // The map also contains historical paths. Only the verified current paths
+    // named by this projection may establish present write authority.
+    return projection.authorizingContainerPaths.some((candidate) => {
+        const headHash = candidate.path.at(-1)?.manifestHash;
+        const path = headHash
+            ? verified.containerPathByManifestHash.get(headHash)
+            : undefined;
+        const leaf = path?.at(-1);
+        if (!path ||
+            !leaf ||
+            leaf.state.containerId === inaccessibleContainerId ||
+            leaf.state.organizationId !== document.state.organizationId ||
+            !document.state.linkedContainerIds.includes(leaf.state.containerId))
+            return false;
+        const access = resolveContainerPathUserAccessLevel({
+            path,
+            principalPolicies: verified.principalPolicies,
+            userId: sync.author.signerUserId,
+        });
+        return access === "write" || access === "admin";
+    });
+}
+//# sourceMappingURL=syncRepairAccess.js.map

package/workflows/documents/syncRepairAccess.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncRepairAccess.js","sourceRoot":"","sources":["syncRepairAccess.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mCAAmC,EAAE,MAAM,mBAAmB,CAAC;AAExE,OAAO,EACL,gCAAgC,EAChC,2CAA2C,GAC5C,MAAM,yCAAyC,CAAC;AAGjD,iFAAiF;AACjF,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,IAA6B,EAC7B,UAA4C,EAC5C,uBAA+B;IAE/B,IAAI,UAAU,CAAC,yBAAyB,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAClE,MAAM,QAAQ,GAAG,MAAM,2CAA2C,CAAC;QACjE,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,8BAA8B,EAAE,KAAK;QACrC,UAAU;QACV,cAAc,EAAE,gCAAgC,CAC9C,IAAI,CAAC,wBAAwB,EAC7B,+BAA+B,CAChC;QACD,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,+BAA+B,EAAE,IAAI,CAAC,+BAA+B;KACtE,CAAC,CAAC;IACH,MAAM,QAAQ,GAAG,QAAQ,CAAC,sBAAsB,CAAC,GAAG,CAClD,UAAU,CAAC,gBAAgB,CAAC,YAAY,CACzC,CAAC;IACF,IACE,CAAC,QAAQ;QACT,QAAQ,CAAC,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC,UAAU;QAC7C,QAAQ,CAAC,KAAK,CAAC,cAAc,KAAK,IAAI,CAAC,MAAM,CAAC,cAAc;QAE5D,OAAO,KAAK,CAAC;IACf,0EAA0E;IAC1E,kEAAkE;IAClE,OAAO,UAAU,CAAC,yBAAyB,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE;QAC7D,MAAM,QAAQ,GAAG,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,YAAY,CAAC;QACrD,MAAM,IAAI,GAAG,QAAQ;YACnB,CAAC,CAAC,QAAQ,CAAC,2BAA2B,CAAC,GAAG,CAAC,QAAQ,CAAC;YACpD,CAAC,CAAC,SAAS,CAAC;QACd,MAAM,IAAI,GAAG,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1B,IACE,CAAC,IAAI;YACL,CAAC,IAAI;YACL,IAAI,CAAC,KAAK,CAAC,WAAW,KAAK,uBAAuB;YAClD,IAAI,CAAC,KAAK,CAAC,cAAc,KAAK,QAAQ,CAAC,KAAK,CAAC,cAAc;YAC3D,CAAC,QAAQ,CAAC,KAAK,CAAC,kBAAkB,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC;YAEnE,OAAO,KAAK,CAAC;QACf,MAAM,MAAM,GAAG,mCAAmC,CAAC;YACjD,IAAI;YACJ,iBAAiB,EAAE,QAAQ,CAAC,iBAAiB;YAC7C,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,YAAY;SACjC,CAAC,CAAC;QACH,OAAO,MAAM,KAAK,OAAO,IAAI,MAAM,KAAK,OAAO,CAAC;IAClD,CAAC,CAAC,CAAC;AACL,CAAC","sourcesContent":["import { resolveContainerPathUserAccessLevel } from \"@tearleads/crypto\";\nimport type { DocumentWriterProjectionResponse } from \"@tearleads/validators/response\";\nimport {\n  requireProjectionUserKeyResolver,\n  verifyDocumentWriterProjectionAuthorization,\n} from \"../../data/keyingProjectionVerification\";\nimport type { SyncRemoteDocumentInput } from \"./readOnlySync\";\n\n/** A repair refusal on one link does not revoke write access through another. */\nexport async function hasOtherLinkedWriteAccess(\n  sync: SyncRemoteDocumentInput,\n  projection: DocumentWriterProjectionResponse,\n  inaccessibleContainerId: string,\n): Promise<boolean> {\n  if (projection.authorizingContainerPaths.length < 2) return false;\n  const verified = await verifyDocumentWriterProjectionAuthorization({\n    execSql: sync.execSql,\n    persistVerificationCheckpoints: false,\n    projection,\n    resolveUserKey: requireProjectionUserKeyResolver(\n      sync.resolveProjectionUserKey,\n      \"Document linked repair access\",\n    ),\n    stillCurrent: sync.stillCurrent,\n    warmReferencedPrincipalPolicies: sync.warmReferencedPrincipalPolicies,\n  });\n  const document = verified.documentManifestByHash.get(\n    projection.documentManifest.manifestHash,\n  );\n  if (\n    !document ||\n    document.state.documentId !== sync.documentId ||\n    document.state.organizationId !== sync.author.organizationId\n  )\n    return false;\n  // The map also contains historical paths. Only the verified current paths\n  // named by this projection may establish present write authority.\n  return projection.authorizingContainerPaths.some((candidate) => {\n    const headHash = candidate.path.at(-1)?.manifestHash;\n    const path = headHash\n      ? verified.containerPathByManifestHash.get(headHash)\n      : undefined;\n    const leaf = path?.at(-1);\n    if (\n      !path ||\n      !leaf ||\n      leaf.state.containerId === inaccessibleContainerId ||\n      leaf.state.organizationId !== document.state.organizationId ||\n      !document.state.linkedContainerIds.includes(leaf.state.containerId)\n    )\n      return false;\n    const access = resolveContainerPathUserAccessLevel({\n      path,\n      principalPolicies: verified.principalPolicies,\n      userId: sync.author.signerUserId,\n    });\n    return access === \"write\" || access === \"admin\";\n  });\n}\n"]}

package/workflows/documents/syncResponseResult.js

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

package/workflows/documents/syncResponseResult.js.map

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

package/workflows/documents/syncSubmittedResult.js

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