@tearleads/client-sdk 0.1.61 → 0.1.63

package/workflows/documents/create/createAdoption.js

@@ -0,0 +1,100 @@
+import { KeyingVerificationError, } from "../../../internal/crypto/index.js";
+import { assertDocumentWriterProjectionConsistent, readLinkedContainerIdsFromDocumentManifest, unwrapDocumentContentKeyFromWriterProjection, } from "../../../data/documents/shared/projection.js";
+import { persistedDocumentCreateStateFromWriterProjection } from "../../../data/documents/shared/responses.js";
+import { projectionVerificationOptions } from "../../../data/documents/shared/types.js";
+import { readAccessEvent, readAccessManifest, } from "../../../data/keyingProjectionVerification/readers.js";
+/**
+ * A retry after a lost create response can only recover the local user's own
+ * create: the server serves whatever document holds the stable id we minted,
+ * and an honest server only ever committed ours under it. A create event signed
+ * by anyone else is a foreign document colliding on that id (a member with
+ * write access on the same container, or a dishonest server), which must not be
+ * adopted as if it were the pending local write.
+ *
+ * The create event is located by walking the served head's predecessor chain,
+ * not by scanning the history for any parentless manifest: the history is
+ * server-supplied, so a dishonest server could splice in a genesis this user
+ * signed for a different document. Every manifest on the chain must also name
+ * the requested document.
+ */
+function assertCreateEventSignedLocally(input, writerProjection) {
+    const label = "Document create conflict";
+    const historyByHash = new Map(writerProjection.documentManifestHistory.map((bundle) => [
+        bundle.manifestHash,
+        bundle,
+    ]));
+    const visited = new Set();
+    let bundle = writerProjection.documentManifest;
+    for (;;) {
+        const manifest = readAccessManifest(bundle.manifest, `${label} manifest`);
+        if (manifest.objectKind !== "document" ||
+            manifest.objectId !== input.documentId) {
+            throw new KeyingVerificationError("object_mismatch", `${label} manifest chain names another document`);
+        }
+        if (manifest.previousManifestHash === null) {
+            const createEvent = readAccessEvent(bundle.event.event, `${label} create event`);
+            if (createEvent.signerUserId !== input.expectedSignerUserId) {
+                throw new KeyingVerificationError("signer_mismatch", `${label} create event was signed by another user`);
+            }
+            return;
+        }
+        if (visited.has(bundle.manifestHash)) {
+            throw new KeyingVerificationError("invalid_shape", `${label} manifest history is cyclic`);
+        }
+        visited.add(bundle.manifestHash);
+        const previous = historyByHash.get(manifest.previousManifestHash);
+        if (!previous) {
+            throw new KeyingVerificationError("invalid_shape", `${label} does not expose its create event`);
+        }
+        bundle = previous;
+    }
+}
+function assertExpectedAdoptionScope(input, writerProjection) {
+    const linkedContainerIds = readLinkedContainerIdsFromDocumentManifest(writerProjection);
+    const expectedPath = writerProjection.authorizingContainerPaths.find((projection) => projection.containerId === input.expectedContainerId &&
+        projection.organizationId === input.expectedOrganizationId);
+    if (linkedContainerIds.length !== 1 ||
+        linkedContainerIds[0] !== input.expectedContainerId ||
+        !expectedPath) {
+        throw new Error("Document create conflict belongs to another container or organization");
+    }
+}
+/** Recover a committed retry only when it belongs to the intended org scope. */
+export async function adoptExistingRemoteDocument(input) {
+    const writerProjection = await input.apiClient.getDocumentWriterProjection(input.documentId);
+    if (!writerProjection)
+        return null;
+    // Reject a foreign collision before verification can pin its checkpoints.
+    assertExpectedAdoptionScope(input, writerProjection);
+    assertCreateEventSignedLocally(input, writerProjection);
+    const verifiedByHash = new Map();
+    const principalPolicyCache = new Map();
+    const targets = await assertDocumentWriterProjectionConsistent(writerProjection, {
+        execSql: input.execSql,
+        principalPolicyCache,
+        verifiedByHash,
+        ...projectionVerificationOptions(input),
+    });
+    if (targets.length !== 1 ||
+        targets[0]?.containerId !== input.expectedContainerId) {
+        throw new Error("Document create conflict belongs to another container or organization");
+    }
+    const contentKey = await unwrapDocumentContentKeyFromWriterProjection({
+        execSql: input.execSql,
+        principalPolicyCache,
+        secretKey: input.targetSecretKey,
+        verifiedByHash,
+        writerProjection,
+        ...projectionVerificationOptions(input),
+    });
+    if (input.stillCurrent?.() === false)
+        return null;
+    input.apiClient.primeDocumentWriterProjection(writerProjection.documentId, writerProjection);
+    return {
+        contentKey,
+        documentId: writerProjection.documentId,
+        persistedState: persistedDocumentCreateStateFromWriterProjection(writerProjection),
+        writerProjection,
+    };
+}
+//# sourceMappingURL=createAdoption.js.map

