@adcp/sdk 14.1.0 → 14.2.0

package/dist/lib/core/buyer-account-registry.js

@@ -28,25 +28,32 @@ var import_account_resolution = require('./account-resolution.js');
 var import_errors = require('../errors/index.js');
 var import_abort = require('../protocols/abort.js');
 var import_task_deadline = require('./task-deadline.js');
+var import_idempotency = require('../utils/idempotency.js');
 function setupTerms(options) {
   const stable = (value) => Array.isArray(value) ? value.map(stable) : value && typeof value === "object" ? Object.fromEntries(
     Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => [key, stable(item)])
   ) : value;
   return Object.fromEntries(
-    Object.entries(options).map(([key, value]) => [
+    Object.entries(options).filter(([key]) => key !== "idempotencyKey").map(([key, value]) => [
       key,
       (0, import_node_crypto.createHash)("sha256").update(JSON.stringify(stable(value))).digest("hex")
     ])
   );
 }
+function isDefinitiveRejection(result) {
+  return Boolean(
+    result.adcpError && !result.adcpError.synthetic && !result.adcpError.code.startsWith("IDEMPOTENCY_") && ["terminal", "correctable"].includes(result.adcpError.recovery ?? "")
+  );
+}
 class BuyerAccountRegistry {
-  constructor(scope, provision, storage, repair, options = {}) {
+  constructor(scope, provision, storage, repair, registryOptions = {}) {
     this.scope = scope;
     this.provision = provision;
     this.storage = storage;
     this.repair = repair;
-    this.maxEntries = options.maxEntries ?? 1e4;
-    this.normalizeOptions = options.normalizeOptions;
+    this.registryOptions = registryOptions;
+    this.maxEntries = registryOptions.maxEntries ?? 1e4;
+    this.normalizeOptions = registryOptions.normalizeOptions;
     if (!Number.isSafeInteger(this.maxEntries) || this.maxEntries < 2)
       throw new Error("Account registry maxEntries must be an integer >= 2.");
   }
@@ -54,6 +61,7 @@ class BuyerAccountRegistry {
   provision;
   storage;
   repair;
+  registryOptions;
   entries = /* @__PURE__ */ new Map();
   pending = /* @__PURE__ */ new Map();
   writes = Promise.resolve();
@@ -87,13 +95,15 @@ class BuyerAccountRegistry {
   }
   async get(account) {
     const key = this.key(account);
-    let entry = this.entries.get(key);
-    if (!entry) {
+    let entry = this.storage?.compareAndSet ? await this.storage.get(key) : this.entries.get(key);
+    if (!entry && !this.storage?.compareAndSet) {
       const persisted = await this.storage?.get(key);
       entry = this.entries.get(key) ?? persisted;
     }
     if (key !== this.key(account) || entry && (0, import_account_key.accountReferenceKey)(entry.account) !== (0, import_account_key.accountReferenceKey)(account))
       return void 0;
+    if (entry && this.storage?.compareAndSet && (!Number.isSafeInteger(entry.revision) || entry.revision < 1))
+      throw new Error("CAS account storage must return a positive integer revision.");
     if (entry) this.remember(key, entry);
     if (entry?.account_id && this.invalidatedHandles.has(this.key({ account_id: entry.account_id })))
       return { ...structuredClone(entry), status: "unknown" };
@@ -106,6 +116,8 @@ class BuyerAccountRegistry {
     account = structuredClone(account);
     if (this.normalizeOptions) options = await this.normalizeOptions(structuredClone(options), taskOptions);
     options = structuredClone(Object.fromEntries(Object.entries(options).filter(([, value]) => value !== void 0)));
+    if (options.idempotencyKey !== void 0 && !(0, import_idempotency.isValidIdempotencyKey)(options.idempotencyKey))
+      throw new TypeError("idempotencyKey must match [A-Za-z0-9_.:-]{16,255}.");
     const scope = this.scope();
     const key = this.key(account, scope);
     const current = await this.get(account);
@@ -118,7 +130,9 @@ class BuyerAccountRegistry {
     );
     if (shared) {
       if (!(0, import_node_util.isDeepStrictEqual)(shared.options, options))
-        throw new import_errors.AccountSetupRequiredError("Provisioning is already in progress with different billing terms.");
+        throw new import_errors.AccountSetupRequiredError(
+          "Provisioning is already in progress with different billing terms or idempotency keys."
+        );
       const entry2 = await wait(shared.promise);
       if (shared.result) onTaskResult?.(shared.result);
       return entry2;
@@ -157,6 +171,10 @@ class BuyerAccountRegistry {
         throw new import_errors.AccountNotFoundError(
           "Reconcile this account with listAccounts or explicitly reestablish it with syncAccounts."
         );
+      if (current.status === "provisioning" && current.dispatch)
+        throw new import_errors.AccountSetupRequiredError(
+          `Provisioning is claimed or in doubt in durable storage.${current.pendingTaskId ? ` Recover task ${current.pendingTaskId}.` : ""} Reconcile the recorded idempotency key and observeSync before retrying.`
+        );
       if (current.status === "provisioning" && current.pendingTaskId)
         throw new import_errors.AccountSetupRequiredError(
           `Reconcile pending sync_accounts task ${current.pendingTaskId} and observe its completed account rows before provisioning again.`
@@ -186,42 +204,97 @@ class BuyerAccountRegistry {
     };
     const operationOptions = { ...taskOptions, signal: void 0, timeout: void 0 };
     const observationEpoch = this.captureObservation();
-    const request = this.provision(structuredClone(account), pending.options, operationOptions).then(async (initial) => {
+    const idempotencyKey = options.idempotencyKey ?? (0, import_node_crypto.randomUUID)();
+    const dispatch = { storageKey: key, account: structuredClone(account), idempotencyKey };
+    let claimRevision;
+    let dispatched = false;
+    const releaseClaim = async () => {
+      if (!this.storage?.compareAndSet || claimRevision === void 0) return;
+      const latest = await this.storage.get(key);
+      if (latest?.revision !== claimRevision || latest.dispatch?.idempotencyKey !== idempotencyKey) return;
+      await this.write({ ...latest, status: "failed_provisioning", dispatch: void 0 }, scope);
+    };
+    const beforeDispatch = async () => {
+      if (scope !== this.scope()) throw new import_errors.AccountNotFoundError("Caller credentials changed before dispatch.");
+      if (this.storage?.compareAndSet) {
+        await this.write(
+          {
+            account,
+            status: "provisioning",
+            setupTerms: terms,
+            revision: current?.revision,
+            dispatch: { idempotencyKey, startedAt: (/* @__PURE__ */ new Date()).toISOString() }
+          },
+          scope
+        );
+        claimRevision = (current?.revision ?? 0) + 1;
+      }
+      await this.registryOptions.onDispatchStart?.(structuredClone(dispatch));
+      if (scope !== this.scope()) throw new import_errors.AccountNotFoundError("Caller credentials changed before dispatch.");
+      dispatched = true;
+    };
+    const request = (async () => {
+      try {
+        if (!this.registryOptions.provisionOwnsDispatchBoundary) await beforeDispatch();
+        return await this.provision(structuredClone(account), pending.options, operationOptions, {
+          idempotencyKey,
+          beforeDispatch,
+          requireIdempotencyKey: Boolean(
+            options.idempotencyKey || this.storage?.compareAndSet || this.registryOptions.onDispatchStart || this.registryOptions.onResult
+          )
+        });
+      } catch (error) {
+        if (!dispatched) await releaseClaim();
+        throw error;
+      }
+    })().then(async (initial) => {
       let result = initial;
       pending.result = result;
+      if (dispatched) await this.registryOptions.onResult?.({ ...structuredClone(dispatch), result });
       notify(result);
       if (this.key(account) !== key) throw new import_errors.AccountNotFoundError("Caller credentials changed during provisioning.");
-      if (!result.success)
+      if (!result.success) {
+        if (!dispatched || isDefinitiveRejection(result)) await releaseClaim();
         throw (0, import_errors.adcpErrorToTypedError)(result.adcpError ?? { code: "ACCOUNT_NOT_FOUND", message: result.error }) ?? new Error(result.error);
+      }
       if (result.status !== "completed") {
         const provisional = {
           account: structuredClone(account),
           status: "provisioning",
           setupTerms: current?.setupTerms ?? terms,
-          ...result.metadata.taskId && { pendingTaskId: result.metadata.taskId }
+          ...(result.metadata.serverTaskId ?? result.metadata.taskId) && {
+            pendingTaskId: result.metadata.serverTaskId ?? result.metadata.taskId
+          }
         };
         await this.enqueue(async () => {
           const latest = await this.get(account);
-          if (!latest || latest.status === "failed_provisioning" || latest.status === current?.status && latest.account_id === current?.account_id)
-            await this.write(provisional, scope);
+          if (this.storage?.compareAndSet ? latest?.revision === claimRevision && latest?.dispatch?.idempotencyKey === idempotencyKey : !latest || latest.status === "failed_provisioning" || latest.status === current?.status && latest.account_id === current?.account_id) {
+            await this.write({ ...provisional, revision: latest?.revision, dispatch: latest?.dispatch }, scope);
+            if (claimRevision !== void 0) claimRevision = (latest?.revision ?? 0) + 1;
+          }
         });
         if (!result.submitted) return provisional;
         result = await result.submitted.waitForCompletion();
         pending.result = result;
+        await this.registryOptions.onResult?.({ ...structuredClone(dispatch), result });
         notify(result);
         if (!result.success) {
-          await this.enqueue(async () => {
-            const latest = await this.get(account);
-            if (!latest || latest.status === "provisioning")
-              await this.write(
-                {
-                  account: structuredClone(account),
-                  status: "failed_provisioning",
-                  setupTerms: current?.setupTerms ?? terms
-                },
-                scope
-              );
-          });
+          if (this.storage?.compareAndSet) {
+            if (isDefinitiveRejection(result)) await releaseClaim();
+          } else {
+            await this.enqueue(async () => {
+              const latest = await this.get(account);
+              if (!latest || latest.status === "provisioning")
+                await this.write(
+                  {
+                    account: structuredClone(account),
+                    status: "failed_provisioning",
+                    setupTerms: current?.setupTerms ?? terms
+                  },
+                  scope
+                );
+            });
+          }
           throw (0, import_errors.adcpErrorToTypedError)(result.adcpError ?? { code: "ACCOUNT_SETUP_REQUIRED", message: result.error }) ?? new Error(result.error);
         }
       }
@@ -230,35 +303,36 @@ class BuyerAccountRegistry {
         throw new import_errors.AccountSetupRequiredError(
           "sync_accounts has not completed; observe its completion before provisioning again."
         );
-      await this.observeSync([account], result.data.accounts, false, observationEpoch);
+      await this.observeSync([account], result.data.accounts, false, observationEpoch, claimRevision);
       const entry2 = await this.get(account);
       if (scope !== this.scope()) throw new import_errors.AccountNotFoundError("Caller credentials changed during provisioning.");
       if (!entry2 || entry2.status === "provisioning" || entry2.status === "failed_provisioning") {
-        await this.enqueue(async () => {
-          const latest = await this.get(account);
-          if (!latest || ["provisioning", "failed_provisioning"].includes(latest.status))
-            await this.write(
-              {
-                account,
-                status: "failed_provisioning",
-                setupTerms: current?.setupTerms ?? terms
-              },
-              scope
-            );
-        });
+        if (this.storage?.compareAndSet) await releaseClaim();
+        else
+          await this.enqueue(async () => {
+            const latest = await this.get(account);
+            if (!latest || ["provisioning", "failed_provisioning"].includes(latest.status))
+              await this.write(
+                { account, status: "failed_provisioning", setupTerms: current?.setupTerms ?? terms },
+                scope
+              );
+          });
         const failed = result.data.accounts.find((row) => row.action === "failed");
         const error = failed?.errors?.[0];
         throw (error && (0, import_errors.adcpErrorToTypedError)(error)) ?? new import_errors.AccountNotFoundError("sync_accounts did not establish the requested account.");
       }
+      if (claimRevision !== void 0 && entry2.revision !== claimRevision + 1) return entry2;
       let settled = entry2;
       await this.enqueue(async () => {
         const latest = await this.get(account);
         if (scope !== this.scope()) throw new import_errors.AccountNotFoundError("Caller credentials changed during provisioning.");
         if (!latest) throw new import_errors.AccountNotFoundError("The provisioned account is no longer registered.");
         settled = latest;
-        if (latest.account_id !== entry2.account_id) return;
+        if (latest.account_id !== entry2.account_id || this.storage?.compareAndSet && latest.revision !== entry2.revision)
+          return;
         settled = { ...latest, setupTerms: setupTerms(options) };
         await this.write(settled, scope);
+        settled = await this.get(account) ?? settled;
         if (settled.account_id && !("account_id" in account)) {
           const idEntry = await this.get({ account_id: settled.account_id });
           if (scope !== this.scope()) throw new import_errors.AccountNotFoundError("Caller credentials changed during provisioning.");
@@ -280,16 +354,24 @@ class BuyerAccountRegistry {
   async write(entry, scope, isCurrent = () => true) {
     if (!isCurrent()) return;
     const key = this.key(entry.account, scope);
+    if (this.storage?.compareAndSet) {
+      const revision = entry.revision;
+      entry = { ...entry, revision: (revision ?? 0) + 1 };
+      if (!await this.storage.compareAndSet(key, revision, structuredClone(entry)))
+        throw new import_errors.AccountSetupRequiredError("Account storage revision changed. Reload and reconcile before retrying.");
+    } else {
+      await this.storage?.set(key, structuredClone(entry));
+    }
     if (scope === this.scope()) this.remember(key, entry);
-    await this.storage?.set(key, structuredClone(entry));
   }
-  async record(ref, row, scope, preserveTerms = false, isCurrent = () => true) {
+  async record(ref, row, scope, preserveTerms = false, isCurrent = () => true, expectedRevision) {
     const entry = {
       account: structuredClone(ref),
       status: row.status,
       ...row.account_id && { account_id: row.account_id }
     };
     const prior = await this.get(ref);
+    if (expectedRevision !== void 0 && prior?.revision !== expectedRevision) return;
     if (scope !== this.scope() || !isCurrent()) return;
     const idRef = row.account_id && !("account_id" in ref) ? { account_id: row.account_id } : void 0;
     const priorId = idRef ? await this.get(idRef) : void 0;
@@ -311,6 +393,7 @@ class BuyerAccountRegistry {
         );
       }
     }
+    entry.revision = prior?.revision;
     if (preserveTerms && prior?.setupTerms) entry.setupTerms = prior.setupTerms;
     if ("account_id" in ref) {
       if (prior?.aliases) entry.aliases = prior.aliases;
@@ -320,6 +403,7 @@ class BuyerAccountRegistry {
     await this.write(
       {
         account: idRef,
+        revision: priorId?.revision,
         account_id: row.account_id,
         status: row.status,
         aliases: [...aliases.values()],
@@ -335,7 +419,7 @@ class BuyerAccountRegistry {
     });
     return next;
   }
-  async observeSync(refs, rows, dryRun = false, observationEpoch) {
+  async observeSync(refs, rows, dryRun = false, observationEpoch, expectedRevision) {
     if (dryRun) return;
     const scope = this.scope();
     return this.enqueue(async () => {
@@ -367,7 +451,7 @@ class BuyerAccountRegistry {
           repairedBinding = true;
         }
         const isCurrent = () => scope === this.scope() && this.observationIsCurrent(row.account_id, rowEpoch, scope);
-        await this.record(ref, row, scope, false, isCurrent);
+        await this.record(ref, row, scope, false, isCurrent, expectedRevision);
         if (!isCurrent() || repairedBinding) continue;
         for (const id of [row.account_id])
           if (id) {

package/dist/lib/core/buyer-account-registry.mjs

@@ -1,29 +1,36 @@
 import { isDeepStrictEqual } from "node:util";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { accountReferenceKey } from "./account-key.mjs";
 import { sameCountrySet } from "./account-resolution.mjs";
 import { adcpErrorToTypedError, AccountNotFoundError, AccountSetupRequiredError } from "../errors/index.mjs";
 import { isAbortOrTimeoutError, MAX_TIMER_DELAY_MS, throwIfAborted, withAbortSignal } from "../protocols/abort.mjs";
 import { withTaskDeadline } from "./task-deadline.mjs";
+import { isValidIdempotencyKey } from "../utils/idempotency.mjs";
 function setupTerms(options) {
   const stable = (value) => Array.isArray(value) ? value.map(stable) : value && typeof value === "object" ? Object.fromEntries(
     Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => [key, stable(item)])
   ) : value;
   return Object.fromEntries(
-    Object.entries(options).map(([key, value]) => [
+    Object.entries(options).filter(([key]) => key !== "idempotencyKey").map(([key, value]) => [
       key,
       createHash("sha256").update(JSON.stringify(stable(value))).digest("hex")
     ])
   );
 }
+function isDefinitiveRejection(result) {
+  return Boolean(
+    result.adcpError && !result.adcpError.synthetic && !result.adcpError.code.startsWith("IDEMPOTENCY_") && ["terminal", "correctable"].includes(result.adcpError.recovery ?? "")
+  );
+}
 class BuyerAccountRegistry {
-  constructor(scope, provision, storage, repair, options = {}) {
+  constructor(scope, provision, storage, repair, registryOptions = {}) {
     this.scope = scope;
     this.provision = provision;
     this.storage = storage;
     this.repair = repair;
-    this.maxEntries = options.maxEntries ?? 1e4;
-    this.normalizeOptions = options.normalizeOptions;
+    this.registryOptions = registryOptions;
+    this.maxEntries = registryOptions.maxEntries ?? 1e4;
+    this.normalizeOptions = registryOptions.normalizeOptions;
     if (!Number.isSafeInteger(this.maxEntries) || this.maxEntries < 2)
       throw new Error("Account registry maxEntries must be an integer >= 2.");
   }
@@ -31,6 +38,7 @@ class BuyerAccountRegistry {
   provision;
   storage;
   repair;
+  registryOptions;
   entries = /* @__PURE__ */ new Map();
   pending = /* @__PURE__ */ new Map();
   writes = Promise.resolve();
@@ -64,13 +72,15 @@ class BuyerAccountRegistry {
   }
   async get(account) {
     const key = this.key(account);
-    let entry = this.entries.get(key);
-    if (!entry) {
+    let entry = this.storage?.compareAndSet ? await this.storage.get(key) : this.entries.get(key);
+    if (!entry && !this.storage?.compareAndSet) {
       const persisted = await this.storage?.get(key);
       entry = this.entries.get(key) ?? persisted;
     }
     if (key !== this.key(account) || entry && accountReferenceKey(entry.account) !== accountReferenceKey(account))
       return void 0;
+    if (entry && this.storage?.compareAndSet && (!Number.isSafeInteger(entry.revision) || entry.revision < 1))
+      throw new Error("CAS account storage must return a positive integer revision.");
     if (entry) this.remember(key, entry);
     if (entry?.account_id && this.invalidatedHandles.has(this.key({ account_id: entry.account_id })))
       return { ...structuredClone(entry), status: "unknown" };
@@ -83,6 +93,8 @@ class BuyerAccountRegistry {
     account = structuredClone(account);
     if (this.normalizeOptions) options = await this.normalizeOptions(structuredClone(options), taskOptions);
     options = structuredClone(Object.fromEntries(Object.entries(options).filter(([, value]) => value !== void 0)));
+    if (options.idempotencyKey !== void 0 && !isValidIdempotencyKey(options.idempotencyKey))
+      throw new TypeError("idempotencyKey must match [A-Za-z0-9_.:-]{16,255}.");
     const scope = this.scope();
     const key = this.key(account, scope);
     const current = await this.get(account);
@@ -95,7 +107,9 @@ class BuyerAccountRegistry {
     );
     if (shared) {
       if (!isDeepStrictEqual(shared.options, options))
-        throw new AccountSetupRequiredError("Provisioning is already in progress with different billing terms.");
+        throw new AccountSetupRequiredError(
+          "Provisioning is already in progress with different billing terms or idempotency keys."
+        );
       const entry2 = await wait(shared.promise);
       if (shared.result) onTaskResult?.(shared.result);
       return entry2;
@@ -134,6 +148,10 @@ class BuyerAccountRegistry {
         throw new AccountNotFoundError(
           "Reconcile this account with listAccounts or explicitly reestablish it with syncAccounts."
         );
+      if (current.status === "provisioning" && current.dispatch)
+        throw new AccountSetupRequiredError(
+          `Provisioning is claimed or in doubt in durable storage.${current.pendingTaskId ? ` Recover task ${current.pendingTaskId}.` : ""} Reconcile the recorded idempotency key and observeSync before retrying.`
+        );
       if (current.status === "provisioning" && current.pendingTaskId)
         throw new AccountSetupRequiredError(
           `Reconcile pending sync_accounts task ${current.pendingTaskId} and observe its completed account rows before provisioning again.`
@@ -163,42 +181,97 @@ class BuyerAccountRegistry {
     };
     const operationOptions = { ...taskOptions, signal: void 0, timeout: void 0 };
     const observationEpoch = this.captureObservation();
-    const request = this.provision(structuredClone(account), pending.options, operationOptions).then(async (initial) => {
+    const idempotencyKey = options.idempotencyKey ?? randomUUID();
+    const dispatch = { storageKey: key, account: structuredClone(account), idempotencyKey };
+    let claimRevision;
+    let dispatched = false;
+    const releaseClaim = async () => {
+      if (!this.storage?.compareAndSet || claimRevision === void 0) return;
+      const latest = await this.storage.get(key);
+      if (latest?.revision !== claimRevision || latest.dispatch?.idempotencyKey !== idempotencyKey) return;
+      await this.write({ ...latest, status: "failed_provisioning", dispatch: void 0 }, scope);
+    };
+    const beforeDispatch = async () => {
+      if (scope !== this.scope()) throw new AccountNotFoundError("Caller credentials changed before dispatch.");
+      if (this.storage?.compareAndSet) {
+        await this.write(
+          {
+            account,
+            status: "provisioning",
+            setupTerms: terms,
+            revision: current?.revision,
+            dispatch: { idempotencyKey, startedAt: (/* @__PURE__ */ new Date()).toISOString() }
+          },
+          scope
+        );
+        claimRevision = (current?.revision ?? 0) + 1;
+      }
+      await this.registryOptions.onDispatchStart?.(structuredClone(dispatch));
+      if (scope !== this.scope()) throw new AccountNotFoundError("Caller credentials changed before dispatch.");
+      dispatched = true;
+    };
+    const request = (async () => {
+      try {
+        if (!this.registryOptions.provisionOwnsDispatchBoundary) await beforeDispatch();
+        return await this.provision(structuredClone(account), pending.options, operationOptions, {
+          idempotencyKey,
+          beforeDispatch,
+          requireIdempotencyKey: Boolean(
+            options.idempotencyKey || this.storage?.compareAndSet || this.registryOptions.onDispatchStart || this.registryOptions.onResult
+          )
+        });
+      } catch (error) {
+        if (!dispatched) await releaseClaim();
+        throw error;
+      }
+    })().then(async (initial) => {
       let result = initial;
       pending.result = result;
+      if (dispatched) await this.registryOptions.onResult?.({ ...structuredClone(dispatch), result });
       notify(result);
       if (this.key(account) !== key) throw new AccountNotFoundError("Caller credentials changed during provisioning.");
-      if (!result.success)
+      if (!result.success) {
+        if (!dispatched || isDefinitiveRejection(result)) await releaseClaim();
         throw adcpErrorToTypedError(result.adcpError ?? { code: "ACCOUNT_NOT_FOUND", message: result.error }) ?? new Error(result.error);
+      }
       if (result.status !== "completed") {
         const provisional = {
           account: structuredClone(account),
           status: "provisioning",
           setupTerms: current?.setupTerms ?? terms,
-          ...result.metadata.taskId && { pendingTaskId: result.metadata.taskId }
+          ...(result.metadata.serverTaskId ?? result.metadata.taskId) && {
+            pendingTaskId: result.metadata.serverTaskId ?? result.metadata.taskId
+          }
         };
         await this.enqueue(async () => {
           const latest = await this.get(account);
-          if (!latest || latest.status === "failed_provisioning" || latest.status === current?.status && latest.account_id === current?.account_id)
-            await this.write(provisional, scope);
+          if (this.storage?.compareAndSet ? latest?.revision === claimRevision && latest?.dispatch?.idempotencyKey === idempotencyKey : !latest || latest.status === "failed_provisioning" || latest.status === current?.status && latest.account_id === current?.account_id) {
+            await this.write({ ...provisional, revision: latest?.revision, dispatch: latest?.dispatch }, scope);
+            if (claimRevision !== void 0) claimRevision = (latest?.revision ?? 0) + 1;
+          }
         });
         if (!result.submitted) return provisional;
         result = await result.submitted.waitForCompletion();
         pending.result = result;
+        await this.registryOptions.onResult?.({ ...structuredClone(dispatch), result });
         notify(result);
         if (!result.success) {
-          await this.enqueue(async () => {
-            const latest = await this.get(account);
-            if (!latest || latest.status === "provisioning")
-              await this.write(
-                {
-                  account: structuredClone(account),
-                  status: "failed_provisioning",
-                  setupTerms: current?.setupTerms ?? terms
-                },
-                scope
-              );
-          });
+          if (this.storage?.compareAndSet) {
+            if (isDefinitiveRejection(result)) await releaseClaim();
+          } else {
+            await this.enqueue(async () => {
+              const latest = await this.get(account);
+              if (!latest || latest.status === "provisioning")
+                await this.write(
+                  {
+                    account: structuredClone(account),
+                    status: "failed_provisioning",
+                    setupTerms: current?.setupTerms ?? terms
+                  },
+                  scope
+                );
+            });
+          }
           throw adcpErrorToTypedError(result.adcpError ?? { code: "ACCOUNT_SETUP_REQUIRED", message: result.error }) ?? new Error(result.error);
         }
       }
@@ -207,35 +280,36 @@ class BuyerAccountRegistry {
         throw new AccountSetupRequiredError(
           "sync_accounts has not completed; observe its completion before provisioning again."
         );
-      await this.observeSync([account], result.data.accounts, false, observationEpoch);
+      await this.observeSync([account], result.data.accounts, false, observationEpoch, claimRevision);
       const entry2 = await this.get(account);
       if (scope !== this.scope()) throw new AccountNotFoundError("Caller credentials changed during provisioning.");
       if (!entry2 || entry2.status === "provisioning" || entry2.status === "failed_provisioning") {
-        await this.enqueue(async () => {
-          const latest = await this.get(account);
-          if (!latest || ["provisioning", "failed_provisioning"].includes(latest.status))
-            await this.write(
-              {
-                account,
-                status: "failed_provisioning",
-                setupTerms: current?.setupTerms ?? terms
-              },
-              scope
-            );
-        });
+        if (this.storage?.compareAndSet) await releaseClaim();
+        else
+          await this.enqueue(async () => {
+            const latest = await this.get(account);
+            if (!latest || ["provisioning", "failed_provisioning"].includes(latest.status))
+              await this.write(
+                { account, status: "failed_provisioning", setupTerms: current?.setupTerms ?? terms },
+                scope
+              );
+          });
         const failed = result.data.accounts.find((row) => row.action === "failed");
         const error = failed?.errors?.[0];
         throw (error && adcpErrorToTypedError(error)) ?? new AccountNotFoundError("sync_accounts did not establish the requested account.");
       }
+      if (claimRevision !== void 0 && entry2.revision !== claimRevision + 1) return entry2;
       let settled = entry2;
       await this.enqueue(async () => {
         const latest = await this.get(account);
         if (scope !== this.scope()) throw new AccountNotFoundError("Caller credentials changed during provisioning.");
         if (!latest) throw new AccountNotFoundError("The provisioned account is no longer registered.");
         settled = latest;
-        if (latest.account_id !== entry2.account_id) return;
+        if (latest.account_id !== entry2.account_id || this.storage?.compareAndSet && latest.revision !== entry2.revision)
+          return;
         settled = { ...latest, setupTerms: setupTerms(options) };
         await this.write(settled, scope);
+        settled = await this.get(account) ?? settled;
         if (settled.account_id && !("account_id" in account)) {
           const idEntry = await this.get({ account_id: settled.account_id });
           if (scope !== this.scope()) throw new AccountNotFoundError("Caller credentials changed during provisioning.");
@@ -257,16 +331,24 @@ class BuyerAccountRegistry {
   async write(entry, scope, isCurrent = () => true) {
     if (!isCurrent()) return;
     const key = this.key(entry.account, scope);
+    if (this.storage?.compareAndSet) {
+      const revision = entry.revision;
+      entry = { ...entry, revision: (revision ?? 0) + 1 };
+      if (!await this.storage.compareAndSet(key, revision, structuredClone(entry)))
+        throw new AccountSetupRequiredError("Account storage revision changed. Reload and reconcile before retrying.");
+    } else {
+      await this.storage?.set(key, structuredClone(entry));
+    }
     if (scope === this.scope()) this.remember(key, entry);
-    await this.storage?.set(key, structuredClone(entry));
   }
-  async record(ref, row, scope, preserveTerms = false, isCurrent = () => true) {
+  async record(ref, row, scope, preserveTerms = false, isCurrent = () => true, expectedRevision) {
     const entry = {
       account: structuredClone(ref),
       status: row.status,
       ...row.account_id && { account_id: row.account_id }
     };
     const prior = await this.get(ref);
+    if (expectedRevision !== void 0 && prior?.revision !== expectedRevision) return;
     if (scope !== this.scope() || !isCurrent()) return;
     const idRef = row.account_id && !("account_id" in ref) ? { account_id: row.account_id } : void 0;
     const priorId = idRef ? await this.get(idRef) : void 0;
@@ -288,6 +370,7 @@ class BuyerAccountRegistry {
         );
       }
     }
+    entry.revision = prior?.revision;
     if (preserveTerms && prior?.setupTerms) entry.setupTerms = prior.setupTerms;
     if ("account_id" in ref) {
       if (prior?.aliases) entry.aliases = prior.aliases;
@@ -297,6 +380,7 @@ class BuyerAccountRegistry {
     await this.write(
       {
         account: idRef,
+        revision: priorId?.revision,
         account_id: row.account_id,
         status: row.status,
         aliases: [...aliases.values()],
@@ -312,7 +396,7 @@ class BuyerAccountRegistry {
     });
     return next;
   }
-  async observeSync(refs, rows, dryRun = false, observationEpoch) {
+  async observeSync(refs, rows, dryRun = false, observationEpoch, expectedRevision) {
     if (dryRun) return;
     const scope = this.scope();
     return this.enqueue(async () => {
@@ -344,7 +428,7 @@ class BuyerAccountRegistry {
           repairedBinding = true;
         }
         const isCurrent = () => scope === this.scope() && this.observationIsCurrent(row.account_id, rowEpoch, scope);
-        await this.record(ref, row, scope, false, isCurrent);
+        await this.record(ref, row, scope, false, isCurrent, expectedRevision);
         if (!isCurrent() || repairedBinding) continue;
         for (const id of [row.account_id])
           if (id) {