@tearleads/client-sdk 0.0.0-stage → 0.1.11

package/workflows/documents/syncSubmittedResult.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncSubmittedResult.js","sourceRoot":"","sources":["syncSubmittedResult.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,6BAA6B,EAAE,MAAM,mCAAmC,CAAC;AAClF,OAAO,EAEL,2CAA2C,GAC5C,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,yBAAyB,EAAE,MAAM,+CAA+C,CAAC;AAG1F,OAAO,EAAE,kCAAkC,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,kCAAkC,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EACL,oCAAoC,EACpC,gCAAgC,GACjC,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,oCAAoC,EAAE,MAAM,sBAAsB,CAAC;AAC5E,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAa1C,kFAAkF;AAClF,MAAM,UAAU,4BAA4B,CAAC,KAO5C;IACC,IACE,CAAC,KAAK,CAAC,gBAAgB,CAAC,2BAA2B;QACnD,CAAC,gCAAgC,CAAC,KAAK,CAAC,gBAAgB,EAAE,KAAK,CAAC,QAAQ,CAAC;QACzE,KAAK,CAAC,YAAY,EAAE,EAAE,KAAK,KAAK,EAChC,CAAC;QACD,OAAO;IACT,CAAC;IACD,KAAK,CAAC,qBAAqB,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAChD,IAAI,KAAK,CAAC,YAAY,EAAE,EAAE,KAAK,KAAK,EAAE,CAAC;QACrC,OAAO;IACT,CAAC;IACD,WAAW,CAAC,KAAK,CAAC,WAAW,EAAE;QAC7B,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,yBAAyB,CAAC,MAAM;QACzD,UAAU,EAAE,KAAK,CAAC,gBAAgB,CAAC,IAAI,CAAC,UAAU;QAClD,KAAK,EAAE,KAAK,CAAC,gBAAgB,CAAC,IAAI,CAAC,eAAe;KACnD,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,2BAA2B,CACxC,KAAuC;IAEvC,MAAM,MAAM,GAAG,MAAM,oCAAoC,CAAC;QACxD,GAAG,6BAA6B,CAAC,KAAK,CAAC,IAAI,CAAC;QAC5C,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,OAAO;QAC3B,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;QACxC,uBAAuB,EAAE,KAAK,CAAC,IAAI,CAAC,uBAAuB;QAC3D,0BAA0B,EAAE,KAAK,CAAC,0BAA0B;QAC5D,kBAAkB,EAAE,KAAK,CAAC,IAAI,CAAC,kBAAkB;QACjD,sBAAsB,EAAE,KAAK,CAAC,IAAI,CAAC,sBAAsB;QACzD,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,YAAY,EAAE,KAAK,CAAC,IAAI,CAAC,YAAY;QACrC,eAAe,EAAE,KAAK,CAAC,IAAI,CAAC,eAAe;QAC3C,uBAAuB,EAAE,KAAK,CAAC,IAAI,CAAC,uBAAuB;QAC3D,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;QACxC,wBAAwB,EAAE,KAAK,CAAC,wBAAwB;KACzD,CAAC,CAAC;IACH,IACE,CAAC,KAAK,CAAC,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC;QACtE,KAAK,CAAC,IAAI,CAAC,YAAY,EAAE,EAAE,KAAK,KAAK,EACrC,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,2BAA2B,EAAE,EAAE,CAAC;IACvD,CAAC;IACD,4BAA4B,CAAC;QAC3B,UAAU,EAAE,KAAK,CAAC,IAAI,CAAC,UAAU;QACjC,qBAAqB,EACnB,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,6BAA6B,EAAE,IAAI,CACtD,KAAK,CAAC,IAAI,CAAC,SAAS,CACrB;QACH,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;QACxC,WAAW,EAAE,KAAK,CAAC,IAAI,CAAC,WAAW;QACnC,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,YAAY,EAAE,KAAK,CAAC,IAAI,CAAC,YAAY;KACtC,CAAC,CAAC;IACH,OAAO;QACL,GAAG,MAAM;QACT,yBAAyB,EACvB,CAAC,KAAK,CAAC,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,KAAK,SAAS;YAC3D,KAAK,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC;YACjC,MAAM,CAAC,2BAA2B,KAAK,CAAC,CAAC;YAC3C,oCAAoC,CAAC;gBACnC,wBAAwB,EAAE,MAAM,CAAC,wBAAwB;gBACzD,2BAA2B,EAAE,MAAM,CAAC,2BAA2B;gBAC/D,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;gBACxC,uBAAuB,EAAE,MAAM,CAAC,uBAAuB;gBACvD,uBAAuB,EAAE,MAAM,CAAC,uBAAuB;aACxD,CAAC;QACJ,iBAAiB,EAAE,CAAC,KAAK,CAAC,YAAY;KACvC,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,yCAAyC,CACtD,KAAuC,EACvC,gBAAyB,EACzB,oBAA6B;IAE7B,MAAM,gBAAgB,GAAG,MAAM,kCAAkC,CAAC;QAChE,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC,SAAS;QAC/B,UAAU,EAAE,KAAK,CAAC,IAAI,CAAC,UAAU;QACjC,uBAAuB,EAAE,KAAK,CAAC,IAAI,CAAC,uBAAuB;QAC3D,eAAe,EAAE,KAAK,CAAC,IAAI,CAAC,eAAe;QAC3C,WAAW,EAAE,KAAK,CAAC,IAAI,CAAC,WAAW;QACnC,iBAAiB,EAAE,KAAK,CAAC,IAAI,CAAC,2BAA2B;QACzD,YAAY,EAAE,KAAK,CAAC,IAAI,CAAC,YAAY;QACrC,gBAAgB;KACjB,CAAC,CAAC;IACH,IAAI,CAAC,gBAAgB;QAAE,OAAO,IAAI,CAAC;IACnC,MAAM,gBAAgB,GAAG,oBAAoB;QAC3C,CAAC,CAAC;YACE,GAAG,KAAK,CAAC,gBAAgB;YACzB,IAAI,EAAE;gBACJ,GAAG,KAAK,CAAC,gBAAgB,CAAC,IAAI;gBAC9B,2BAA2B,EACzB,MAAM,2CAA2C,CAAC;oBAChD,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,OAAO;oBAC3B,UAAU,EAAE,gBAAgB;oBAC5B,cAAc,EAAE,KAAK,CAAC,wBAAwB;oBAC9C,YAAY,EAAE,KAAK,CAAC,IAAI,CAAC,YAAY;oBACrC,+BAA+B,EAC7B,KAAK,CAAC,IAAI,CAAC,+BAA+B;iBAC7C,CAAC;aACL;SACF;QACH,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC;IAC3B,yEAAyE;IACzE,6EAA6E;IAC7E,OAAO,2BAA2B,CAAC;QACjC,GAAG,KAAK;QACR,gBAAgB;QAChB,gBAAgB;KACjB,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kCAAkC,CACtD,KAAuC;IAEvC,IAAI,CAAC;QACH,OAAO,MAAM,2BAA2B,CAAC,KAAK,CAAC,CAAC;IAClD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,iBAAiB,GACrB,yBAAyB,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,oBAAoB,CAAC;QAC1E,IACE,CAAC,iBAAiB;YAClB,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,KAAK,KAAK;gBAC/B,CAAC,CAAC,KAAK,YAAY,kCAAkC,CAAC,CAAC,EACzD,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;QACD,OAAO,yCAAyC,CAC9C,KAAK,EACL,KAAK,EACL,iBAAiB,CAClB,CAAC;IACJ,CAAC;AACH,CAAC","sourcesContent":["import type {\n  DocumentSyncResponse,\n  DocumentWriterProjectionResponse,\n} from \"@tearleads/validators/response\";\nimport type {\n  MaterializedDocumentSyncPlan,\n  SyncRemoteDocumentResult,\n} from \"../../data/documents/shared/types\";\nimport { projectionVerificationOptions } from \"../../data/documents/shared/types\";\nimport {\n  type ProjectionUserKeyResolver,\n  verifyDocumentWriterProjectionAuthorization,\n} from \"../../data/keyingProjectionVerification\";\nimport { isKeyingVerificationError } from \"../../data/keyingProjectionVerification/error\";\nimport type { PendingUpdateRecord } from \"../../data/sqlite/documentPersistence\";\nimport type { SyncRemoteDocumentInput } from \"./readOnlySync\";\nimport { DocumentRawHistoryUnavailableError } from \"./syncContentKeys\";\nimport { refreshSyncAttemptWriterProjection } from \"./syncFailures\";\nimport {\n  hasDeferredPendingUpdatesAfterSubmit,\n  responseAcceptedRecoveryBaseline,\n} from \"./syncPlanRequestBounds\";\nimport { syncRemoteDocumentResultFromResponse } from \"./syncResponseResult\";\nimport { traceHealed } from \"./syncTrace\";\n\ntype SubmittedDocumentSyncResultInput = {\n  materializedPlan: MaterializedDocumentSyncPlan;\n  pendingUpdateIds: readonly string[];\n  pullComplete: boolean;\n  recoveryPendingUpdatesById: ReadonlyMap<string, PendingUpdateRecord>;\n  resolveProjectionUserKey: ProjectionUserKeyResolver;\n  response: DocumentSyncResponse;\n  sync: SyncRemoteDocumentInput;\n  writerProjection: DocumentWriterProjectionResponse;\n};\n\n/** @internal Applies post-verification heal effects under the sync generation. */\nexport function applyAcceptedHealSideEffects(input: {\n  documentId: string;\n  evictWriterProjection?: ((documentId: string) => void) | undefined;\n  materializedPlan: MaterializedDocumentSyncPlan;\n  onSyncTrace: SyncRemoteDocumentInput[\"onSyncTrace\"];\n  response: DocumentSyncResponse;\n  stillCurrent: SyncRemoteDocumentInput[\"stillCurrent\"];\n}): void {\n  if (\n    !input.materializedPlan.healedStaleContentKeyBundle ||\n    !responseAcceptedRecoveryBaseline(input.materializedPlan, input.response) ||\n    input.stillCurrent?.() === false\n  ) {\n    return;\n  }\n  input.evictWriterProjection?.(input.documentId);\n  if (input.stillCurrent?.() === false) {\n    return;\n  }\n  traceHealed(input.onSyncTrace, {\n    accepted: input.response.acceptedOutgoingUpdateIds.length,\n    documentId: input.materializedPlan.plan.documentId,\n    epoch: input.materializedPlan.plan.contentKeyEpoch,\n  });\n}\n\nasync function submittedDocumentSyncResult(\n  input: SubmittedDocumentSyncResultInput,\n): Promise<SyncRemoteDocumentResult> {\n  const result = await syncRemoteDocumentResultFromResponse({\n    ...projectionVerificationOptions(input.sync),\n    execSql: input.sync.execSql,\n    materializedPlan: input.materializedPlan,\n    onTerminalSubmitFailure: input.sync.onTerminalSubmitFailure,\n    recoveryPendingUpdatesById: input.recoveryPendingUpdatesById,\n    rekeyPendingUpdate: input.sync.rekeyPendingUpdate,\n    resolveWriterPublicKey: input.sync.resolveWriterPublicKey,\n    response: input.response,\n    stillCurrent: input.sync.stillCurrent,\n    targetSecretKey: input.sync.targetSecretKey,\n    validateIncomingUpdates: input.sync.validateIncomingUpdates,\n    writerProjection: input.writerProjection,\n    resolveProjectionUserKey: input.resolveProjectionUserKey,\n  });\n  if (\n    (input.materializedPlan.plan.request.containerRekeys?.length ?? 0) > 0 &&\n    input.sync.stillCurrent?.() !== false\n  ) {\n    input.sync.apiClient.clearWriterProjectionCaches?.();\n  }\n  applyAcceptedHealSideEffects({\n    documentId: input.sync.documentId,\n    evictWriterProjection:\n      input.sync.apiClient.evictDocumentWriterProjection?.bind(\n        input.sync.apiClient,\n      ),\n    materializedPlan: input.materializedPlan,\n    onSyncTrace: input.sync.onSyncTrace,\n    response: input.response,\n    stillCurrent: input.sync.stillCurrent,\n  });\n  return {\n    ...result,\n    hasDeferredPendingUpdates:\n      (input.materializedPlan.plan.request.pullCursor !== undefined &&\n        input.pendingUpdateIds.length > 0 &&\n        result.exhaustedPendingUpdateCount === 0) ||\n      hasDeferredPendingUpdatesAfterSubmit({\n        acceptedRecoveryBaseline: result.acceptedRecoveryBaseline,\n        exhaustedPendingUpdateCount: result.exhaustedPendingUpdateCount,\n        pendingUpdateIds: input.pendingUpdateIds,\n        rekeyedPendingUpdateIds: result.rekeyedPendingUpdateIds,\n        settledPendingUpdateIds: result.settledPendingUpdateIds,\n      }),\n    hasIncompletePull: !input.pullComplete,\n  };\n}\n\nasync function retrySubmittedResponseWithFreshProjection(\n  input: SubmittedDocumentSyncResultInput,\n  unavailableError: unknown,\n  refreshAuthorization: boolean,\n): Promise<SyncRemoteDocumentResult | null> {\n  const writerProjection = await refreshSyncAttemptWriterProjection({\n    apiClient: input.sync.apiClient,\n    documentId: input.sync.documentId,\n    onRemoteDocumentDeleted: input.sync.onRemoteDocumentDeleted,\n    onSyncAbandoned: input.sync.onSyncAbandoned,\n    onSyncTrace: input.sync.onSyncTrace,\n    onTerminalFailure: input.sync.onReadOnlyProjectionFailure,\n    stillCurrent: input.sync.stillCurrent,\n    unavailableError,\n  });\n  if (!writerProjection) return null;\n  const materializedPlan = refreshAuthorization\n    ? {\n        ...input.materializedPlan,\n        plan: {\n          ...input.materializedPlan.plan,\n          documentWriterAuthorization:\n            await verifyDocumentWriterProjectionAuthorization({\n              execSql: input.sync.execSql,\n              projection: writerProjection,\n              resolveUserKey: input.resolveProjectionUserKey,\n              stillCurrent: input.sync.stillCurrent,\n              warmReferencedPrincipalPolicies:\n                input.sync.warmReferencedPrincipalPolicies,\n            }),\n        },\n      }\n    : input.materializedPlan;\n  // Keep the submitted request, keys, and response frozen. Only refreshed,\n  // verified evidence may be added; this retry never resubmits outgoing edits.\n  return submittedDocumentSyncResult({\n    ...input,\n    materializedPlan,\n    writerProjection,\n  });\n}\n\nexport async function resolveSubmittedDocumentSyncResult(\n  input: SubmittedDocumentSyncResultInput,\n): Promise<SyncRemoteDocumentResult | null> {\n  try {\n    return await submittedDocumentSyncResult(input);\n  } catch (error) {\n    const missingDependency =\n      isKeyingVerificationError(error) && error.code === \"missing_dependency\";\n    if (\n      !missingDependency &&\n      (input.sync.historyMode !== \"raw\" ||\n        !(error instanceof DocumentRawHistoryUnavailableError))\n    ) {\n      throw error;\n    }\n    return retrySubmittedResponseWithFreshProjection(\n      input,\n      error,\n      missingDependency,\n    );\n  }\n}\n"]}