package/workflows/documents/create/createAdoption.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createAdoption.js","sourceRoot":"","sources":["createAdoption.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  KeyingVerificationError,\n  type VerifiedContainerAccessManifest,\n  type VerifiedPrincipalPolicy,\n} from \"@tearleads/crypto\";\nimport type { DocumentWriterProjectionResponse } from \"@tearleads/validators/response\";\nimport {\n  assertDocumentWriterProjectionConsistent,\n  readLinkedContainerIdsFromDocumentManifest,\n  unwrapDocumentContentKeyFromWriterProjection,\n} from \"../../../data/documents/shared/projection\";\nimport { persistedDocumentCreateStateFromWriterProjection } from \"../../../data/documents/shared/responses\";\nimport type {\n  CreateRemoteDocumentResult,\n  DocumentCreateApi,\n  ProjectionVerificationOptions,\n} from \"../../../data/documents/shared/types\";\nimport { projectionVerificationOptions } from \"../../../data/documents/shared/types\";\nimport {\n  readAccessEvent,\n  readAccessManifest,\n} from \"../../../data/keyingProjectionVerification/readers\";\nimport type { ExecSql } from \"../../../data/sqlite/sqlSchema\";\n\ntype RemoteDocumentAdoptionInput = {\n  readonly apiClient: DocumentCreateApi;\n  readonly documentId: string;\n  readonly execSql: ExecSql;\n  readonly expectedContainerId: string;\n  readonly expectedOrganizationId: string;\n  /** The local user whose pending create the retry is recovering. */\n  readonly expectedSignerUserId: string;\n  readonly targetSecretKey: Uint8Array;\n} & ProjectionVerificationOptions;\n\n/**\n * A retry after a lost create response can only recover the local user's own\n * create: the server serves whatever document holds the stable id we minted,\n * and an honest server only ever committed ours under it. A create event signed\n * by anyone else is a foreign document colliding on that id (a member with\n * write access on the same container, or a dishonest server), which must not be\n * adopted as if it were the pending local write.\n *\n * The create event is located by walking the served head's predecessor chain,\n * not by scanning the history for any parentless manifest: the history is\n * server-supplied, so a dishonest server could splice in a genesis this user\n * signed for a different document. Every manifest on the chain must also name\n * the requested document.\n */\nfunction assertCreateEventSignedLocally(\n  input: RemoteDocumentAdoptionInput,\n  writerProjection: DocumentWriterProjectionResponse,\n): void {\n  const label = \"Document create conflict\";\n  const historyByHash = new Map(\n    writerProjection.documentManifestHistory.map((bundle) => [\n      bundle.manifestHash,\n      bundle,\n    ]),\n  );\n  const visited = new Set<string>();\n  let bundle = writerProjection.documentManifest;\n  for (;;) {\n    const manifest = readAccessManifest(bundle.manifest, `${label} manifest`);\n    if (\n      manifest.objectKind !== \"document\" ||\n      manifest.objectId !== input.documentId\n    ) {\n      throw new KeyingVerificationError(\n        \"object_mismatch\",\n        `${label} manifest chain names another document`,\n      );\n    }\n    if (manifest.previousManifestHash === null) {\n      const createEvent = readAccessEvent(\n        bundle.event.event,\n        `${label} create event`,\n      );\n      if (createEvent.signerUserId !== input.expectedSignerUserId) {\n        throw new KeyingVerificationError(\n          \"signer_mismatch\",\n          `${label} create event was signed by another user`,\n        );\n      }\n      return;\n    }\n    if (visited.has(bundle.manifestHash)) {\n      throw new KeyingVerificationError(\n        \"invalid_shape\",\n        `${label} manifest history is cyclic`,\n      );\n    }\n    visited.add(bundle.manifestHash);\n    const previous = historyByHash.get(manifest.previousManifestHash);\n    if (!previous) {\n      throw new KeyingVerificationError(\n        \"invalid_shape\",\n        `${label} does not expose its create event`,\n      );\n    }\n    bundle = previous;\n  }\n}\n\nfunction assertExpectedAdoptionScope(\n  input: RemoteDocumentAdoptionInput,\n  writerProjection: DocumentWriterProjectionResponse,\n): void {\n  const linkedContainerIds =\n    readLinkedContainerIdsFromDocumentManifest(writerProjection);\n  const expectedPath = writerProjection.authorizingContainerPaths.find(\n    (projection) =>\n      projection.containerId === input.expectedContainerId &&\n      projection.organizationId === input.expectedOrganizationId,\n  );\n  if (\n    linkedContainerIds.length !== 1 ||\n    linkedContainerIds[0] !== input.expectedContainerId ||\n    !expectedPath\n  ) {\n    throw new Error(\n      \"Document create conflict belongs to another container or organization\",\n    );\n  }\n}\n\n/** Recover a committed retry only when it belongs to the intended org scope. */\nexport async function adoptExistingRemoteDocument(\n  input: RemoteDocumentAdoptionInput,\n): Promise<CreateRemoteDocumentResult | null> {\n  const writerProjection = await input.apiClient.getDocumentWriterProjection(\n    input.documentId,\n  );\n  if (!writerProjection) return null;\n\n  // Reject a foreign collision before verification can pin its checkpoints.\n  assertExpectedAdoptionScope(input, writerProjection);\n  assertCreateEventSignedLocally(input, writerProjection);\n  const verifiedByHash = new Map<string, VerifiedContainerAccessManifest>();\n  const principalPolicyCache = new Map<string, VerifiedPrincipalPolicy>();\n  const targets = await assertDocumentWriterProjectionConsistent(\n    writerProjection,\n    {\n      execSql: input.execSql,\n      principalPolicyCache,\n      verifiedByHash,\n      ...projectionVerificationOptions(input),\n    },\n  );\n  if (\n    targets.length !== 1 ||\n    targets[0]?.containerId !== input.expectedContainerId\n  ) {\n    throw new Error(\n      \"Document create conflict belongs to another container or organization\",\n    );\n  }\n  const contentKey = await unwrapDocumentContentKeyFromWriterProjection({\n    execSql: input.execSql,\n    principalPolicyCache,\n    secretKey: input.targetSecretKey,\n    verifiedByHash,\n    writerProjection,\n    ...projectionVerificationOptions(input),\n  });\n  if (input.stillCurrent?.() === false) return null;\n  input.apiClient.primeDocumentWriterProjection(\n    writerProjection.documentId,\n    writerProjection,\n  );\n  return {\n    contentKey,\n    documentId: writerProjection.documentId,\n    persistedState:\n      persistedDocumentCreateStateFromWriterProjection(writerProjection),\n    writerProjection,\n  };\n}\n"]}

package/workflows/documents/create/createProjection.d.ts

