@tearleads/client-sdk 0.0.0-stage → 0.1.11

package/workflows/containers/writeRefusal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writeRefusal.js","sourceRoot":"","sources":["writeRefusal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,MAAM,2CAA2C,CAAC;AACvF,OAAO,EACL,mCAAmC,EACnC,+BAA+B,GAChC,MAAM,kDAAkD,CAAC;AAkB1D,SAAS,UAAU,CAAC,KAAc,EAAE,IAAY;IAC9C,OAAO,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC;AACvD,CAAC;AAED,mFAAmF;AACnF,SAAS,iBAAiB,CAAC,KAAc;IACvC,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,CAAC;IAC9D,OAAO,OAAO,WAAW,KAAK,QAAQ,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC;QAC9D,CAAC,CAAC,WAAW;QACb,CAAC,CAAC,IAAI,CAAC;AACX,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,6BAA6B,CAC3C,KAAc;IAEd,0EAA0E;IAC1E,IACE,KAAK,YAAY,mCAAmC;QACpD,UAAU,CAAC,KAAK,EAAE,qCAAqC,CAAC,EACxD,CAAC;QACD,MAAM,WAAW,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;QAC7C,OAAO,WAAW,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,qBAAqB,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAC3E,CAAC;IACD,IACE,KAAK,YAAY,+BAA+B;QAChD,UAAU,CAAC,KAAK,EAAE,iCAAiC,CAAC,EACpD,CAAC;QACD,MAAM,WAAW,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;QAC7C,OAAO,WAAW,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACvE,CAAC;IACD,IACE,KAAK,YAAY,0BAA0B;QAC3C,UAAU,CAAC,KAAK,EAAE,4BAA4B,CAAC,EAC/C,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC;IAClC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC","sourcesContent":["import { ContainerAuthorAccessError } from \"../../data/containers/shared/authorAccess\";\nimport {\n  ContainerKekRepairInaccessibleError,\n  ContainerKekRepairRequiredError,\n} from \"../../data/documents/shared/containerKekCurrency\";\n\n/**\n * Why the SDK refused to author a container-scoped write before anything was\n * encrypted or sent:\n *\n * - `repair-required`: the path cites a retired ancestor key epoch. Retry; this\n *   writer's next document sync pass, or a peer, re-keys it parent-first.\n * - `repair-inaccessible`: the same, but the stale container is one this writer\n *   can neither re-key nor be given the key for. Queued changes stay queued and\n *   sync once a member with access to `containerId` repairs it.\n * - `unauthorized`: the signed path grants this signer too little access.\n */\nexport type ContainerWriteRefusal =\n  | { readonly kind: \"repair-required\"; readonly containerId: string }\n  | { readonly kind: \"repair-inaccessible\"; readonly containerId: string }\n  | { readonly kind: \"unauthorized\" };\n\nfunction namedError(error: unknown, name: string): error is Error {\n  return error instanceof Error && error.name === name;\n}\n\n/** A same-named error from elsewhere may lack the field; never say \"undefined\". */\nfunction repairContainerId(error: unknown): string | null {\n  const containerId = Reflect.get(Object(error), \"containerId\");\n  return typeof containerId === \"string\" && containerId.length > 0\n    ? containerId\n    : null;\n}\n\n/** Null for anything else, including keying-verification failures. */\nexport function classifyContainerWriteRefusal(\n  error: unknown,\n): ContainerWriteRefusal | null {\n  // Match by name as well: a host bundling the SDK twice holds two classes.\n  if (\n    error instanceof ContainerKekRepairInaccessibleError ||\n    namedError(error, \"ContainerKekRepairInaccessibleError\")\n  ) {\n    const containerId = repairContainerId(error);\n    return containerId ? { kind: \"repair-inaccessible\", containerId } : null;\n  }\n  if (\n    error instanceof ContainerKekRepairRequiredError ||\n    namedError(error, \"ContainerKekRepairRequiredError\")\n  ) {\n    const containerId = repairContainerId(error);\n    return containerId ? { kind: \"repair-required\", containerId } : null;\n  }\n  if (\n    error instanceof ContainerAuthorAccessError ||\n    namedError(error, \"ContainerAuthorAccessError\")\n  ) {\n    return { kind: \"unauthorized\" };\n  }\n  return null;\n}\n"]}