package/workflows/documents/syncTrace.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Production-safe trace lines for the document sync workflow.
+ *
+ * Every line is assembled here from a CLOSED vocabulary — strict document
+ * UUIDs, integers, and enumerated reason/action/code values that appear as
+ * literal alternatives in the pattern below. No decrypted content, names,
+ * key material, or free-form error text can enter a line, and because the
+ * System Monitor validates LINES (it cannot know their emitter), the pattern
+ * itself rejects any token outside that vocabulary rather than trusting
+ * emitter-side sanitization. The format tests assert emitter output and
+ * pattern stay in lockstep, including that leaks fail closed.
+ */
+export type DocumentSyncTraceEmitter = (line: string) => void;
+/**
+ * Enumerated, clipboard-safe reasons an ancestor repair abandons a pass. The
+ * emitter maps to these rather than passing the error's prose through, so the
+ * line stays inside the closed vocabulary the System Monitor validates.
+ */
+export declare const ANCESTOR_REPAIR_ABANDON_REASONS: readonly ["blocked", "depth-budget", "inaccessible", "peer-rotation", "refused", "unrefreshable"];
+export type AncestorRepairAbandonReason = (typeof ANCESTOR_REPAIR_ABANDON_REASONS)[number];
+type DocumentSyncTraceAction = "recover-update-ids" | "regenerate-checkpoints" | "retry" | "stop";
+/**
+ * Unanchored alternatives for composition into a larger allowlist (the
+ * System Monitor wraps this in its own prefix/suffix anchors). Use
+ * DOCUMENT_SYNC_TRACE_PATTERN to validate a complete line.
+ */
+export declare const DOCUMENT_SYNC_TRACE_FRAGMENT: string;
+/** Anchored validator: a string is a trace line in full, or not at all. */
+export declare const DOCUMENT_SYNC_TRACE_PATTERN: RegExp;
+export declare function traceStaleBundle(emit: DocumentSyncTraceEmitter | undefined, input: {
+    documentId: string;
+    epoch: number;
+    pending: number;
+}): void;
+export declare function traceHealPlanned(emit: DocumentSyncTraceEmitter | undefined, input: {
+    documentId: string;
+    fromEpoch: number;
+    heldBack: number;
+    toEpoch: number;
+    updates: number;
+}): void;
+export declare function traceStaleRead(emit: DocumentSyncTraceEmitter | undefined, input: {
+    documentId: string;
+    epoch: number;
+}): void;
+export declare function traceCheckpointRegeneration(emit: DocumentSyncTraceEmitter | undefined, input: {
+    checkpoints: number;
+    documentId: string;
+    updates: number;
+}): void;
+export declare function traceHealBlocked(emit: DocumentSyncTraceEmitter | undefined, input: {
+    documentId: string;
+    error: unknown;
+}): void;
+export declare function traceSubmitFailed(emit: DocumentSyncTraceEmitter | undefined, input: {
+    action: DocumentSyncTraceAction;
+    code: string | undefined;
+    documentId: string;
+    status: number | null;
+}): void;
+export declare function traceAncestorRepairAbandoned(emit: DocumentSyncTraceEmitter | undefined, input: {
+    documentId: string;
+    reason: AncestorRepairAbandonReason;
+}): void;
+export declare function traceProjectionFailed(emit: DocumentSyncTraceEmitter | undefined, input: {
+    code?: string | undefined;
+    documentId: string;
+    status: number | null;
+}): void;
+export declare function traceHealed(emit: DocumentSyncTraceEmitter | undefined, input: {
+    accepted: number;
+    documentId: string;
+    epoch: number;
+}): void;
+export {};