@@ -0,0 +1,14 @@
+import type { ContainerWriterProjectionResponse, DocumentCreateResponse, DocumentWriterProjectionResponse } from "../../../internal/validators/response/index.js";
+/**
+ * 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;

package/workflows/documents/create/createProjectionFetch.d.ts

@@ -0,0 +1,27 @@
+import type { ContainerWriterProjectionResponse } from "../../../internal/validators/response/index.js";
+import type { DocumentCreateApi } from "../../../data/documents/shared/types.js";
+export type DocumentCreateTerminalFailureHandler = (failure: {
+    readonly message: string;
+    readonly status: number | null;
+}) => Promise<void> | void;
+/**
+ * Resolve the container writer projection a create is authored against,
+ * persisting a terminal fetch failure through the caller's handler. A pending
+ * local create can never submit without this projection, so the failure (e.g.
+ * a 402 billing block or a 403 after access revocation) is what the write
+ * queue must surface — collapsing it to a silent null left the queued create
+ * invisible forever: no failure row, no attempt timestamp, and sync telemetry
+ * reporting no pending work.
+ *
+ * The recorded row follows the standard failure lifecycle rather than
+ * sticking: a document whose create later succeeds cannot skip its follow-up
+ * sync (its record carries no commit LSN until a sync response persists one,
+ * so shouldSkipCleanScheduledDocumentSync stays false), and that clean pass
+ * clears the row. Across restarts the row itself is a priming ticket that
+ * re-drives the store, exactly like a recorded revalidation refusal.
+ */
+export declare function fetchContainerWriterProjectionForCreate(input: {
+    apiClient: DocumentCreateApi;
+    containerId: string;
+    onTerminalSubmitFailure?: DocumentCreateTerminalFailureHandler | undefined;
+}): Promise<ContainerWriterProjectionResponse | null>;

package/workflows/documents/create/createProjectionFetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createProjectionFetch.js","sourceRoot":"","sources":["createProjectionFetch.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,uCAAuC,CAAC,KAI7D;IACC,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,SAAS,CAAC,kCAAkC,CACrE,KAAK,CAAC,WAAW,EACjB,EAAE,YAAY,EAAE,KAAK,EAAE,CACxB,CAAC;IACF,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;QACd,OAAO,MAAM,CAAC,IAAI,CAAC;IACrB,CAAC;IACD,MAAM,CAAC,MAAM,EAAE,CAAC;IAChB,MAAM,KAAK,CAAC,uBAAuB,EAAE,CAAC,MAAM,CAAC,CAAC;IAC9C,OAAO,IAAI,CAAC;AACd,CAAC","sourcesContent":["import type { ContainerWriterProjectionResponse } from \"@tearleads/validators/response\";\nimport type { DocumentCreateApi } from \"../../../data/documents/shared/types\";\n\nexport type DocumentCreateTerminalFailureHandler = (failure: {\n  readonly message: string;\n  readonly status: number | null;\n}) => Promise<void> | void;\n\n/**\n * Resolve the container writer projection a create is authored against,\n * persisting a terminal fetch failure through the caller's handler. A pending\n * local create can never submit without this projection, so the failure (e.g.\n * a 402 billing block or a 403 after access revocation) is what the write\n * queue must surface — collapsing it to a silent null left the queued create\n * invisible forever: no failure row, no attempt timestamp, and sync telemetry\n * reporting no pending work.\n *\n * The recorded row follows the standard failure lifecycle rather than\n * sticking: a document whose create later succeeds cannot skip its follow-up\n * sync (its record carries no commit LSN until a sync response persists one,\n * so shouldSkipCleanScheduledDocumentSync stays false), and that clean pass\n * clears the row. Across restarts the row itself is a priming ticket that\n * re-drives the store, exactly like a recorded revalidation refusal.\n */\nexport async function fetchContainerWriterProjectionForCreate(input: {\n  apiClient: DocumentCreateApi;\n  containerId: string;\n  onTerminalSubmitFailure?: DocumentCreateTerminalFailureHandler | undefined;\n}): Promise<ContainerWriterProjectionResponse | null> {\n  const result = await input.apiClient.getContainerWriterProjectionResult(\n    input.containerId,\n    { reportErrors: false },\n  );\n  if (result.ok) {\n    return result.data;\n  }\n  result.report();\n  await input.onTerminalSubmitFailure?.(result);\n  return null;\n}\n"]}

package/workflows/documents/create/createResponse.js

@@ -0,0 +1,49 @@
+import { acknowledgeDocumentMutation } from "../../../data/documents/shared/mutationAcknowledgement.js";
+import { assertDocumentWriterProjectionConsistent } from "../../../data/documents/shared/projection.js";
+import { persistedDocumentCreateStateFromResponse } from "../../../data/documents/shared/responses.js";
+import { ProjectionDependencyUnavailableError } from "../../../data/keyingProjectionVerification/dependencyUnavailable.js";
+import { nullOnProjectionVerificationCancellation } from "../../../data/keyingProjectionVerification/types.js";
+import { adoptExistingRemoteDocument } from "./createAdoption.js";
+import { documentWriterProjectionFromCreateResponse } from "./createProjection.js";
+/** A matched acknowledgement remains committed if authorization evidence races. */
+export async function acknowledgeRemoteDocumentCreate(input) {
+    const { materializedPlan, response } = input;
+    const persistedState = persistedDocumentCreateStateFromResponse(materializedPlan.plan, response);
+    await acknowledgeDocumentMutation({
+        execSql: input.execSql,
+        plan: materializedPlan.plan,
+        stillCurrent: input.stillCurrent,
+    });
+    if (input.stillCurrent?.() === false)
+        return null;
+    const writerProjection = documentWriterProjectionFromCreateResponse(input);
+    try {
+        const targets = await nullOnProjectionVerificationCancellation(() => assertDocumentWriterProjectionConsistent(writerProjection, input));
+        if (!targets || input.stillCurrent?.() === false)
+            return null;
+    }
+    catch (error) {
+        if (!(error instanceof ProjectionDependencyUnavailableError))
+            throw error;
+        // A principal pin can advance while POST is in flight. Recover the already
+        // committed document from fresh evidence, without submitting another create.
+        // The adoption path still verifies its author, scope, chain and key binding.
+        return nullOnProjectionVerificationCancellation(() => adoptExistingRemoteDocument({
+            ...input,
+            documentId: response.id,
+            expectedContainerId: input.containerProjection.containerId,
+            expectedOrganizationId: input.containerProjection.organizationId,
+            expectedSignerUserId: input.author.signerUserId,
+        }));
+    }
+    input.apiClient.primeDocumentWriterProjection(response.id, writerProjection);
+    return {
+        contentKey: materializedPlan.contentKey,
+        documentId: response.id,
+        persistedState,
+        plan: materializedPlan.plan,
+        response,
+        writerProjection,
+    };
+}
+//# sourceMappingURL=createResponse.js.map

