@tearleads/client-sdk 0.0.0-stage → 0.1.11

package/workflows/documents/linkSetProjectionSeed.js

@@ -0,0 +1,119 @@
+import { assertDocumentWriterProjectionConsistent } from "../../data/documents/shared/projection.js";
+import { mergeProjectionPolicyEvidence } from "../../data/keyingProjectionVerification/mergeProjectionPolicyEvidence.js";
+function uniqueManifestBundles(bundles) {
+    const byHash = new Map();
+    for (const bundle of bundles) {
+        if (!byHash.has(bundle.manifestHash)) {
+            byHash.set(bundle.manifestHash, bundle);
+        }
+    }
+    return [...byHash.values()];
+}
+function uniqueManifestPaths(paths) {
+    const byLeafHash = new Map();
+    for (const path of paths) {
+        const leafHash = path.at(-1)?.manifestHash;
+        if (!leafHash || byLeafHash.has(leafHash)) {
+            continue;
+        }
+        byLeafHash.set(leafHash, [...path]);
+    }
+    return [...byLeafHash.values()];
+}
+function containerProjectionManifestHistory(projection) {
+    return projection.containerKeks.flatMap((kek) => kek.containerManifestHistory);
+}
+function documentProjectionContainerPaths(projection) {
+    return uniqueManifestPaths([
+        ...projection.documentManifestContainerPaths,
+        ...projection.authorizingContainerPaths.map((path) => path.path),
+    ]);
+}
+function documentProjectionContainerHistory(input) {
+    const priorContainerPaths = documentProjectionContainerPaths(input.priorProjection);
+    const priorAuthorizingContainerProjections = input.priorProjection.authorizingContainerPaths;
+    return uniqueManifestBundles([
+        ...input.priorProjection.documentContainerManifestHistory,
+        ...priorContainerPaths.flat(),
+        ...priorAuthorizingContainerProjections.flatMap((projection) => [
+            ...projection.path,
+            ...containerProjectionManifestHistory(projection),
+        ]),
+        ...input.targetContainerProjection.path,
+        ...containerProjectionManifestHistory(input.targetContainerProjection),
+    ]);
+}
+/**
+ * Reconstruct the post-mutation writer projection from a link/unlink response.
+ * The response carries the fresh manifest, content-key bundle, and KEK targets;
+ * the authorizing container paths change by exactly one entry — link appends
+ * the target container's projection, unlink drops it (keyed by containerId).
+ * Link does not rotate the content key (only unlink does), but either way the
+ * bundle/targets the next write needs come straight from the response. The
+ * caller verifies this projection for internal consistency before seeding it,
+ * so a wrong reconstruction is discarded rather than cached.
+ */
+function linkSetWriterProjectionFromResponse(input) {
+    // The target container's authorizing path is replaced wholesale: link adds
+    // the fresh target projection back, unlink leaves it dropped.
+    const retainedPaths = input.priorProjection.authorizingContainerPaths.filter((path) => path.containerId !== input.targetContainerId);
+    const authorizingContainerPaths = input.operation === "link"
+        ? [...retainedPaths, input.targetContainerProjection]
+        : retainedPaths;
+    const documentManifestContainerPaths = uniqueManifestPaths([
+        ...documentProjectionContainerPaths(input.priorProjection),
+        input.targetContainerProjection.path,
+    ]);
+    return {
+        policyEvidence: mergeProjectionPolicyEvidence([
+            input.priorProjection.policyEvidence,
+            input.targetContainerProjection.policyEvidence,
+        ]),
+        authorizingContainerPaths,
+        contentKeyBundle: input.response.contentKeyBundle,
+        documentId: input.response.id,
+        documentContainerManifestHistory: documentProjectionContainerHistory({
+            priorProjection: input.priorProjection,
+            targetContainerProjection: input.targetContainerProjection,
+        }),
+        documentKekTargets: input.response.documentKekTargets,
+        documentManifest: input.response.accessManifest,
+        documentManifestContainerPaths,
+        documentManifestHistory: [
+            input.priorProjection.documentManifest,
+            ...input.priorProjection.documentManifestHistory,
+        ],
+    };
+}
+/**
+ * Reconstruct and seed the post-mutation writer projection so the first read
+ * after a link/unlink resolves locally instead of a cold GET. Gates the seed on
+ * the projection's internal consistency (manifest hash ↔ content-key bundle ↔
+ * KEK targets ↔ linked containers); on any mismatch the seed is skipped and the
+ * next read falls back to a fetch — the seed is an optimization, never a
+ * correctness dependency. The expensive per-path signature re-verification is
+ * deliberately not run here: the server already verified the mutation, and the
+ * next read re-verifies the projection before any write.
+ */
+export async function seedLinkSetWriterProjection(input) {
+    const projection = linkSetWriterProjectionFromResponse({
+        operation: input.operation,
+        priorProjection: input.priorProjection,
+        response: input.response,
+        targetContainerId: input.targetContainerId,
+        targetContainerProjection: input.targetContainerProjection,
+    });
+    try {
+        await assertDocumentWriterProjectionConsistent(projection, {
+            execSql: input.execSql,
+            trustedLocalProjection: true,
+        });
+    }
+    catch {
+        return;
+    }
+    if (input.stillCurrent?.() === false)
+        return;
+    input.apiClient.primeDocumentWriterProjection(input.response.id, projection);
+}
+//# sourceMappingURL=linkSetProjectionSeed.js.map