package/workflows/documents/syncTrace.js

@@ -0,0 +1,148 @@
+/**
+ * Production-safe trace lines for the document sync workflow.
+ *
+ * Every line is assembled here from a CLOSED vocabulary — strict document
+ * UUIDs, integers, and enumerated reason/action/code values that appear as
+ * literal alternatives in the pattern below. No decrypted content, names,
+ * key material, or free-form error text can enter a line, and because the
+ * System Monitor validates LINES (it cannot know their emitter), the pattern
+ * itself rejects any token outside that vocabulary rather than trusting
+ * emitter-side sanitization. The format tests assert emitter output and
+ * pattern stay in lockstep, including that leaks fail closed.
+ */
+import { DOCUMENT_NOT_FOUND_ERROR_CODE, DOCUMENT_PROJECTION_ERROR_CODES, DOCUMENT_SYNC_ERROR_CODES, } from "../../internal/validators/response/index.js";
+/**
+ * Enumerated, clipboard-safe reasons an ancestor repair abandons a pass. The
+ * emitter maps to these rather than passing the error's prose through, so the
+ * line stays inside the closed vocabulary the System Monitor validates.
+ */
+export const ANCESTOR_REPAIR_ABANDON_REASONS = [
+    "blocked",
+    "depth-budget",
+    "inaccessible",
+    "peer-rotation",
+    "refused",
+    "unrefreshable",
+];
+/** Fixed thrown messages mapped to enumerated, clipboard-safe reasons. */
+const HEAL_BLOCKED_REASONS = [
+    [
+        "Document content-key bundle is stale and no rotation snapshot is available",
+        "snapshot-unavailable",
+    ],
+    [
+        "Document stale-bundle recovery requires a full-history rotation snapshot",
+        "snapshot-not-full-history",
+    ],
+    ["Document stale-bundle recovery snapshot is empty", "snapshot-empty"],
+    [
+        "Document stale-bundle recovery snapshot does not cover a queued rotation checkpoint",
+        "checkpoint-uncovered",
+    ],
+    ["Document content-key re-wrap KEK is unavailable", "rewrap-kek-unavailable"],
+    [
+        "Document stale bundle manifest is missing from the projection history",
+        "stale-manifest-missing",
+    ],
+    ["Document content key could not be unwrapped", "content-key-unwrap-failed"],
+];
+/**
+ * Only the protocol's own coded values are copied; any other server-provided
+ * string — even one that happens to look like a code — is collapsed to
+ * "other" so a hostile or buggy server can never smuggle text into a report.
+ */
+const SAFE_FAILURE_CODES = new Set([
+    ...Object.values(DOCUMENT_SYNC_ERROR_CODES),
+    ...Object.values(DOCUMENT_PROJECTION_ERROR_CODES),
+    DOCUMENT_NOT_FOUND_ERROR_CODE,
+]);
+const TRACE_ACTIONS = [
+    "recover-update-ids",
+    "regenerate-checkpoints",
+    "retry",
+    "stop",
+];
+// Every vocabulary below is enumerated into the pattern as literals; the only
+// open-ended slots are a strict UUID and decimal counts.
+const UUID_FRAGMENT = "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}";
+const REASON_FRAGMENT = HEAL_BLOCKED_REASONS.map(([, reason]) => reason).join("|");
+const ABANDON_REASON_FRAGMENT = ANCESTOR_REPAIR_ABANDON_REASONS.join("|");
+const ACTION_FRAGMENT = TRACE_ACTIONS.join("|");
+const CODE_FRAGMENT = [...SAFE_FAILURE_CODES, "none", "other"].join("|");
+/**
+ * Unanchored alternatives for composition into a larger allowlist (the
+ * System Monitor wraps this in its own prefix/suffix anchors). Use
+ * DOCUMENT_SYNC_TRACE_PATTERN to validate a complete line.
+ */
+export const DOCUMENT_SYNC_TRACE_FRAGMENT = [
+    `document sync blocked document=${UUID_FRAGMENT}`,
+    `document sync stale bundle document=${UUID_FRAGMENT} epoch=\\d+ pending=\\d+`,
+    `document sync heal planned document=${UUID_FRAGMENT} fromEpoch=\\d+ toEpoch=\\d+ updates=\\d+ heldBack=\\d+`,
+    `document sync stale read document=${UUID_FRAGMENT} epoch=\\d+`,
+    `document sync checkpoint regeneration document=${UUID_FRAGMENT} checkpoints=\\d+ updates=\\d+`,
+    `document sync heal blocked document=${UUID_FRAGMENT} reason=(?:${REASON_FRAGMENT})`,
+    `document sync submit failed document=${UUID_FRAGMENT} status=(?:\\d+|none) code=(?:${CODE_FRAGMENT}) action=(?:${ACTION_FRAGMENT})`,
+    `document sync projection failed document=${UUID_FRAGMENT} status=(?:\\d+|none) code=(?:${CODE_FRAGMENT})`,
+    `document sync ancestor repair abandoned document=${UUID_FRAGMENT} reason=(?:${ABANDON_REASON_FRAGMENT})`,
+    `document sync healed document=${UUID_FRAGMENT} epoch=\\d+ accepted=\\d+`,
+]
+    .map((alternative) => `(?:${alternative})`)
+    .join("|");
+/** Anchored validator: a string is a trace line in full, or not at all. */
+export const DOCUMENT_SYNC_TRACE_PATTERN = new RegExp(`^(?:${DOCUMENT_SYNC_TRACE_FRAGMENT})$`, "u");
+/**
+ * Classifies a plan-build failure into an enumerated reason, or null when the
+ * message is not one of the fixed protocol strings — unknown errors fail
+ * closed and emit nothing rather than leaking free text.
+ */
+function classifyHealBlockedReason(error) {
+    const message = error instanceof Error ? error.message : "";
+    for (const [prefix, reason] of HEAL_BLOCKED_REASONS) {
+        if (message.startsWith(prefix)) {
+            return reason;
+        }
+    }
+    return null;
+}
+function safeCode(code) {
+    if (code === undefined) {
+        return "none";
+    }
+    return SAFE_FAILURE_CODES.has(code) ? code : "other";
+}
+function safeStatus(status) {
+    return status !== null && Number.isInteger(status) && status >= 0
+        ? String(status)
+        : "none";
+}
+export function traceStaleBundle(emit, input) {
+    emit?.(`document sync stale bundle document=${input.documentId} epoch=${input.epoch} pending=${input.pending}`);
+}
+export function traceHealPlanned(emit, input) {
+    emit?.(`document sync heal planned document=${input.documentId} fromEpoch=${input.fromEpoch} toEpoch=${input.toEpoch} updates=${input.updates} heldBack=${input.heldBack}`);
+}
+export function traceStaleRead(emit, input) {
+    emit?.(`document sync stale read document=${input.documentId} epoch=${input.epoch}`);
+}
+export function traceCheckpointRegeneration(emit, input) {
+    emit?.(`document sync checkpoint regeneration document=${input.documentId} checkpoints=${input.checkpoints} updates=${input.updates}`);
+}
+export function traceHealBlocked(emit, input) {
+    const reason = classifyHealBlockedReason(input.error);
+    if (reason !== null) {
+        emit?.(`document sync heal blocked document=${input.documentId} reason=${reason}`);
+    }
+}
+export function traceSubmitFailed(emit, input) {
+    emit?.(`document sync submit failed document=${input.documentId} status=${safeStatus(input.status)} code=${safeCode(input.code)} action=${input.action}`);
+}
+export function traceAncestorRepairAbandoned(emit, input) {
+    emit?.(`document sync ancestor repair abandoned document=${input.documentId} reason=${input.reason}`);
+}
+export function traceProjectionFailed(emit, input) {
+    emit?.(`document sync projection failed document=${input.documentId} status=${safeStatus(input.status)} code=${safeCode(input.code)}`);
+}
+export function traceHealed(emit, input) {
+    emit?.(`document sync healed document=${input.documentId} epoch=${input.epoch} accepted=${input.accepted}`);
+}
+//# sourceMappingURL=syncTrace.js.map