package/workflows/documents/create/createResponse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createResponse.js","sourceRoot":"","sources":["createResponse.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,2BAA2B,EAAE,MAAM,wDAAwD,CAAC;AACrG,OAAO,EAAE,wCAAwC,EAAE,MAAM,2CAA2C,CAAC;AACrG,OAAO,EAAE,wCAAwC,EAAE,MAAM,0CAA0C,CAAC;AASpG,OAAO,EAAE,oCAAoC,EAAE,MAAM,kEAAkE,CAAC;AACxH,OAAO,EAAE,wCAAwC,EAAE,MAAM,kDAAkD,CAAC;AAE5G,OAAO,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EAAE,0CAA0C,EAAE,MAAM,oBAAoB,CAAC;AAEhF,mFAAmF;AACnF,MAAM,CAAC,KAAK,UAAU,+BAA+B,CACnD,KASiC;IAEjC,MAAM,EAAE,gBAAgB,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC;IAC7C,MAAM,cAAc,GAAG,wCAAwC,CAC7D,gBAAgB,CAAC,IAAI,EACrB,QAAQ,CACT,CAAC;IACF,MAAM,2BAA2B,CAAC;QAChC,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,IAAI,EAAE,gBAAgB,CAAC,IAAI;QAC3B,YAAY,EAAE,KAAK,CAAC,YAAY;KACjC,CAAC,CAAC;IACH,IAAI,KAAK,CAAC,YAAY,EAAE,EAAE,KAAK,KAAK;QAAE,OAAO,IAAI,CAAC;IAClD,MAAM,gBAAgB,GAAG,0CAA0C,CAAC,KAAK,CAAC,CAAC;IAC3E,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,wCAAwC,CAAC,GAAG,EAAE,CAClE,wCAAwC,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAClE,CAAC;QACF,IAAI,CAAC,OAAO,IAAI,KAAK,CAAC,YAAY,EAAE,EAAE,KAAK,KAAK;YAAE,OAAO,IAAI,CAAC;IAChE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,CAAC,KAAK,YAAY,oCAAoC,CAAC;YAAE,MAAM,KAAK,CAAC;QAC1E,2EAA2E;QAC3E,6EAA6E;QAC7E,6EAA6E;QAC7E,OAAO,wCAAwC,CAAC,GAAG,EAAE,CACnD,2BAA2B,CAAC;YAC1B,GAAG,KAAK;YACR,UAAU,EAAE,QAAQ,CAAC,EAAE;YACvB,mBAAmB,EAAE,KAAK,CAAC,mBAAmB,CAAC,WAAW;YAC1D,sBAAsB,EAAE,KAAK,CAAC,mBAAmB,CAAC,cAAc;YAChE,oBAAoB,EAAE,KAAK,CAAC,MAAM,CAAC,YAAY;SAChD,CAAC,CACH,CAAC;IACJ,CAAC;IACD,KAAK,CAAC,SAAS,CAAC,6BAA6B,CAAC,QAAQ,CAAC,EAAE,EAAE,gBAAgB,CAAC,CAAC;IAC7E,OAAO;QACL,UAAU,EAAE,gBAAgB,CAAC,UAAU;QACvC,UAAU,EAAE,QAAQ,CAAC,EAAE;QACvB,cAAc;QACd,IAAI,EAAE,gBAAgB,CAAC,IAAI;QAC3B,QAAQ;QACR,gBAAgB;KACjB,CAAC;AACJ,CAAC","sourcesContent":["import type {\n  ContainerWriterProjectionResponse,\n  DocumentCreateResponse,\n} from \"@tearleads/validators/response\";\nimport { acknowledgeDocumentMutation } from \"../../../data/documents/shared/mutationAcknowledgement\";\nimport { assertDocumentWriterProjectionConsistent } from \"../../../data/documents/shared/projection\";\nimport { persistedDocumentCreateStateFromResponse } from \"../../../data/documents/shared/responses\";\nimport type {\n  CreateRemoteDocumentResult,\n  DocumentCreateApi,\n  DocumentCreateAuthor,\n  MaterializedDocumentCreatePlan,\n  ProjectionVerificationOptions,\n} from \"../../../data/documents/shared/types\";\nimport type { ProjectionUserKeyResolver } from \"../../../data/keyingProjectionVerification\";\nimport { ProjectionDependencyUnavailableError } from \"../../../data/keyingProjectionVerification/dependencyUnavailable\";\nimport { nullOnProjectionVerificationCancellation } from \"../../../data/keyingProjectionVerification/types\";\nimport type { ExecSql } from \"../../../data/sqlite/sqlSchema\";\nimport { adoptExistingRemoteDocument } from \"./createAdoption\";\nimport { documentWriterProjectionFromCreateResponse } from \"./createProjection\";\n\n/** A matched acknowledgement remains committed if authorization evidence races. */\nexport async function acknowledgeRemoteDocumentCreate(\n  input: {\n    readonly apiClient: DocumentCreateApi;\n    readonly author: DocumentCreateAuthor;\n    readonly containerProjection: ContainerWriterProjectionResponse;\n    readonly execSql: ExecSql;\n    readonly materializedPlan: MaterializedDocumentCreatePlan;\n    readonly resolveProjectionUserKey: ProjectionUserKeyResolver;\n    readonly response: DocumentCreateResponse;\n    readonly targetSecretKey: Uint8Array;\n  } & ProjectionVerificationOptions,\n): Promise<CreateRemoteDocumentResult | null> {\n  const { materializedPlan, response } = input;\n  const persistedState = persistedDocumentCreateStateFromResponse(\n    materializedPlan.plan,\n    response,\n  );\n  await acknowledgeDocumentMutation({\n    execSql: input.execSql,\n    plan: materializedPlan.plan,\n    stillCurrent: input.stillCurrent,\n  });\n  if (input.stillCurrent?.() === false) return null;\n  const writerProjection = documentWriterProjectionFromCreateResponse(input);\n  try {\n    const targets = await nullOnProjectionVerificationCancellation(() =>\n      assertDocumentWriterProjectionConsistent(writerProjection, input),\n    );\n    if (!targets || input.stillCurrent?.() === false) return null;\n  } catch (error) {\n    if (!(error instanceof ProjectionDependencyUnavailableError)) throw error;\n    // A principal pin can advance while POST is in flight. Recover the already\n    // committed document from fresh evidence, without submitting another create.\n    // The adoption path still verifies its author, scope, chain and key binding.\n    return nullOnProjectionVerificationCancellation(() =>\n      adoptExistingRemoteDocument({\n        ...input,\n        documentId: response.id,\n        expectedContainerId: input.containerProjection.containerId,\n        expectedOrganizationId: input.containerProjection.organizationId,\n        expectedSignerUserId: input.author.signerUserId,\n      }),\n    );\n  }\n  input.apiClient.primeDocumentWriterProjection(response.id, writerProjection);\n  return {\n    contentKey: materializedPlan.contentKey,\n    documentId: response.id,\n    persistedState,\n    plan: materializedPlan.plan,\n    response,\n    writerProjection,\n  };\n}\n"]}