package/workflows/documents/linkSetProjectionSeed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"linkSetProjectionSeed.js","sourceRoot":"","sources":["linkSetProjectionSeed.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  AccessManifestBundleWireResponse,\n  ContainerKeyingPathResponse,\n  ContainerWriterProjectionResponse,\n  DocumentLinkSetMutationResponse,\n  DocumentWriterProjectionResponse,\n} from \"@tearleads/validators/response\";\nimport { assertDocumentWriterProjectionConsistent } from \"../../data/documents/shared/projection\";\nimport type { DocumentLinkSetMutationOperation } from \"../../data/documents/shared/types\";\nimport { mergeProjectionPolicyEvidence } from \"../../data/keyingProjectionVerification/mergeProjectionPolicyEvidence\";\nimport type { ExecSql } from \"../../data/sqlite/sqlSchema\";\n\ninterface DocumentLinkSetProjectionSeedApi {\n  primeDocumentWriterProjection(\n    documentId: string,\n    projection: DocumentWriterProjectionResponse,\n  ): void;\n}\n\nfunction uniqueManifestBundles(\n  bundles: readonly AccessManifestBundleWireResponse[],\n): AccessManifestBundleWireResponse[] {\n  const byHash = new Map<string, AccessManifestBundleWireResponse>();\n  for (const bundle of bundles) {\n    if (!byHash.has(bundle.manifestHash)) {\n      byHash.set(bundle.manifestHash, bundle);\n    }\n  }\n\n  return [...byHash.values()];\n}\n\nfunction uniqueManifestPaths(\n  paths: readonly (readonly AccessManifestBundleWireResponse[])[],\n): AccessManifestBundleWireResponse[][] {\n  const byLeafHash = new Map<string, AccessManifestBundleWireResponse[]>();\n  for (const path of paths) {\n    const leafHash = path.at(-1)?.manifestHash;\n    if (!leafHash || byLeafHash.has(leafHash)) {\n      continue;\n    }\n\n    byLeafHash.set(leafHash, [...path]);\n  }\n\n  return [...byLeafHash.values()];\n}\n\nfunction containerProjectionManifestHistory(\n  projection: ContainerKeyingPathResponse,\n): AccessManifestBundleWireResponse[] {\n  return projection.containerKeks.flatMap(\n    (kek) => kek.containerManifestHistory,\n  );\n}\n\nfunction documentProjectionContainerPaths(\n  projection: DocumentWriterProjectionResponse,\n): AccessManifestBundleWireResponse[][] {\n  return uniqueManifestPaths([\n    ...projection.documentManifestContainerPaths,\n    ...projection.authorizingContainerPaths.map((path) => path.path),\n  ]);\n}\n\nfunction documentProjectionContainerHistory(input: {\n  priorProjection: DocumentWriterProjectionResponse;\n  targetContainerProjection: ContainerWriterProjectionResponse;\n}): AccessManifestBundleWireResponse[] {\n  const priorContainerPaths = documentProjectionContainerPaths(\n    input.priorProjection,\n  );\n  const priorAuthorizingContainerProjections =\n    input.priorProjection.authorizingContainerPaths;\n\n  return uniqueManifestBundles([\n    ...input.priorProjection.documentContainerManifestHistory,\n    ...priorContainerPaths.flat(),\n    ...priorAuthorizingContainerProjections.flatMap((projection) => [\n      ...projection.path,\n      ...containerProjectionManifestHistory(projection),\n    ]),\n    ...input.targetContainerProjection.path,\n    ...containerProjectionManifestHistory(input.targetContainerProjection),\n  ]);\n}\n\n/**\n * Reconstruct the post-mutation writer projection from a link/unlink response.\n * The response carries the fresh manifest, content-key bundle, and KEK targets;\n * the authorizing container paths change by exactly one entry — link appends\n * the target container's projection, unlink drops it (keyed by containerId).\n * Link does not rotate the content key (only unlink does), but either way the\n * bundle/targets the next write needs come straight from the response. The\n * caller verifies this projection for internal consistency before seeding it,\n * so a wrong reconstruction is discarded rather than cached.\n */\nfunction linkSetWriterProjectionFromResponse(input: {\n  operation: DocumentLinkSetMutationOperation;\n  priorProjection: DocumentWriterProjectionResponse;\n  response: DocumentLinkSetMutationResponse;\n  targetContainerId: string;\n  targetContainerProjection: ContainerWriterProjectionResponse;\n}): DocumentWriterProjectionResponse {\n  // The target container's authorizing path is replaced wholesale: link adds\n  // the fresh target projection back, unlink leaves it dropped.\n  const retainedPaths = input.priorProjection.authorizingContainerPaths.filter(\n    (path) => path.containerId !== input.targetContainerId,\n  );\n  const authorizingContainerPaths =\n    input.operation === \"link\"\n      ? [...retainedPaths, input.targetContainerProjection]\n      : retainedPaths;\n  const documentManifestContainerPaths = uniqueManifestPaths([\n    ...documentProjectionContainerPaths(input.priorProjection),\n    input.targetContainerProjection.path,\n  ]);\n  return {\n    policyEvidence: mergeProjectionPolicyEvidence([\n      input.priorProjection.policyEvidence,\n      input.targetContainerProjection.policyEvidence,\n    ]),\n    authorizingContainerPaths,\n    contentKeyBundle: input.response.contentKeyBundle,\n    documentId: input.response.id,\n    documentContainerManifestHistory: documentProjectionContainerHistory({\n      priorProjection: input.priorProjection,\n      targetContainerProjection: input.targetContainerProjection,\n    }),\n    documentKekTargets: input.response.documentKekTargets,\n    documentManifest: input.response.accessManifest,\n    documentManifestContainerPaths,\n    documentManifestHistory: [\n      input.priorProjection.documentManifest,\n      ...input.priorProjection.documentManifestHistory,\n    ],\n  };\n}\n\n/**\n * Reconstruct and seed the post-mutation writer projection so the first read\n * after a link/unlink resolves locally instead of a cold GET. Gates the seed on\n * the projection's internal consistency (manifest hash ↔ content-key bundle ↔\n * KEK targets ↔ linked containers); on any mismatch the seed is skipped and the\n * next read falls back to a fetch — the seed is an optimization, never a\n * correctness dependency. The expensive per-path signature re-verification is\n * deliberately not run here: the server already verified the mutation, and the\n * next read re-verifies the projection before any write.\n */\nexport async function seedLinkSetWriterProjection(input: {\n  apiClient: DocumentLinkSetProjectionSeedApi;\n  execSql?: ExecSql | undefined;\n  operation: DocumentLinkSetMutationOperation;\n  priorProjection: DocumentWriterProjectionResponse;\n  response: DocumentLinkSetMutationResponse;\n  targetContainerId: string;\n  targetContainerProjection: ContainerWriterProjectionResponse;\n  stillCurrent?: (() => boolean) | undefined;\n}): Promise<void> {\n  const projection = linkSetWriterProjectionFromResponse({\n    operation: input.operation,\n    priorProjection: input.priorProjection,\n    response: input.response,\n    targetContainerId: input.targetContainerId,\n    targetContainerProjection: input.targetContainerProjection,\n  });\n  try {\n    await assertDocumentWriterProjectionConsistent(projection, {\n      execSql: input.execSql,\n      trustedLocalProjection: true,\n    });\n  } catch {\n    return;\n  }\n  if (input.stillCurrent?.() === false) return;\n  input.apiClient.primeDocumentWriterProjection(input.response.id, projection);\n}\n"]}

package/workflows/documents/linkSetRemote.d.ts

@@ -0,0 +1,20 @@
+import type { DocumentCreateAuthor, DocumentLinkSetFailureHandler, DocumentLinkSetMutationApi, DocumentLinkSetMutationOperation, RelinkRemoteDocumentResult } from "../../data/documents/shared/types.js";
+import { type ProjectionUserKeyResolver, type ReferencedPrincipalPolicyWarmer } from "../../data/keyingProjectionVerification.js";
+import type { ExecSql } from "../../data/sqlite/sqlSchema.js";
+export declare function relinkRemoteDocument(input: {
+    apiClient: DocumentLinkSetMutationApi;
+    author: DocumentCreateAuthor;
+    contentKey?: Uint8Array | undefined;
+    documentId: string;
+    eventId?: string | undefined;
+    execSql: ExecSql;
+    onFailure?: DocumentLinkSetFailureHandler | undefined;
+    operation: DocumentLinkSetMutationOperation;
+    resolveProjectionUserKey: ProjectionUserKeyResolver;
+    rotationSnapshot?: Uint8Array | undefined;
+    signedAt?: string | undefined;
+    stillCurrent?: (() => boolean) | undefined;
+    targetContainerId: string;
+    targetSecretKey: Uint8Array;
+    warmReferencedPrincipalPolicies?: ReferencedPrincipalPolicyWarmer | undefined;
+}): Promise<RelinkRemoteDocumentResult | null>;