package/workflows/documents/syncTrace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncTrace.js","sourceRoot":"","sources":["syncTrace.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Production-safe trace lines for the document sync workflow.\n *\n * Every line is assembled here from a CLOSED vocabulary — strict document\n * UUIDs, integers, and enumerated reason/action/code values that appear as\n * literal alternatives in the pattern below. No decrypted content, names,\n * key material, or free-form error text can enter a line, and because the\n * System Monitor validates LINES (it cannot know their emitter), the pattern\n * itself rejects any token outside that vocabulary rather than trusting\n * emitter-side sanitization. The format tests assert emitter output and\n * pattern stay in lockstep, including that leaks fail closed.\n */\n\nimport {\n  DOCUMENT_NOT_FOUND_ERROR_CODE,\n  DOCUMENT_PROJECTION_ERROR_CODES,\n  DOCUMENT_SYNC_ERROR_CODES,\n} from \"@tearleads/validators/response\";\n\nexport type DocumentSyncTraceEmitter = (line: string) => void;\n\n/**\n * Enumerated, clipboard-safe reasons an ancestor repair abandons a pass. The\n * emitter maps to these rather than passing the error's prose through, so the\n * line stays inside the closed vocabulary the System Monitor validates.\n */\nexport const ANCESTOR_REPAIR_ABANDON_REASONS = [\n  \"blocked\",\n  \"depth-budget\",\n  \"inaccessible\",\n  \"peer-rotation\",\n  \"refused\",\n  \"unrefreshable\",\n] as const;\n\nexport type AncestorRepairAbandonReason =\n  (typeof ANCESTOR_REPAIR_ABANDON_REASONS)[number];\n\n/** Fixed thrown messages mapped to enumerated, clipboard-safe reasons. */\nconst HEAL_BLOCKED_REASONS: ReadonlyArray<readonly [string, string]> = [\n  [\n    \"Document content-key bundle is stale and no rotation snapshot is available\",\n    \"snapshot-unavailable\",\n  ],\n  [\n    \"Document stale-bundle recovery requires a full-history rotation snapshot\",\n    \"snapshot-not-full-history\",\n  ],\n  [\"Document stale-bundle recovery snapshot is empty\", \"snapshot-empty\"],\n  [\n    \"Document stale-bundle recovery snapshot does not cover a queued rotation checkpoint\",\n    \"checkpoint-uncovered\",\n  ],\n  [\"Document content-key re-wrap KEK is unavailable\", \"rewrap-kek-unavailable\"],\n  [\n    \"Document stale bundle manifest is missing from the projection history\",\n    \"stale-manifest-missing\",\n  ],\n  [\"Document content key could not be unwrapped\", \"content-key-unwrap-failed\"],\n];\n\n/**\n * Only the protocol's own coded values are copied; any other server-provided\n * string — even one that happens to look like a code — is collapsed to\n * \"other\" so a hostile or buggy server can never smuggle text into a report.\n */\nconst SAFE_FAILURE_CODES: ReadonlySet<string> = new Set([\n  ...Object.values(DOCUMENT_SYNC_ERROR_CODES),\n  ...Object.values(DOCUMENT_PROJECTION_ERROR_CODES),\n  DOCUMENT_NOT_FOUND_ERROR_CODE,\n]);\n\ntype DocumentSyncTraceAction =\n  | \"recover-update-ids\"\n  | \"regenerate-checkpoints\"\n  | \"retry\"\n  | \"stop\";\n\nconst TRACE_ACTIONS: ReadonlyArray<DocumentSyncTraceAction> = [\n  \"recover-update-ids\",\n  \"regenerate-checkpoints\",\n  \"retry\",\n  \"stop\",\n];\n\n// Every vocabulary below is enumerated into the pattern as literals; the only\n// open-ended slots are a strict UUID and decimal counts.\nconst UUID_FRAGMENT =\n  \"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\";\nconst REASON_FRAGMENT = HEAL_BLOCKED_REASONS.map(([, reason]) => reason).join(\n  \"|\",\n);\nconst ABANDON_REASON_FRAGMENT = ANCESTOR_REPAIR_ABANDON_REASONS.join(\"|\");\nconst ACTION_FRAGMENT = TRACE_ACTIONS.join(\"|\");\nconst CODE_FRAGMENT = [...SAFE_FAILURE_CODES, \"none\", \"other\"].join(\"|\");\n\n/**\n * Unanchored alternatives for composition into a larger allowlist (the\n * System Monitor wraps this in its own prefix/suffix anchors). Use\n * DOCUMENT_SYNC_TRACE_PATTERN to validate a complete line.\n */\nexport const DOCUMENT_SYNC_TRACE_FRAGMENT = [\n  `document sync blocked document=${UUID_FRAGMENT}`,\n  `document sync stale bundle document=${UUID_FRAGMENT} epoch=\\\\d+ pending=\\\\d+`,\n  `document sync heal planned document=${UUID_FRAGMENT} fromEpoch=\\\\d+ toEpoch=\\\\d+ updates=\\\\d+ heldBack=\\\\d+`,\n  `document sync stale read document=${UUID_FRAGMENT} epoch=\\\\d+`,\n  `document sync checkpoint regeneration document=${UUID_FRAGMENT} checkpoints=\\\\d+ updates=\\\\d+`,\n  `document sync heal blocked document=${UUID_FRAGMENT} reason=(?:${REASON_FRAGMENT})`,\n  `document sync submit failed document=${UUID_FRAGMENT} status=(?:\\\\d+|none) code=(?:${CODE_FRAGMENT}) action=(?:${ACTION_FRAGMENT})`,\n  `document sync projection failed document=${UUID_FRAGMENT} status=(?:\\\\d+|none) code=(?:${CODE_FRAGMENT})`,\n  `document sync ancestor repair abandoned document=${UUID_FRAGMENT} reason=(?:${ABANDON_REASON_FRAGMENT})`,\n  `document sync healed document=${UUID_FRAGMENT} epoch=\\\\d+ accepted=\\\\d+`,\n]\n  .map((alternative) => `(?:${alternative})`)\n  .join(\"|\");\n\n/** Anchored validator: a string is a trace line in full, or not at all. */\nexport const DOCUMENT_SYNC_TRACE_PATTERN = new RegExp(\n  `^(?:${DOCUMENT_SYNC_TRACE_FRAGMENT})$`,\n  \"u\",\n);\n\n/**\n * Classifies a plan-build failure into an enumerated reason, or null when the\n * message is not one of the fixed protocol strings — unknown errors fail\n * closed and emit nothing rather than leaking free text.\n */\nfunction classifyHealBlockedReason(error: unknown): string | null {\n  const message = error instanceof Error ? error.message : \"\";\n  for (const [prefix, reason] of HEAL_BLOCKED_REASONS) {\n    if (message.startsWith(prefix)) {\n      return reason;\n    }\n  }\n  return null;\n}\n\nfunction safeCode(code: string | undefined): string {\n  if (code === undefined) {\n    return \"none\";\n  }\n  return SAFE_FAILURE_CODES.has(code) ? code : \"other\";\n}\n\nfunction safeStatus(status: number | null): string {\n  return status !== null && Number.isInteger(status) && status >= 0\n    ? String(status)\n    : \"none\";\n}\n\nexport function traceStaleBundle(\n  emit: DocumentSyncTraceEmitter | undefined,\n  input: { documentId: string; epoch: number; pending: number },\n): void {\n  emit?.(\n    `document sync stale bundle document=${input.documentId} epoch=${input.epoch} pending=${input.pending}`,\n  );\n}\n\nexport function traceHealPlanned(\n  emit: DocumentSyncTraceEmitter | undefined,\n  input: {\n    documentId: string;\n    fromEpoch: number;\n    heldBack: number;\n    toEpoch: number;\n    updates: number;\n  },\n): void {\n  emit?.(\n    `document sync heal planned document=${input.documentId} fromEpoch=${input.fromEpoch} toEpoch=${input.toEpoch} updates=${input.updates} heldBack=${input.heldBack}`,\n  );\n}\n\nexport function traceStaleRead(\n  emit: DocumentSyncTraceEmitter | undefined,\n  input: { documentId: string; epoch: number },\n): void {\n  emit?.(\n    `document sync stale read document=${input.documentId} epoch=${input.epoch}`,\n  );\n}\n\nexport function traceCheckpointRegeneration(\n  emit: DocumentSyncTraceEmitter | undefined,\n  input: { checkpoints: number; documentId: string; updates: number },\n): void {\n  emit?.(\n    `document sync checkpoint regeneration document=${input.documentId} checkpoints=${input.checkpoints} updates=${input.updates}`,\n  );\n}\n\nexport function traceHealBlocked(\n  emit: DocumentSyncTraceEmitter | undefined,\n  input: { documentId: string; error: unknown },\n): void {\n  const reason = classifyHealBlockedReason(input.error);\n  if (reason !== null) {\n    emit?.(\n      `document sync heal blocked document=${input.documentId} reason=${reason}`,\n    );\n  }\n}\n\nexport function traceSubmitFailed(\n  emit: DocumentSyncTraceEmitter | undefined,\n  input: {\n    action: DocumentSyncTraceAction;\n    code: string | undefined;\n    documentId: string;\n    status: number | null;\n  },\n): void {\n  emit?.(\n    `document sync submit failed document=${input.documentId} status=${safeStatus(input.status)} code=${safeCode(input.code)} action=${input.action}`,\n  );\n}\n\nexport function traceAncestorRepairAbandoned(\n  emit: DocumentSyncTraceEmitter | undefined,\n  input: { documentId: string; reason: AncestorRepairAbandonReason },\n): void {\n  emit?.(\n    `document sync ancestor repair abandoned document=${input.documentId} reason=${input.reason}`,\n  );\n}\n\nexport function traceProjectionFailed(\n  emit: DocumentSyncTraceEmitter | undefined,\n  input: {\n    code?: string | undefined;\n    documentId: string;\n    status: number | null;\n  },\n): void {\n  emit?.(\n    `document sync projection failed document=${input.documentId} status=${safeStatus(input.status)} code=${safeCode(input.code)}`,\n  );\n}\n\nexport function traceHealed(\n  emit: DocumentSyncTraceEmitter | undefined,\n  input: { accepted: number; documentId: string; epoch: number },\n): void {\n  emit?.(\n    `document sync healed document=${input.documentId} epoch=${input.epoch} accepted=${input.accepted}`,\n  );\n}\n"]}