package/workflows/documents/create/documentCreationPersistence.js

@@ -0,0 +1,16 @@
+import { bytesToBase64 } from "../../../internal/encoding/index.js";
+import { encodeVersionVector, exportFullHistorySnapshot, } from "../../../internal/loro/index.js";
+export function createInitialDocumentRows(input) {
+    return input.persistence.createDocumentWithHistoryCheckpoint(input.execSql, input.record, {
+        endVersionVector: encodeVersionVector(input.currentDoc),
+        snapshot: bytesToBase64(exportFullHistorySnapshot(input.currentDoc)),
+    }, input.pendingUpdate || input.stillCurrent
+        ? {
+            ...(input.pendingUpdate
+                ? { pendingUpdate: input.pendingUpdate }
+                : {}),
+            ...(input.stillCurrent ? { stillCurrent: input.stillCurrent } : {}),
+        }
+        : undefined, input.saveClientProjection);
+}
+//# sourceMappingURL=documentCreationPersistence.js.map

package/workflows/documents/create/documentCreationPersistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"documentCreationPersistence.js","sourceRoot":"","sources":["documentCreationPersistence.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EACL,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,iBAAiB,CAAC;AAQzB,MAAM,UAAU,yBAAyB,CAAC,KAUzC;IACC,OAAO,KAAK,CAAC,WAAW,CAAC,mCAAmC,CAC1D,KAAK,CAAC,OAAO,EACb,KAAK,CAAC,MAAM,EACZ;QACE,gBAAgB,EAAE,mBAAmB,CAAC,KAAK,CAAC,UAAU,CAAC;QACvD,QAAQ,EAAE,aAAa,CAAC,yBAAyB,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;KACrE,EACD,KAAK,CAAC,aAAa,IAAI,KAAK,CAAC,YAAY;QACvC,CAAC,CAAC;YACE,GAAG,CAAC,KAAK,CAAC,aAAa;gBACrB,CAAC,CAAC,EAAE,aAAa,EAAE,KAAK,CAAC,aAAa,EAAE;gBACxC,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,KAAK,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACpE;QACH,CAAC,CAAC,SAAS,EACb,KAAK,CAAC,oBAAoB,CAC3B,CAAC;AACJ,CAAC","sourcesContent":["import { bytesToBase64 } from \"@tearleads/encoding\";\nimport {\n  encodeVersionVector,\n  exportFullHistorySnapshot,\n} from \"@tearleads/loro\";\nimport type {\n  DocumentsPersistence,\n  StoredDocumentRecord,\n} from \"../../../data/persistence/documents/documentsPersistence\";\nimport type { PendingUpdateFields } from \"../../../data/sqlite/documentPersistence\";\nimport type { ExecSql } from \"../../../data/sqlite/sqlSchema\";\n\nexport function createInitialDocumentRows(input: {\n  currentDoc: Parameters<typeof encodeVersionVector>[0];\n  execSql: ExecSql;\n  persistence: DocumentsPersistence;\n  pendingUpdate?: PendingUpdateFields | undefined;\n  record: StoredDocumentRecord;\n  stillCurrent?: (() => boolean) | undefined;\n  saveClientProjection: Parameters<\n    DocumentsPersistence[\"createDocumentWithHistoryCheckpoint\"]\n  >[4];\n}): Promise<string | null> {\n  return input.persistence.createDocumentWithHistoryCheckpoint(\n    input.execSql,\n    input.record,\n    {\n      endVersionVector: encodeVersionVector(input.currentDoc),\n      snapshot: bytesToBase64(exportFullHistorySnapshot(input.currentDoc)),\n    },\n    input.pendingUpdate || input.stillCurrent\n      ? {\n          ...(input.pendingUpdate\n            ? { pendingUpdate: input.pendingUpdate }\n            : {}),\n          ...(input.stillCurrent ? { stillCurrent: input.stillCurrent } : {}),\n        }\n      : undefined,\n    input.saveClientProjection,\n  );\n}\n"]}

package/workflows/documents/create/index.d.ts

@@ -0,0 +1,56 @@
+import { type ContainerWriterProjectionResponse, type DocumentCreateResponse } 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/index.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>;
+export { documentWriterProjectionFromCreateResponse } from "./createProjection.js";
+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;

package/workflows/documents/create/index.js