package/workflows/documents/linkSetRemote.js

@@ -0,0 +1,184 @@
+import { acknowledgeDocumentMutation } from "../../data/documents/shared/mutationAcknowledgement.js";
+import { persistedDocumentLinkSetMutationStateFromResponse } from "../../data/documents/shared/responses.js";
+import { nullOnProjectionVerificationCancellation, requireProjectionUserKeyResolver, } from "../../data/keyingProjectionVerification.js";
+import { recordDocumentAuthorAccessFailure } from "./authorAccessFailure.js";
+import { buildMaterializedDocumentLinkSetMutationPlan } from "./linkSet.js";
+import { prepareDocumentLinkBlobRewraps } from "./linkSetBlobRewraps.js";
+import { seedLinkSetWriterProjection } from "./linkSetProjectionSeed.js";
+import { completeLinkSetMutationRequest } from "./rotationBaseline.js";
+async function submitLinkSetMutation(input) {
+    if (input.stillCurrent?.() === false)
+        return null;
+    const { apiClient } = input;
+    // Preserve the HTTP failure for the durable move-intent queue.
+    const resultFn = input.operation === "link"
+        ? apiClient.linkDocumentResult.bind(apiClient)
+        : apiClient.unlinkDocumentResult.bind(apiClient);
+    const result = await resultFn(input.documentId, input.request, {
+        expectedPaymentRequiredOrganizationId: input.expectedOrganizationId,
+    });
+    if (result.ok) {
+        return result.data;
+    }
+    input.onFailure?.({
+        code: result.code,
+        message: result.message,
+        status: result.status,
+    });
+    return null;
+}
+// Cold-cache projection fetches must keep their HTTP status: collapsing a
+// 403 to null would leave an access-denied link/unlink routinely retriable
+// instead of parking its move for the access-restored signal (row 7).
+async function fetchLinkSetProjection(input) {
+    const result = await input.fetchProjectionResult();
+    if (result.ok) {
+        return { failure: null, projection: result.data };
+    }
+    result.report();
+    return {
+        failure: {
+            code: result.code,
+            message: result.message,
+            status: result.status,
+        },
+        projection: null,
+    };
+}
+function fetchLinkSetDocumentProjection(apiClient, documentId) {
+    return fetchLinkSetProjection({
+        fetchProjectionResult: apiClient.getDocumentWriterProjectionResult.bind(apiClient, documentId, { reportErrors: false }),
+    });
+}
+function fetchLinkSetContainerProjection(apiClient, containerId) {
+    return fetchLinkSetProjection({
+        fetchProjectionResult: apiClient.getContainerWriterProjectionResult.bind(apiClient, containerId, { reportErrors: false }),
+    });
+}
+async function completeRemoteDocumentLinkSet(input) {
+    const persistedState = persistedDocumentLinkSetMutationStateFromResponse(input.completedPlan, input.response);
+    await acknowledgeDocumentMutation({
+        execSql: input.execSql,
+        plan: input.completedPlan,
+        stillCurrent: input.stillCurrent,
+    });
+    await seedLinkSetWriterProjection({
+        apiClient: input.apiClient,
+        execSql: input.execSql,
+        operation: input.operation,
+        priorProjection: input.writerProjection,
+        response: input.response,
+        targetContainerId: input.targetContainerId,
+        targetContainerProjection: input.targetContainerProjection,
+        stillCurrent: input.stillCurrent,
+    });
+    if (input.stillCurrent?.() === false)
+        return null;
+    return {
+        contentKey: input.materializedPlan.contentKey,
+        contentKeyRotated: input.materializedPlan.contentKeyRotated,
+        documentId: input.response.id,
+        linkedContainerIds: [
+            ...input.materializedPlan.plan.state.linkedContainerIds,
+        ],
+        persistedState,
+        plan: input.completedPlan,
+        response: input.response,
+    };
+}
+export async function relinkRemoteDocument(input) {
+    if (input.operation === "unlink" && !input.rotationSnapshot) {
+        throw new Error("Document unlink requires a proven full-history rotation snapshot");
+    }
+    const resolveProjectionUserKey = requireProjectionUserKeyResolver(input.resolveProjectionUserKey, "Remote document link-set mutation");
+    const [writerFetch, targetContainerFetch] = await Promise.all([
+        fetchLinkSetDocumentProjection(input.apiClient, input.documentId),
+        fetchLinkSetContainerProjection(input.apiClient, input.targetContainerId),
+    ]);
+    if (!writerFetch.projection || !targetContainerFetch.projection) {
+        for (const failure of orderedProjectionFailures([
+            writerFetch.failure,
+            targetContainerFetch.failure,
+        ])) {
+            input.onFailure?.(failure);
+        }
+        return null;
+    }
+    const writerProjection = writerFetch.projection;
+    const targetContainerProjection = targetContainerFetch.projection;
+    if (input.stillCurrent?.() === false)
+        return null;
+    const signedAt = input.signedAt ?? new Date().toISOString();
+    const materializedPlan = await prepareRemoteLinkSetMutation({ ...input, resolveProjectionUserKey, signedAt }, writerProjection, targetContainerProjection);
+    if (!materializedPlan)
+        return null;
+    const request = await completeLinkSetMutationRequest({
+        author: input.author,
+        materializedPlan,
+        operation: input.operation,
+        rotationSnapshot: input.rotationSnapshot,
+        signedAt,
+    });
+    const completedPlan = { ...materializedPlan.plan, request };
+    const response = await submitLinkSetMutation({
+        apiClient: input.apiClient,
+        documentId: completedPlan.documentId,
+        expectedOrganizationId: completedPlan.state.organizationId,
+        onFailure: input.onFailure,
+        operation: input.operation,
+        request: completedPlan.request,
+        stillCurrent: input.stillCurrent,
+    });
+    if (!response) {
+        return null;
+    }
+    if (input.stillCurrent?.() === false)
+        return null;
+    return completeRemoteDocumentLinkSet({
+        apiClient: input.apiClient,
+        completedPlan,
+        execSql: input.execSql,
+        materializedPlan,
+        operation: input.operation,
+        response,
+        stillCurrent: input.stillCurrent,
+        targetContainerId: input.targetContainerId,
+        targetContainerProjection,
+        writerProjection,
+    });
+}
+// Every projection failure reaches the handler: the queued-move accumulator
+// classifies a vanished container from ANY coded container 404, so a document
+// fetch failure must not hide a container one (or vice versa). A 403 is
+// delivered last, so a single-slot consumer keeps the denial that parks the
+// move (row 7) while the accumulator still sees both.
+function orderedProjectionFailures(failures) {
+    const present = failures.filter((failure) => failure !== null);
+    return [
+        ...present.filter((failure) => failure.status !== 403),
+        ...present.filter((failure) => failure.status === 403),
+    ];
+}
+function prepareRemoteLinkSetMutation(input, writerProjection, targetContainerProjection) {
+    return recordDocumentAuthorAccessFailure(() => nullOnProjectionVerificationCancellation(() => buildMaterializedDocumentLinkSetMutationPlan({
+        author: input.author,
+        prepareBlobRewraps: (targets) => prepareDocumentLinkBlobRewraps({
+            ...input,
+            targets,
+            targetContainerProjection,
+            writerProjection,
+        }),
+        contentKey: input.contentKey,
+        eventId: input.eventId,
+        execSql: input.execSql,
+        operation: input.operation,
+        resolveProjectionUserKey: input.resolveProjectionUserKey,
+        signedAt: input.signedAt,
+        stillCurrent: input.stillCurrent,
+        targetContainerProjection,
+        targetSecretKey: input.targetSecretKey,
+        warmReferencedPrincipalPolicies: input.warmReferencedPrincipalPolicies,
+        writerProjection,
+    })), input.onFailure);
+}
+//# sourceMappingURL=linkSetRemote.js.map