package/workflows/documents/writerKeys.d.ts

@@ -0,0 +1,14 @@
+import type { DocumentWriterPublicKeyResolver } from "../../data/documents/shared/types.js";
+import { type TrustedUserIdentityResolver } from "../../data/trustedUserIdentity/index.js";
+interface DocumentWriterPublicKeyRuntime {
+    readonly resolveTrustedUserIdentity: TrustedUserIdentityResolver;
+    readonly util: {
+        readonly log: (message: string) => void;
+    };
+}
+export declare function createDocumentWriterPublicKeyResolver(input: {
+    readonly logPrefix: string;
+    readonly runtime: DocumentWriterPublicKeyRuntime;
+    readonly writerKeyLabel: string;
+}): DocumentWriterPublicKeyResolver;
+export {};

package/workflows/documents/writerKeys.js

@@ -0,0 +1,55 @@
+import { KeyingVerificationError } from "../../internal/crypto/index.js";
+import { isDatabaseUnavailableError } from "../../data/sync/databaseUnavailable.js";
+import { requireTrustedUserIdentityResolver, } from "../../data/trustedUserIdentity/index.js";
+export function createDocumentWriterPublicKeyResolver(input) {
+    const resolveTrustedUserIdentity = requireTrustedUserIdentityResolver(input.runtime.resolveTrustedUserIdentity);
+    const cache = new Map();
+    return async ({ writerSigningKeyFingerprint, writerUserId }) => {
+        const cacheKey = `${writerUserId}:${writerSigningKeyFingerprint}`;
+        let cached = cache.get(cacheKey);
+        if (!cached) {
+            cached = resolveWriterPublicKey({
+                authorFingerprint: writerSigningKeyFingerprint,
+                logPrefix: input.logPrefix,
+                resolveTrustedUserIdentity,
+                util: input.runtime.util,
+                writerKeyLabel: input.writerKeyLabel,
+                writerUserId,
+            }).catch((error) => {
+                cache.delete(cacheKey);
+                throw error;
+            });
+            cache.set(cacheKey, cached);
+        }
+        return cached;
+    };
+}
+async function resolveWriterPublicKey(input) {
+    try {
+        const identity = await input.resolveTrustedUserIdentity(input.writerUserId);
+        if (!identity) {
+            return null;
+        }
+        if (identity.signingKeyFingerprint !== input.authorFingerprint) {
+            input.util.log(`${input.logPrefix}: skipped ${input.writerKeyLabel} for ${input.writerUserId} because the signing fingerprint does not match the writer.`);
+            return null;
+        }
+        return identity.signingPublicKey;
+    }
+    catch (error) {
+        if (error instanceof KeyingVerificationError) {
+            throw error;
+        }
+        // A vanished database is infrastructure loss, not an unresolvable writer.
+        // Returning null here would surface downstream as a generic "writer public
+        // key missing" verification error that sync lanes cannot classify, so the
+        // lane would count a real failure for a routine runtime swap. Rethrow and
+        // let the lanes' shouldIgnoreError treat it as the benign signal it is.
+        if (isDatabaseUnavailableError(error)) {
+            throw error;
+        }
+        input.util.log(`${input.logPrefix}: skipped ${input.writerKeyLabel} for ${input.writerUserId} because it could not be loaded.`);
+        return null;
+    }
+}
+//# sourceMappingURL=writerKeys.js.map

package/workflows/documents/writerKeys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writerKeys.js","sourceRoot":"","sources":["writerKeys.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAE5D,OAAO,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AACjF,OAAO,EACL,kCAAkC,GAEnC,MAAM,gCAAgC,CAAC;AASxC,MAAM,UAAU,qCAAqC,CAAC,KAIrD;IACC,MAAM,0BAA0B,GAAG,kCAAkC,CACnE,KAAK,CAAC,OAAO,CAAC,0BAA0B,CACzC,CAAC;IACF,MAAM,KAAK,GAAG,IAAI,GAAG,EAAsC,CAAC;IAE5D,OAAO,KAAK,EAAE,EAAE,2BAA2B,EAAE,YAAY,EAAE,EAAE,EAAE;QAC7D,MAAM,QAAQ,GAAG,GAAG,YAAY,IAAI,2BAA2B,EAAE,CAAC;QAClE,IAAI,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACjC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,GAAG,sBAAsB,CAAC;gBAC9B,iBAAiB,EAAE,2BAA2B;gBAC9C,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,0BAA0B;gBAC1B,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI;gBACxB,cAAc,EAAE,KAAK,CAAC,cAAc;gBACpC,YAAY;aACb,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;gBAC1B,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;gBACvB,MAAM,KAAK,CAAC;YACd,CAAC,CAAC,CAAC;YACH,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC9B,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,sBAAsB,CAAC,KAOrC;IACC,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,0BAA0B,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;QAC5E,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,QAAQ,CAAC,qBAAqB,KAAK,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC/D,KAAK,CAAC,IAAI,CAAC,GAAG,CACZ,GAAG,KAAK,CAAC,SAAS,aAAa,KAAK,CAAC,cAAc,QAAQ,KAAK,CAAC,YAAY,6DAA6D,CAC3I,CAAC;YACF,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,QAAQ,CAAC,gBAAgB,CAAC;IACnC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,uBAAuB,EAAE,CAAC;YAC7C,MAAM,KAAK,CAAC;QACd,CAAC;QACD,0EAA0E;QAC1E,2EAA2E;QAC3E,0EAA0E;QAC1E,0EAA0E;QAC1E,wEAAwE;QACxE,IAAI,0BAA0B,CAAC,KAAK,CAAC,EAAE,CAAC;YACtC,MAAM,KAAK,CAAC;QACd,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,GAAG,CACZ,GAAG,KAAK,CAAC,SAAS,aAAa,KAAK,CAAC,cAAc,QAAQ,KAAK,CAAC,YAAY,kCAAkC,CAChH,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC","sourcesContent":["import { KeyingVerificationError } from \"@tearleads/crypto\";\nimport type { DocumentWriterPublicKeyResolver } from \"../../data/documents/shared/types\";\nimport { isDatabaseUnavailableError } from \"../../data/sync/databaseUnavailable\";\nimport {\n  requireTrustedUserIdentityResolver,\n  type TrustedUserIdentityResolver,\n} from \"../../data/trustedUserIdentity\";\n\ninterface DocumentWriterPublicKeyRuntime {\n  readonly resolveTrustedUserIdentity: TrustedUserIdentityResolver;\n  readonly util: {\n    readonly log: (message: string) => void;\n  };\n}\n\nexport function createDocumentWriterPublicKeyResolver(input: {\n  readonly logPrefix: string;\n  readonly runtime: DocumentWriterPublicKeyRuntime;\n  readonly writerKeyLabel: string;\n}): DocumentWriterPublicKeyResolver {\n  const resolveTrustedUserIdentity = requireTrustedUserIdentityResolver(\n    input.runtime.resolveTrustedUserIdentity,\n  );\n  const cache = new Map<string, Promise<Uint8Array | null>>();\n\n  return async ({ writerSigningKeyFingerprint, writerUserId }) => {\n    const cacheKey = `${writerUserId}:${writerSigningKeyFingerprint}`;\n    let cached = cache.get(cacheKey);\n    if (!cached) {\n      cached = resolveWriterPublicKey({\n        authorFingerprint: writerSigningKeyFingerprint,\n        logPrefix: input.logPrefix,\n        resolveTrustedUserIdentity,\n        util: input.runtime.util,\n        writerKeyLabel: input.writerKeyLabel,\n        writerUserId,\n      }).catch((error: unknown) => {\n        cache.delete(cacheKey);\n        throw error;\n      });\n      cache.set(cacheKey, cached);\n    }\n\n    return cached;\n  };\n}\n\nasync function resolveWriterPublicKey(input: {\n  readonly authorFingerprint: string;\n  readonly logPrefix: string;\n  readonly resolveTrustedUserIdentity: TrustedUserIdentityResolver;\n  readonly util: DocumentWriterPublicKeyRuntime[\"util\"];\n  readonly writerKeyLabel: string;\n  readonly writerUserId: string;\n}): Promise<Uint8Array | null> {\n  try {\n    const identity = await input.resolveTrustedUserIdentity(input.writerUserId);\n    if (!identity) {\n      return null;\n    }\n\n    if (identity.signingKeyFingerprint !== input.authorFingerprint) {\n      input.util.log(\n        `${input.logPrefix}: skipped ${input.writerKeyLabel} for ${input.writerUserId} because the signing fingerprint does not match the writer.`,\n      );\n      return null;\n    }\n\n    return identity.signingPublicKey;\n  } catch (error) {\n    if (error instanceof KeyingVerificationError) {\n      throw error;\n    }\n    // A vanished database is infrastructure loss, not an unresolvable writer.\n    // Returning null here would surface downstream as a generic \"writer public\n    // key missing\" verification error that sync lanes cannot classify, so the\n    // lane would count a real failure for a routine runtime swap. Rethrow and\n    // let the lanes' shouldIgnoreError treat it as the benign signal it is.\n    if (isDatabaseUnavailableError(error)) {\n      throw error;\n    }\n    input.util.log(\n      `${input.logPrefix}: skipped ${input.writerKeyLabel} for ${input.writerUserId} because it could not be loaded.`,\n    );\n    return null;\n  }\n}\n"]}