@@ -0,0 +1,258 @@
+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 { wrapDocumentContentKeyForCreate } from "../../../data/documents/shared/projection.js";
+import { projectionVerificationOptions } from "../../../data/documents/shared/types.js";
+import { collectContainerWriterProjectionPrincipalPolicies, nullOnProjectionVerificationCancellation, requireProjectionUserKeyResolver, } from "../../../data/keyingProjectionVerification/index.js";
+import { isContainerCreatePending } from "../../../data/persistence/container-contents/pendingContainerCreate.js";
+import { recordDocumentAuthorAccessFailure } from "../authorAccessFailure.js";
+import { isDocumentManifestAlreadyExistsConflict, shouldRetryWithFreshProjection, } from "../syncFailures/syncFailureClassification.js";
+import { adoptExistingRemoteDocument } from "./createAdoption.js";
+import { fetchContainerWriterProjectionForCreate } from "./createProjectionFetch.js";
+import { acknowledgeRemoteDocumentCreate } from "./createResponse.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,
+    };
+}
+export { documentWriterProjectionFromCreateResponse } from "./createProjection.js";
+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)
+        return acknowledgeRemoteDocumentCreate({
+            ...input,
+            ...createPlan,
+            resolveProjectionUserKey,
+            response: submission.data,
+        });
+    // 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=index.js.map