package/workflows/documents/linkSetRemote.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"linkSetRemote.js","sourceRoot":"","sources":["linkSetRemote.ts"],"names":[],"mappings":"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","sourcesContent":["import type { DocumentLinkSetMutationRequest } from \"@tearleads/validators/request\";\nimport type {\n  ContainerWriterProjectionResponse,\n  DocumentLinkSetMutationResponse,\n  DocumentWriterProjectionResponse,\n} from \"@tearleads/validators/response\";\nimport { acknowledgeDocumentMutation } from \"../../data/documents/shared/mutationAcknowledgement\";\nimport { persistedDocumentLinkSetMutationStateFromResponse } from \"../../data/documents/shared/responses\";\nimport type {\n  DocumentCreateAuthor,\n  DocumentLinkSetFailureHandler,\n  DocumentLinkSetMutationApi,\n  DocumentLinkSetMutationFailure,\n  DocumentLinkSetMutationOperation,\n  DocumentSyncSubmitFailure,\n  RelinkRemoteDocumentResult,\n} from \"../../data/documents/shared/types\";\nimport {\n  nullOnProjectionVerificationCancellation,\n  type ProjectionUserKeyResolver,\n  type ReferencedPrincipalPolicyWarmer,\n  requireProjectionUserKeyResolver,\n} from \"../../data/keyingProjectionVerification\";\nimport type { ExecSql } from \"../../data/sqlite/sqlSchema\";\nimport { recordDocumentAuthorAccessFailure } from \"./authorAccessFailure\";\nimport { buildMaterializedDocumentLinkSetMutationPlan } from \"./linkSet\";\nimport { prepareDocumentLinkBlobRewraps } from \"./linkSetBlobRewraps\";\nimport { seedLinkSetWriterProjection } from \"./linkSetProjectionSeed\";\nimport { completeLinkSetMutationRequest } from \"./rotationBaseline\";\n\nasync function submitLinkSetMutation(input: {\n  apiClient: DocumentLinkSetMutationApi;\n  documentId: string;\n  expectedOrganizationId: string;\n  onFailure?: DocumentLinkSetFailureHandler | undefined;\n  operation: DocumentLinkSetMutationOperation;\n  request: DocumentLinkSetMutationRequest;\n  stillCurrent?: (() => boolean) | undefined;\n}): Promise<DocumentLinkSetMutationResponse | null> {\n  if (input.stillCurrent?.() === false) return null;\n  const { apiClient } = input;\n  // Preserve the HTTP failure for the durable move-intent queue.\n  const resultFn =\n    input.operation === \"link\"\n      ? apiClient.linkDocumentResult.bind(apiClient)\n      : apiClient.unlinkDocumentResult.bind(apiClient);\n  const result = await resultFn(input.documentId, input.request, {\n    expectedPaymentRequiredOrganizationId: input.expectedOrganizationId,\n  });\n  if (result.ok) {\n    return result.data;\n  }\n  input.onFailure?.({\n    code: result.code,\n    message: result.message,\n    status: result.status,\n  });\n  return null;\n}\n\ninterface LinkSetProjectionFetch<TProjection> {\n  failure: DocumentLinkSetMutationFailure | null;\n  projection: TProjection | null;\n}\n\n// Cold-cache projection fetches must keep their HTTP status: collapsing a\n// 403 to null would leave an access-denied link/unlink routinely retriable\n// instead of parking its move for the access-restored signal (row 7).\nasync function fetchLinkSetProjection<TProjection>(input: {\n  fetchProjectionResult: () => Promise<\n    | { readonly data: TProjection; readonly ok: true }\n    | DocumentSyncSubmitFailure\n  >;\n}): Promise<LinkSetProjectionFetch<TProjection>> {\n  const result = await input.fetchProjectionResult();\n  if (result.ok) {\n    return { failure: null, projection: result.data };\n  }\n  result.report();\n  return {\n    failure: {\n      code: result.code,\n      message: result.message,\n      status: result.status,\n    },\n    projection: null,\n  };\n}\n\nfunction fetchLinkSetDocumentProjection(\n  apiClient: DocumentLinkSetMutationApi,\n  documentId: string,\n): Promise<LinkSetProjectionFetch<DocumentWriterProjectionResponse>> {\n  return fetchLinkSetProjection({\n    fetchProjectionResult: apiClient.getDocumentWriterProjectionResult.bind(\n      apiClient,\n      documentId,\n      { reportErrors: false },\n    ),\n  });\n}\n\nfunction fetchLinkSetContainerProjection(\n  apiClient: DocumentLinkSetMutationApi,\n  containerId: string,\n): Promise<LinkSetProjectionFetch<ContainerWriterProjectionResponse>> {\n  return fetchLinkSetProjection({\n    fetchProjectionResult: apiClient.getContainerWriterProjectionResult.bind(\n      apiClient,\n      containerId,\n      { reportErrors: false },\n    ),\n  });\n}\n\nasync function completeRemoteDocumentLinkSet(input: {\n  completedPlan: Parameters<\n    typeof persistedDocumentLinkSetMutationStateFromResponse\n  >[0];\n  execSql: ExecSql;\n  materializedPlan: Awaited<\n    ReturnType<typeof buildMaterializedDocumentLinkSetMutationPlan>\n  >;\n  operation: DocumentLinkSetMutationOperation;\n  response: DocumentLinkSetMutationResponse;\n  stillCurrent?: (() => boolean) | undefined;\n  targetContainerId: string;\n  targetContainerProjection: ContainerWriterProjectionResponse;\n  writerProjection: DocumentWriterProjectionResponse;\n  apiClient: DocumentLinkSetMutationApi;\n}): Promise<RelinkRemoteDocumentResult | null> {\n  const persistedState = persistedDocumentLinkSetMutationStateFromResponse(\n    input.completedPlan,\n    input.response,\n  );\n  await acknowledgeDocumentMutation({\n    execSql: input.execSql,\n    plan: input.completedPlan,\n    stillCurrent: input.stillCurrent,\n  });\n  await seedLinkSetWriterProjection({\n    apiClient: input.apiClient,\n    execSql: input.execSql,\n    operation: input.operation,\n    priorProjection: input.writerProjection,\n    response: input.response,\n    targetContainerId: input.targetContainerId,\n    targetContainerProjection: input.targetContainerProjection,\n    stillCurrent: input.stillCurrent,\n  });\n  if (input.stillCurrent?.() === false) return null;\n  return {\n    contentKey: input.materializedPlan.contentKey,\n    contentKeyRotated: input.materializedPlan.contentKeyRotated,\n    documentId: input.response.id,\n    linkedContainerIds: [\n      ...input.materializedPlan.plan.state.linkedContainerIds,\n    ],\n    persistedState,\n    plan: input.completedPlan,\n    response: input.response,\n  };\n}\n\nexport async function relinkRemoteDocument(input: {\n  apiClient: DocumentLinkSetMutationApi;\n  author: DocumentCreateAuthor;\n  contentKey?: Uint8Array | undefined;\n  documentId: string;\n  eventId?: string | undefined;\n  execSql: ExecSql;\n  onFailure?: DocumentLinkSetFailureHandler | undefined;\n  operation: DocumentLinkSetMutationOperation;\n  resolveProjectionUserKey: ProjectionUserKeyResolver;\n  rotationSnapshot?: Uint8Array | undefined;\n  signedAt?: string | undefined;\n  stillCurrent?: (() => boolean) | undefined;\n  targetContainerId: string;\n  targetSecretKey: Uint8Array;\n  warmReferencedPrincipalPolicies?: ReferencedPrincipalPolicyWarmer | undefined;\n}): Promise<RelinkRemoteDocumentResult | null> {\n  if (input.operation === \"unlink\" && !input.rotationSnapshot) {\n    throw new Error(\n      \"Document unlink requires a proven full-history rotation snapshot\",\n    );\n  }\n  const resolveProjectionUserKey = requireProjectionUserKeyResolver(\n    input.resolveProjectionUserKey,\n    \"Remote document link-set mutation\",\n  );\n  const [writerFetch, targetContainerFetch] = await Promise.all([\n    fetchLinkSetDocumentProjection(input.apiClient, input.documentId),\n    fetchLinkSetContainerProjection(input.apiClient, input.targetContainerId),\n  ]);\n  if (!writerFetch.projection || !targetContainerFetch.projection) {\n    for (const failure of orderedProjectionFailures([\n      writerFetch.failure,\n      targetContainerFetch.failure,\n    ])) {\n      input.onFailure?.(failure);\n    }\n    return null;\n  }\n  const writerProjection = writerFetch.projection;\n  const targetContainerProjection = targetContainerFetch.projection;\n  if (input.stillCurrent?.() === false) return null;\n\n  const signedAt = input.signedAt ?? new Date().toISOString();\n  const materializedPlan = await prepareRemoteLinkSetMutation(\n    { ...input, resolveProjectionUserKey, signedAt },\n    writerProjection,\n    targetContainerProjection,\n  );\n  if (!materializedPlan) return null;\n  const request = await completeLinkSetMutationRequest({\n    author: input.author,\n    materializedPlan,\n    operation: input.operation,\n    rotationSnapshot: input.rotationSnapshot,\n    signedAt,\n  });\n  const completedPlan = { ...materializedPlan.plan, request };\n  const response = await submitLinkSetMutation({\n    apiClient: input.apiClient,\n    documentId: completedPlan.documentId,\n    expectedOrganizationId: completedPlan.state.organizationId,\n    onFailure: input.onFailure,\n    operation: input.operation,\n    request: completedPlan.request,\n    stillCurrent: input.stillCurrent,\n  });\n  if (!response) {\n    return null;\n  }\n  if (input.stillCurrent?.() === false) return null;\n  return completeRemoteDocumentLinkSet({\n    apiClient: input.apiClient,\n    completedPlan,\n    execSql: input.execSql,\n    materializedPlan,\n    operation: input.operation,\n    response,\n    stillCurrent: input.stillCurrent,\n    targetContainerId: input.targetContainerId,\n    targetContainerProjection,\n    writerProjection,\n  });\n}\n\n// Every projection failure reaches the handler: the queued-move accumulator\n// classifies a vanished container from ANY coded container 404, so a document\n// fetch failure must not hide a container one (or vice versa). A 403 is\n// delivered last, so a single-slot consumer keeps the denial that parks the\n// move (row 7) while the accumulator still sees both.\nfunction orderedProjectionFailures(\n  failures: readonly (DocumentLinkSetMutationFailure | null)[],\n): DocumentLinkSetMutationFailure[] {\n  const present = failures.filter(\n    (failure): failure is DocumentLinkSetMutationFailure => failure !== null,\n  );\n  return [\n    ...present.filter((failure) => failure.status !== 403),\n    ...present.filter((failure) => failure.status === 403),\n  ];\n}\n\nfunction prepareRemoteLinkSetMutation(\n  input: Parameters<typeof relinkRemoteDocument>[0] & {\n    resolveProjectionUserKey: ProjectionUserKeyResolver;\n    signedAt: string;\n  },\n  writerProjection: DocumentWriterProjectionResponse,\n  targetContainerProjection: ContainerWriterProjectionResponse,\n) {\n  return recordDocumentAuthorAccessFailure(\n    () =>\n      nullOnProjectionVerificationCancellation(() =>\n        buildMaterializedDocumentLinkSetMutationPlan({\n          author: input.author,\n          prepareBlobRewraps: (targets) =>\n            prepareDocumentLinkBlobRewraps({\n              ...input,\n              targets,\n              targetContainerProjection,\n              writerProjection,\n            }),\n          contentKey: input.contentKey,\n          eventId: input.eventId,\n          execSql: input.execSql,\n          operation: input.operation,\n          resolveProjectionUserKey: input.resolveProjectionUserKey,\n          signedAt: input.signedAt,\n          stillCurrent: input.stillCurrent,\n          targetContainerProjection,\n          targetSecretKey: input.targetSecretKey,\n          warmReferencedPrincipalPolicies:\n            input.warmReferencedPrincipalPolicies,\n          writerProjection,\n        }),\n      ),\n    input.onFailure,\n  );\n}\n"]}