package/workflows/organizations/billing.d.ts

@@ -0,0 +1,111 @@
+import type { RequestResult, RequestResultOptions } from "../../internal/api-client/index.js";
+import type { NativeSubscriptionStore } from "../../internal/validators/billing.js";
+import type { OrganizationBillingHistoryResponse, OrganizationBillingManagementUrlResponse, OrganizationBillingResponse, OrganizationBillingStatus, OrganizationBillingSubscriptionSource, OrganizationNativePurchaseEligibilityResponse, StripeCancelResponse, StripeCheckoutIntentResponse, StripeCheckoutOptionsResponse, StripeCheckoutSessionResponse } from "../../internal/validators/response/index.js";
+/** Per-organization sync-billing snapshot (the server wire shape). */
+export type OrganizationBilling = OrganizationBillingResponse;
+/** Per-organization billing lifecycle history (the server wire shape). */
+export type OrganizationBillingHistory = OrganizationBillingHistoryResponse;
+/** One lifecycle event in an organization's billing history, newest first. */
+export type OrganizationBillingHistoryEntry = OrganizationBillingHistoryResponse["entries"][number];
+/** Per-organization subscription-management URL (the server wire shape). */
+export type OrganizationBillingManagementUrl = OrganizationBillingManagementUrlResponse;
+/** Server-backed, point-in-time policy decision made before native checkout. */
+export type OrganizationNativePurchaseEligibility = OrganizationNativePurchaseEligibilityResponse;
+/** Purchasable sync options for the direct Stripe checkout (the wire shape). */
+export type StripeCheckoutOptions = StripeCheckoutOptionsResponse;
+/** What the Payment Element needs to confirm a purchase (the wire shape). */
+export type StripeCheckoutIntent = StripeCheckoutIntentResponse;
+/** The billing methods these workflows need from the api client. */
+interface OrganizationBillingApi {
+    readonly getOrganizationBilling: (organizationId: string) => Promise<OrganizationBillingResponse | null>;
+    readonly getOrganizationBillingHistory: (organizationId: string) => Promise<OrganizationBillingHistoryResponse | null>;
+    readonly getOrganizationBillingManagementUrl: (organizationId: string) => Promise<OrganizationBillingManagementUrlResponse | null>;
+    readonly startOrganizationTrial: (organizationId: string) => Promise<OrganizationBillingResponse | null>;
+    readonly claimNativeOrganizationSubscription: (organizationId: string, store: NativeSubscriptionStore) => Promise<RequestResult<OrganizationBillingResponse>>;
+    readonly getOrganizationNativePurchaseEligibility: (organizationId: string, store: NativeSubscriptionStore) => Promise<OrganizationNativePurchaseEligibilityResponse | null>;
+    readonly getStripeCheckoutOptions: (organizationId: string, options?: RequestResultOptions) => Promise<RequestResult<StripeCheckoutOptionsResponse>>;
+    readonly createStripeCheckout: (organizationId: string) => Promise<StripeCheckoutIntentResponse | null>;
+    readonly createStripeCheckoutSession: (organizationId: string, returnUrl: string) => Promise<StripeCheckoutSessionResponse | null>;
+    readonly cancelStripeSubscription: (organizationId: string) => Promise<StripeCancelResponse | null>;
+}
+export declare function loadOrganizationBilling(input: {
+    readonly apiClient: Pick<OrganizationBillingApi, "getOrganizationBilling">;
+    readonly organizationId: string;
+}): Promise<OrganizationBilling | null>;
+export declare function loadOrganizationBillingHistory(input: {
+    readonly apiClient: Pick<OrganizationBillingApi, "getOrganizationBillingHistory">;
+    readonly organizationId: string;
+}): Promise<OrganizationBillingHistory | null>;
+export declare function loadOrganizationBillingManagementUrl(input: {
+    readonly apiClient: Pick<OrganizationBillingApi, "getOrganizationBillingManagementUrl">;
+    readonly organizationId: string;
+}): Promise<OrganizationBillingManagementUrl | null>;
+export declare function startOrganizationTrial(input: {
+    readonly apiClient: Pick<OrganizationBillingApi, "startOrganizationTrial">;
+    readonly organizationId: string;
+}): Promise<OrganizationBilling | null>;
+export declare function claimNativeOrganizationSubscription(input: {
+    readonly apiClient: Pick<OrganizationBillingApi, "claimNativeOrganizationSubscription">;
+    readonly organizationId: string;
+    readonly store: NativeSubscriptionStore;
+}): Promise<OrganizationBilling | null>;
+export declare function checkNativePurchaseEligibility(input: {
+    readonly apiClient: Pick<OrganizationBillingApi, "getOrganizationNativePurchaseEligibility">;
+    readonly organizationId: string;
+    readonly store: NativeSubscriptionStore;
+}): Promise<OrganizationNativePurchaseEligibility | null>;
+export declare function loadStripeCheckoutOptions(input: {
+    readonly apiClient: Pick<OrganizationBillingApi, "getStripeCheckoutOptions">;
+    readonly organizationId: string;
+}): Promise<StripeCheckoutOptions | null>;
+export declare function createStripeCheckout(input: {
+    readonly apiClient: Pick<OrganizationBillingApi, "createStripeCheckout">;
+    readonly organizationId: string;
+}): Promise<StripeCheckoutIntent | null>;
+export declare function createStripeCheckoutSession(input: {
+    readonly apiClient: Pick<OrganizationBillingApi, "createStripeCheckoutSession">;
+    readonly organizationId: string;
+    readonly returnUrl: string;
+}): Promise<StripeCheckoutSessionResponse | null>;
+export declare function cancelStripeSubscription(input: {
+    readonly apiClient: Pick<OrganizationBillingApi, "cancelStripeSubscription">;
+    readonly organizationId: string;
+}): Promise<StripeCancelResponse | null>;
+/** Client-side projection of a billing snapshot for display and gating. */
+export interface OrganizationBillingView {
+    readonly status: OrganizationBillingStatus;
+    /** Whether the org may sync right now (mirrors the server's organizationCanSync). */
+    readonly canSync: boolean;
+    /** Free, on-device only (status "local"). */
+    readonly isLocal: boolean;
+    /** Actively in a non-expired free trial. */
+    readonly isTrialing: boolean;
+    /** Active paid subscription within its current period. */
+    readonly isActive: boolean;
+    /** Whole days left in the trial (ceil, floored at 0); null unless trialing. */
+    readonly trialDaysRemaining: number | null;
+    readonly trialEndsAtMs: number | null;
+    readonly currentPeriodStartsAtMs: number | null;
+    readonly currentPeriodEndsAtMs: number | null;
+    readonly seatCount: number;
+    readonly assignedSeatCount: number;
+    readonly currentUserHasSyncSeat: boolean;
+    /** The organization is entitled to sync, but this identity has no assigned seat. */
+    readonly syncSeatUnavailable: boolean;
+    /** Native destination tier announced by the store but not effective yet. */
+    readonly pendingSeatCount: number | null;
+    /** A retained Stripe subscription can be cancelled, including during native ownership. */
+    readonly canCancelDirectly: boolean;
+    /** Store of record for the bound subscription, or null when none binds. */
+    readonly subscriptionSource: OrganizationBillingSubscriptionSource | null;
+    /** Sync is expected but currently off (lapsed/disabled) — prompt to fix. */
+    readonly needsAttention: boolean;
+}
+/**
+ * Resolve a billing snapshot into a display/gating view. Mirrors the server's
+ * `organizationCanSync` so the client shows the same "can this org sync?" answer
+ * the server enforces — the server stays the source of truth via the 402 gate;
+ * this is only for presentation.
+ */
+export declare function resolveOrganizationBillingView(billing: OrganizationBilling, nowMs: number): OrganizationBillingView;
+export {};