package/workflows/documents/attachmentPersistence.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Attachment-slot persistence for stored documents.
+ *
+ * These are the workflow-level seams the document store writes attachment rows
+ * through: the pending-upload queue, the local blob projection, and the detach
+ * marker that keeps an unlinked slot's row alive for the next sync.
+ */
+import type { DocumentsPersistence, LocalAttachmentRecord, PendingAttachmentRecord } from "../../data/persistence/documents/documentsPersistence.js";
+import type { ExecSql } from "../../data/sqlite/sqlSchema.js";
+export declare function saveLocalDocumentAttachments(input: {
+    attachments: ReadonlyArray<LocalAttachmentRecord>;
+    execSql: ExecSql;
+    persistence: DocumentsPersistence;
+}): Promise<void>;
+export declare function deleteLocalDocumentAttachment(input: {
+    execSql: ExecSql;
+    localId: string;
+    persistence: DocumentsPersistence;
+    slotId: string;
+    storageKey: string;
+}): Promise<void>;
+/**
+ * Mark a slot's local blob row detached without dropping it.
+ *
+ * Unlinking an attachment from a synced document cannot delete the row: it is
+ * also the marker `syncDetachedAttachments` needs to detach the remote binding
+ * on the next sync (and to survive a restart before that sync runs). Marking it
+ * keeps that marker while taking the slot out of the local blob read models
+ * right away, so the blob browser stops listing a reference the document no
+ * longer has.
+ */
+export declare function markLocalDocumentAttachmentDetached(input: {
+    execSql: ExecSql;
+    localId: string;
+    persistence: DocumentsPersistence;
+    slotId: string;
+    storageKey: string;
+}): Promise<void>;
+export declare function savePendingDocumentAttachment(input: {
+    attachment: PendingAttachmentRecord;
+    execSql: ExecSql;
+    persistence: DocumentsPersistence;
+}): Promise<void>;
+export declare function deletePendingDocumentAttachment(input: {
+    execSql: ExecSql;
+    localId: string;
+    persistence: DocumentsPersistence;
+    slotId: string;
+    storageKey: string;
+}): Promise<void>;
+export declare function saveHydratedDocumentAttachment(input: {
+    execSql: ExecSql;
+    persistence: DocumentsPersistence;
+    attachment: LocalAttachmentRecord;
+    expectedStorageKey: string | null;
+    expectedSnapshotEndVersion: string | null;
+    stillCurrent: () => boolean;
+}): Promise<boolean>;

package/workflows/documents/attachmentPersistence.js

@@ -0,0 +1,31 @@
+export async function saveLocalDocumentAttachments(input) {
+    for (const attachment of input.attachments) {
+        await input.persistence.saveLocalAttachment(input.execSql, attachment);
+    }
+}
+export async function deleteLocalDocumentAttachment(input) {
+    await input.persistence.deleteLocalAttachment(input.execSql, input.localId, input.slotId, input.storageKey);
+}
+/**
+ * Mark a slot's local blob row detached without dropping it.
+ *
+ * Unlinking an attachment from a synced document cannot delete the row: it is
+ * also the marker `syncDetachedAttachments` needs to detach the remote binding
+ * on the next sync (and to survive a restart before that sync runs). Marking it
+ * keeps that marker while taking the slot out of the local blob read models
+ * right away, so the blob browser stops listing a reference the document no
+ * longer has.
+ */
+export async function markLocalDocumentAttachmentDetached(input) {
+    await input.persistence.markLocalAttachmentDetached(input.execSql, input.localId, input.slotId, input.storageKey);
+}
+export async function savePendingDocumentAttachment(input) {
+    await input.persistence.savePendingAttachment(input.execSql, input.attachment);
+}
+export async function deletePendingDocumentAttachment(input) {
+    await input.persistence.deletePendingAttachment(input.execSql, input.localId, input.slotId, input.storageKey);
+}
+export function saveHydratedDocumentAttachment(input) {
+    return input.persistence.saveHydratedAttachment(input.execSql, input);
+}
+//# sourceMappingURL=attachmentPersistence.js.map

package/workflows/documents/attachmentPersistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachmentPersistence.js","sourceRoot":"","sources":["attachmentPersistence.ts"],"names":[],"mappings":"AAcA,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAAC,KAIlD;IACC,KAAK,MAAM,UAAU,IAAI,KAAK,CAAC,WAAW,EAAE,CAAC;QAC3C,MAAM,KAAK,CAAC,WAAW,CAAC,mBAAmB,CAAC,KAAK,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IACzE,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,6BAA6B,CAAC,KAMnD;IACC,MAAM,KAAK,CAAC,WAAW,CAAC,qBAAqB,CAC3C,KAAK,CAAC,OAAO,EACb,KAAK,CAAC,OAAO,EACb,KAAK,CAAC,MAAM,EACZ,KAAK,CAAC,UAAU,CACjB,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,mCAAmC,CAAC,KAMzD;IACC,MAAM,KAAK,CAAC,WAAW,CAAC,2BAA2B,CACjD,KAAK,CAAC,OAAO,EACb,KAAK,CAAC,OAAO,EACb,KAAK,CAAC,MAAM,EACZ,KAAK,CAAC,UAAU,CACjB,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,6BAA6B,CAAC,KAInD;IACC,MAAM,KAAK,CAAC,WAAW,CAAC,qBAAqB,CAC3C,KAAK,CAAC,OAAO,EACb,KAAK,CAAC,UAAU,CACjB,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,+BAA+B,CAAC,KAMrD;IACC,MAAM,KAAK,CAAC,WAAW,CAAC,uBAAuB,CAC7C,KAAK,CAAC,OAAO,EACb,KAAK,CAAC,OAAO,EACb,KAAK,CAAC,MAAM,EACZ,KAAK,CAAC,UAAU,CACjB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,8BAA8B,CAAC,KAO9C;IACC,OAAO,KAAK,CAAC,WAAW,CAAC,sBAAsB,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;AACxE,CAAC","sourcesContent":["/**\n * Attachment-slot persistence for stored documents.\n *\n * These are the workflow-level seams the document store writes attachment rows\n * through: the pending-upload queue, the local blob projection, and the detach\n * marker that keeps an unlinked slot's row alive for the next sync.\n */\nimport type {\n  DocumentsPersistence,\n  LocalAttachmentRecord,\n  PendingAttachmentRecord,\n} from \"../../data/persistence/documents/documentsPersistence\";\nimport type { ExecSql } from \"../../data/sqlite/sqlSchema\";\n\nexport async function saveLocalDocumentAttachments(input: {\n  attachments: ReadonlyArray<LocalAttachmentRecord>;\n  execSql: ExecSql;\n  persistence: DocumentsPersistence;\n}): Promise<void> {\n  for (const attachment of input.attachments) {\n    await input.persistence.saveLocalAttachment(input.execSql, attachment);\n  }\n}\n\nexport async function deleteLocalDocumentAttachment(input: {\n  execSql: ExecSql;\n  localId: string;\n  persistence: DocumentsPersistence;\n  slotId: string;\n  storageKey: string;\n}): Promise<void> {\n  await input.persistence.deleteLocalAttachment(\n    input.execSql,\n    input.localId,\n    input.slotId,\n    input.storageKey,\n  );\n}\n\n/**\n * Mark a slot's local blob row detached without dropping it.\n *\n * Unlinking an attachment from a synced document cannot delete the row: it is\n * also the marker `syncDetachedAttachments` needs to detach the remote binding\n * on the next sync (and to survive a restart before that sync runs). Marking it\n * keeps that marker while taking the slot out of the local blob read models\n * right away, so the blob browser stops listing a reference the document no\n * longer has.\n */\nexport async function markLocalDocumentAttachmentDetached(input: {\n  execSql: ExecSql;\n  localId: string;\n  persistence: DocumentsPersistence;\n  slotId: string;\n  storageKey: string;\n}): Promise<void> {\n  await input.persistence.markLocalAttachmentDetached(\n    input.execSql,\n    input.localId,\n    input.slotId,\n    input.storageKey,\n  );\n}\n\nexport async function savePendingDocumentAttachment(input: {\n  attachment: PendingAttachmentRecord;\n  execSql: ExecSql;\n  persistence: DocumentsPersistence;\n}): Promise<void> {\n  await input.persistence.savePendingAttachment(\n    input.execSql,\n    input.attachment,\n  );\n}\n\nexport async function deletePendingDocumentAttachment(input: {\n  execSql: ExecSql;\n  localId: string;\n  persistence: DocumentsPersistence;\n  slotId: string;\n  storageKey: string;\n}): Promise<void> {\n  await input.persistence.deletePendingAttachment(\n    input.execSql,\n    input.localId,\n    input.slotId,\n    input.storageKey,\n  );\n}\n\nexport function saveHydratedDocumentAttachment(input: {\n  execSql: ExecSql;\n  persistence: DocumentsPersistence;\n  attachment: LocalAttachmentRecord;\n  expectedStorageKey: string | null;\n  expectedSnapshotEndVersion: string | null;\n  stillCurrent: () => boolean;\n}): Promise<boolean> {\n  return input.persistence.saveHydratedAttachment(input.execSql, input);\n}\n"]}