package/workflows/documents/orphanBlobReclaims.d.ts

@@ -0,0 +1,5 @@
+import type { DocumentsWorkflowRuntimeGroups } from "./runtime.js";
+type DocumentOrphanBlobReclaimRuntime = Pick<DocumentsWorkflowRuntimeGroups, "infra" | "util">;
+/** Sweep orphan rows and reclaim their queued local attachment bytes. */
+export declare function reclaimDocumentOrphanBlobs(runtime: DocumentOrphanBlobReclaimRuntime): Promise<void>;
+export {};

package/workflows/documents/orphanBlobReclaims.js

@@ -0,0 +1,141 @@
+import { errorMessage } from "../../data/errorMessage.js";
+import { acknowledgeDocumentOrphanBlobReclaim, deleteOrphanedDocumentSideRows, isDocumentBlobStorageKeyReferenced, listDocumentOrphanBlobReclaims, } from "../../data/persistence/documents/internal/orphanSideRows.js";
+import { resolveCanonicalExecSql, runOncePerConnection, runSerializedSqlMutation, } from "../../data/sqlite/sqlSchema.js";
+import { runSerializedDocumentBlobMutation } from "./blobMutationLock.js";
+import { defaultDocumentsPersistence } from "./persistence.js";
+const reclaimByExecSql = new WeakMap();
+const reclaimRerunByExecSql = new WeakSet();
+const deferredStorageKeysByExecSql = new WeakMap();
+const ORPHAN_BLOB_RECLAIM_BATCH_SIZE = 16;
+const ORPHAN_BLOB_RECLAIM_TIME_BUDGET_MS = 250;
+const ORPHAN_BLOB_RECLAIM_RETRY_DELAY_MS = 30_000;
+const ORPHAN_BLOB_RECLAIM_LOG_SAMPLE_SIZE = 3;
+const ORPHAN_BLOB_RECLAIM_YIELD_MS = 16;
+const DOCUMENT_ORPHAN_SWEEP_ONCE_KEY = "sweep:document-orphans";
+function clearExpiredDeferredStorageKeys(deferredStorageKeys, now) {
+    for (const [storageKey, retryAt] of deferredStorageKeys) {
+        if (retryAt <= now)
+            deferredStorageKeys.delete(storageKey);
+    }
+}
+function waitForMaintenanceYield() {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ORPHAN_BLOB_RECLAIM_YIELD_MS);
+    });
+}
+async function sweepAgedDocumentOrphans(execSql) {
+    let swept = false;
+    await runOncePerConnection(execSql, DOCUMENT_ORPHAN_SWEEP_ONCE_KEY, async () => {
+        swept = true;
+        while (await deleteOrphanedDocumentSideRows(execSql)) {
+            await waitForMaintenanceYield();
+        }
+    });
+    return swept;
+}
+async function reclaimQueuedBlobs(runtime) {
+    const execSql = runtime.infra.execSql;
+    await defaultDocumentsPersistence.ensureSchema(execSql);
+    let shouldContinue = false;
+    const startedAt = Date.now();
+    const canonicalExecSql = resolveCanonicalExecSql(execSql);
+    const deferredStorageKeys = deferredStorageKeysByExecSql.get(canonicalExecSql) ??
+        new Map();
+    deferredStorageKeysByExecSql.set(canonicalExecSql, deferredStorageKeys);
+    const failedStorageKeys = [];
+    let warmedBlobStore = false;
+    let sweptAgedOrphans = false;
+    reclaimQueue: while (true) {
+        clearExpiredDeferredStorageKeys(deferredStorageKeys, Date.now());
+        const queuedStorageKeys = await listDocumentOrphanBlobReclaims(execSql, ORPHAN_BLOB_RECLAIM_BATCH_SIZE + deferredStorageKeys.size);
+        const storageKeys = queuedStorageKeys
+            .filter((storageKey) => !deferredStorageKeys.has(storageKey))
+            .slice(0, ORPHAN_BLOB_RECLAIM_BATCH_SIZE);
+        if (storageKeys.length === 0) {
+            // Explicit delete paths get priority. Once their queue is drained, sweep
+            // crash residue once per connection and immediately drain what it queues.
+            if (!sweptAgedOrphans && (await sweepAgedDocumentOrphans(execSql))) {
+                sweptAgedOrphans = true;
+                continue;
+            }
+            break;
+        }
+        const firstStorageKey = storageKeys[0];
+        if (!warmedBlobStore && firstStorageKey) {
+            // Initialize lazy keyring/OPFS-backed stores before taking any blob-key
+            // lock. A failed preview is harmless: deletion can still reclaim the key.
+            await runtime.infra.blobStore
+                .openByteSource(firstStorageKey)
+                .catch(() => undefined);
+            warmedBlobStore = true;
+        }
+        for (const storageKey of storageKeys) {
+            await runSerializedDocumentBlobMutation(execSql, storageKey, async () => {
+                const shouldDelete = await runSerializedSqlMutation(execSql, async (lockedExecSql) => {
+                    if (await isDocumentBlobStorageKeyReferenced(lockedExecSql, storageKey)) {
+                        await acknowledgeDocumentOrphanBlobReclaim(lockedExecSql, storageKey);
+                        return false;
+                    }
+                    return true;
+                });
+                if (!shouldDelete)
+                    return;
+                try {
+                    await runtime.infra.blobStore.deleteBytes(storageKey);
+                    await runSerializedSqlMutation(execSql, (lockedExecSql) => acknowledgeDocumentOrphanBlobReclaim(lockedExecSql, storageKey));
+                }
+                catch {
+                    failedStorageKeys.push(storageKey);
+                    deferredStorageKeys.set(storageKey, Date.now() + ORPHAN_BLOB_RECLAIM_RETRY_DELAY_MS);
+                }
+            });
+            if (Date.now() - startedAt >= ORPHAN_BLOB_RECLAIM_TIME_BUDGET_MS) {
+                shouldContinue = true;
+                break reclaimQueue;
+            }
+        }
+    }
+    if (deferredStorageKeys.size === 0) {
+        deferredStorageKeysByExecSql.delete(canonicalExecSql);
+    }
+    if (failedStorageKeys.length > 0) {
+        const sample = failedStorageKeys
+            .slice(0, ORPHAN_BLOB_RECLAIM_LOG_SAMPLE_SIZE)
+            .join(", ");
+        runtime.util.log(`Documents: orphan maintenance deferred ${failedStorageKeys.length} blob(s): ${sample}`);
+    }
+    return shouldContinue;
+}
+/** Sweep orphan rows and reclaim their queued local attachment bytes. */
+export function reclaimDocumentOrphanBlobs(runtime) {
+    if (runtime.infra.dbStatus !== "ready") {
+        return Promise.resolve();
+    }
+    const execSql = resolveCanonicalExecSql(runtime.infra.execSql);
+    const existing = reclaimByExecSql.get(execSql);
+    if (existing) {
+        reclaimRerunByExecSql.add(execSql);
+        return existing;
+    }
+    let shouldContinue = false;
+    const reclaim = reclaimQueuedBlobs(runtime)
+        .then((hasMore) => {
+        shouldContinue = hasMore;
+    })
+        .catch((error) => {
+        const message = errorMessage(error);
+        runtime.util.log(`Documents: orphan maintenance failed: ${message}`);
+    })
+        .finally(() => {
+        reclaimByExecSql.delete(execSql);
+        const wasRerunRequested = reclaimRerunByExecSql.delete(execSql);
+        if (shouldContinue || wasRerunRequested) {
+            setTimeout(() => {
+                void reclaimDocumentOrphanBlobs(runtime);
+            }, ORPHAN_BLOB_RECLAIM_YIELD_MS);
+        }
+    });
+    reclaimByExecSql.set(execSql, reclaim);
+    return reclaim;
+}
+//# sourceMappingURL=orphanBlobReclaims.js.map