package/workflows/organizations/billing.js

@@ -0,0 +1,92 @@
+export async function loadOrganizationBilling(input) {
+    return input.apiClient.getOrganizationBilling(input.organizationId);
+}
+export async function loadOrganizationBillingHistory(input) {
+    return input.apiClient.getOrganizationBillingHistory(input.organizationId);
+}
+export async function loadOrganizationBillingManagementUrl(input) {
+    return input.apiClient.getOrganizationBillingManagementUrl(input.organizationId);
+}
+export async function startOrganizationTrial(input) {
+    return input.apiClient.startOrganizationTrial(input.organizationId);
+}
+export async function claimNativeOrganizationSubscription(input) {
+    const result = await input.apiClient.claimNativeOrganizationSubscription(input.organizationId, input.store);
+    if (!result.ok) {
+        result.report();
+        throw Object.assign(new Error(result.message), { status: result.status });
+    }
+    return result.data;
+}
+export function checkNativePurchaseEligibility(input) {
+    return input.apiClient.getOrganizationNativePurchaseEligibility(input.organizationId, input.store);
+}
+export async function loadStripeCheckoutOptions(input) {
+    const result = await input.apiClient.getStripeCheckoutOptions(input.organizationId, { reportErrors: false });
+    if (!result.ok) {
+        result.report();
+        throw Object.assign(new Error(result.message), {
+            ...(result.code === undefined ? {} : { code: result.code }),
+        });
+    }
+    return result.data;
+}
+export async function createStripeCheckout(input) {
+    return input.apiClient.createStripeCheckout(input.organizationId);
+}
+export async function createStripeCheckoutSession(input) {
+    return input.apiClient.createStripeCheckoutSession(input.organizationId, input.returnUrl);
+}
+export async function cancelStripeSubscription(input) {
+    return input.apiClient.cancelStripeSubscription(input.organizationId);
+}
+const DAY_MS = 24 * 60 * 60 * 1000;
+function parseIsoMs(value) {
+    if (value === null) {
+        return null;
+    }
+    const ms = Date.parse(value);
+    return Number.isNaN(ms) ? null : ms;
+}
+/**
+ * Resolve a billing snapshot into a display/gating view. Mirrors the server's
+ * `organizationCanSync` so the client shows the same "can this org sync?" answer
+ * the server enforces — the server stays the source of truth via the 402 gate;
+ * this is only for presentation.
+ */
+export function resolveOrganizationBillingView(billing, nowMs) {
+    const trialEndsAtMs = parseIsoMs(billing.trialEndsAt);
+    const currentPeriodStartsAtMs = parseIsoMs(billing.currentPeriodStartsAt);
+    const currentPeriodEndsAtMs = parseIsoMs(billing.currentPeriodEndsAt);
+    const isActive = billing.status === "active" &&
+        (currentPeriodEndsAtMs === null || currentPeriodEndsAtMs > nowMs);
+    const isTrialing = billing.status === "trialing" &&
+        trialEndsAtMs !== null &&
+        trialEndsAtMs > nowMs;
+    const organizationCanSync = isActive || isTrialing;
+    const canSync = organizationCanSync && billing.currentUserHasSyncSeat;
+    const isLocal = billing.status === "local";
+    const trialDaysRemaining = billing.status === "trialing" && trialEndsAtMs !== null
+        ? Math.max(0, Math.ceil((trialEndsAtMs - nowMs) / DAY_MS))
+        : null;
+    return {
+        status: billing.status,
+        canSync,
+        isLocal,
+        isTrialing,
+        isActive,
+        trialDaysRemaining,
+        trialEndsAtMs,
+        currentPeriodStartsAtMs,
+        currentPeriodEndsAtMs,
+        seatCount: billing.seatCount,
+        assignedSeatCount: billing.assignedSeatCount,
+        currentUserHasSyncSeat: billing.currentUserHasSyncSeat,
+        syncSeatUnavailable: organizationCanSync && !billing.currentUserHasSyncSeat,
+        pendingSeatCount: billing.pendingSeatCount,
+        subscriptionSource: billing.subscriptionSource,
+        canCancelDirectly: billing.canCancelDirectly,
+        needsAttention: !isLocal && !canSync,
+    };
+}
+//# sourceMappingURL=billing.js.map