package/workflows/documents/author.d.ts

@@ -0,0 +1,15 @@
+import type { DocumentCreateAuthor } from "../../data/documents/shared/types.js";
+interface DocumentAuthorRuntime {
+    auth: {
+        organizationId?: string | null;
+        userId?: string | null;
+    };
+    crypto: {
+        signingFingerprint?: string | null;
+        signingKeyPair?: {
+            signingPrivateKey: Uint8Array;
+        } | null | undefined;
+    };
+}
+export declare function resolveDocumentCreateAuthor(runtime: DocumentAuthorRuntime): DocumentCreateAuthor | null;
+export {};

package/workflows/documents/author.js

@@ -0,0 +1,17 @@
+import { createDocumentSignerDeviceId } from "../../data/documents/documentConstants.js";
+export function resolveDocumentCreateAuthor(runtime) {
+    if (!runtime.auth.organizationId ||
+        !runtime.crypto.signingFingerprint ||
+        !runtime.crypto.signingKeyPair ||
+        !runtime.auth.userId) {
+        return null;
+    }
+    return {
+        organizationId: runtime.auth.organizationId,
+        signerDeviceId: createDocumentSignerDeviceId(runtime.crypto.signingFingerprint),
+        signerKeyFingerprint: runtime.crypto.signingFingerprint,
+        signerPrivateKey: runtime.crypto.signingKeyPair.signingPrivateKey,
+        signerUserId: runtime.auth.userId,
+    };
+}
+//# sourceMappingURL=author.js.map

package/workflows/documents/author.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"author.js","sourceRoot":"","sources":["author.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,4BAA4B,EAAE,MAAM,wCAAwC,CAAC;AAmBtF,MAAM,UAAU,2BAA2B,CACzC,OAA8B;IAE9B,IACE,CAAC,OAAO,CAAC,IAAI,CAAC,cAAc;QAC5B,CAAC,OAAO,CAAC,MAAM,CAAC,kBAAkB;QAClC,CAAC,OAAO,CAAC,MAAM,CAAC,cAAc;QAC9B,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,EACpB,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO;QACL,cAAc,EAAE,OAAO,CAAC,IAAI,CAAC,cAAc;QAC3C,cAAc,EAAE,4BAA4B,CAC1C,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAClC;QACD,oBAAoB,EAAE,OAAO,CAAC,MAAM,CAAC,kBAAkB;QACvD,gBAAgB,EAAE,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,iBAAiB;QACjE,YAAY,EAAE,OAAO,CAAC,IAAI,CAAC,MAAM;KAClC,CAAC;AACJ,CAAC","sourcesContent":["import { createDocumentSignerDeviceId } from \"../../data/documents/documentConstants\";\nimport type { DocumentCreateAuthor } from \"../../data/documents/shared/types\";\n\ninterface DocumentAuthorRuntime {\n  auth: {\n    organizationId?: string | null;\n    userId?: string | null;\n  };\n  crypto: {\n    signingFingerprint?: string | null;\n    signingKeyPair?:\n      | {\n          signingPrivateKey: Uint8Array;\n        }\n      | null\n      | undefined;\n  };\n}\n\nexport function resolveDocumentCreateAuthor(\n  runtime: DocumentAuthorRuntime,\n): DocumentCreateAuthor | null {\n  if (\n    !runtime.auth.organizationId ||\n    !runtime.crypto.signingFingerprint ||\n    !runtime.crypto.signingKeyPair ||\n    !runtime.auth.userId\n  ) {\n    return null;\n  }\n\n  return {\n    organizationId: runtime.auth.organizationId,\n    signerDeviceId: createDocumentSignerDeviceId(\n      runtime.crypto.signingFingerprint,\n    ),\n    signerKeyFingerprint: runtime.crypto.signingFingerprint,\n    signerPrivateKey: runtime.crypto.signingKeyPair.signingPrivateKey,\n    signerUserId: runtime.auth.userId,\n  };\n}\n"]}