package/workflows/documents/create/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"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","sourcesContent":["import type { DocumentCreateRequest } from \"@tearleads/validators/request\";\nimport {\n  type ContainerWriterProjectionResponse,\n  DOCUMENT_SYNC_ERROR_CODES,\n  type DocumentCreateResponse,\n} from \"@tearleads/validators/response\";\nimport { assertContainerAuthorAccess } from \"../../../data/containers/shared/authorAccess\";\nimport { buildDocumentCreatePlan } from \"../../../data/documents/shared/events\";\nimport { wrapDocumentContentKeyForCreate } from \"../../../data/documents/shared/projection\";\nimport type {\n  CreateRemoteDocumentResult,\n  DocumentCreateApi,\n  DocumentCreateAuthor,\n  MaterializedDocumentCreatePlan,\n  ProjectionVerificationOptions,\n} from \"../../../data/documents/shared/types\";\nimport { projectionVerificationOptions } from \"../../../data/documents/shared/types\";\nimport type {\n  ProjectionUserKeyResolver,\n  ReferencedPrincipalPolicyWarmer,\n} from \"../../../data/keyingProjectionVerification\";\nimport {\n  collectContainerWriterProjectionPrincipalPolicies,\n  nullOnProjectionVerificationCancellation,\n  requireProjectionUserKeyResolver,\n} from \"../../../data/keyingProjectionVerification\";\nimport { isContainerCreatePending } from \"../../../data/persistence/container-contents/pendingContainerCreate\";\nimport type { ExecSql } from \"../../../data/sqlite/sqlSchema\";\nimport { recordDocumentAuthorAccessFailure } from \"../authorAccessFailure\";\nimport {\n  isDocumentManifestAlreadyExistsConflict,\n  shouldRetryWithFreshProjection,\n} from \"../syncFailures/syncFailureClassification\";\nimport { adoptExistingRemoteDocument } from \"./createAdoption\";\nimport type { DocumentCreateTerminalFailureHandler } from \"./createProjectionFetch\";\nimport { fetchContainerWriterProjectionForCreate } from \"./createProjectionFetch\";\nimport { acknowledgeRemoteDocumentCreate } from \"./createResponse\";\n\nexport async function buildMaterializedDocumentCreatePlan(\n  input: {\n    author: DocumentCreateAuthor;\n    containerProjection: ContainerWriterProjectionResponse;\n    contentKey?: Uint8Array | undefined;\n    contentKeyEpoch?: number | undefined;\n    documentId?: string | undefined;\n    eventId?: string | undefined;\n    execSql?: ExecSql | undefined;\n    knownContainerKeks?: ReadonlyMap<string, Uint8Array> | undefined;\n    persistVerificationCheckpoints?: boolean | undefined;\n    signedAt?: string | undefined;\n    targetSecretKey: Uint8Array;\n  } & ProjectionVerificationOptions,\n): Promise<MaterializedDocumentCreatePlan> {\n  const contentKey =\n    input.contentKey ?? crypto.getRandomValues(new Uint8Array(32));\n  if (contentKey.byteLength !== 32) {\n    throw new Error(\"Document content key must be 32 bytes\");\n  }\n  // Resolved before wrapping: each envelope is sealed to its document and\n  // content-key epoch.\n  const documentId = input.documentId ?? crypto.randomUUID();\n  const contentKeyEpoch = input.contentKeyEpoch ?? 1;\n  const targetEnvelopes = await wrapDocumentContentKeyForCreate({\n    contentKey,\n    contentKeyEpoch,\n    documentId,\n    execSql: input.execSql,\n    knownContainerKeks: input.knownContainerKeks,\n    persistVerificationCheckpoints: input.persistVerificationCheckpoints,\n    projection: input.containerProjection,\n    secretKey: input.targetSecretKey,\n    ...projectionVerificationOptions(input),\n  });\n  if (input.resolveProjectionUserKey) {\n    const principalPolicies =\n      await collectContainerWriterProjectionPrincipalPolicies({\n        ...projectionVerificationOptions(input),\n        execSql: input.execSql,\n        projection: input.containerProjection,\n        resolveUserKey: input.resolveProjectionUserKey,\n      });\n    assertContainerAuthorAccess({\n      // Document signing derives its organization from the verified target.\n      author: {\n        ...input.author,\n        organizationId: input.containerProjection.organizationId,\n      },\n      projection: input.containerProjection,\n      principalPolicies,\n      minimumAccess: \"write\",\n    });\n  }\n  // The explicit local-trust variant builds provisioning artifacts before\n  // their new principal policies exist remotely; remote creates cannot use it.\n  const plan = await buildDocumentCreatePlan({\n    author: input.author,\n    containerProjection: input.containerProjection,\n    contentKeyEpoch,\n    documentId,\n    ...(input.eventId === undefined ? {} : { eventId: input.eventId }),\n    ...(input.signedAt === undefined ? {} : { signedAt: input.signedAt }),\n    targetEnvelopes,\n  });\n\n  return {\n    contentKey,\n    plan,\n  };\n}\n\nexport { documentWriterProjectionFromCreateResponse } from \"./createProjection\";\n\ninterface MaterializedDocumentCreatePlanWithProjection {\n  readonly containerProjection: ContainerWriterProjectionResponse;\n  readonly materializedPlan: MaterializedDocumentCreatePlan;\n}\n\nasync function buildMaterializedDocumentCreatePlanWithFreshProjection(input: {\n  apiClient: DocumentCreateApi;\n  author: DocumentCreateAuthor;\n  containerId: string;\n  containerProjection?: ContainerWriterProjectionResponse | undefined;\n  contentKey?: Uint8Array | undefined;\n  contentKeyEpoch?: number | undefined;\n  documentId?: string | undefined;\n  eventId?: string | undefined;\n  execSql: ExecSql;\n  expectedOrganizationId?: string | undefined;\n  knownContainerKeks?: ReadonlyMap<string, Uint8Array> | undefined;\n  onTerminalSubmitFailure?: DocumentCreateTerminalFailureHandler | undefined;\n  persistVerificationCheckpoints?: boolean | undefined;\n  resolveProjectionUserKey: ProjectionUserKeyResolver;\n  signedAt?: string | undefined;\n  stillCurrent?: (() => boolean) | undefined;\n  targetSecretKey: Uint8Array;\n  warmReferencedPrincipalPolicies?: ReferencedPrincipalPolicyWarmer | undefined;\n}): Promise<MaterializedDocumentCreatePlanWithProjection | null> {\n  const buildWithProjection = async (\n    containerProjection: ContainerWriterProjectionResponse,\n  ) => {\n    if (\n      containerProjection.containerId !== input.containerId ||\n      (input.expectedOrganizationId !== undefined &&\n        containerProjection.organizationId !== input.expectedOrganizationId)\n    ) {\n      throw new Error(\n        \"Container writer projection belongs to another container or organization\",\n      );\n    }\n    return {\n      containerProjection,\n      materializedPlan: await buildMaterializedDocumentCreatePlan({\n        author: input.author,\n        containerProjection,\n        contentKey: input.contentKey,\n        contentKeyEpoch: input.contentKeyEpoch,\n        documentId: input.documentId,\n        eventId: input.eventId,\n        execSql: input.execSql,\n        knownContainerKeks: input.knownContainerKeks,\n        persistVerificationCheckpoints: input.persistVerificationCheckpoints,\n        resolveProjectionUserKey: input.resolveProjectionUserKey,\n        signedAt: input.signedAt,\n        stillCurrent: input.stillCurrent,\n        targetSecretKey: input.targetSecretKey,\n        warmReferencedPrincipalPolicies: input.warmReferencedPrincipalPolicies,\n      }),\n    };\n  };\n\n  const containerProjection =\n    input.containerProjection ??\n    (await fetchContainerWriterProjectionForCreate({\n      apiClient: input.apiClient,\n      containerId: input.containerId,\n      onTerminalSubmitFailure: input.onTerminalSubmitFailure,\n    }));\n  if (!containerProjection) {\n    return null;\n  }\n\n  try {\n    return await buildWithProjection(containerProjection);\n  } catch (error) {\n    if (\n      !shouldRetryWithFreshProjection(error, (message) =>\n        message.includes(\"could not be unwrapped\"),\n      )\n    ) {\n      throw error;\n    }\n  }\n\n  // Only this container's projection was stale; evict just it rather than\n  // wiping every cached projection.\n  input.apiClient.evictContainerWriterProjection(input.containerId);\n  const refreshedProjection = await fetchContainerWriterProjectionForCreate({\n    apiClient: input.apiClient,\n    containerId: input.containerId,\n    onTerminalSubmitFailure: input.onTerminalSubmitFailure,\n  });\n  return refreshedProjection ? buildWithProjection(refreshedProjection) : null;\n}\n\ninterface RemoteDocumentCreateInput {\n  apiClient: DocumentCreateApi;\n  author: DocumentCreateAuthor;\n  containerId: string;\n  containerProjection?: ContainerWriterProjectionResponse | undefined;\n  contentKey?: Uint8Array | undefined;\n  contentKeyEpoch?: number | undefined;\n  documentId?: string | undefined;\n  eventId?: string | undefined;\n  execSql: ExecSql;\n  expectedOrganizationId?: string | undefined;\n  isRemoteSyncBlocked?: ((organizationId: string) => boolean) | undefined;\n  knownContainerKeks?: ReadonlyMap<string, Uint8Array> | undefined;\n  /**\n   * Invoked when the create submission fails terminally (not a benign\n   * adopt/stale-target conflict) — e.g. the server denies the write. Callers\n   * persist the failure so the write queue can surface it.\n   */\n  onTerminalSubmitFailure?: DocumentCreateTerminalFailureHandler | undefined;\n  resolveProjectionUserKey: ProjectionUserKeyResolver;\n  signedAt?: string | undefined;\n  stillCurrent?: (() => boolean) | undefined;\n  targetSecretKey: Uint8Array;\n  warmReferencedPrincipalPolicies?: ReferencedPrincipalPolicyWarmer | undefined;\n}\n\nfunction isRemoteDocumentCreatePlanBlocked(\n  input: RemoteDocumentCreateInput,\n  createPlan: MaterializedDocumentCreatePlanWithProjection,\n): boolean {\n  const organizationId = createPlan.containerProjection.organizationId;\n  return input.isRemoteSyncBlocked?.(organizationId) ?? false;\n}\n\nasync function submitPlannedDocumentCreate(\n  input: RemoteDocumentCreateInput,\n  resolveProjectionUserKey: ProjectionUserKeyResolver,\n): Promise<{\n  readonly createPlan: MaterializedDocumentCreatePlanWithProjection;\n  readonly submission: DocumentCreateSubmission;\n} | null> {\n  const verificationOptions = { stillCurrent: input.stillCurrent };\n  const warmReferencedPrincipalPolicies = input.warmReferencedPrincipalPolicies;\n  let createPlan = await buildMaterializedDocumentCreatePlanWithFreshProjection(\n    {\n      apiClient: input.apiClient,\n      author: input.author,\n      containerId: input.containerId,\n      containerProjection: input.containerProjection,\n      contentKey: input.contentKey,\n      contentKeyEpoch: input.contentKeyEpoch,\n      documentId: input.documentId,\n      eventId: input.eventId,\n      execSql: input.execSql,\n      expectedOrganizationId: input.expectedOrganizationId,\n      knownContainerKeks: input.knownContainerKeks,\n      onTerminalSubmitFailure: input.onTerminalSubmitFailure,\n      resolveProjectionUserKey,\n      signedAt: input.signedAt,\n      targetSecretKey: input.targetSecretKey,\n      warmReferencedPrincipalPolicies,\n      ...verificationOptions,\n    },\n  );\n  if (!createPlan) {\n    return null;\n  }\n  if (isRemoteDocumentCreatePlanBlocked(input, createPlan)) return null;\n  if (input.stillCurrent?.() === false) return null;\n  let submission = await submitDocumentCreate(\n    input.apiClient,\n    createPlan.materializedPlan.plan.request,\n    createPlan.containerProjection.organizationId,\n  );\n  if (isStaleDocumentCreateTargetConflict(submission)) {\n    if (input.stillCurrent?.() === false) {\n      return { createPlan, submission };\n    }\n    input.apiClient.evictContainerWriterProjection(input.containerId);\n    const firstPlan = createPlan.materializedPlan;\n    const refreshedPlan =\n      await buildMaterializedDocumentCreatePlanWithFreshProjection({\n        apiClient: input.apiClient,\n        author: input.author,\n        containerId: input.containerId,\n        contentKey: firstPlan.contentKey,\n        contentKeyEpoch:\n          firstPlan.plan.request.contentKeyBundle.contentKeyEpoch,\n        documentId: firstPlan.plan.documentId,\n        eventId: firstPlan.plan.event.eventId,\n        execSql: input.execSql,\n        expectedOrganizationId: input.expectedOrganizationId,\n        knownContainerKeks: input.knownContainerKeks,\n        onTerminalSubmitFailure: input.onTerminalSubmitFailure,\n        resolveProjectionUserKey,\n        signedAt: firstPlan.plan.event.signedAt,\n        targetSecretKey: input.targetSecretKey,\n        warmReferencedPrincipalPolicies,\n        ...verificationOptions,\n      });\n    if (!refreshedPlan) {\n      return null;\n    }\n    if (isRemoteDocumentCreatePlanBlocked(input, refreshedPlan)) return null;\n    createPlan = refreshedPlan;\n    if (input.stillCurrent?.() === false) return null;\n    submission = await submitDocumentCreate(\n      input.apiClient,\n      createPlan.materializedPlan.plan.request,\n      createPlan.containerProjection.organizationId,\n    );\n  }\n  return { createPlan, submission };\n}\n\nexport async function createRemoteDocument(\n  input: RemoteDocumentCreateInput,\n): Promise<CreateRemoteDocumentResult | null> {\n  // The store retries once the folder's own create settles.\n  if (await isContainerCreatePending(input.execSql, input.containerId)) {\n    return null;\n  }\n  const resolveProjectionUserKey = requireProjectionUserKeyResolver(\n    input.resolveProjectionUserKey,\n    \"Remote document create\",\n  );\n  const plannedSubmission = await recordDocumentAuthorAccessFailure(\n    () =>\n      nullOnProjectionVerificationCancellation(() =>\n        submitPlannedDocumentCreate(input, resolveProjectionUserKey),\n      ),\n    input.onTerminalSubmitFailure,\n  );\n  if (!plannedSubmission) {\n    return null;\n  }\n  const { createPlan, submission } = plannedSubmission;\n  if (input.stillCurrent?.() === false) return null;\n  if (submission.ok)\n    return acknowledgeRemoteDocumentCreate({\n      ...input,\n      ...createPlan,\n      resolveProjectionUserKey,\n      response: submission.data,\n    });\n\n  // A stable documentId means a retry after a lost create response re-submits\n  // the same id; the server then reports the manifest already exists. That is\n  // not a failure — the first attempt committed. Adopt the existing remote\n  // document instead of leaking a duplicate. Requires the stable id we sent, so\n  // we can fetch its projection back.\n  const stableDocumentId = input.documentId;\n  if (stableDocumentId && isDocumentManifestAlreadyExistsConflict(submission)) {\n    if (input.stillCurrent?.() === false) return null;\n    const adopted = await nullOnProjectionVerificationCancellation(() =>\n      adoptExistingRemoteDocument({\n        apiClient: input.apiClient,\n        documentId: stableDocumentId,\n        execSql: input.execSql,\n        expectedContainerId: input.containerId,\n        expectedOrganizationId:\n          input.expectedOrganizationId ??\n          createPlan.containerProjection.organizationId,\n        expectedSignerUserId: input.author.signerUserId,\n        resolveProjectionUserKey,\n        stillCurrent: input.stillCurrent,\n        targetSecretKey: input.targetSecretKey,\n        warmReferencedPrincipalPolicies: input.warmReferencedPrincipalPolicies,\n      }),\n    );\n    if (adopted) {\n      return adopted;\n    }\n    // A conflict is the expected, benign outcome of an idempotent retry after a\n    // lost create response. If adoption cannot complete yet (e.g. the writer\n    // projection fetch failed transiently), do not surface the conflict as a UI\n    // error — the sync engine retries and adopts it on a later tick.\n    return null;\n  }\n\n  submission.report?.();\n  await input.onTerminalSubmitFailure?.(submission);\n  return null;\n}\n\ntype DocumentCreateSubmission =\n  | {\n      readonly data: DocumentCreateResponse;\n      readonly ok: true;\n    }\n  | {\n      readonly code?: string | undefined;\n      readonly message: string;\n      readonly ok: false;\n      readonly report?: (() => void) | undefined;\n      readonly status: number | null;\n    };\n\nexport function isStaleDocumentCreateTargetConflict(\n  submission: DocumentCreateSubmission,\n): boolean {\n  return (\n    !submission.ok &&\n    submission.status === 409 &&\n    submission.code === DOCUMENT_SYNC_ERROR_CODES.stateStale\n  );\n}\n\nasync function submitDocumentCreate(\n  apiClient: DocumentCreateApi,\n  request: DocumentCreateRequest,\n  expectedOrganizationId: string,\n): Promise<DocumentCreateSubmission> {\n  return apiClient.createDocumentResult(request, {\n    expectedPaymentRequiredOrganizationId: expectedOrganizationId,\n    reportErrors: false,\n  });\n}\n"]}