package/workflows/documents/orphanBlobReclaims.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orphanBlobReclaims.js","sourceRoot":"","sources":["orphanBlobReclaims.ts"],"names":[],"mappings":"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","sourcesContent":["import { errorMessage } from \"../../data/errorMessage\";\nimport {\n  acknowledgeDocumentOrphanBlobReclaim,\n  deleteOrphanedDocumentSideRows,\n  isDocumentBlobStorageKeyReferenced,\n  listDocumentOrphanBlobReclaims,\n} from \"../../data/persistence/documents/internal/orphanSideRows\";\nimport {\n  type ExecSql,\n  resolveCanonicalExecSql,\n  runOncePerConnection,\n  runSerializedSqlMutation,\n} from \"../../data/sqlite/sqlSchema\";\nimport { runSerializedDocumentBlobMutation } from \"./blobMutationLock\";\nimport { defaultDocumentsPersistence } from \"./persistence\";\nimport type { DocumentsWorkflowRuntimeGroups } from \"./runtime\";\n\nconst reclaimByExecSql = new WeakMap<ExecSql, Promise<void>>();\nconst reclaimRerunByExecSql = new WeakSet<ExecSql>();\nconst deferredStorageKeysByExecSql = new WeakMap<\n  ExecSql,\n  Map<string, number>\n>();\nconst ORPHAN_BLOB_RECLAIM_BATCH_SIZE = 16;\nconst ORPHAN_BLOB_RECLAIM_TIME_BUDGET_MS = 250;\nconst ORPHAN_BLOB_RECLAIM_RETRY_DELAY_MS = 30_000;\nconst ORPHAN_BLOB_RECLAIM_LOG_SAMPLE_SIZE = 3;\nconst ORPHAN_BLOB_RECLAIM_YIELD_MS = 16;\nconst DOCUMENT_ORPHAN_SWEEP_ONCE_KEY = \"sweep:document-orphans\";\n\ntype DocumentOrphanBlobReclaimRuntime = Pick<\n  DocumentsWorkflowRuntimeGroups,\n  \"infra\" | \"util\"\n>;\n\nfunction clearExpiredDeferredStorageKeys(\n  deferredStorageKeys: Map<string, number>,\n  now: number,\n): void {\n  for (const [storageKey, retryAt] of deferredStorageKeys) {\n    if (retryAt <= now) deferredStorageKeys.delete(storageKey);\n  }\n}\n\nfunction waitForMaintenanceYield(): Promise<void> {\n  return new Promise((resolve) => {\n    setTimeout(resolve, ORPHAN_BLOB_RECLAIM_YIELD_MS);\n  });\n}\n\nasync function sweepAgedDocumentOrphans(execSql: ExecSql): Promise<boolean> {\n  let swept = false;\n  await runOncePerConnection(\n    execSql,\n    DOCUMENT_ORPHAN_SWEEP_ONCE_KEY,\n    async () => {\n      swept = true;\n      while (await deleteOrphanedDocumentSideRows(execSql)) {\n        await waitForMaintenanceYield();\n      }\n    },\n  );\n  return swept;\n}\n\nasync function reclaimQueuedBlobs(\n  runtime: DocumentOrphanBlobReclaimRuntime,\n): Promise<boolean> {\n  const execSql = runtime.infra.execSql;\n  await defaultDocumentsPersistence.ensureSchema(execSql);\n  let shouldContinue = false;\n\n  const startedAt = Date.now();\n  const canonicalExecSql = resolveCanonicalExecSql(execSql);\n  const deferredStorageKeys =\n    deferredStorageKeysByExecSql.get(canonicalExecSql) ??\n    new Map<string, number>();\n  deferredStorageKeysByExecSql.set(canonicalExecSql, deferredStorageKeys);\n  const failedStorageKeys: string[] = [];\n  let warmedBlobStore = false;\n  let sweptAgedOrphans = false;\n\n  reclaimQueue: while (true) {\n    clearExpiredDeferredStorageKeys(deferredStorageKeys, Date.now());\n    const queuedStorageKeys = await listDocumentOrphanBlobReclaims(\n      execSql,\n      ORPHAN_BLOB_RECLAIM_BATCH_SIZE + deferredStorageKeys.size,\n    );\n    const storageKeys = queuedStorageKeys\n      .filter((storageKey) => !deferredStorageKeys.has(storageKey))\n      .slice(0, ORPHAN_BLOB_RECLAIM_BATCH_SIZE);\n    if (storageKeys.length === 0) {\n      // Explicit delete paths get priority. Once their queue is drained, sweep\n      // crash residue once per connection and immediately drain what it queues.\n      if (!sweptAgedOrphans && (await sweepAgedDocumentOrphans(execSql))) {\n        sweptAgedOrphans = true;\n        continue;\n      }\n      break;\n    }\n\n    const firstStorageKey = storageKeys[0];\n    if (!warmedBlobStore && firstStorageKey) {\n      // Initialize lazy keyring/OPFS-backed stores before taking any blob-key\n      // lock. A failed preview is harmless: deletion can still reclaim the key.\n      await runtime.infra.blobStore\n        .openByteSource(firstStorageKey)\n        .catch(() => undefined);\n      warmedBlobStore = true;\n    }\n\n    for (const storageKey of storageKeys) {\n      await runSerializedDocumentBlobMutation(execSql, storageKey, async () => {\n        const shouldDelete = await runSerializedSqlMutation(\n          execSql,\n          async (lockedExecSql) => {\n            if (\n              await isDocumentBlobStorageKeyReferenced(\n                lockedExecSql,\n                storageKey,\n              )\n            ) {\n              await acknowledgeDocumentOrphanBlobReclaim(\n                lockedExecSql,\n                storageKey,\n              );\n              return false;\n            }\n            return true;\n          },\n        );\n        if (!shouldDelete) return;\n        try {\n          await runtime.infra.blobStore.deleteBytes(storageKey);\n          await runSerializedSqlMutation(execSql, (lockedExecSql) =>\n            acknowledgeDocumentOrphanBlobReclaim(lockedExecSql, storageKey),\n          );\n        } catch {\n          failedStorageKeys.push(storageKey);\n          deferredStorageKeys.set(\n            storageKey,\n            Date.now() + ORPHAN_BLOB_RECLAIM_RETRY_DELAY_MS,\n          );\n        }\n      });\n      if (Date.now() - startedAt >= ORPHAN_BLOB_RECLAIM_TIME_BUDGET_MS) {\n        shouldContinue = true;\n        break reclaimQueue;\n      }\n    }\n  }\n\n  if (deferredStorageKeys.size === 0) {\n    deferredStorageKeysByExecSql.delete(canonicalExecSql);\n  }\n  if (failedStorageKeys.length > 0) {\n    const sample = failedStorageKeys\n      .slice(0, ORPHAN_BLOB_RECLAIM_LOG_SAMPLE_SIZE)\n      .join(\", \");\n    runtime.util.log(\n      `Documents: orphan maintenance deferred ${failedStorageKeys.length} blob(s): ${sample}`,\n    );\n  }\n  return shouldContinue;\n}\n\n/** Sweep orphan rows and reclaim their queued local attachment bytes. */\nexport function reclaimDocumentOrphanBlobs(\n  runtime: DocumentOrphanBlobReclaimRuntime,\n): Promise<void> {\n  if (runtime.infra.dbStatus !== \"ready\") {\n    return Promise.resolve();\n  }\n  const execSql = resolveCanonicalExecSql(runtime.infra.execSql);\n  const existing = reclaimByExecSql.get(execSql);\n  if (existing) {\n    reclaimRerunByExecSql.add(execSql);\n    return existing;\n  }\n\n  let shouldContinue = false;\n  const reclaim = reclaimQueuedBlobs(runtime)\n    .then((hasMore) => {\n      shouldContinue = hasMore;\n    })\n    .catch((error: unknown) => {\n      const message = errorMessage(error);\n      runtime.util.log(`Documents: orphan maintenance failed: ${message}`);\n    })\n    .finally(() => {\n      reclaimByExecSql.delete(execSql);\n      const wasRerunRequested = reclaimRerunByExecSql.delete(execSql);\n      if (shouldContinue || wasRerunRequested) {\n        setTimeout(() => {\n          void reclaimDocumentOrphanBlobs(runtime);\n        }, ORPHAN_BLOB_RECLAIM_YIELD_MS);\n      }\n    });\n  reclaimByExecSql.set(execSql, reclaim);\n  return reclaim;\n}\n"]}