package/workflows/organizations/billing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"billing.js","sourceRoot":"","sources":["billing.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  RequestResult,\n  RequestResultOptions,\n} from \"@tearleads/api-client\";\nimport type { NativeSubscriptionStore } from \"@tearleads/validators/billing\";\nimport type {\n  OrganizationBillingHistoryResponse,\n  OrganizationBillingManagementUrlResponse,\n  OrganizationBillingResponse,\n  OrganizationBillingStatus,\n  OrganizationBillingSubscriptionSource,\n  OrganizationNativePurchaseEligibilityResponse,\n  StripeCancelResponse,\n  StripeCheckoutIntentResponse,\n  StripeCheckoutOptionsResponse,\n  StripeCheckoutSessionResponse,\n} from \"@tearleads/validators/response\";\n\n/** Per-organization sync-billing snapshot (the server wire shape). */\nexport type OrganizationBilling = OrganizationBillingResponse;\n\n/** Per-organization billing lifecycle history (the server wire shape). */\nexport type OrganizationBillingHistory = OrganizationBillingHistoryResponse;\n\n/** One lifecycle event in an organization's billing history, newest first. */\nexport type OrganizationBillingHistoryEntry =\n  OrganizationBillingHistoryResponse[\"entries\"][number];\n\n/** Per-organization subscription-management URL (the server wire shape). */\nexport type OrganizationBillingManagementUrl =\n  OrganizationBillingManagementUrlResponse;\n\n/** Server-backed, point-in-time policy decision made before native checkout. */\nexport type OrganizationNativePurchaseEligibility =\n  OrganizationNativePurchaseEligibilityResponse;\n\n/** Purchasable sync options for the direct Stripe checkout (the wire shape). */\nexport type StripeCheckoutOptions = StripeCheckoutOptionsResponse;\n\n/** What the Payment Element needs to confirm a purchase (the wire shape). */\nexport type StripeCheckoutIntent = StripeCheckoutIntentResponse;\n\n/** The billing methods these workflows need from the api client. */\ninterface OrganizationBillingApi {\n  readonly getOrganizationBilling: (\n    organizationId: string,\n  ) => Promise<OrganizationBillingResponse | null>;\n  readonly getOrganizationBillingHistory: (\n    organizationId: string,\n  ) => Promise<OrganizationBillingHistoryResponse | null>;\n  readonly getOrganizationBillingManagementUrl: (\n    organizationId: string,\n  ) => Promise<OrganizationBillingManagementUrlResponse | null>;\n  readonly startOrganizationTrial: (\n    organizationId: string,\n  ) => Promise<OrganizationBillingResponse | null>;\n  readonly claimNativeOrganizationSubscription: (\n    organizationId: string,\n    store: NativeSubscriptionStore,\n  ) => Promise<RequestResult<OrganizationBillingResponse>>;\n  readonly getOrganizationNativePurchaseEligibility: (\n    organizationId: string,\n    store: NativeSubscriptionStore,\n  ) => Promise<OrganizationNativePurchaseEligibilityResponse | null>;\n  readonly getStripeCheckoutOptions: (\n    organizationId: string,\n    options?: RequestResultOptions,\n  ) => Promise<RequestResult<StripeCheckoutOptionsResponse>>;\n  readonly createStripeCheckout: (\n    organizationId: string,\n  ) => Promise<StripeCheckoutIntentResponse | null>;\n  readonly createStripeCheckoutSession: (\n    organizationId: string,\n    returnUrl: string,\n  ) => Promise<StripeCheckoutSessionResponse | null>;\n  readonly cancelStripeSubscription: (\n    organizationId: string,\n  ) => Promise<StripeCancelResponse | null>;\n}\n\nexport async function loadOrganizationBilling(input: {\n  readonly apiClient: Pick<OrganizationBillingApi, \"getOrganizationBilling\">;\n  readonly organizationId: string;\n}): Promise<OrganizationBilling | null> {\n  return input.apiClient.getOrganizationBilling(input.organizationId);\n}\n\nexport async function loadOrganizationBillingHistory(input: {\n  readonly apiClient: Pick<\n    OrganizationBillingApi,\n    \"getOrganizationBillingHistory\"\n  >;\n  readonly organizationId: string;\n}): Promise<OrganizationBillingHistory | null> {\n  return input.apiClient.getOrganizationBillingHistory(input.organizationId);\n}\n\nexport async function loadOrganizationBillingManagementUrl(input: {\n  readonly apiClient: Pick<\n    OrganizationBillingApi,\n    \"getOrganizationBillingManagementUrl\"\n  >;\n  readonly organizationId: string;\n}): Promise<OrganizationBillingManagementUrl | null> {\n  return input.apiClient.getOrganizationBillingManagementUrl(\n    input.organizationId,\n  );\n}\n\nexport async function startOrganizationTrial(input: {\n  readonly apiClient: Pick<OrganizationBillingApi, \"startOrganizationTrial\">;\n  readonly organizationId: string;\n}): Promise<OrganizationBilling | null> {\n  return input.apiClient.startOrganizationTrial(input.organizationId);\n}\n\nexport async function claimNativeOrganizationSubscription(input: {\n  readonly apiClient: Pick<\n    OrganizationBillingApi,\n    \"claimNativeOrganizationSubscription\"\n  >;\n  readonly organizationId: string;\n  readonly store: NativeSubscriptionStore;\n}): Promise<OrganizationBilling | null> {\n  const result = await input.apiClient.claimNativeOrganizationSubscription(\n    input.organizationId,\n    input.store,\n  );\n  if (!result.ok) {\n    result.report();\n    throw Object.assign(new Error(result.message), { status: result.status });\n  }\n  return result.data;\n}\n\nexport function checkNativePurchaseEligibility(input: {\n  readonly apiClient: Pick<\n    OrganizationBillingApi,\n    \"getOrganizationNativePurchaseEligibility\"\n  >;\n  readonly organizationId: string;\n  readonly store: NativeSubscriptionStore;\n}): Promise<OrganizationNativePurchaseEligibility | null> {\n  return input.apiClient.getOrganizationNativePurchaseEligibility(\n    input.organizationId,\n    input.store,\n  );\n}\n\nexport async function loadStripeCheckoutOptions(input: {\n  readonly apiClient: Pick<OrganizationBillingApi, \"getStripeCheckoutOptions\">;\n  readonly organizationId: string;\n}): Promise<StripeCheckoutOptions | null> {\n  const result = await input.apiClient.getStripeCheckoutOptions(\n    input.organizationId,\n    { reportErrors: false },\n  );\n  if (!result.ok) {\n    result.report();\n    throw Object.assign(new Error(result.message), {\n      ...(result.code === undefined ? {} : { code: result.code }),\n    });\n  }\n  return result.data;\n}\n\nexport async function createStripeCheckout(input: {\n  readonly apiClient: Pick<OrganizationBillingApi, \"createStripeCheckout\">;\n  readonly organizationId: string;\n}): Promise<StripeCheckoutIntent | null> {\n  return input.apiClient.createStripeCheckout(input.organizationId);\n}\n\nexport async function createStripeCheckoutSession(input: {\n  readonly apiClient: Pick<\n    OrganizationBillingApi,\n    \"createStripeCheckoutSession\"\n  >;\n  readonly organizationId: string;\n  readonly returnUrl: string;\n}): Promise<StripeCheckoutSessionResponse | null> {\n  return input.apiClient.createStripeCheckoutSession(\n    input.organizationId,\n    input.returnUrl,\n  );\n}\n\nexport async function cancelStripeSubscription(input: {\n  readonly apiClient: Pick<OrganizationBillingApi, \"cancelStripeSubscription\">;\n  readonly organizationId: string;\n}): Promise<StripeCancelResponse | null> {\n  return input.apiClient.cancelStripeSubscription(input.organizationId);\n}\n\nconst DAY_MS = 24 * 60 * 60 * 1000;\n\n/** Client-side projection of a billing snapshot for display and gating. */\nexport interface OrganizationBillingView {\n  readonly status: OrganizationBillingStatus;\n  /** Whether the org may sync right now (mirrors the server's organizationCanSync). */\n  readonly canSync: boolean;\n  /** Free, on-device only (status \"local\"). */\n  readonly isLocal: boolean;\n  /** Actively in a non-expired free trial. */\n  readonly isTrialing: boolean;\n  /** Active paid subscription within its current period. */\n  readonly isActive: boolean;\n  /** Whole days left in the trial (ceil, floored at 0); null unless trialing. */\n  readonly trialDaysRemaining: number | null;\n  readonly trialEndsAtMs: number | null;\n  readonly currentPeriodStartsAtMs: number | null;\n  readonly currentPeriodEndsAtMs: number | null;\n  readonly seatCount: number;\n  readonly assignedSeatCount: number;\n  readonly currentUserHasSyncSeat: boolean;\n  /** The organization is entitled to sync, but this identity has no assigned seat. */\n  readonly syncSeatUnavailable: boolean;\n  /** Native destination tier announced by the store but not effective yet. */\n  readonly pendingSeatCount: number | null;\n  /** A retained Stripe subscription can be cancelled, including during native ownership. */\n  readonly canCancelDirectly: boolean;\n  /** Store of record for the bound subscription, or null when none binds. */\n  readonly subscriptionSource: OrganizationBillingSubscriptionSource | null;\n  /** Sync is expected but currently off (lapsed/disabled) — prompt to fix. */\n  readonly needsAttention: boolean;\n}\n\nfunction parseIsoMs(value: string | null): number | null {\n  if (value === null) {\n    return null;\n  }\n  const ms = Date.parse(value);\n  return Number.isNaN(ms) ? null : ms;\n}\n\n/**\n * Resolve a billing snapshot into a display/gating view. Mirrors the server's\n * `organizationCanSync` so the client shows the same \"can this org sync?\" answer\n * the server enforces — the server stays the source of truth via the 402 gate;\n * this is only for presentation.\n */\nexport function resolveOrganizationBillingView(\n  billing: OrganizationBilling,\n  nowMs: number,\n): OrganizationBillingView {\n  const trialEndsAtMs = parseIsoMs(billing.trialEndsAt);\n  const currentPeriodStartsAtMs = parseIsoMs(billing.currentPeriodStartsAt);\n  const currentPeriodEndsAtMs = parseIsoMs(billing.currentPeriodEndsAt);\n\n  const isActive =\n    billing.status === \"active\" &&\n    (currentPeriodEndsAtMs === null || currentPeriodEndsAtMs > nowMs);\n  const isTrialing =\n    billing.status === \"trialing\" &&\n    trialEndsAtMs !== null &&\n    trialEndsAtMs > nowMs;\n  const organizationCanSync = isActive || isTrialing;\n  const canSync = organizationCanSync && billing.currentUserHasSyncSeat;\n  const isLocal = billing.status === \"local\";\n\n  const trialDaysRemaining =\n    billing.status === \"trialing\" && trialEndsAtMs !== null\n      ? Math.max(0, Math.ceil((trialEndsAtMs - nowMs) / DAY_MS))\n      : null;\n\n  return {\n    status: billing.status,\n    canSync,\n    isLocal,\n    isTrialing,\n    isActive,\n    trialDaysRemaining,\n    trialEndsAtMs,\n    currentPeriodStartsAtMs,\n    currentPeriodEndsAtMs,\n    seatCount: billing.seatCount,\n    assignedSeatCount: billing.assignedSeatCount,\n    currentUserHasSyncSeat: billing.currentUserHasSyncSeat,\n    syncSeatUnavailable: organizationCanSync && !billing.currentUserHasSyncSeat,\n    pendingSeatCount: billing.pendingSeatCount,\n    subscriptionSource: billing.subscriptionSource,\n    canCancelDirectly: billing.canCancelDirectly,\n    needsAttention: !isLocal && !canSync,\n  };\n}\n"]}

package/workflows/organizations/containerGrantRevocation.d.ts

@@ -0,0 +1,31 @@
+import type { ContainerDirectGrant } from "../../internal/crypto/index.js";
+import type { ContainerMutationResponse } from "../../internal/validators/response/index.js";
+import type { ReferencedPrincipalPolicyWarmer } from "../../data/keyingProjectionVerification.js";
+import type { SecurityIncidentReporter } from "../../data/securityIncidents.js";
+import type { ExecSql } from "../../data/sqlite/sqlSchema.js";
+import type { TrustedUserIdentityResolver } from "../../data/trustedUserIdentity/index.js";
+import { revokeRemoteContainer } from "../containers/index.js";
+type OrganizationContainerGrantSubject = Pick<ContainerDirectGrant, "subjectId" | "subjectType">;
+type OrganizationContainerGrantRevocationApi = Parameters<typeof revokeRemoteContainer>[0]["apiClient"];
+export declare function revokeOrganizationContainerGrant(input: {
+    readonly stillCurrent: () => boolean;
+    readonly reportSecurityIncident: SecurityIncidentReporter;
+    readonly apiClient: OrganizationContainerGrantRevocationApi;
+    readonly containerId: string;
+    readonly encapsulationKeyPair: {
+        readonly publicKey: Uint8Array;
+        readonly secretKey: Uint8Array;
+    };
+    readonly execSql: ExecSql;
+    readonly organizationId: string;
+    readonly resolveTrustedUserIdentity: TrustedUserIdentityResolver;
+    readonly revokedSubject: OrganizationContainerGrantSubject;
+    readonly signerUserId: string;
+    readonly signingFingerprint: string;
+    readonly signingKeyPair: {
+        readonly signingPrivateKey: Uint8Array;
+        readonly signingPublicKey: Uint8Array;
+    };
+    readonly warmReferencedPrincipalPolicies?: ReferencedPrincipalPolicyWarmer | undefined;
+}): Promise<ContainerMutationResponse>;
+export {};