@devlab.group/agent-commerce 1.4.0 → 1.4.1

package/dist/index.d.ts

@@ -4,8 +4,8 @@ export { f as AuthorizationMethodName, g as BackendMethod, h as DEFAULT_BACKEND_
 import { X as X402FacilitatorConfig } from './guardrails-Dmwi63KB.js';
 import { a as AuthorizationRequirement, b as AuthorizationSubmission, A as AuthorizationProvider } from './authorization-CPDcpJVa.js';
 export { c as AuthorizationFinalizeContext, d as AuthorizationRecord, e as AuthorizationVerification, f as AuthorizationVerificationContext } from './authorization-CPDcpJVa.js';
-import { D as DeliveredOutcome, P as PaymentRequiredOutcome, C as CommerceEvent, a as PaymentAttempt, b as CommerceReceipt, E as ExecutionPipeline, c as ProtocolAdapter, H as HttpProtocolAdapter, A as AdapterHttpRoute, d as ProtocolAdapterContext } from './protocol-adapter-CaMZj6Wm.js';
-export { e as COMMERCE_EVENT_TYPES, f as CanonicalRequest, g as CommerceEventType, h as EventSink, i as ExecutionOutcome, j as isHttpProtocolAdapter } from './protocol-adapter-CaMZj6Wm.js';
+import { D as DeliveredOutcome, P as PaymentRequiredOutcome, C as CommerceEvent, a as PaymentAttempt, b as CommerceReceipt, E as ExecutionPipeline, c as ProtocolAdapter, H as HttpProtocolAdapter, A as AdapterHttpRoute, d as ProtocolAdapterContext } from './protocol-adapter-Bebmggf_.js';
+export { e as COMMERCE_EVENT_TYPES, f as CanonicalRequest, g as CommerceEventType, h as EventSink, i as ExecutionOutcome, j as isHttpProtocolAdapter } from './protocol-adapter-Bebmggf_.js';
 import { FastifyInstance } from 'fastify';
 import { IncomingMessage, ServerResponse } from 'node:http';
 
@@ -303,6 +303,16 @@ interface BackendRequest {
     readonly resourceId: string;
     /** Validated resource input. */
     readonly input: unknown;
+    /**
+     * Names the *operation*, so the merchant can recognise a repeat of it.
+     *
+     * Not `requestId`, which is fresh per call and would make every retry look
+     * like new work. An adapter sets this only when it can derive a value that
+     * survives a client retry, a reconnect and a gateway restart; the HTTP
+     * executor forwards it as the `Idempotency-Key` request header. Absent
+     * means the protocol has no such notion, and the merchant sees no header.
+     */
+    readonly idempotencyKey?: string;
 }
 interface BackendResponse {
     readonly status: number;
@@ -630,8 +640,14 @@ declare class AcpProtocolAdapter implements HttpProtocolAdapter {
     private readonly token;
     private readonly operations;
     private readonly idempotencyOptions;
-    /** Derived once: the token is fixed, and only its digest may be persisted. */
-    private readonly identityHash;
+    /**
+     * What an idempotency claim is scoped to, from `context.publicBaseUrl`.
+     *
+     * Not readonly because, unlike the token, it is known only once the adapter
+     * starts. Worth that: scoping by the credential meant a rotation freed
+     * every outstanding claim.
+     */
+    private deployment;
     private readonly discoveryMetadata;
     private idempotency;
     private resources;

package/dist/index.js

@@ -1,7 +1,7 @@
-import { AP2_SPEC_VERSION, AP2_MODES, AP2_DEFAULT_CLOCK_SKEW_SECONDS, AP2_JWK_MEMBERS, AP2_KEY_TYPE, AP2_SIGNING_ALGORITHM, AP2_JWK_CURVE, AP2_JWK_COORDINATE_BYTES, openSqliteDatabase, AP2_MAX_CLOCK_SKEW_SECONDS } from './chunk-7NKWFGBY.js';
-import { resolveX402Deployment, resolveDeploymentMode, requireNetworkProfile } from './chunk-IUR3Q7DE.js';
-import { RESERVED_INPUT_FIELDS, PROTOCOL_NAMES, PAYMENT_HEADER, AUTHORIZATION_HEADER, CommerceError, systemClock, NOOP_LOGGER, PACKAGE_VERSION, toCommerceError, DEFAULT_BACKEND_TIMEOUT_MS, toErrorEnvelope, isHttpProtocolAdapter, isCommerceError, parseAuthorizationHeader, toPaymentRequiredEnvelope, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER } from './chunk-ZDVJ7EVL.js';
-export { AUTHORIZATION_HEADER, AUTHORIZATION_INPUT_FIELD, COMMERCE_ERROR_CODES, COMMERCE_ERROR_HTTP_STATUS, COMMERCE_EVENT_TYPES, CommerceError, DEFAULT_BACKEND_TIMEOUT_MS, DELIVERY_SUMMARY_META_KEY, MAX_AUTHORIZATION_HEADER_BYTES, NOOP_LOGGER, PAYMENT_HEADER, PAYMENT_INPUT_FIELD, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER, PROTOCOL_NAMES, RESERVED_INPUT_FIELDS, RETRYABLE_ERROR_CODES, extractReservedInputFields, isCommerceError, isHttpProtocolAdapter, isPaymentRequiredEnvelope, parseAuthorizationHeader, parseAuthorizationSubmission, systemClock, toCommerceError, toDeliverySummary, toErrorEnvelope, toPaymentRequiredEnvelope } from './chunk-ZDVJ7EVL.js';
+import { AP2_SPEC_VERSION, AP2_MODES, AP2_DEFAULT_CLOCK_SKEW_SECONDS, AP2_JWK_MEMBERS, AP2_KEY_TYPE, AP2_SIGNING_ALGORITHM, AP2_JWK_CURVE, AP2_JWK_COORDINATE_BYTES, openSqliteDatabase, AP2_MAX_CLOCK_SKEW_SECONDS } from './chunk-GF6KHHKL.js';
+import { resolveX402Deployment, resolveDeploymentMode, requireNetworkProfile } from './chunk-NWIQLJNU.js';
+import { RESERVED_INPUT_FIELDS, PROTOCOL_NAMES, PAYMENT_HEADER, AUTHORIZATION_HEADER, CommerceError, systemClock, NOOP_LOGGER, PACKAGE_VERSION, toCommerceError, DEFAULT_BACKEND_TIMEOUT_MS, toErrorEnvelope, isHttpProtocolAdapter, isCommerceError, parseAuthorizationHeader, toPaymentRequiredEnvelope, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER } from './chunk-ZEGFLRGV.js';
+export { AUTHORIZATION_HEADER, AUTHORIZATION_INPUT_FIELD, COMMERCE_ERROR_CODES, COMMERCE_ERROR_HTTP_STATUS, COMMERCE_EVENT_TYPES, CommerceError, DEFAULT_BACKEND_TIMEOUT_MS, DELIVERY_SUMMARY_META_KEY, MAX_AUTHORIZATION_HEADER_BYTES, NOOP_LOGGER, PAYMENT_HEADER, PAYMENT_INPUT_FIELD, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER, PROTOCOL_NAMES, RESERVED_INPUT_FIELDS, RETRYABLE_ERROR_CODES, extractReservedInputFields, isCommerceError, isHttpProtocolAdapter, isPaymentRequiredEnvelope, parseAuthorizationHeader, parseAuthorizationSubmission, systemClock, toCommerceError, toDeliverySummary, toErrorEnvelope, toPaymentRequiredEnvelope } from './chunk-ZEGFLRGV.js';
 import { promises, accessSync, constants } from 'fs';
 import * as path from 'path';
 import { parse, YAMLError } from 'yaml';
@@ -85,6 +85,7 @@ var DEFAULT_CONFIG_FILENAME = "config.yaml";
 
 // src/core/execution/backend-http.ts
 var MAX_BODY_SNIPPET_LENGTH = 512;
+var IDEMPOTENCY_KEY_HEADER = "idempotency-key";
 var PATH_PARAM_PATTERN = /\{([a-zA-Z0-9_.-]+)\}/g;
 var MAX_RESPONSE_BODY_BYTES = 1024 * 1024;
 var HttpBackendExecutor = class {
@@ -126,6 +127,10 @@ var HttpBackendExecutor = class {
       if (error instanceof CommerceError) throw error;
     }
     const headers = { ...handler.headers ?? {} };
+    if (request.idempotencyKey !== void 0) {
+      deleteHeader(headers, IDEMPOTENCY_KEY_HEADER);
+      headers[IDEMPOTENCY_KEY_HEADER] = request.idempotencyKey;
+    }
     let body;
     checkQueryCollision(target, parts.query, context);
     for (const [key, value] of Object.entries(parts.query)) {
@@ -334,6 +339,12 @@ function hasHeader(headers, name) {
   const target = name.toLowerCase();
   return Object.keys(headers).some((key) => key.toLowerCase() === target);
 }
+function deleteHeader(headers, name) {
+  const target = name.toLowerCase();
+  for (const key of Object.keys(headers)) {
+    if (key.toLowerCase() === target) delete headers[key];
+  }
+}
 function headersToRecord(headers) {
   const record = {};
   headers.forEach((value, key) => {
@@ -924,17 +935,16 @@ function createExecutionPipeline(options) {
           verification
         });
       } catch (error) {
-        const uncertainTxHash = uncertainSettlementTxHash(error);
-        await hold?.finalize(uncertainTxHash !== void 0 ? "markUncertain" : "release");
+        const txHash = settlementTxHash(error);
+        await hold?.finalize("markUncertain");
         await safePersist(
-          () => options.store.updatePaymentAttempt(
-            uncertainTxHash !== void 0 ? { replayKey, status: "settlement-uncertain", externalReference: uncertainTxHash } : {
-              replayKey,
-              status: "failed",
-              ...error instanceof Error ? { rejectionReason: error.message } : {}
-            }
-          ),
-          uncertainTxHash !== void 0 ? "updatePaymentAttempt(settlement-uncertain)" : "updatePaymentAttempt(failed)",
+          () => options.store.updatePaymentAttempt({
+            replayKey,
+            status: "settlement-uncertain",
+            ...txHash !== void 0 ? { externalReference: txHash } : {},
+            ...error instanceof Error ? { rejectionReason: error.message } : {}
+          }),
+          "updatePaymentAttempt(settlement-uncertain)",
           request.requestId
         );
         await safeEmit(
@@ -945,19 +955,21 @@ function createExecutionPipeline(options) {
             adapter: request.protocol,
             paymentProvider: provider.name,
             status: "error",
-            data: uncertainTxHash !== void 0 ? { reason: "settlement-uncertain", transactionHash: uncertainTxHash } : { reason: "settlement-threw" }
+            data: {
+              reason: "settlement-uncertain",
+              ...txHash !== void 0 ? { transactionHash: txHash } : {}
+            }
           })
         );
-        throw new CommerceError(
-          "PAYMENT_SETTLEMENT_FAILED",
-          uncertainTxHash !== void 0 ? "Settlement could not be confirmed" : "Payment settlement failed",
-          {
-            requestId: request.requestId,
-            resourceId: resource.id,
-            cause: error,
-            ...uncertainTxHash !== void 0 ? { details: { settlementUncertain: true, transactionHash: uncertainTxHash } } : {}
+        throw new CommerceError("PAYMENT_SETTLEMENT_FAILED", "Settlement could not be confirmed", {
+          requestId: request.requestId,
+          resourceId: resource.id,
+          cause: error,
+          details: {
+            settlementUncertain: true,
+            ...txHash !== void 0 ? { transactionHash: txHash } : {}
           }
-        );
+        });
       }
       if (settlement.status !== "settled") {
         await hold?.finalize("release");
@@ -1018,7 +1030,8 @@ function createExecutionPipeline(options) {
       backendResponse = await options.backend.call(resource.handler, {
         requestId: request.requestId,
         resourceId: resource.id,
-        input: validInput
+        input: validInput,
+        ...request.idempotencyKey !== void 0 ? { idempotencyKey: request.idempotencyKey } : {}
       });
     } catch (error) {
       const commerceError = toCommerceError(error, "BACKEND_ERROR", "Backend call failed");
@@ -1124,9 +1137,8 @@ function backendErrorStatus(error) {
   const status = error.details?.["status"];
   return typeof status === "number" ? status : 0;
 }
-function uncertainSettlementTxHash(error) {
-  if (!isCommerceError(error) || error.code !== "PAYMENT_PROVIDER_UNAVAILABLE") return void 0;
-  const hash = error.details?.["transactionHash"];
+function settlementTxHash(error) {
+  const hash = isCommerceError(error) ? error.details?.["transactionHash"] : void 0;
   return typeof hash === "string" ? hash : void 0;
 }
 function resolveAuthorizationProviders(providers, resource, requestId) {
@@ -3334,13 +3346,14 @@ async function createGateway(options) {
 
 // src/protocols/acp/checkout-mapping.ts
 function toCanonicalRequest(options) {
-  const { request, resourceId, requestId, receivedAt } = options;
+  const { request, resourceId, requestId, receivedAt, idempotencyKey } = options;
   return {
     requestId,
     resourceId,
     input: canonicalInput(request),
     protocol: "acp",
-    receivedAt
+    receivedAt,
+    ...idempotencyKey !== void 0 ? { idempotencyKey } : {}
   };
 }
 function canonicalInput(request) {
@@ -3448,8 +3461,8 @@ function writeAcpJson(res, status, body, headers = {}) {
 function writeAcpFailure(res, failure, headers = {}) {
   writeAcpJson(res, failure.status, failure.error, headers);
 }
-function identityHash(token) {
-  return sha256(`acp-auth:${token}`);
+function operationKey(scope) {
+  return sha256(`acp-operation:${scope.deployment}:${scope.endpoint}:${scope.key}`);
 }
 function requestFingerprint(body) {
   return sha256(canonicalize(body));
@@ -3468,6 +3481,7 @@ function sha256(value) {
 }
 
 // src/protocols/acp/idempotency/store.ts
+var SCHEMA_VERSION = 2;
 var ACP_MAX_IDEMPOTENCY_KEY_LENGTH = 255;
 function createAcpIdempotencyStore(options) {
   const logger = options.logger ?? NOOP_LOGGER;
@@ -3478,33 +3492,39 @@ function createAcpIdempotencyStore(options) {
     label: "ACP idempotency database",
     logger
   });
-  migrate(db);
+  migrate(db, logger);
   const selectStmt = db.prepare(
     `SELECT state, fingerprint, status, body_json FROM acp_idempotency
-      WHERE identity_hash = ? AND endpoint = ? AND idempotency_key = ?`
+      WHERE deployment = ? AND endpoint = ? AND idempotency_key = ?`
   );
   const insertStmt = db.prepare(
     `INSERT INTO acp_idempotency
-       (identity_hash, endpoint, idempotency_key, fingerprint, state, created_at, expires_at)
-     VALUES (@identity_hash, @endpoint, @idempotency_key, @fingerprint, 'in_flight', @created_at, @expires_at)`
+       (deployment, endpoint, idempotency_key, fingerprint, state, created_at, expires_at)
+     VALUES (@deployment, @endpoint, @idempotency_key, @fingerprint, 'in_flight', @created_at, @expires_at)`
   );
   const completeStmt = db.prepare(
     `UPDATE acp_idempotency SET state = 'completed', status = @status, body_json = @body_json
-      WHERE identity_hash = @identity_hash AND endpoint = @endpoint AND idempotency_key = @idempotency_key`
+      WHERE deployment = @deployment AND endpoint = @endpoint AND idempotency_key = @idempotency_key`
   );
   const deleteStmt = db.prepare(
     `DELETE FROM acp_idempotency
-      WHERE identity_hash = ? AND endpoint = ? AND idempotency_key = ?`
+      WHERE deployment = ? AND endpoint = ? AND idempotency_key = ?`
+  );
+  const unresolvedStmt = db.prepare(
+    `UPDATE acp_idempotency SET state = 'unresolved'
+      WHERE deployment = @deployment AND endpoint = @endpoint AND idempotency_key = @idempotency_key`
+  );
+  const expireStmt = db.prepare(
+    "DELETE FROM acp_idempotency WHERE expires_at <= ? AND state = 'completed'"
   );
-  const expireStmt = db.prepare("DELETE FROM acp_idempotency WHERE expires_at <= ?");
   const claimTx = db.transaction(
     (scope, fingerprint) => {
       const at = now();
       expireStmt.run(new Date(at).toISOString());
-      const existing = selectStmt.get(scope.identityHash, scope.endpoint, scope.key);
+      const existing = selectStmt.get(scope.deployment, scope.endpoint, scope.key);
       if (existing === void 0) {
         insertStmt.run({
-          identity_hash: scope.identityHash,
+          deployment: scope.deployment,
           endpoint: scope.endpoint,
           idempotency_key: scope.key,
           fingerprint,
@@ -3514,6 +3534,7 @@ function createAcpIdempotencyStore(options) {
         return { kind: "reserved" };
       }
       if (existing.fingerprint !== fingerprint) return { kind: "conflict" };
+      if (existing.state === "unresolved") return { kind: "unresolved" };
       if (existing.state !== "completed") return { kind: "in-flight" };
       return {
         kind: "replay",
@@ -3529,15 +3550,22 @@ function createAcpIdempotencyStore(options) {
     },
     complete(scope, response) {
       completeStmt.run({
-        identity_hash: scope.identityHash,
+        deployment: scope.deployment,
         endpoint: scope.endpoint,
         idempotency_key: scope.key,
         status: response.status,
         body_json: JSON.stringify(response.body ?? null)
       });
     },
+    markUnresolved(scope) {
+      unresolvedStmt.run({
+        deployment: scope.deployment,
+        endpoint: scope.endpoint,
+        idempotency_key: scope.key
+      });
+    },
     release(scope) {
-      deleteStmt.run(scope.identityHash, scope.endpoint, scope.key);
+      deleteStmt.run(scope.deployment, scope.endpoint, scope.key);
     },
     close() {
       if (closed) return;
@@ -3546,13 +3574,23 @@ function createAcpIdempotencyStore(options) {
     }
   };
 }
-function migrate(db) {
+function migrate(db, logger) {
   const current = db.pragma("user_version", { simple: true });
-  if (current >= 1) return;
+  if (current >= SCHEMA_VERSION) return;
   const apply = db.transaction(() => {
+    if (current === 1) {
+      const carried = db.prepare("SELECT COUNT(*) AS count FROM acp_idempotency WHERE state != 'completed'").get();
+      if (carried.count > 0) {
+        logger.warn(
+          { unresolved: carried.count },
+          "acp idempotency: schema v1 -> v2 discards claims keyed by the old bearer-token digest; reconcile these operations against the merchant before trusting a retry"
+        );
+      }
+      db.exec("DROP TABLE acp_idempotency");
+    }
     db.exec(`
       CREATE TABLE IF NOT EXISTS acp_idempotency (
-        identity_hash    TEXT NOT NULL,
+        deployment       TEXT NOT NULL,
         endpoint         TEXT NOT NULL,
         idempotency_key  TEXT NOT NULL,
         fingerprint      TEXT NOT NULL,
@@ -3561,12 +3599,12 @@ function migrate(db) {
         body_json        TEXT,
         created_at       TEXT NOT NULL,
         expires_at       TEXT NOT NULL,
-        PRIMARY KEY (identity_hash, endpoint, idempotency_key)
+        PRIMARY KEY (deployment, endpoint, idempotency_key)
       );
       CREATE INDEX IF NOT EXISTS idx_acp_idempotency_expires_at
         ON acp_idempotency(expires_at);
     `);
-    db.pragma("user_version = 1");
+    db.pragma(`user_version = ${SCHEMA_VERSION}`);
   });
   apply();
 }
@@ -7974,6 +8012,28 @@ function asResponse(failure) {
 
 // src/protocols/acp/adapter.ts
 var DISCOVERY_CACHE_CONTROL = "public, max-age=3600";
+var PRE_BACKEND_ERROR_CODES = /* @__PURE__ */ new Set([
+  "CONFIG_INVALID",
+  "RESOURCE_NOT_FOUND",
+  "INPUT_INVALID",
+  "PROTOCOL_UNSUPPORTED",
+  "GATEWAY_BUSY",
+  "PAYMENT_REQUIRED",
+  "PAYMENT_INVALID",
+  "PAYMENT_REPLAYED",
+  "PAYMENT_PROVIDER_UNAVAILABLE",
+  "PAYMENT_SETTLEMENT_FAILED",
+  "AUTHORIZATION_REQUIRED",
+  "AUTHORIZATION_INVALID",
+  "AUTHORIZATION_REPLAYED",
+  "AUTHORIZATION_PROVIDER_UNAVAILABLE"
+]);
+function reachedFor(code) {
+  return PRE_BACKEND_ERROR_CODES.has(code) ? "no" : "unknown";
+}
+function notReached(failure) {
+  return { response: asResponse(failure), reached: "no" };
+}
 var AcpProtocolAdapter = class {
   name = "acp";
   mountPath;
@@ -7982,8 +8042,14 @@ var AcpProtocolAdapter = class {
   token;
   operations;
   idempotencyOptions;
-  /** Derived once: the token is fixed, and only its digest may be persisted. */
-  identityHash;
+  /**
+   * What an idempotency claim is scoped to, from `context.publicBaseUrl`.
+   *
+   * Not readonly because, unlike the token, it is known only once the adapter
+   * starts. Worth that: scoping by the credential meant a rotation freed
+   * every outstanding claim.
+   */
+  deployment;
   discoveryMetadata;
   idempotency;
   resources = /* @__PURE__ */ new Map();
@@ -7998,7 +8064,6 @@ var AcpProtocolAdapter = class {
     this.token = options.token;
     this.operations = options.operations;
     this.idempotencyOptions = options.idempotency;
-    this.identityHash = identityHash(options.token);
     this.discoveryMetadata = options.discovery;
     this.descriptor = buildDescriptor(PACKAGE_VERSION);
     this.additionalHttpRoutes = [
@@ -8042,6 +8107,7 @@ var AcpProtocolAdapter = class {
       resolved.set(operation, resource);
     }
     this.resources = resolved;
+    this.deployment = context.publicBaseUrl;
     this.idempotency = createAcpIdempotencyStore({
       path: this.idempotencyOptions.path,
       retentionHours: this.idempotencyOptions.retentionHours,
@@ -8130,22 +8196,33 @@ var AcpProtocolAdapter = class {
    */
   async dispatch(request) {
     const store = this.idempotency;
+    const deployment = this.deployment;
     const key = request.idempotencyKey;
-    if (store === void 0 || key === void 0) return this.runCheckout(request);
-    const scope = {
-      identityHash: this.identityHash,
-      endpoint: request.route.path,
-      key
-    };
+    if (store === void 0 || deployment === void 0 || key === void 0) {
+      return (await this.runCheckout(request)).response;
+    }
+    const scope = { deployment, endpoint: request.route.path, key };
     const claim = store.claim(scope, requestFingerprint(request.body));
     switch (claim.kind) {
       case "in-flight":
+        return {
+          ...asResponse(
+            acpFailure(
+              409,
+              "invalid_request",
+              "idempotency_in_flight",
+              "A request with this Idempotency-Key is still being processed."
+            )
+          ),
+          retryAfterSeconds: ACP_IN_FLIGHT_RETRY_AFTER_SECONDS
+        };
+      case "unresolved":
         return asResponse(
           acpFailure(
             409,
-            "invalid_request",
-            "idempotency_in_flight",
-            "A request with this Idempotency-Key is still being processed."
+            "processing_error",
+            "idempotency_unresolved",
+            "An earlier request with this Idempotency-Key reached the merchant and its outcome is unknown. Check the operation with the merchant before retrying."
           )
         );
       case "conflict":
@@ -8160,16 +8237,21 @@ var AcpProtocolAdapter = class {
       case "replay":
         return { status: claim.status, body: claim.body, replayed: true };
     }
-    let response;
+    let outcome;
     try {
-      response = await this.runCheckout(request);
+      outcome = await this.runCheckout(request, operationKey(scope));
     } catch (err) {
-      store.release(scope);
+      store.markUnresolved(scope);
       throw err;
     }
-    if (response.status >= 500) store.release(scope);
-    else store.complete(scope, response);
-    return response;
+    if (outcome.response.status < 500) {
+      store.complete(scope, outcome.response);
+    } else if (outcome.reached === "no") {
+      store.release(scope);
+    } else {
+      store.markUnresolved(scope);
+    }
+    return outcome.response;
   }
   /**
    * One accepted request, one `pipeline.execute()`.
@@ -8178,11 +8260,11 @@ var AcpProtocolAdapter = class {
    * merchant backend: the adapter builds a canonical request and reads back
    * what the pipeline decided.
    */
-  async runCheckout(request) {
+  async runCheckout(request, idempotencyKey) {
     const context = this.context;
     const resource = this.resources.get(request.route.operation);
     if (context === void 0 || resource === void 0) {
-      return asResponse(
+      return notReached(
         acpFailure(
           503,
           "service_unavailable",
@@ -8195,7 +8277,8 @@ var AcpProtocolAdapter = class {
       request,
       resourceId: resource.id,
       requestId: context.ids.next("acp"),
-      receivedAt: context.clock.nowIso()
+      receivedAt: context.clock.nowIso(),
+      ...idempotencyKey !== void 0 ? { idempotencyKey } : {}
     });
     try {
       const outcome = await context.pipeline.execute(canonical);
@@ -8204,7 +8287,7 @@ var AcpProtocolAdapter = class {
           { resourceId: resource.id, requestId: canonical.requestId },
           "acp adapter: mapped checkout resource returned payment-required - it must be priced free"
         );
-        return asResponse(
+        return notReached(
           acpFailure(
             500,
             "processing_error",
@@ -8220,14 +8303,22 @@ var AcpProtocolAdapter = class {
           "acp adapter: refusing to forward a non-conformant merchant response"
         );
       }
-      return mapped.response;
+      return { response: mapped.response, reached: "yes" };
     } catch (err) {
       const error = toCommerceError(err);
       context.logger.warn(
-        { resourceId: resource.id, requestId: canonical.requestId, err: error.toInfo() },
+        {
+          resourceId: resource.id,
+          requestId: canonical.requestId,
+          reached: reachedFor(error.code),
+          err: error.toInfo()
+        },
         "acp adapter: checkout execution failed"
       );
-      return asResponse(mapCommerceErrorToAcp(error, request.route.operation));
+      return {
+        response: asResponse(mapCommerceErrorToAcp(error, request.route.operation)),
+        reached: reachedFor(error.code)
+      };
     }
   }
   /**
@@ -8240,7 +8331,7 @@ var AcpProtocolAdapter = class {
       ...request.requestId !== void 0 ? { [ACP_REQUEST_ID_HEADER]: request.requestId } : {},
       ...request.idempotencyKey !== void 0 ? { [ACP_IDEMPOTENCY_KEY_HEADER]: request.idempotencyKey } : {},
       ...replayed ? { [ACP_IDEMPOTENT_REPLAYED_HEADER]: "true" } : {},
-      ...response?.status === 409 ? { "retry-after": String(ACP_IN_FLIGHT_RETRY_AFTER_SECONDS) } : {}
+      ...response?.retryAfterSeconds !== void 0 ? { "retry-after": String(response.retryAfterSeconds) } : {}
     };
   }
   fail(res, err, message) {
@@ -8267,6 +8358,7 @@ var AcpProtocolAdapter = class {
     this.resources = /* @__PURE__ */ new Map();
     this.idempotency?.close();
     this.idempotency = void 0;
+    this.deployment = void 0;
     this.context = void 0;
   }
 };
@@ -8443,7 +8535,7 @@ var MIGRATIONS = [
     }
   }
 ];
-var SCHEMA_VERSION = MIGRATIONS[MIGRATIONS.length - 1]?.version ?? 0;
+var SCHEMA_VERSION2 = MIGRATIONS[MIGRATIONS.length - 1]?.version ?? 0;
 function migrate2(db) {
   const current = db.pragma("user_version", { simple: true });
   for (const migration of MIGRATIONS) {
@@ -8529,17 +8621,17 @@ function createSqliteReceiptStore(options) {
     name: "sqlite-receipt-store",
     kind: "storage",
     implementationVersion: PACKAGE_VERSION,
-    supportedSpec: `sqlite-schema-v${SCHEMA_VERSION}`,
+    supportedSpec: `sqlite-schema-v${SCHEMA_VERSION2}`,
     capabilities: ["receipts", "events", "payment-attempts"],
     status: "stable"
   };
   const store = {
     async init() {
       const version = db.pragma("user_version", { simple: true });
-      if (version !== SCHEMA_VERSION) {
+      if (version !== SCHEMA_VERSION2) {
         throw new CommerceError(
           "STORAGE_ERROR",
-          `Receipt store schema version mismatch (found ${version}, expected ${SCHEMA_VERSION})`
+          `Receipt store schema version mismatch (found ${version}, expected ${SCHEMA_VERSION2})`
         );
       }
     },
@@ -8673,9 +8765,9 @@ function createSqliteReceiptStore(options) {
       }
       try {
         const version = db.pragma("user_version", { simple: true });
-        if (version !== SCHEMA_VERSION) {
+        if (version !== SCHEMA_VERSION2) {
           logger.warn(
-            { found: version, expected: SCHEMA_VERSION },
+            { found: version, expected: SCHEMA_VERSION2 },
             "receipt-store: health check failed (schema version mismatch)"
           );
           return {
@@ -8687,7 +8779,7 @@ function createSqliteReceiptStore(options) {
         }
         return {
           status: "pass",
-          detail: `sqlite schema v${SCHEMA_VERSION} writable`,
+          detail: `sqlite schema v${SCHEMA_VERSION2} writable`,
           checkedAt: clock.nowIso(),
           durationMs: clock.monotonicMs() - startedAt
         };