package/workflows/documents/authorAccessFailure.js

@@ -0,0 +1,14 @@
+import { ContainerAuthorAccessError } from "../../data/containers/shared/authorAccess.js";
+/** A verified read-only path is a local permission refusal, not tampered proof. */
+export async function recordDocumentAuthorAccessFailure(build, onFailure) {
+    try {
+        return await build();
+    }
+    catch (error) {
+        if (!(error instanceof ContainerAuthorAccessError))
+            throw error;
+        await onFailure?.({ message: error.message, status: error.status });
+        return null;
+    }
+}
+//# sourceMappingURL=authorAccessFailure.js.map

package/workflows/documents/authorAccessFailure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorAccessFailure.js","sourceRoot":"","sources":["authorAccessFailure.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,MAAM,2CAA2C,CAAC;AAGvF,mFAAmF;AACnF,MAAM,CAAC,KAAK,UAAU,iCAAiC,CACrD,KAAuB,EACvB,SAA2D;IAE3D,IAAI,CAAC;QACH,OAAO,MAAM,KAAK,EAAE,CAAC;IACvB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,CAAC,KAAK,YAAY,0BAA0B,CAAC;YAAE,MAAM,KAAK,CAAC;QAChE,MAAM,SAAS,EAAE,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QACpE,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC","sourcesContent":["import { ContainerAuthorAccessError } from \"../../data/containers/shared/authorAccess\";\nimport type { DocumentCreateTerminalFailureHandler } from \"./createProjectionFetch\";\n\n/** A verified read-only path is a local permission refusal, not tampered proof. */\nexport async function recordDocumentAuthorAccessFailure<T>(\n  build: () => Promise<T>,\n  onFailure: DocumentCreateTerminalFailureHandler | undefined,\n): Promise<T | null> {\n  try {\n    return await build();\n  } catch (error) {\n    if (!(error instanceof ContainerAuthorAccessError)) throw error;\n    await onFailure?.({ message: error.message, status: error.status });\n    return null;\n  }\n}\n"]}

package/workflows/documents/blobMutationLock.d.ts

@@ -0,0 +1,8 @@
+import { type ExecSql } from "../../data/sqlite/sqlSchema.js";
+/**
+ * Serialize byte-store mutations that address the same document blob key.
+ *
+ * Lock order is blob key, then the connection-wide SQL mutation lock. Callers
+ * must not acquire this lock from inside `runSerializedSqlMutation`.
+ */
+export declare function runSerializedDocumentBlobMutation<T>(execSql: ExecSql, storageKey: string, operation: () => Promise<T> | T): Promise<T>;

package/workflows/documents/blobMutationLock.js

@@ -0,0 +1,35 @@
+import { resolveCanonicalExecSql, } from "../../data/sqlite/sqlSchema.js";
+const mutationQueuesByExecSql = new WeakMap();
+/**
+ * Serialize byte-store mutations that address the same document blob key.
+ *
+ * Lock order is blob key, then the connection-wide SQL mutation lock. Callers
+ * must not acquire this lock from inside `runSerializedSqlMutation`.
+ */
+export async function runSerializedDocumentBlobMutation(execSql, storageKey, operation) {
+    const canonicalExecSql = resolveCanonicalExecSql(execSql);
+    const queues = mutationQueuesByExecSql.get(canonicalExecSql) ?? new Map();
+    mutationQueuesByExecSql.set(canonicalExecSql, queues);
+    const previous = queues.get(storageKey) ?? Promise.resolve();
+    let releaseCurrent = () => undefined;
+    const current = new Promise((resolve) => {
+        releaseCurrent = resolve;
+    });
+    const waitForPrevious = previous.catch(() => undefined);
+    const queuedCurrent = waitForPrevious.then(() => current);
+    queues.set(storageKey, queuedCurrent);
+    await waitForPrevious;
+    try {
+        return await operation();
+    }
+    finally {
+        releaseCurrent();
+        if (queues.get(storageKey) === queuedCurrent) {
+            queues.delete(storageKey);
+            if (queues.size === 0) {
+                mutationQueuesByExecSql.delete(canonicalExecSql);
+            }
+        }
+    }
+}
+//# sourceMappingURL=blobMutationLock.js.map