package/workflows/documents/pendingUpdatePersistence.d.ts

@@ -0,0 +1,22 @@
+import type { DocumentsPersistence, PendingUpdateRecord } from "../../data/persistence/documents/documentsPersistence.js";
+import type { ExecSql } from "../../data/sqlite/sqlSchema.js";
+export declare function listPendingDocumentUpdates(input: {
+    execSql: ExecSql;
+    localId: string;
+    persistence: DocumentsPersistence;
+}): Promise<PendingUpdateRecord[]>;
+type EnqueuePendingDocumentUpdateInput = {
+    execSql: ExecSql;
+    localId: string;
+    persistence: DocumentsPersistence;
+    sourceVersionVector?: string | null;
+    update: Uint8Array;
+} & ({
+    expectedDocumentId: string | null;
+    expectedRecoveryGeneration: number;
+} | {
+    expectedDocumentId?: undefined;
+    expectedRecoveryGeneration?: never;
+});
+export declare function enqueuePendingDocumentUpdate(input: EnqueuePendingDocumentUpdateInput): Promise<boolean>;
+export {};

package/workflows/documents/pendingUpdatePersistence.js

@@ -0,0 +1,22 @@
+import { createPendingUpdateFields } from "../../data/documents/documentSync.js";
+export async function listPendingDocumentUpdates(input) {
+    return input.persistence.listPendingUpdates(input.execSql, input.localId);
+}
+export async function enqueuePendingDocumentUpdate(input) {
+    const pendingUpdateFields = createPendingUpdateFields(input.update, input.sourceVersionVector);
+    if (!pendingUpdateFields) {
+        return input.expectedDocumentId === undefined
+            ? true
+            : input.persistence.documentIdentityMatches(input.execSql, input.localId, input.expectedDocumentId, input.expectedRecoveryGeneration);
+    }
+    return input.persistence.enqueuePendingUpdate(input.execSql, {
+        localId: input.localId,
+        ...pendingUpdateFields,
+    }, input.expectedDocumentId === undefined
+        ? undefined
+        : {
+            expectedDocumentId: input.expectedDocumentId,
+            expectedRecoveryGeneration: input.expectedRecoveryGeneration,
+        });
+}
+//# sourceMappingURL=pendingUpdatePersistence.js.map