package/workflows/documents/blobMutationLock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blobMutationLock.js","sourceRoot":"","sources":["blobMutationLock.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,uBAAuB,GACxB,MAAM,6BAA6B,CAAC;AAErC,MAAM,uBAAuB,GAAG,IAAI,OAAO,EAGxC,CAAC;AAEJ;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,iCAAiC,CACrD,OAAgB,EAChB,UAAkB,EAClB,SAA+B;IAE/B,MAAM,gBAAgB,GAAG,uBAAuB,CAAC,OAAO,CAAC,CAAC;IAC1D,MAAM,MAAM,GAAG,uBAAuB,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,IAAI,GAAG,EAAE,CAAC;IAC1E,uBAAuB,CAAC,GAAG,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;IAEtD,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAC7D,IAAI,cAAc,GAAe,GAAG,EAAE,CAAC,SAAS,CAAC;IACjD,MAAM,OAAO,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QAC5C,cAAc,GAAG,OAAO,CAAC;IAC3B,CAAC,CAAC,CAAC;IACH,MAAM,eAAe,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACxD,MAAM,aAAa,GAAG,eAAe,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC;IAC1D,MAAM,CAAC,GAAG,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;IACtC,MAAM,eAAe,CAAC;IAEtB,IAAI,CAAC;QACH,OAAO,MAAM,SAAS,EAAE,CAAC;IAC3B,CAAC;YAAS,CAAC;QACT,cAAc,EAAE,CAAC;QACjB,IAAI,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,aAAa,EAAE,CAAC;YAC7C,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;YAC1B,IAAI,MAAM,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;gBACtB,uBAAuB,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;YACnD,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC","sourcesContent":["import {\n  type ExecSql,\n  resolveCanonicalExecSql,\n} from \"../../data/sqlite/sqlSchema\";\n\nconst mutationQueuesByExecSql = new WeakMap<\n  ExecSql,\n  Map<string, Promise<void>>\n>();\n\n/**\n * Serialize byte-store mutations that address the same document blob key.\n *\n * Lock order is blob key, then the connection-wide SQL mutation lock. Callers\n * must not acquire this lock from inside `runSerializedSqlMutation`.\n */\nexport async function runSerializedDocumentBlobMutation<T>(\n  execSql: ExecSql,\n  storageKey: string,\n  operation: () => Promise<T> | T,\n): Promise<T> {\n  const canonicalExecSql = resolveCanonicalExecSql(execSql);\n  const queues = mutationQueuesByExecSql.get(canonicalExecSql) ?? new Map();\n  mutationQueuesByExecSql.set(canonicalExecSql, queues);\n\n  const previous = queues.get(storageKey) ?? Promise.resolve();\n  let releaseCurrent: () => void = () => undefined;\n  const current = new Promise<void>((resolve) => {\n    releaseCurrent = resolve;\n  });\n  const waitForPrevious = previous.catch(() => undefined);\n  const queuedCurrent = waitForPrevious.then(() => current);\n  queues.set(storageKey, queuedCurrent);\n  await waitForPrevious;\n\n  try {\n    return await operation();\n  } finally {\n    releaseCurrent();\n    if (queues.get(storageKey) === queuedCurrent) {\n      queues.delete(storageKey);\n      if (queues.size === 0) {\n        mutationQueuesByExecSql.delete(canonicalExecSql);\n      }\n    }\n  }\n}\n"]}

package/workflows/documents/create.d.ts

@@ -0,0 +1,69 @@
+import { type ContainerWriterProjectionResponse, type DocumentCreateResponse, type DocumentWriterProjectionResponse } from "../../internal/validators/response/index.js";
+import type { CreateRemoteDocumentResult, DocumentCreateApi, DocumentCreateAuthor, MaterializedDocumentCreatePlan, ProjectionVerificationOptions } from "../../data/documents/shared/types.js";
+import type { ProjectionUserKeyResolver, ReferencedPrincipalPolicyWarmer } from "../../data/keyingProjectionVerification.js";
+import type { ExecSql } from "../../data/sqlite/sqlSchema.js";
+import type { DocumentCreateTerminalFailureHandler } from "./createProjectionFetch.js";
+export declare function buildMaterializedDocumentCreatePlan(input: {
+    author: DocumentCreateAuthor;
+    containerProjection: ContainerWriterProjectionResponse;
+    contentKey?: Uint8Array | undefined;
+    contentKeyEpoch?: number | undefined;
+    documentId?: string | undefined;
+    eventId?: string | undefined;
+    execSql?: ExecSql | undefined;
+    knownContainerKeks?: ReadonlyMap<string, Uint8Array> | undefined;
+    persistVerificationCheckpoints?: boolean | undefined;
+    signedAt?: string | undefined;
+    targetSecretKey: Uint8Array;
+} & ProjectionVerificationOptions): Promise<MaterializedDocumentCreatePlan>;
+/**
+ * Build the writer projection a document-create response establishes, from the
+ * container projection the create was authored against plus the manifest,
+ * content-key bundle, and KEK targets the server just returned. This is the
+ * same material a cold `GET /documents/:id/writer-projection` would yield, so
+ * seeding it lets the first read after a create resolve locally. Shared by the
+ * plain document-create path and the container-with-metadata-document path,
+ * whose response carries an equivalent `DocumentCreateResponse`.
+ */
+export declare function documentWriterProjectionFromCreateResponse(input: {
+    containerProjection: ContainerWriterProjectionResponse;
+    response: DocumentCreateResponse;
+}): DocumentWriterProjectionResponse;
+interface RemoteDocumentCreateInput {
+    apiClient: DocumentCreateApi;
+    author: DocumentCreateAuthor;
+    containerId: string;
+    containerProjection?: ContainerWriterProjectionResponse | undefined;
+    contentKey?: Uint8Array | undefined;
+    contentKeyEpoch?: number | undefined;
+    documentId?: string | undefined;
+    eventId?: string | undefined;
+    execSql: ExecSql;
+    expectedOrganizationId?: string | undefined;
+    isRemoteSyncBlocked?: ((organizationId: string) => boolean) | undefined;
+    knownContainerKeks?: ReadonlyMap<string, Uint8Array> | undefined;
+    /**
+     * Invoked when the create submission fails terminally (not a benign
+     * adopt/stale-target conflict) — e.g. the server denies the write. Callers
+     * persist the failure so the write queue can surface it.
+     */
+    onTerminalSubmitFailure?: DocumentCreateTerminalFailureHandler | undefined;
+    resolveProjectionUserKey: ProjectionUserKeyResolver;
+    signedAt?: string | undefined;
+    stillCurrent?: (() => boolean) | undefined;
+    targetSecretKey: Uint8Array;
+    warmReferencedPrincipalPolicies?: ReferencedPrincipalPolicyWarmer | undefined;
+}
+export declare function createRemoteDocument(input: RemoteDocumentCreateInput): Promise<CreateRemoteDocumentResult | null>;
+type DocumentCreateSubmission = {
+    readonly data: DocumentCreateResponse;
+    readonly ok: true;
+} | {
+    readonly code?: string | undefined;
+    readonly message: string;
+    readonly ok: false;
+    readonly report?: (() => void) | undefined;
+    readonly status: number | null;
+};
+export declare function isStaleDocumentCreateTargetConflict(submission: DocumentCreateSubmission): boolean;
+export {};