package/workflows/documents/pendingUpdatePersistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pendingUpdatePersistence.js","sourceRoot":"","sources":["pendingUpdatePersistence.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAO9E,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAAC,KAIhD;IACC,OAAO,KAAK,CAAC,WAAW,CAAC,kBAAkB,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;AAC5E,CAAC;AAmBD,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAChD,KAAwC;IAExC,MAAM,mBAAmB,GAAG,yBAAyB,CACnD,KAAK,CAAC,MAAM,EACZ,KAAK,CAAC,mBAAmB,CAC1B,CAAC;IACF,IAAI,CAAC,mBAAmB,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,kBAAkB,KAAK,SAAS;YAC3C,CAAC,CAAC,IAAI;YACN,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,uBAAuB,CACvC,KAAK,CAAC,OAAO,EACb,KAAK,CAAC,OAAO,EACb,KAAK,CAAC,kBAAkB,EACxB,KAAK,CAAC,0BAA0B,CACjC,CAAC;IACR,CAAC;IAED,OAAO,KAAK,CAAC,WAAW,CAAC,oBAAoB,CAC3C,KAAK,CAAC,OAAO,EACb;QACE,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,GAAG,mBAAmB;KACvB,EACD,KAAK,CAAC,kBAAkB,KAAK,SAAS;QACpC,CAAC,CAAC,SAAS;QACX,CAAC,CAAC;YACE,kBAAkB,EAAE,KAAK,CAAC,kBAAkB;YAC5C,0BAA0B,EAAE,KAAK,CAAC,0BAA0B;SAC7D,CACN,CAAC;AACJ,CAAC","sourcesContent":["import { createPendingUpdateFields } from \"../../data/documents/documentSync\";\nimport type {\n  DocumentsPersistence,\n  PendingUpdateRecord,\n} from \"../../data/persistence/documents/documentsPersistence\";\nimport type { ExecSql } from \"../../data/sqlite/sqlSchema\";\n\nexport async function listPendingDocumentUpdates(input: {\n  execSql: ExecSql;\n  localId: string;\n  persistence: DocumentsPersistence;\n}): Promise<PendingUpdateRecord[]> {\n  return input.persistence.listPendingUpdates(input.execSql, input.localId);\n}\n\ntype EnqueuePendingDocumentUpdateInput = {\n  execSql: ExecSql;\n  localId: string;\n  persistence: DocumentsPersistence;\n  sourceVersionVector?: string | null;\n  update: Uint8Array;\n} & (\n  | {\n      expectedDocumentId: string | null;\n      expectedRecoveryGeneration: number;\n    }\n  | {\n      expectedDocumentId?: undefined;\n      expectedRecoveryGeneration?: never;\n    }\n);\n\nexport async function enqueuePendingDocumentUpdate(\n  input: EnqueuePendingDocumentUpdateInput,\n): Promise<boolean> {\n  const pendingUpdateFields = createPendingUpdateFields(\n    input.update,\n    input.sourceVersionVector,\n  );\n  if (!pendingUpdateFields) {\n    return input.expectedDocumentId === undefined\n      ? true\n      : input.persistence.documentIdentityMatches(\n          input.execSql,\n          input.localId,\n          input.expectedDocumentId,\n          input.expectedRecoveryGeneration,\n        );\n  }\n\n  return input.persistence.enqueuePendingUpdate(\n    input.execSql,\n    {\n      localId: input.localId,\n      ...pendingUpdateFields,\n    },\n    input.expectedDocumentId === undefined\n      ? undefined\n      : {\n          expectedDocumentId: input.expectedDocumentId,\n          expectedRecoveryGeneration: input.expectedRecoveryGeneration,\n        },\n  );\n}\n"]}