package/workflows/documents/create.js

@@ -0,0 +1,313 @@
+import { DOCUMENT_SYNC_ERROR_CODES, } from "../../internal/validators/response/index.js";
+import { assertContainerAuthorAccess } from "../../data/containers/shared/authorAccess.js";
+import { buildDocumentCreatePlan } from "../../data/documents/shared/events.js";
+import { acknowledgeDocumentMutation } from "../../data/documents/shared/mutationAcknowledgement.js";
+import { assertDocumentWriterProjectionConsistent, wrapDocumentContentKeyForCreate, } from "../../data/documents/shared/projection.js";
+import { persistedDocumentCreateStateFromResponse } from "../../data/documents/shared/responses.js";
+import { projectionVerificationOptions } from "../../data/documents/shared/types.js";
+import { collectContainerWriterProjectionPrincipalPolicies, nullOnProjectionVerificationCancellation, requireProjectionUserKeyResolver, } from "../../data/keyingProjectionVerification.js";
+import { isContainerCreatePending } from "../../data/persistence/container-contents/pendingContainerCreate.js";
+import { recordDocumentAuthorAccessFailure } from "./authorAccessFailure.js";
+import { adoptExistingRemoteDocument } from "./createAdoption.js";
+import { fetchContainerWriterProjectionForCreate } from "./createProjectionFetch.js";
+import { isDocumentManifestAlreadyExistsConflict, shouldRetryWithFreshProjection, } from "./syncFailureClassification.js";
+export async function buildMaterializedDocumentCreatePlan(input) {
+    const contentKey = input.contentKey ?? crypto.getRandomValues(new Uint8Array(32));
+    if (contentKey.byteLength !== 32) {
+        throw new Error("Document content key must be 32 bytes");
+    }
+    // Resolved before wrapping: each envelope is sealed to its document and
+    // content-key epoch.
+    const documentId = input.documentId ?? crypto.randomUUID();
+    const contentKeyEpoch = input.contentKeyEpoch ?? 1;
+    const targetEnvelopes = await wrapDocumentContentKeyForCreate({
+        contentKey,
+        contentKeyEpoch,
+        documentId,
+        execSql: input.execSql,
+        knownContainerKeks: input.knownContainerKeks,
+        persistVerificationCheckpoints: input.persistVerificationCheckpoints,
+        projection: input.containerProjection,
+        secretKey: input.targetSecretKey,
+        ...projectionVerificationOptions(input),
+    });
+    if (input.resolveProjectionUserKey) {
+        const principalPolicies = await collectContainerWriterProjectionPrincipalPolicies({
+            ...projectionVerificationOptions(input),
+            execSql: input.execSql,
+            projection: input.containerProjection,
+            resolveUserKey: input.resolveProjectionUserKey,
+        });
+        assertContainerAuthorAccess({
+            // Document signing derives its organization from the verified target.
+            author: {
+                ...input.author,
+                organizationId: input.containerProjection.organizationId,
+            },
+            projection: input.containerProjection,
+            principalPolicies,
+            minimumAccess: "write",
+        });
+    }
+    // The explicit local-trust variant builds provisioning artifacts before
+    // their new principal policies exist remotely; remote creates cannot use it.
+    const plan = await buildDocumentCreatePlan({
+        author: input.author,
+        containerProjection: input.containerProjection,
+        contentKeyEpoch,
+        documentId,
+        ...(input.eventId === undefined ? {} : { eventId: input.eventId }),
+        ...(input.signedAt === undefined ? {} : { signedAt: input.signedAt }),
+        targetEnvelopes,
+    });
+    return {
+        contentKey,
+        plan,
+    };
+}
+/**
+ * Build the writer projection a document-create response establishes, from the
+ * container projection the create was authored against plus the manifest,
+ * content-key bundle, and KEK targets the server just returned. This is the
+ * same material a cold `GET /documents/:id/writer-projection` would yield, so
+ * seeding it lets the first read after a create resolve locally. Shared by the
+ * plain document-create path and the container-with-metadata-document path,
+ * whose response carries an equivalent `DocumentCreateResponse`.
+ */
+export function documentWriterProjectionFromCreateResponse(input) {
+    return {
+        policyEvidence: input.containerProjection.policyEvidence,
+        authorizingContainerPaths: [input.containerProjection],
+        contentKeyBundle: input.response.contentKeyBundle,
+        documentContainerManifestHistory: [
+            ...input.containerProjection.path,
+            ...input.containerProjection.containerKeks.flatMap((kek) => kek.containerManifestHistory),
+        ],
+        documentId: input.response.id,
+        documentKekTargets: input.response.documentKekTargets,
+        documentManifest: input.response.accessManifest,
+        documentManifestContainerPaths: [[...input.containerProjection.path]],
+        documentManifestHistory: [],
+    };
+}
+async function buildMaterializedDocumentCreatePlanWithFreshProjection(input) {
+    const buildWithProjection = async (containerProjection) => {
+        if (containerProjection.containerId !== input.containerId ||
+            (input.expectedOrganizationId !== undefined &&
+                containerProjection.organizationId !== input.expectedOrganizationId)) {
+            throw new Error("Container writer projection belongs to another container or organization");
+        }
+        return {
+            containerProjection,
+            materializedPlan: await buildMaterializedDocumentCreatePlan({
+                author: input.author,
+                containerProjection,
+                contentKey: input.contentKey,
+                contentKeyEpoch: input.contentKeyEpoch,
+                documentId: input.documentId,
+                eventId: input.eventId,
+                execSql: input.execSql,
+                knownContainerKeks: input.knownContainerKeks,
+                persistVerificationCheckpoints: input.persistVerificationCheckpoints,
+                resolveProjectionUserKey: input.resolveProjectionUserKey,
+                signedAt: input.signedAt,
+                stillCurrent: input.stillCurrent,
+                targetSecretKey: input.targetSecretKey,
+                warmReferencedPrincipalPolicies: input.warmReferencedPrincipalPolicies,
+            }),
+        };
+    };
+    const containerProjection = input.containerProjection ??
+        (await fetchContainerWriterProjectionForCreate({
+            apiClient: input.apiClient,
+            containerId: input.containerId,
+            onTerminalSubmitFailure: input.onTerminalSubmitFailure,
+        }));
+    if (!containerProjection) {
+        return null;
+    }
+    try {
+        return await buildWithProjection(containerProjection);
+    }
+    catch (error) {
+        if (!shouldRetryWithFreshProjection(error, (message) => message.includes("could not be unwrapped"))) {
+            throw error;
+        }
+    }
+    // Only this container's projection was stale; evict just it rather than
+    // wiping every cached projection.
+    input.apiClient.evictContainerWriterProjection(input.containerId);
+    const refreshedProjection = await fetchContainerWriterProjectionForCreate({
+        apiClient: input.apiClient,
+        containerId: input.containerId,
+        onTerminalSubmitFailure: input.onTerminalSubmitFailure,
+    });
+    return refreshedProjection ? buildWithProjection(refreshedProjection) : null;
+}
+function isRemoteDocumentCreatePlanBlocked(input, createPlan) {
+    const organizationId = createPlan.containerProjection.organizationId;
+    return input.isRemoteSyncBlocked?.(organizationId) ?? false;
+}
+async function submitPlannedDocumentCreate(input, resolveProjectionUserKey) {
+    const verificationOptions = { stillCurrent: input.stillCurrent };
+    const warmReferencedPrincipalPolicies = input.warmReferencedPrincipalPolicies;
+    let createPlan = await buildMaterializedDocumentCreatePlanWithFreshProjection({
+        apiClient: input.apiClient,
+        author: input.author,
+        containerId: input.containerId,
+        containerProjection: input.containerProjection,
+        contentKey: input.contentKey,
+        contentKeyEpoch: input.contentKeyEpoch,
+        documentId: input.documentId,
+        eventId: input.eventId,
+        execSql: input.execSql,
+        expectedOrganizationId: input.expectedOrganizationId,
+        knownContainerKeks: input.knownContainerKeks,
+        onTerminalSubmitFailure: input.onTerminalSubmitFailure,
+        resolveProjectionUserKey,
+        signedAt: input.signedAt,
+        targetSecretKey: input.targetSecretKey,
+        warmReferencedPrincipalPolicies,
+        ...verificationOptions,
+    });
+    if (!createPlan) {
+        return null;
+    }
+    if (isRemoteDocumentCreatePlanBlocked(input, createPlan))
+        return null;
+    if (input.stillCurrent?.() === false)
+        return null;
+    let submission = await submitDocumentCreate(input.apiClient, createPlan.materializedPlan.plan.request, createPlan.containerProjection.organizationId);
+    if (isStaleDocumentCreateTargetConflict(submission)) {
+        if (input.stillCurrent?.() === false) {
+            return { createPlan, submission };
+        }
+        input.apiClient.evictContainerWriterProjection(input.containerId);
+        const firstPlan = createPlan.materializedPlan;
+        const refreshedPlan = await buildMaterializedDocumentCreatePlanWithFreshProjection({
+            apiClient: input.apiClient,
+            author: input.author,
+            containerId: input.containerId,
+            contentKey: firstPlan.contentKey,
+            contentKeyEpoch: firstPlan.plan.request.contentKeyBundle.contentKeyEpoch,
+            documentId: firstPlan.plan.documentId,
+            eventId: firstPlan.plan.event.eventId,
+            execSql: input.execSql,
+            expectedOrganizationId: input.expectedOrganizationId,
+            knownContainerKeks: input.knownContainerKeks,
+            onTerminalSubmitFailure: input.onTerminalSubmitFailure,
+            resolveProjectionUserKey,
+            signedAt: firstPlan.plan.event.signedAt,
+            targetSecretKey: input.targetSecretKey,
+            warmReferencedPrincipalPolicies,
+            ...verificationOptions,
+        });
+        if (!refreshedPlan) {
+            return null;
+        }
+        if (isRemoteDocumentCreatePlanBlocked(input, refreshedPlan))
+            return null;
+        createPlan = refreshedPlan;
+        if (input.stillCurrent?.() === false)
+            return null;
+        submission = await submitDocumentCreate(input.apiClient, createPlan.materializedPlan.plan.request, createPlan.containerProjection.organizationId);
+    }
+    return { createPlan, submission };
+}
+export async function createRemoteDocument(input) {
+    // The store retries once the folder's own create settles.
+    if (await isContainerCreatePending(input.execSql, input.containerId)) {
+        return null;
+    }
+    const resolveProjectionUserKey = requireProjectionUserKeyResolver(input.resolveProjectionUserKey, "Remote document create");
+    const plannedSubmission = await recordDocumentAuthorAccessFailure(() => nullOnProjectionVerificationCancellation(() => submitPlannedDocumentCreate(input, resolveProjectionUserKey)), input.onTerminalSubmitFailure);
+    if (!plannedSubmission) {
+        return null;
+    }
+    const { createPlan, submission } = plannedSubmission;
+    if (input.stillCurrent?.() === false)
+        return null;
+    if (submission.ok) {
+        const response = submission.data;
+        const persistedState = persistedDocumentCreateStateFromResponse(createPlan.materializedPlan.plan, response);
+        await acknowledgeDocumentMutation({
+            execSql: input.execSql,
+            plan: createPlan.materializedPlan.plan,
+            stillCurrent: input.stillCurrent,
+        });
+        if (input.stillCurrent?.() === false)
+            return null;
+        const writerProjection = documentWriterProjectionFromCreateResponse({
+            containerProjection: createPlan.containerProjection,
+            response,
+        });
+        const verifiedTargets = await nullOnProjectionVerificationCancellation(() => assertDocumentWriterProjectionConsistent(writerProjection, {
+            execSql: input.execSql,
+            resolveProjectionUserKey,
+            stillCurrent: input.stillCurrent,
+            warmReferencedPrincipalPolicies: input.warmReferencedPrincipalPolicies,
+        }));
+        if (!verifiedTargets)
+            return null;
+        if (input.stillCurrent?.() === false)
+            return null;
+        // Seed the projection the create response already gave us so the first read
+        // after create (sync, blob attach, container-contents hydration) resolves
+        // locally instead of a cold GET writer-projection.
+        input.apiClient.primeDocumentWriterProjection(response.id, writerProjection);
+        return {
+            contentKey: createPlan.materializedPlan.contentKey,
+            documentId: response.id,
+            persistedState,
+            plan: createPlan.materializedPlan.plan,
+            response,
+            writerProjection,
+        };
+    }
+    // A stable documentId means a retry after a lost create response re-submits
+    // the same id; the server then reports the manifest already exists. That is
+    // not a failure — the first attempt committed. Adopt the existing remote
+    // document instead of leaking a duplicate. Requires the stable id we sent, so
+    // we can fetch its projection back.
+    const stableDocumentId = input.documentId;
+    if (stableDocumentId && isDocumentManifestAlreadyExistsConflict(submission)) {
+        if (input.stillCurrent?.() === false)
+            return null;
+        const adopted = await nullOnProjectionVerificationCancellation(() => adoptExistingRemoteDocument({
+            apiClient: input.apiClient,
+            documentId: stableDocumentId,
+            execSql: input.execSql,
+            expectedContainerId: input.containerId,
+            expectedOrganizationId: input.expectedOrganizationId ??
+                createPlan.containerProjection.organizationId,
+            expectedSignerUserId: input.author.signerUserId,
+            resolveProjectionUserKey,
+            stillCurrent: input.stillCurrent,
+            targetSecretKey: input.targetSecretKey,
+            warmReferencedPrincipalPolicies: input.warmReferencedPrincipalPolicies,
+        }));
+        if (adopted) {
+            return adopted;
+        }
+        // A conflict is the expected, benign outcome of an idempotent retry after a
+        // lost create response. If adoption cannot complete yet (e.g. the writer
+        // projection fetch failed transiently), do not surface the conflict as a UI
+        // error — the sync engine retries and adopts it on a later tick.
+        return null;
+    }
+    submission.report?.();
+    await input.onTerminalSubmitFailure?.(submission);
+    return null;
+}
+export function isStaleDocumentCreateTargetConflict(submission) {
+    return (!submission.ok &&
+        submission.status === 409 &&
+        submission.code === DOCUMENT_SYNC_ERROR_CODES.stateStale);
+}
+async function submitDocumentCreate(apiClient, request, expectedOrganizationId) {
+    return apiClient.createDocumentResult(request, {
+        expectedPaymentRequiredOrganizationId: expectedOrganizationId,
+        reportErrors: false,
+    });
+}
+//# sourceMappingURL=create.js.map