@devlab.group/agent-commerce 1.6.0 → 2.0.0

package/dist/index.js

@@ -1,18 +1,20 @@
-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-RAJGPGJG.js';
-import { MCP_TOOL_NAME_PATTERN } from './chunk-AFI2CEZS.js';
-import { MPP_DEFAULT_NETWORK, isMppNetwork, MPP_NETWORKS, MPP_MIN_CHALLENGE_SECRET_LENGTH, MPP_PROFILE } from './chunk-V2V2E7HX.js';
-import { resolveX402Deployment, resolveDeploymentMode, requireNetworkProfile } from './chunk-74BSEXB5.js';
-import { RESERVED_INPUT_FIELDS, PROTOCOL_NAMES, PAYMENT_METHOD_NAMES, PAYMENT_HEADER, AUTHORIZATION_HEADER, isRecord, CommerceError, systemClock, NOOP_LOGGER, PACKAGE_VERSION, toCommerceError, DEFAULT_BACKEND_TIMEOUT_MS, isCommerceError, describeError, isHttpProtocolAdapter, toLogInfo, extractReservedInputFields, parseAuthorizationHeader, toPaymentRequiredEnvelope, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER, toErrorEnvelope, DELIVERY_SUMMARY_META_KEY, toDeliverySummary } from './chunk-IVJC5YLE.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_METHOD_NAMES, 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-IVJC5YLE.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-SYEGCNJZ.js';
+import { MCP_TOOL_NAME_PATTERN, readCappedBody, createBearerCheck, settlementResponse, joinUrl, settlementResponseFromDetails, x402ErrorCode, settlementFailure } from './chunk-HOZA3IWP.js';
+import { MPP_DEFAULT_NETWORK, isMppNetwork, MPP_NETWORKS, MPP_MIN_CHALLENGE_SECRET_LENGTH, MPP_PROFILE } from './chunk-3LUJHVKX.js';
+import { contentDigest, CONTENT_DIGEST_METADATA_KEY, mppProblem, mppProblemDetail } from './chunk-CKJRITWY.js';
+import { X402_PAYMENT_FLOWS, X402_DEFAULT_PAYMENT_FLOW, resolveX402Deployment, SETTLE_AFTER_BACKEND_METADATA_KEY, resolveDeploymentMode, requireNetworkProfile } from './chunk-TWRUNWDR.js';
+import { RESERVED_INPUT_FIELDS, PROTOCOL_NAMES, PAYMENT_METHOD_NAMES, PAYMENT_HEADER, AUTHORIZATION_HEADER, isRecord, CommerceError, systemClock, NOOP_LOGGER, PACKAGE_VERSION, toCommerceError, DEFAULT_BACKEND_TIMEOUT_MS, isCommerceError, describeError, isHttpProtocolAdapter, toLogInfo, extractReservedInputFields, parseAuthorizationHeader, toPaymentRequiredEnvelope, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER, toErrorEnvelope, DELIVERY_SUMMARY_META_KEY, toDeliverySummary, AUTHORIZATION_INPUT_FIELD, parseAuthorizationSubmission, PAYMENT_INPUT_FIELD } from './chunk-53WXXIPR.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_METHOD_NAMES, 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-53WXXIPR.js';
 import { promises, accessSync, constants } from 'fs';
 import * as path from 'path';
 import { parse, YAMLError } from 'yaml';
 import { z } from 'zod';
 import { isDeepStrictEqual } from 'util';
 import Fastify from 'fastify';
-import { randomUUID, timingSafeEqual, createHash } from 'crypto';
+import { randomUUID, createHash } from 'crypto';
 import { createRequire } from 'module';
 import pino from 'pino';
+import { Transform } from 'stream';
 import Ajv2020 from 'ajv/dist/2020.js';
 import addFormats from 'ajv-formats';
 
@@ -85,8 +87,19 @@ 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 NEVER_FORWARDED_HEADER = /^(authorization|cookie|set-cookie|host|content-length|content-type|connection|keep-alive|te|trailer|transfer-encoding|upgrade|idempotency-key|proxy-.*)$/;
 var PATH_PARAM_PATTERN = /\{([a-zA-Z0-9_.-]+)\}/g;
 var MAX_RESPONSE_BODY_BYTES = 1024 * 1024;
+var BackendErrorResponse = class {
+  constructor(status, body, headers = {}) {
+    this.status = status;
+    this.body = body;
+    this.headers = headers;
+  }
+  status;
+  body;
+  headers;
+};
 var HttpBackendExecutor = class {
   fetchImpl;
   logger;
@@ -117,7 +130,7 @@ var HttpBackendExecutor = class {
         context
       );
     }
-    const headers = buildHeaders(handler, context);
+    const headers = buildHeaders(handler, context, request.backendHeaders);
     if (request.idempotencyKey !== void 0) {
       setHeader(headers, IDEMPOTENCY_KEY_HEADER, request.idempotencyKey, context);
     }
@@ -205,7 +218,8 @@ var HttpBackendExecutor = class {
       throw new CommerceError("BACKEND_ERROR", `Backend responded with status ${response.status}`, {
         requestId: request.requestId,
         resourceId: request.resourceId,
-        details: { status: response.status }
+        details: { status: response.status },
+        cause: new BackendErrorResponse(response.status, parsedBody, responseHeaders)
       });
     }
     return {
@@ -226,10 +240,10 @@ function findUnparsedBraceToken(url) {
   const token = /\{[^{}]*\}?|\}/.exec(residue.slice(index));
   return token?.[0] ?? residue[index];
 }
-function validateBackendRequestShape(handler, input, context) {
+function validateBackendRequestShape(handler, input, context, backendHeaders) {
   const inputRecord = isRecord(input) ? input : {};
   const parts = buildBackendRequestParts(handler, inputRecord, context);
-  buildHeaders(handler, context);
+  buildHeaders(handler, context, backendHeaders);
   let target;
   try {
     target = new URL(parts.url);
@@ -321,12 +335,25 @@ function stringifyPrimitive(value) {
     return String(value);
   }
 }
-function buildHeaders(handler, context) {
+function buildHeaders(handler, context, forwarded = {}) {
+  let headers;
   try {
-    return new Headers(handler.headers);
+    headers = new Headers(handler.headers);
   } catch {
     throw invalidHeaderError(context);
   }
+  for (const [name, value] of Object.entries(forwarded)) {
+    if (NEVER_FORWARDED_HEADER.test(name.toLowerCase())) continue;
+    try {
+      if (!headers.has(name)) headers.set(name, value);
+    } catch {
+      throw new CommerceError("INPUT_INVALID", "A forwarded request header is invalid", {
+        ...context,
+        details: { reason: "invalid-forwarded-header" }
+      });
+    }
+  }
+  return headers;
 }
 function setHeader(headers, name, value, context) {
   try {
@@ -645,6 +672,138 @@ function createExecutionPipeline(options) {
       }
     };
   }
+  async function settle(args) {
+    const { request, resource, provider, requirement, payment, verification, replayKey, hold } = args;
+    let settlement;
+    try {
+      settlement = await provider.settle({
+        requestId: request.requestId,
+        resource,
+        requirement,
+        submission: payment,
+        verification
+      });
+    } catch (error) {
+      const txHash = settlementTxHash(error);
+      await hold?.finalize("markUncertain");
+      await safePersist(
+        () => 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(
+        buildEvent({
+          type: "payment.rejected",
+          requestId: request.requestId,
+          resourceId: resource.id,
+          adapter: request.protocol,
+          paymentProvider: provider.name,
+          status: "error",
+          data: {
+            reason: "settlement-uncertain",
+            ...txHash !== void 0 ? { transactionHash: txHash } : {}
+          }
+        })
+      );
+      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 } : {},
+          ...settlementParties(requirement, verification)
+        }
+      });
+    }
+    if (settlement.status !== "settled") {
+      await hold?.finalize("release");
+      await safePersist(
+        () => options.store.updatePaymentAttempt({
+          replayKey,
+          status: "rejected",
+          ...settlement.rejectionReason !== void 0 ? { rejectionReason: settlement.rejectionReason } : {}
+        }),
+        "updatePaymentAttempt(rejected)",
+        request.requestId
+      );
+      await safeEmit(
+        buildEvent({
+          type: "payment.rejected",
+          requestId: request.requestId,
+          resourceId: resource.id,
+          adapter: request.protocol,
+          paymentProvider: provider.name,
+          status: "error",
+          data: settlement.rejectionReason ? { reason: settlement.rejectionReason } : {}
+        })
+      );
+      const rejectionDetails = retryChallenge(requirement, settlement.rejectionReason).details;
+      throw new CommerceError(
+        "PAYMENT_SETTLEMENT_FAILED",
+        settlement.rejectionReason ?? "Settlement was rejected",
+        {
+          requestId: request.requestId,
+          resourceId: resource.id,
+          httpStatus: 402,
+          details: {
+            ...rejectionDetails,
+            ...settlementParties(requirement, settlement, verification)
+          }
+        }
+      );
+    }
+    await hold?.finalize("consume");
+    await safePersist(
+      () => options.store.updatePaymentAttempt({
+        replayKey,
+        status: "settled",
+        ...settlement.externalReference !== void 0 ? { externalReference: settlement.externalReference } : {}
+      }),
+      "updatePaymentAttempt(settled)",
+      request.requestId
+    );
+    await safeEmit(
+      buildEvent({
+        type: "payment.settled",
+        requestId: request.requestId,
+        resourceId: resource.id,
+        adapter: request.protocol,
+        paymentProvider: provider.name,
+        status: "ok"
+      })
+    );
+    return settlement;
+  }
+  async function abandonSettlement(args, backendErrorCode) {
+    const { request, resource, provider, replayKey, hold } = args;
+    await hold?.finalize("release");
+    await safePersist(
+      () => options.store.updatePaymentAttempt({
+        replayKey,
+        status: "rejected",
+        rejectionReason: "backend_failed"
+      }),
+      "updatePaymentAttempt(backend-failed)",
+      request.requestId
+    );
+    await safeEmit(
+      buildEvent({
+        type: "payment.rejected",
+        requestId: request.requestId,
+        resourceId: resource.id,
+        adapter: request.protocol,
+        paymentProvider: provider.name,
+        status: "error",
+        data: { reason: "backend-failed", backendErrorCode }
+      })
+    );
+  }
   async function execute(request) {
     const pipelineStart = options.clock.monotonicMs();
     const resource = options.resources.get(request.resourceId);
@@ -680,10 +839,12 @@ function createExecutionPipeline(options) {
       );
     }
     const validInput = validation.value;
-    validateBackendRequestShape(resource.handler, validInput, {
-      requestId: request.requestId,
-      resourceId: resource.id
-    });
+    validateBackendRequestShape(
+      resource.handler,
+      validInput,
+      { requestId: request.requestId, resourceId: resource.id },
+      request.backendHeaders
+    );
     if (resource.pricing.type === "dynamic") {
       throw new CommerceError(
         "CONFIG_INVALID",
@@ -706,6 +867,7 @@ function createExecutionPipeline(options) {
     }
     let paymentResult;
     let authorization;
+    let deferredSettlement;
     if (resource.pricing.type === "fixed") {
       const pricing = resource.pricing;
       const provider = pickProvider(options.paymentProviders, resource.paymentMethods);
@@ -732,7 +894,9 @@ function createExecutionPipeline(options) {
           resource,
           amount: pricing.amount,
           currency: pricing.currency,
-          requestedAt: options.clock.nowIso()
+          requestedAt: options.clock.nowIso(),
+          // Transport facts a rail may bind into its challenge, such as a body digest
+          ...request.metadata !== void 0 ? { metadata: request.metadata } : {}
         });
       } catch (error) {
         throw isCommerceError(error) ? error : new CommerceError("PAYMENT_PROVIDER_UNAVAILABLE", "Payment provider is unavailable", {
@@ -806,7 +970,7 @@ function createExecutionPipeline(options) {
           {
             requestId: request.requestId,
             resourceId: resource.id,
-            ...retryChallenge(requirement)
+            ...retryChallenge(requirement, verification.rejectionReason)
           }
         );
       }
@@ -865,7 +1029,7 @@ function createExecutionPipeline(options) {
             data: { reason: mapped.code }
           })
         );
-        throw mapped;
+        throw finishedReplay(mapped, requirement);
       }
       await safeEmit(
         buildEvent({
@@ -877,104 +1041,21 @@ function createExecutionPipeline(options) {
           status: "ok"
         })
       );
-      let settlement;
-      try {
-        settlement = await provider.settle({
-          requestId: request.requestId,
-          resource,
-          requirement,
-          submission: payment,
-          verification
-        });
-      } catch (error) {
-        const txHash = settlementTxHash(error);
-        await hold?.finalize("markUncertain");
-        await safePersist(
-          () => 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(
-          buildEvent({
-            type: "payment.rejected",
-            requestId: request.requestId,
-            resourceId: resource.id,
-            adapter: request.protocol,
-            paymentProvider: provider.name,
-            status: "error",
-            data: {
-              reason: "settlement-uncertain",
-              ...txHash !== void 0 ? { transactionHash: txHash } : {}
-            }
-          })
-        );
-        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");
-        await safePersist(
-          () => options.store.updatePaymentAttempt({
-            replayKey,
-            status: "rejected",
-            ...settlement.rejectionReason !== void 0 ? { rejectionReason: settlement.rejectionReason } : {}
-          }),
-          "updatePaymentAttempt(rejected)",
-          request.requestId
-        );
-        await safeEmit(
-          buildEvent({
-            type: "payment.rejected",
-            requestId: request.requestId,
-            resourceId: resource.id,
-            adapter: request.protocol,
-            paymentProvider: provider.name,
-            status: "error",
-            data: settlement.rejectionReason ? { reason: settlement.rejectionReason } : {}
-          })
-        );
-        throw new CommerceError(
-          "PAYMENT_SETTLEMENT_FAILED",
-          settlement.rejectionReason ?? "Settlement was rejected",
-          {
-            requestId: request.requestId,
-            resourceId: resource.id
-          }
-        );
+      const settleArgs = {
+        request,
+        resource,
+        provider,
+        requirement,
+        payment,
+        verification,
+        replayKey,
+        hold
+      };
+      if (requirement.metadata?.[SETTLE_AFTER_BACKEND_METADATA_KEY] === true) {
+        deferredSettlement = settleArgs;
+      } else {
+        paymentResult = await settle(settleArgs);
       }
-      await hold?.finalize("consume");
-      await safePersist(
-        () => options.store.updatePaymentAttempt({
-          replayKey,
-          status: "settled",
-          ...settlement.externalReference !== void 0 ? { externalReference: settlement.externalReference } : {}
-        }),
-        "updatePaymentAttempt(settled)",
-        request.requestId
-      );
-      await safeEmit(
-        buildEvent({
-          type: "payment.settled",
-          requestId: request.requestId,
-          resourceId: resource.id,
-          adapter: request.protocol,
-          paymentProvider: provider.name,
-          status: "ok"
-        })
-      );
-      paymentResult = settlement;
     }
     const backendStart = options.clock.monotonicMs();
     let backendResponse;
@@ -983,7 +1064,8 @@ function createExecutionPipeline(options) {
         requestId: request.requestId,
         resourceId: resource.id,
         input: validInput,
-        ...request.idempotencyKey !== void 0 ? { idempotencyKey: request.idempotencyKey } : {}
+        ...request.idempotencyKey !== void 0 ? { idempotencyKey: request.idempotencyKey } : {},
+        ...request.backendHeaders !== void 0 ? { backendHeaders: request.backendHeaders } : {}
       });
     } catch (error) {
       const commerceError = toCommerceError(error, "BACKEND_ERROR", "Backend call failed");
@@ -998,6 +1080,10 @@ function createExecutionPipeline(options) {
           data: { code: commerceError.code }
         })
       );
+      if (deferredSettlement !== void 0) {
+        await abandonSettlement(deferredSettlement, commerceError.code);
+        throw commerceError;
+      }
       if (paymentResult !== void 0) {
         const failedReceipt = {
           id: options.ids.next("receipt"),
@@ -1030,6 +1116,8 @@ function createExecutionPipeline(options) {
                 currency: paymentResult.currency,
                 ...paymentResult.network !== void 0 ? { network: paymentResult.network } : {},
                 ...paymentResult.externalReference !== void 0 ? { externalReference: paymentResult.externalReference } : {},
+                ...paymentResult.payer !== void 0 ? { payer: paymentResult.payer } : {},
+                ...typeof paymentResult.metadata?.["amountBaseUnits"] === "string" ? { amountBaseUnits: paymentResult.metadata["amountBaseUnits"] } : {},
                 ...typeof paymentResult.metadata?.["receipt"] === "string" ? { receipt: paymentResult.metadata["receipt"] } : {}
               }
             }
@@ -1049,6 +1137,9 @@ function createExecutionPipeline(options) {
         data: { status: backendResponse.status }
       })
     );
+    if (deferredSettlement !== void 0) {
+      paymentResult = await settle(deferredSettlement);
+    }
     const receipt = {
       id: options.ids.next("receipt"),
       requestId: request.requestId,
@@ -1108,9 +1199,35 @@ function resolveAuthorizationProviders(providers, resource, requestId) {
     return found;
   });
 }
-function retryChallenge(requirement) {
+function retryChallenge(requirement, reason) {
   const envelope = requirement.challenge.envelope;
-  return envelope === void 0 ? {} : { details: { challenge: envelope } };
+  if (envelope === void 0 && reason === void 0) return {};
+  return {
+    details: {
+      ...envelope !== void 0 ? { challenge: envelope } : {},
+      ...reason !== void 0 ? { reason } : {}
+    }
+  };
+}
+var FINISHED_ATTEMPT_STATUSES = /* @__PURE__ */ new Set(["settled", "rejected"]);
+function finishedReplay(error, requirement) {
+  const status = error.details?.["attemptStatus"];
+  if (error.code !== "PAYMENT_REPLAYED" || typeof status !== "string") return error;
+  if (!FINISHED_ATTEMPT_STATUSES.has(status)) return error;
+  return new CommerceError("PAYMENT_REPLAYED", error.message, {
+    ...error.requestId !== void 0 ? { requestId: error.requestId } : {},
+    ...error.resourceId !== void 0 ? { resourceId: error.resourceId } : {},
+    httpStatus: 402,
+    details: { ...error.details, ...retryChallenge(requirement).details }
+  });
+}
+function settlementParties(requirement, ...results) {
+  const network = results.find((r) => r.network !== void 0)?.network ?? requirement.network;
+  const payer = results.find((r) => r.payer !== void 0)?.payer;
+  return {
+    ...network !== void 0 ? { network } : {},
+    ...payer !== void 0 ? { payer } : {}
+  };
 }
 function pickProvider(providers, methods) {
   for (const method of methods) {
@@ -1199,6 +1316,7 @@ var ACP_OPERATION_INPUT_KEYS = {
 var ACP_OPERATION_OPTIONAL_INPUT_KEYS = {
   cancelCheckoutSession: ["body"]
 };
+var ACP_SESSION_ID_INPUT_KEY = "checkout_session_id";
 var ACP_JSON_MEDIA_TYPE = "application/json";
 var ACP_API_VERSION_HEADER = "api-version";
 var ACP_REQUEST_ID_HEADER = "request-id";
@@ -1206,6 +1324,17 @@ var ACP_IDEMPOTENCY_KEY_HEADER = "idempotency-key";
 var ACP_IDEMPOTENT_REPLAYED_HEADER = "idempotent-replayed";
 var ACP_IN_FLIGHT_RETRY_AFTER_SECONDS = 1;
 var ACP_MAX_REQUEST_ID_LENGTH = 128;
+var ACP_FORWARDED_HEADERS = [
+  "accept-language",
+  "user-agent",
+  ACP_REQUEST_ID_HEADER,
+  ACP_API_VERSION_HEADER,
+  "signature",
+  "timestamp"
+];
+var ACP_MAX_FORWARDED_HEADER_LENGTH = 2048;
+var ACP_MERCHANT_RETRY_AFTER_DEFAULT_SECONDS = 5;
+var ACP_MERCHANT_RETRY_AFTER_MAX_SECONDS = 300;
 
 // src/config/schema.ts
 var SUPPORTED_CONFIG_VERSION = 1;
@@ -1272,7 +1401,11 @@ var MountPathSchema = z.string().min(1).refine((value) => value.startsWith("/"),
   }
 );
 var AcpAuthSchema = z.object({ type: z.literal("bearer"), token: z.string().min(1) }).strict();
-var AcpIdempotencySchema = z.object({ path: z.string().min(1), retentionHours: NumberOrString.optional() }).strict();
+var AcpIdempotencySchema = z.object({
+  path: z.string().min(1),
+  retentionHours: NumberOrString.optional(),
+  merchantIdempotent: z.boolean().optional()
+}).strict();
 var AcpCheckoutSchema = z.object({ operations: z.record(z.string().min(1)) }).strict();
 var AcpDiscoverySchema = z.object({
   documentationUrl: z.string().min(1).optional(),
@@ -1342,6 +1475,7 @@ var ResourceEntrySchema = z.object({
   pricing: PricingSchema,
   expose: z.array(z.string().min(1)).min(1),
   payments: z.array(z.string().min(1)).optional(),
+  paymentFlow: z.enum(X402_PAYMENT_FLOWS).optional(),
   authorization: z.object({ required: z.array(z.string().min(1)).min(1) }).strict().optional()
 }).strict();
 var ResourcesMapSchema = z.record(z.string().min(1), ResourceEntrySchema);
@@ -1379,6 +1513,8 @@ var X402Schema = z.object({
   assetDecimals: NumberOrString,
   payTo: z.string().min(1),
   maxTimeoutSeconds: NumberOrString,
+  // `authorization` (the x402 default) settles after the backend call
+  paymentFlow: z.enum(X402_PAYMENT_FLOWS).optional(),
   facilitator: FacilitatorSchema,
   // Real funds. Never defaulted; see src/payments/x402/guardrails.ts
   allowMainnet: BooleanOrString.optional(),
@@ -1396,6 +1532,8 @@ var MppSchema = z.object({
   realm: z.string().min(1),
   challengeSecret: z.string().min(1),
   challengeTtlSeconds: NumberOrString.optional(),
+  // Same values and default as `payments.x402.paymentFlow`
+  paymentFlow: z.enum(X402_PAYMENT_FLOWS).optional(),
   facilitator: FacilitatorSchema,
   // Real funds. Never defaulted; see src/payments/x402/guardrails.ts
   allowMainnet: BooleanOrString.optional(),
@@ -1426,6 +1564,8 @@ var Ap2Schema = z.object({
     checkoutIssuers: z.array(Ap2IssuerSchema).optional()
   }).strict().optional(),
   clockSkewSeconds: NumberOrString.optional(),
+  requireMandateAudience: BooleanOrString.optional(),
+  requireMandateExpiry: BooleanOrString.optional(),
   replay: z.object({ path: z.string().min(1) }).strict().optional()
 }).strict();
 var AuthorizationSchema = z.object({ ap2: Ap2Schema.optional() }).strict();
@@ -1573,6 +1713,7 @@ function normalize(raw) {
         min: 1
       }
     ),
+    paymentFlow: x402Raw.paymentFlow ?? X402_DEFAULT_PAYMENT_FLOW,
     facilitator: normalizeFacilitator(x402Raw.facilitator),
     ...x402Raw.allowMainnet !== void 0 ? { allowMainnet: toBoolean(x402Raw.allowMainnet, "payments.x402.allowMainnet") } : {},
     ...x402Raw.allowUnauthenticatedFacilitator !== void 0 ? {
@@ -1604,7 +1745,22 @@ function normalize(raw) {
   const resources = Object.entries(raw.resources).map(
     ([id, entry]) => normalizeResource(id, entry, protocols, x402, mpp, ap2)
   );
+  const resourcePaymentFlows = Object.fromEntries(
+    Object.entries(raw.resources).flatMap(
+      ([id, entry]) => entry.paymentFlow !== void 0 ? [[id, entry.paymentFlow]] : []
+    )
+  );
+  const hasFlowOverrides = Object.keys(resourcePaymentFlows).length > 0;
+  const x402WithFlows = x402 !== void 0 && hasFlowOverrides ? { ...x402, resourcePaymentFlows } : x402;
+  const mppWithFlows = mpp !== void 0 && hasFlowOverrides ? { ...mpp, resourcePaymentFlows } : mpp;
   if (protocols.acp.enabled) validateAcpCheckoutMapping(protocols.acp, resources);
+  if (protocols.a2a.enabled && !resources.some((r) => r.exposedVia.includes("a2a"))) {
+    throw new CommerceError(
+      "CONFIG_INVALID",
+      'protocols.a2a.enabled is true but no resource lists "a2a" in its expose',
+      { details: { path: "protocols.a2a.enabled" } }
+    );
+  }
   return {
     version: SUPPORTED_CONFIG_VERSION,
     merchant: {
@@ -1623,8 +1779,8 @@ function normalize(raw) {
     protocols,
     resources,
     payments: {
-      ...x402 !== void 0 ? { x402 } : {},
-      ...mpp !== void 0 ? { mpp } : {}
+      ...x402WithFlows !== void 0 ? { x402: x402WithFlows } : {},
+      ...mppWithFlows !== void 0 ? { mpp: mppWithFlows } : {}
     },
     ...ap2 !== void 0 ? { authorization: { ap2 } } : {}
   };
@@ -1693,6 +1849,14 @@ function normalizeAp2(raw) {
       "authorization.ap2.clockSkewSeconds",
       { min: 0, max: AP2_MAX_CLOCK_SKEW_SECONDS }
     ),
+    requireMandateAudience: toBoolean(
+      raw.requireMandateAudience ?? false,
+      "authorization.ap2.requireMandateAudience"
+    ),
+    requireMandateExpiry: toBoolean(
+      raw.requireMandateExpiry ?? false,
+      "authorization.ap2.requireMandateExpiry"
+    ),
     replay: { path: raw.replay.path }
   };
 }
@@ -1868,7 +2032,8 @@ function normalizeAcp(raw) {
         raw.idempotency.retentionHours ?? ACP_RETENTION_HOURS,
         "protocols.acp.idempotency.retentionHours",
         { min: ACP_RETENTION_HOURS }
-      )
+      ),
+      merchantIdempotent: raw.idempotency.merchantIdempotent ?? false
     },
     checkout: { operations: normalizeAcpOperations(raw.checkout) },
     // Built key by key so absent metadata stays absent rather than `undefined`
@@ -1951,10 +2116,11 @@ function validateAcpOperationInput(path2, operation, resource) {
   if (schema === void 0) return;
   const keys = ACP_OPERATION_INPUT_KEYS[operation];
   const optionalKeys = ACP_OPERATION_OPTIONAL_INPUT_KEYS[operation] ?? [];
-  const properties = schema["properties"];
-  if (schema["additionalProperties"] === false && isRecord(properties)) {
-    for (const key of [...keys, ...optionalKeys]) {
-      if (!Object.hasOwn(properties, key)) {
+  const sent = [...keys, ...optionalKeys];
+  const topLevel = closedObjectProperties(schema);
+  if (topLevel !== void 0) {
+    for (const key of sent) {
+      if (!Object.hasOwn(topLevel, key)) {
         const when = keys.includes(key) ? "always sends" : "sends when the caller supplies it";
         throw acpInvalid(
           path2,
@@ -1964,6 +2130,23 @@ function validateAcpOperationInput(path2, operation, resource) {
       }
     }
   }
+  const declared = isRecord(schema["properties"]) ? schema["properties"] : {};
+  const pathKeys = closedObjectProperties(declared["path"]);
+  if (sent.includes("path") && pathKeys !== void 0 && !Object.hasOwn(pathKeys, ACP_SESSION_ID_INPUT_KEY)) {
+    throw acpInvalid(
+      path2,
+      `Resource "${resource.id}" implements ACP operation "${operation}" but its "path" schema sets additionalProperties: false without declaring "${ACP_SESSION_ID_INPUT_KEY}", which the adapter always sends inside "path"`,
+      { resourceId: resource.id }
+    );
+  }
+  const bodyKeys = closedObjectProperties(declared["body"]);
+  if (sent.includes("body") && bodyKeys !== void 0 && Object.keys(bodyKeys).length === 0) {
+    throw acpInvalid(
+      path2,
+      `Resource "${resource.id}" implements ACP operation "${operation}" but its "body" schema accepts no keys, so it refuses every ACP document. Config load closes an object schema that omits additionalProperties: declare body as { type: object, additionalProperties: true }`,
+      { resourceId: resource.id }
+    );
+  }
   const required = schema["required"];
   if (Array.isArray(required)) {
     for (const entry of required) {
@@ -1977,6 +2160,10 @@ function validateAcpOperationInput(path2, operation, resource) {
     }
   }
 }
+function closedObjectProperties(schema) {
+  if (!isRecord(schema) || schema["additionalProperties"] !== false) return void 0;
+  return isRecord(schema["properties"]) ? schema["properties"] : {};
+}
 function normalizeFacilitator(raw) {
   return raw.mode === "local" ? { mode: "local", signerPrivateKey: raw.signerPrivateKey } : { mode: "remote", url: raw.url, auth: raw.auth ?? { type: "none" } };
 }
@@ -2007,6 +2194,7 @@ function normalizeMpp(raw) {
         { min: 1 }
       )
     } : {},
+    paymentFlow: raw.paymentFlow ?? X402_DEFAULT_PAYMENT_FLOW,
     facilitator: normalizeFacilitator(raw.facilitator),
     ...raw.allowMainnet !== void 0 ? { allowMainnet: toBoolean(raw.allowMainnet, "payments.mpp.allowMainnet") } : {},
     ...raw.allowUnauthenticatedFacilitator !== void 0 ? {
@@ -2160,6 +2348,13 @@ function normalizeResource(id, entry, protocols, x402, mpp, ap2) {
       validatePricingAmount(id, entry.pricing.amount, MPP_PROFILE.assetDecimals);
     }
   }
+  if (entry.paymentFlow !== void 0 && (entry.pricing.type !== "fixed" || !paymentMethods.some((method) => method === "x402" || method === "mpp"))) {
+    throw new CommerceError(
+      "CONFIG_INVALID",
+      `Resource "${id}" sets paymentFlow, which requires fixed pricing and "x402" or "mpp" in payments`,
+      { details: { path: `resources.${id}.paymentFlow`, resourceId: id } }
+    );
+  }
   const pricing = entry.pricing.type === "free" ? { type: "free" } : { type: "fixed", amount: entry.pricing.amount, currency: entry.pricing.currency };
   const authorization = normalizeResourceAuthorization(id, entry, pricing, ap2);
   return {
@@ -2566,36 +2761,6 @@ function resolveConfigPath(explicitPath, env, cwd) {
   if (fromEnv) return path.resolve(cwd, fromEnv);
   return path.resolve(cwd, DEFAULT_CONFIG_FILENAME);
 }
-var BEARER_PREFIX = /^Bearer +/i;
-function createBearerCheck(expectedToken) {
-  const expected = sha256(expectedToken);
-  return (header2) => {
-    if (header2 === void 0 || !BEARER_PREFIX.test(header2)) return false;
-    const presented = header2.replace(BEARER_PREFIX, "");
-    return presented.length > 0 && timingSafeEqual(sha256(presented), expected);
-  };
-}
-function sha256(value) {
-  return createHash("sha256").update(value, "utf8").digest();
-}
-async function readCappedBody(req, maxBytes) {
-  const chunks = [];
-  let total = 0;
-  try {
-    for await (const chunk of req) {
-      const buffer = chunk;
-      total += buffer.length;
-      if (total > maxBytes) return { kind: "too-large" };
-      chunks.push(buffer);
-    }
-  } catch {
-    return { kind: "unreadable" };
-  }
-  return { kind: "ok", text: Buffer.concat(chunks).toString("utf8") };
-}
-function joinUrl(baseUrl, mountPath) {
-  return `${baseUrl.replace(/\/+$/, "")}/${mountPath.replace(/^\/+|\/+$/g, "")}`;
-}
 
 // src/gateway/access-control.ts
 var CORS_METHODS = "GET,POST,OPTIONS";
@@ -2604,9 +2769,29 @@ var CORS_HEADERS = [
   PAYMENT_HEADER,
   AUTHORIZATION_HEADER,
   "x-request-id",
-  "authorization"
+  "authorization",
+  "mcp-protocol-version",
+  "mcp-method",
+  "mcp-name",
+  "a2a-version",
+  "a2a-extensions",
+  "api-version",
+  "idempotency-key",
+  "request-id",
+  "signature",
+  "timestamp",
+  "access-control-expose-headers"
+].join(",");
+var CORS_EXPOSED_HEADERS = [
+  "payment-required",
+  "payment-response",
+  "www-authenticate",
+  "payment-receipt",
+  "idempotency-key",
+  "request-id",
+  "idempotent-replayed",
+  "retry-after"
 ].join(",");
-var CORS_EXPOSED_HEADERS = "payment-required,payment-response,www-authenticate,payment-receipt";
 function buildAccessControlHook(options) {
   const allowedOrigins = new Set(options.allowedOrigins.map((origin) => origin.toLowerCase()));
   const publicHostname = hostnameOf(options.publicBaseUrl);
@@ -3146,6 +3331,7 @@ function buildWellKnownDocument(options) {
 }
 
 // src/gateway/routes.ts
+var X402_V1_PAYMENT_HEADER = "x-payment";
 function registerRoutes(options) {
   const { server } = options;
   const readinessProbe = createReadinessProbe({
@@ -3172,12 +3358,20 @@ function registerRoutes(options) {
       adapters: await readinessProbe.adapterHealth()
     })
   );
+  const backed = (method) => options.paymentProviders.some((provider) => provider.name === method);
   server.get("/api/resources", async () => ({
-    resources: options.resources.list().map(toPublicResource)
+    resources: options.resources.list().map((resource) => {
+      const listed = toPublicResource(resource);
+      return { ...listed, paymentMethods: listed.paymentMethods.filter(backed) };
+    })
   }));
-  server.post("/api/resources/:id/invoke", async (request, reply) => {
-    await handleInvoke(request, reply, options);
-  });
+  server.post(
+    "/api/resources/:id/invoke",
+    { preParsing: async (request, _reply, payload) => payload.pipe(digestingStream(request)) },
+    async (request, reply) => {
+      await handleInvoke(request, reply, options);
+    }
+  );
   const tokenHook = buildOperatorTokenHook(options.config.server.adminToken);
   server.get(
     "/api/receipts",
@@ -3190,6 +3384,20 @@ function registerRoutes(options) {
     ledgerHandler("events", (list) => options.store.listEvents(list))
   );
 }
+var bodyDigests = /* @__PURE__ */ new WeakMap();
+function digestingStream(request) {
+  const chunks = [];
+  return new Transform({
+    transform(chunk, _encoding, callback) {
+      chunks.push(chunk);
+      callback(null, chunk);
+    },
+    flush(callback) {
+      if (chunks.length > 0) bodyDigests.set(request, contentDigest(Buffer.concat(chunks)));
+      callback();
+    }
+  });
+}
 function ledgerHandler(key, list) {
   return async (request, reply) => {
     try {
@@ -3204,6 +3412,7 @@ function ledgerHandler(key, list) {
 }
 async function handleInvoke(request, reply, options) {
   const resourceId = request.params.id;
+  let paymentMethod;
   try {
     const resource = options.resources.get(resourceId);
     if (!resource?.exposedVia.includes("http")) {
@@ -3212,13 +3421,14 @@ async function handleInvoke(request, reply, options) {
         resourceId
       });
     }
-    const paymentMethod = resource.paymentMethods[0];
+    paymentMethod = resource.paymentMethods[0];
     const paymentValue = paymentProof(request, paymentMethod);
     const payment = paymentValue !== void 0 && paymentMethod !== void 0 ? { method: paymentMethod, payload: paymentValue } : void 0;
     const authorization = parseAuthorizationHeader(
       request.headers[AUTHORIZATION_HEADER],
       request.id
     );
+    const digest = bodyDigests.get(request);
     const canonicalRequest = {
       requestId: request.id,
       resourceId,
@@ -3226,7 +3436,8 @@ async function handleInvoke(request, reply, options) {
       protocol: "http",
       receivedAt: options.clock.nowIso(),
       ...payment !== void 0 ? { payment } : {},
-      ...authorization !== void 0 ? { authorization } : {}
+      ...authorization !== void 0 ? { authorization } : {},
+      ...digest !== void 0 ? { metadata: { [CONTENT_DIGEST_METADATA_KEY]: digest } } : {}
     };
     const outcome = await options.pipeline.execute(canonicalRequest);
     if (outcome.kind === "payment-required") {
@@ -3235,36 +3446,88 @@ async function handleInvoke(request, reply, options) {
         const challenge = envelope.payment.envelope?.["wwwAuthenticate"];
         if (typeof challenge === "string") reply.header("www-authenticate", challenge);
       } else if (envelope.payment.envelope !== void 0) {
-        reply.header(PAYMENT_REQUIRED_HEADER, encodeHeaderDocument(envelope.payment.envelope));
+        const v1Only = request.headers[X402_V1_PAYMENT_HEADER] !== void 0 && request.headers[PAYMENT_HEADER] === void 0;
+        reply.header(
+          PAYMENT_REQUIRED_HEADER,
+          encodeHeaderDocument(
+            v1Only ? { ...envelope.payment.envelope, error: "invalid_x402_version" } : envelope.payment.envelope
+          )
+        );
       }
       reply.header("cache-control", "no-store");
+      if (envelope.payment.provider === "mpp") {
+        const { status: _envelopeStatus, ...members } = envelope;
+        reply.header("content-type", "application/problem+json").status(402).send({
+          ...mppProblem(envelope.code, 402),
+          status: 402,
+          detail: envelope.message,
+          ...members
+        });
+        return;
+      }
       reply.status(402).send(envelope);
       return;
     }
     if (outcome.payment) {
-      reply.header(PAYMENT_RESPONSE_HEADER, encodePaymentSummary(outcome.payment));
+      reply.header(
+        PAYMENT_RESPONSE_HEADER,
+        encodeHeaderDocument(settlementResponse(outcome.payment))
+      );
       const receipt = outcome.payment.metadata?.["receipt"];
       if (outcome.payment.provider === "mpp" && typeof receipt === "string") {
         reply.header("payment-receipt", receipt);
       }
+      reply.header("cache-control", "private");
     }
     reply.status(outcome.backendStatus).send(outcome.body);
   } catch (error) {
-    const commerceError = toCommerceError(error);
-    const settledPayment = errorPaymentSummary(commerceError);
-    if (settledPayment !== void 0) {
-      reply.header(PAYMENT_RESPONSE_HEADER, encodePaymentSummary(settledPayment));
-      if (settledPayment.provider === "mpp" && settledPayment.receipt !== void 0) {
-        reply.header("payment-receipt", settledPayment.receipt);
-      }
-    }
-    const challenge = commerceError.details?.["challenge"];
-    if (commerceError.code === "PAYMENT_INVALID" && typeof challenge?.["wwwAuthenticate"] === "string") {
+    sendInvokeError(reply, toCommerceError(error), paymentMethod);
+  }
+}
+var MPP_PROBLEM_CODES = /* @__PURE__ */ new Set([
+  "PAYMENT_INVALID",
+  "PAYMENT_REPLAYED",
+  "PAYMENT_SETTLEMENT_FAILED",
+  "PAYMENT_PROVIDER_UNAVAILABLE"
+]);
+function sendInvokeError(reply, error, paymentMethod) {
+  const details = error.details;
+  const settled = settlementResponseFromDetails(details);
+  if (settled !== void 0) {
+    reply.header(PAYMENT_RESPONSE_HEADER, encodeHeaderDocument(settled));
+  }
+  if (error.code === "PAYMENT_SETTLEMENT_FAILED") {
+    reply.header(PAYMENT_RESPONSE_HEADER, encodeHeaderDocument(settlementFailure(details)));
+  }
+  const challenge = details?.["challenge"];
+  if (error.httpStatus === 402 && isRecord(challenge)) {
+    if (paymentMethod === "mpp" && typeof challenge["wwwAuthenticate"] === "string") {
       reply.header("www-authenticate", challenge["wwwAuthenticate"]);
-      reply.header("cache-control", "no-store");
+    } else if (paymentMethod === "x402" && error.code !== "PAYMENT_SETTLEMENT_FAILED") {
+      reply.header(
+        PAYMENT_REQUIRED_HEADER,
+        encodeHeaderDocument({
+          ...challenge,
+          error: x402ErrorCode(error.code, details?.["reason"])
+        })
+      );
     }
-    reply.status(commerceError.httpStatus).send(toErrorEnvelope(commerceError));
+    reply.header("cache-control", "no-store");
+  }
+  const envelope = toErrorEnvelope(error);
+  if (paymentMethod === "mpp" && MPP_PROBLEM_CODES.has(error.code)) {
+    const { status: _envelopeStatus, ...members } = envelope;
+    const reason = typeof details?.["reason"] === "string" ? details["reason"] : void 0;
+    reply.header("content-type", "application/problem+json").status(error.httpStatus).send({
+      ...mppProblem(error.code, error.httpStatus, reason),
+      status: error.httpStatus,
+      // The reason token stays in `message` and `details.reason`
+      detail: mppProblemDetail(reason, error.message),
+      ...members
+    });
+    return;
   }
+  reply.status(error.httpStatus).send(envelope);
 }
 function paymentProof(request, method) {
   if (method === "mpp") {
@@ -3274,38 +3537,9 @@ function paymentProof(request, method) {
   const value = request.headers[PAYMENT_HEADER];
   return Array.isArray(value) ? value[0] : value;
 }
-function errorPaymentSummary(error) {
-  const payment = error.details?.["payment"];
-  if (!isRecord(payment)) return void 0;
-  const { status, provider, amount, currency, network, externalReference, receipt } = payment;
-  if (typeof status !== "string" || typeof provider !== "string" || typeof amount !== "string" || typeof currency !== "string") {
-    return void 0;
-  }
-  return {
-    status,
-    provider,
-    amount,
-    currency,
-    ...typeof network === "string" ? { network } : {},
-    ...typeof externalReference === "string" ? { externalReference } : {},
-    ...typeof receipt === "string" ? { receipt } : {}
-  };
-}
 function encodeHeaderDocument(document) {
   return Buffer.from(JSON.stringify(document), "utf8").toString("base64");
 }
-function encodePaymentSummary(payment) {
-  return encodeHeaderDocument({
-    success: payment.status === "settled",
-    transaction: payment.externalReference ?? "",
-    network: payment.network ?? "",
-    status: payment.status,
-    provider: payment.provider,
-    amount: payment.amount,
-    currency: payment.currency,
-    ...payment.externalReference !== void 0 ? { externalReference: payment.externalReference } : {}
-  });
-}
 function parseLimit(value) {
   if (Array.isArray(value)) return parseLimit(value[0]);
   let n;
@@ -3437,7 +3671,7 @@ async function createGateway(options) {
 }
 
 // src/protocols/a2a/constants.ts
-var A2A_SPEC_VERSION = "1.0.0";
+var A2A_SPEC_VERSION = "1.0.1";
 var A2A_PROTOCOL_VERSION = "1.0";
 var A2A_PROTOCOL_BINDING = "JSONRPC";
 var A2A_AGENT_CARD_PATH = "/.well-known/agent-card.json";
@@ -3446,93 +3680,26 @@ var A2A_JSON_MEDIA_TYPE = "application/json";
 var A2A_DEFAULT_AGENT_NAME = "agent-commerce";
 var A2A_VERSION_HEADER = "a2a-version";
 var A2A_METHOD_SEND_MESSAGE = "SendMessage";
+var A2A_PUSH_CONFIG_METHODS = [
+  "CreateTaskPushNotificationConfig",
+  "GetTaskPushNotificationConfig",
+  "ListTaskPushNotificationConfigs",
+  "DeleteTaskPushNotificationConfig"
+];
 var A2A_UNSUPPORTED_METHODS = [
   "SendStreamingMessage",
   "GetTask",
   "ListTasks",
   "CancelTask",
   "SubscribeToTask",
-  "CreateTaskPushNotificationConfig",
-  "GetTaskPushNotificationConfig",
-  "ListTaskPushNotificationConfigs",
-  "DeleteTaskPushNotificationConfig",
+  ...A2A_PUSH_CONFIG_METHODS,
   "GetExtendedAgentCard"
 ];
+var A2A_TASK_LOOKUP_METHODS = ["GetTask", "CancelTask"];
 var A2A_TASK_STATE_COMPLETED = "TASK_STATE_COMPLETED";
 var A2A_TASK_STATE_FAILED = "TASK_STATE_FAILED";
-
-// src/protocols/a2a/agent-card.ts
-function skillTags(resource) {
-  return ["agent-commerce", resource.pricing.type === "free" ? "free" : "paid"];
-}
-function skillDescription(resource) {
-  const base = resource.description ?? resource.name;
-  if (resource.pricing.type === "fixed") {
-    return `${base} Costs ${resource.pricing.amount} ${resource.pricing.currency} per call.`;
-  }
-  if (resource.pricing.type === "dynamic") {
-    return `${base} Requires payment (amount determined at request time).`;
-  }
-  return base;
-}
-function buildAgentSkill(resource) {
-  return {
-    id: resource.id,
-    name: resource.name,
-    description: skillDescription(resource),
-    tags: skillTags(resource),
-    inputModes: [A2A_JSON_MEDIA_TYPE],
-    outputModes: [A2A_JSON_MEDIA_TYPE]
-  };
-}
-function buildAgentCard(options) {
-  return {
-    name: options.name,
-    description: options.description,
-    version: options.version,
-    supportedInterfaces: [
-      {
-        url: joinUrl(options.publicBaseUrl, options.mountPath),
-        protocolBinding: A2A_PROTOCOL_BINDING,
-        protocolVersion: A2A_PROTOCOL_VERSION
-      }
-    ],
-    capabilities: { streaming: false, pushNotifications: false, extendedAgentCard: false },
-    defaultInputModes: [A2A_JSON_MEDIA_TYPE],
-    defaultOutputModes: [A2A_JSON_MEDIA_TYPE],
-    skills: options.resources.map(buildAgentSkill)
-  };
-}
-
-// src/protocols/a2a/descriptor.ts
-var A2A_CAPABILITIES = ["agent-card", "jsonrpc", "SendMessage"];
-var A2A_UNSUPPORTED = [
-  // Methods, as the protocol names them; the transport refuses the same list
-  ...A2A_UNSUPPORTED_METHODS,
-  // Transports other than the one binding served
-  "HTTP+JSON/REST binding",
-  "gRPC binding",
-  // Behaviors
-  "SSE",
-  "long-running task persistence",
-  "task resumption",
-  "push notifications",
-  "multi-turn conversational continuation",
-  "authenticated extended agent cards",
-  "A2A authentication schemes",
-  "artifact types beyond Agent Commerce outcome data"
-];
-function buildDescriptor(implementationVersion) {
-  return {
-    name: "a2a",
-    kind: "protocol",
-    implementationVersion,
-    supportedSpec: A2A_SPEC_VERSION,
-    capabilities: A2A_CAPABILITIES,
-    status: "experimental",
-    unsupported: A2A_UNSUPPORTED
-  };
-}
+var A2A_TASK_STATE_INPUT_REQUIRED = "TASK_STATE_INPUT_REQUIRED";
+var A2A_EXTENSIONS_HEADER = "a2a-extensions";
 
 // src/protocols/a2a/jsonrpc.ts
 var JSONRPC_PARSE_ERROR = -32700;
@@ -3540,7 +3707,18 @@ var JSONRPC_INVALID_REQUEST = -32600;
 var JSONRPC_METHOD_NOT_FOUND = -32601;
 var JSONRPC_INVALID_PARAMS = -32602;
 var JSONRPC_INTERNAL_ERROR = -32603;
+var A2A_ERROR_TASK_NOT_FOUND = -32001;
+var A2A_ERROR_PUSH_NOTIFICATION_NOT_SUPPORTED = -32003;
 var A2A_ERROR_UNSUPPORTED_OPERATION = -32004;
+var A2A_ERROR_CONTENT_TYPE_NOT_SUPPORTED = -32005;
+var A2A_ERROR_VERSION_NOT_SUPPORTED = -32009;
+var A2A_ERROR_REASONS = /* @__PURE__ */ new Map([
+  [A2A_ERROR_TASK_NOT_FOUND, "TASK_NOT_FOUND"],
+  [A2A_ERROR_PUSH_NOTIFICATION_NOT_SUPPORTED, "PUSH_NOTIFICATION_NOT_SUPPORTED"],
+  [A2A_ERROR_UNSUPPORTED_OPERATION, "UNSUPPORTED_OPERATION"],
+  [A2A_ERROR_CONTENT_TYPE_NOT_SUPPORTED, "CONTENT_TYPE_NOT_SUPPORTED"],
+  [A2A_ERROR_VERSION_NOT_SUPPORTED, "VERSION_NOT_SUPPORTED"]
+]);
 function readId(value) {
   if (typeof value === "string" || typeof value === "number") return value;
   return null;
@@ -3549,7 +3727,21 @@ function jsonRpcResult(id, result) {
   return { jsonrpc: "2.0", id, result };
 }
 function jsonRpcError(id, code, message) {
-  return { jsonrpc: "2.0", id, error: { code, message } };
+  const reason = A2A_ERROR_REASONS.get(code);
+  const error = {
+    code,
+    message,
+    ...reason !== void 0 ? {
+      data: [
+        {
+          "@type": "type.googleapis.com/google.rpc.ErrorInfo",
+          reason,
+          domain: "a2a-protocol.org"
+        }
+      ]
+    } : {}
+  };
+  return { jsonrpc: "2.0", id, error };
 }
 function parseJsonRpcRequest(rawBody) {
   let payload;
@@ -3576,6 +3768,16 @@ function parseJsonRpcRequest(rawBody) {
     };
   }
   const id = readId(payload["id"]);
+  if (payload["id"] === void 0) {
+    return {
+      ok: false,
+      id,
+      error: {
+        code: JSONRPC_INVALID_REQUEST,
+        message: 'Request must include an "id"; notifications are unsupported.'
+      }
+    };
+  }
   if (payload["jsonrpc"] !== "2.0") {
     return {
       ok: false,
@@ -3604,7 +3806,13 @@ function parseJsonRpcRequest(rawBody) {
   }
   return { ok: true, request: { id, method, params: params ?? {} } };
 }
+
+// src/protocols/a2a/message-mapping.ts
 var A2A_USER_ROLE = "ROLE_USER";
+var A2A_CALL_SHAPE = 'one data part {"resource": "<skill id>", "input": {...}}';
+function userRoleProblem(role) {
+  return role === A2A_USER_ROLE ? void 0 : `Unsupported message role "${String(role)}": only ${A2A_USER_ROLE} is accepted.`;
+}
 var UnknownRecord = z.record(z.string(), z.unknown());
 var MessageSchema = z.object({
   role: z.string(),
@@ -3622,13 +3830,20 @@ var ParamsSchema = z.object({
 function invalid(message) {
   return new CommerceError("INPUT_INVALID", message);
 }
-function unsupported(message) {
-  return new CommerceError("PROTOCOL_UNSUPPORTED", message);
+function unsupported(message, a2aErrorCode) {
+  return new CommerceError(
+    "PROTOCOL_UNSUPPORTED",
+    message,
+    a2aErrorCode !== void 0 ? { details: { a2aErrorCode } } : {}
+  );
 }
 function assertNoContinuation(params) {
   const message = params.message;
   if (params.taskId !== void 0 || message.taskId !== void 0) {
-    throw unsupported("Task continuation is not supported: send a request with no taskId.");
+    throw unsupported(
+      "Task not found: tasks are not persisted, so send a request with no taskId.",
+      A2A_ERROR_TASK_NOT_FOUND
+    );
   }
   if (params.contextId !== void 0 || message.contextId !== void 0) {
     throw unsupported(
@@ -3641,10 +3856,16 @@ function assertNoContinuation(params) {
 }
 function assertSupportedPart(part) {
   if ("file" in part || "raw" in part || "url" in part) {
-    throw unsupported("File and URL parts are not supported: send a structured data part.");
+    throw unsupported(
+      `File and URL parts are not supported: send ${A2A_CALL_SHAPE}.`,
+      A2A_ERROR_CONTENT_TYPE_NOT_SUPPORTED
+    );
   }
   if ("text" in part) {
-    throw unsupported("Text parts are not supported: send a structured data part.");
+    throw unsupported(
+      `Text parts are not supported: send ${A2A_CALL_SHAPE}.`,
+      A2A_ERROR_CONTENT_TYPE_NOT_SUPPORTED
+    );
   }
   if (!("data" in part)) {
     throw invalid('Message part carries no "data": send a structured data part.');
@@ -3652,7 +3873,8 @@ function assertSupportedPart(part) {
   const mediaType = part["mediaType"];
   if (mediaType !== void 0 && mediaType !== A2A_JSON_MEDIA_TYPE) {
     throw unsupported(
-      `Media type "${String(mediaType)}" is not supported: parts must be ${A2A_JSON_MEDIA_TYPE}.`
+      `Media type "${String(mediaType)}" is not supported: parts must be ${A2A_JSON_MEDIA_TYPE}.`,
+      A2A_ERROR_CONTENT_TYPE_NOT_SUPPORTED
     );
   }
 }
@@ -3665,10 +3887,13 @@ function parseInvocation(rawParams) {
   }
   const params = parsed.data;
   const message = params.message;
-  assertNoContinuation(params);
-  if (message.role !== A2A_USER_ROLE) {
-    throw invalid(`Unsupported message role "${message.role}": only ${A2A_USER_ROLE} is accepted.`);
+  if (message.messageId === void 0 || message.messageId.length === 0) {
+    throw invalid('Message must carry a non-empty "messageId".');
   }
+  const messageId = message.messageId;
+  assertNoContinuation(params);
+  const roleProblem = userRoleProblem(message.role);
+  if (roleProblem !== void 0) throw invalid(roleProblem);
   if (message.parts.length === 0) {
     throw invalid("Message carries no parts: send exactly one structured data part.");
   }
@@ -3677,28 +3902,287 @@ function parseInvocation(rawParams) {
       `Multi-part messages are not supported: send exactly one structured data part (received ${message.parts.length}).`
     );
   }
-  const part = message.parts[0];
-  if (part === void 0) throw invalid("Message carries no parts.");
-  assertSupportedPart(part);
-  const data = part["data"];
-  if (!isRecord(data)) {
-    throw invalid('Message part "data" must be a JSON object.');
+  const part = message.parts[0];
+  if (part === void 0) throw invalid("Message carries no parts.");
+  assertSupportedPart(part);
+  const data = part["data"];
+  if (!isRecord(data)) {
+    throw invalid('Message part "data" must be a JSON object.');
+  }
+  const resourceId = data["resource"];
+  if (typeof resourceId !== "string") {
+    throw invalid('Message part data must carry a "resource" string naming a canonical resource.');
+  }
+  if (resourceId.length === 0) {
+    throw invalid('Message part data "resource" must not be empty.');
+  }
+  const rawInput = data["input"];
+  if (rawInput !== void 0 && !isRecord(rawInput)) {
+    throw invalid('Message part data "input" must be a JSON object.');
+  }
+  return { resourceId, input: rawInput ?? {}, messageId };
+}
+
+// src/protocols/a2a/x402-extension.ts
+var A2A_X402_EXTENSION_URI = "https://github.com/google-a2a/a2a-x402/v0.1";
+var A2A_X402_PROTOCOL_VERSION = 2;
+var X402_PAYMENT_STATUS_KEY = "x402.payment.status";
+var X402_PAYMENT_REQUIRED_KEY = "x402.payment.required";
+var X402_PAYMENT_PAYLOAD_KEY = "x402.payment.payload";
+var X402_PAYMENT_RECEIPTS_KEY = "x402.payment.receipts";
+var X402_PAYMENT_ERROR_KEY = "x402.payment.error";
+var DEFAULT_PENDING_TTL_MS = 10 * 60 * 1e3;
+var MAX_PENDING_TTL_MS = 60 * 60 * 1e3;
+var MAX_PENDING_PAYMENTS = 256;
+function requestsX402Extension(header2) {
+  const values = typeof header2 === "string" ? [header2] : header2 ?? [];
+  return values.some(
+    (value) => value.split(",").some((uri) => uri.trim() === A2A_X402_EXTENSION_URI)
+  );
+}
+function createPendingPayments(clock, maxEntries = MAX_PENDING_PAYMENTS) {
+  const tasks = /* @__PURE__ */ new Map();
+  const now = () => clock.now().getTime();
+  function purgeExpired() {
+    const at = now();
+    for (const [taskId, pending] of tasks) {
+      if (pending.expiresAtMs <= at) tasks.delete(taskId);
+    }
+  }
+  return {
+    /** Holds a purchase until `expiresAt`, evicting the oldest one when full */
+    put(taskId, pending, expiresAt) {
+      purgeExpired();
+      if (tasks.size >= maxEntries) {
+        const [oldest] = tasks.keys();
+        if (oldest !== void 0) tasks.delete(oldest);
+      }
+      const requested = expiresAt !== void 0 ? Date.parse(expiresAt) : Number.NaN;
+      const ttl = Number.isFinite(requested) ? requested - now() : DEFAULT_PENDING_TTL_MS;
+      const expiresAtMs = now() + Math.min(Math.max(ttl, 0), MAX_PENDING_TTL_MS);
+      tasks.set(taskId, { ...pending, expiresAtMs });
+    },
+    get(taskId) {
+      const pending = tasks.get(taskId);
+      if (pending === void 0) return void 0;
+      if (pending.expiresAtMs <= now()) {
+        tasks.delete(taskId);
+        return void 0;
+      }
+      return pending;
+    },
+    delete(taskId) {
+      tasks.delete(taskId);
+    },
+    size() {
+      return tasks.size;
+    },
+    clear() {
+      tasks.clear();
+    }
+  };
+}
+function readPaymentSubmission(message) {
+  const metadata = isRecord(message) ? message["metadata"] : void 0;
+  if (!isRecord(metadata)) return void 0;
+  const status = metadata[X402_PAYMENT_STATUS_KEY];
+  if (status === "payment-rejected") return { kind: "rejected" };
+  const payload = metadata[X402_PAYMENT_PAYLOAD_KEY];
+  if (status === "payment-submitted" && isRecord(payload)) return { kind: "submitted", payload };
+  return void 0;
+}
+function readFollowUpAuthorization(message) {
+  const parts = isRecord(message) ? message["parts"] : void 0;
+  if (!Array.isArray(parts)) return void 0;
+  for (const part of parts) {
+    const data = isRecord(part) ? part["data"] : void 0;
+    const input = isRecord(data) ? data["input"] : void 0;
+    if (isRecord(input) && input[AUTHORIZATION_INPUT_FIELD] !== void 0) {
+      return parseAuthorizationSubmission(input[AUTHORIZATION_INPUT_FIELD]);
+    }
+  }
+  return void 0;
+}
+function paymentRequiredMetadata(envelope) {
+  return {
+    [X402_PAYMENT_STATUS_KEY]: "payment-required",
+    [X402_PAYMENT_REQUIRED_KEY]: envelope
+  };
+}
+function paymentCompletedMetadata(payment) {
+  return {
+    [X402_PAYMENT_STATUS_KEY]: "payment-completed",
+    [X402_PAYMENT_RECEIPTS_KEY]: [settlementResponse(payment)]
+  };
+}
+function paymentFailureMetadata(error, network) {
+  const settled = settlementResponseFromDetails(error.details);
+  if (settled !== void 0 && settled["success"] === true) {
+    return {
+      [X402_PAYMENT_STATUS_KEY]: "payment-completed",
+      [X402_PAYMENT_RECEIPTS_KEY]: [settled]
+    };
+  }
+  const code = error.code.startsWith("PAYMENT_") ? x402ErrorCode(error.code, error.details?.["reason"]) : error.code.toLowerCase();
+  const failure = settlementFailure(error.details);
+  const receipt = failure["network"] === "" && network !== void 0 ? { ...failure, network } : failure;
+  return {
+    [X402_PAYMENT_STATUS_KEY]: "payment-failed",
+    [X402_PAYMENT_ERROR_KEY]: code,
+    // Keep the failure reason, including `settlement_pending` when a hash is known
+    [X402_PAYMENT_RECEIPTS_KEY]: [
+      error.details?.["settlementUncertain"] === true ? receipt : { ...receipt, errorReason: code }
+    ]
+  };
+}
+function paymentRejectedMetadata() {
+  return { [X402_PAYMENT_STATUS_KEY]: "payment-rejected" };
+}
+
+// src/protocols/a2a/agent-card.ts
+var RESOURCES_PATH = "/api/resources";
+function skillTags(resource) {
+  return ["agent-commerce", resource.pricing.type === "free" ? "free" : "paid"];
+}
+function skillDescription(resource) {
+  const base = resource.description ?? resource.name;
+  if (resource.pricing.type === "fixed") {
+    return `${base} Costs ${resource.pricing.amount} ${resource.pricing.currency} per call.`;
   }
-  const resourceId = data["resource"];
-  if (typeof resourceId !== "string") {
-    throw invalid('Message part data must carry a "resource" string naming a canonical resource.');
+  if (resource.pricing.type === "dynamic") {
+    return `${base} Requires payment (amount determined at request time).`;
   }
-  if (resourceId.length === 0) {
-    throw invalid('Message part data "resource" must not be empty.');
+  return base;
+}
+function exampleValue(schema, name) {
+  if (!isRecord(schema)) return `<${name}>`;
+  const examples = schema["examples"];
+  if (Array.isArray(examples) && examples.length > 0) return examples[0];
+  if (schema["default"] !== void 0) return schema["default"];
+  const allowed = schema["enum"];
+  if (Array.isArray(allowed) && allowed.length > 0) return allowed[0];
+  const declared = schema["type"];
+  const type = Array.isArray(declared) ? declared[0] : declared;
+  switch (type) {
+    case "object":
+      return exampleObject(schema);
+    case "array":
+      return schema["items"] !== void 0 ? [exampleValue(schema["items"], name)] : [];
+    case "number":
+    case "integer":
+      return 0;
+    case "boolean":
+      return false;
+    case "null":
+      return null;
+    default:
+      return `<${name}>`;
   }
-  const rawInput = data["input"];
-  if (rawInput !== void 0 && !isRecord(rawInput)) {
-    throw invalid('Message part data "input" must be a JSON object.');
+}
+function exampleObject(schema) {
+  const properties = isRecord(schema["properties"]) ? schema["properties"] : {};
+  const required = Array.isArray(schema["required"]) ? schema["required"] : [];
+  const example = {};
+  for (const key of required) {
+    if (typeof key !== "string" || key === PAYMENT_INPUT_FIELD || key === AUTHORIZATION_INPUT_FIELD)
+      continue;
+    example[key] = exampleValue(properties[key], key);
   }
+  return example;
+}
+function skillExample(resource) {
+  return JSON.stringify({
+    resource: resource.id,
+    input: exampleObject(resource.inputSchema ?? {})
+  });
+}
+function buildAgentSkill(resource) {
   return {
-    resourceId,
-    input: rawInput ?? {},
-    ...message.messageId !== void 0 ? { messageId: message.messageId } : {}
+    id: resource.id,
+    name: resource.name,
+    description: skillDescription(resource),
+    tags: skillTags(resource),
+    examples: [skillExample(resource)],
+    inputModes: [A2A_JSON_MEDIA_TYPE],
+    outputModes: [A2A_JSON_MEDIA_TYPE]
+  };
+}
+function agentDescription(options) {
+  const call = `Call a skill by sending ${A2A_CALL_SHAPE} with media type ${A2A_JSON_MEDIA_TYPE}. Each skill has an example; input schemas are at ${joinUrl(options.publicBaseUrl, RESOURCES_PATH)}.`;
+  const pay = options.resources.some((resource) => resource.pricing.type !== "free") ? ` For paid skills, retry with a payment proof in "input.${PAYMENT_INPUT_FIELD}".` : "";
+  return `${options.description} ${call}${pay}`;
+}
+function buildAgentCard(options) {
+  return {
+    name: options.name,
+    description: agentDescription(options),
+    version: options.version,
+    supportedInterfaces: [
+      {
+        url: joinUrl(options.publicBaseUrl, options.mountPath),
+        protocolBinding: A2A_PROTOCOL_BINDING,
+        protocolVersion: A2A_PROTOCOL_VERSION
+      }
+    ],
+    capabilities: {
+      streaming: false,
+      pushNotifications: false,
+      extendedAgentCard: false,
+      // Only a skill whose rail is x402 can be paid through the extension.
+      // Not required: `_payment` keeps working for clients without it.
+      ...options.resources.some((resource) => resource.paymentMethods[0] === "x402") ? {
+        extensions: [
+          {
+            uri: A2A_X402_EXTENSION_URI,
+            description: "x402 payments: input-required tasks carrying x402 v2 documents.",
+            required: false,
+            // Lets a client holding an x402 v1 library tell before it pays
+            params: { x402Version: A2A_X402_PROTOCOL_VERSION }
+          }
+        ]
+      } : {}
+    },
+    defaultInputModes: [A2A_JSON_MEDIA_TYPE],
+    defaultOutputModes: [A2A_JSON_MEDIA_TYPE],
+    skills: options.resources.map(buildAgentSkill)
+  };
+}
+
+// src/protocols/a2a/descriptor.ts
+var A2A_CAPABILITIES = [
+  "agent-card",
+  "jsonrpc",
+  "SendMessage",
+  // The x402 A2A transport, opt-in per request
+  "x402-extension"
+];
+var A2A_UNSUPPORTED = [
+  // Methods, as the protocol names them; the transport refuses the same list
+  ...A2A_UNSUPPORTED_METHODS,
+  // Transports other than the one binding served
+  "HTTP+JSON/REST binding",
+  "gRPC binding",
+  // Behaviors
+  "SSE",
+  "long-running task persistence",
+  "task resumption other than an x402 extension payment",
+  "push notifications",
+  "multi-turn conversational continuation",
+  "authenticated extended agent cards",
+  "A2A authentication schemes",
+  "artifact types beyond Agent Commerce outcome data",
+  // Pending x402 payments live in process memory
+  "x402 extension payments across gateway restarts or instances"
+];
+function buildDescriptor(implementationVersion) {
+  return {
+    name: "a2a",
+    kind: "protocol",
+    implementationVersion,
+    supportedSpec: A2A_SPEC_VERSION,
+    capabilities: A2A_CAPABILITIES,
+    status: "experimental",
+    unsupported: A2A_UNSUPPORTED
   };
 }
 
@@ -3724,19 +4208,56 @@ function completedTask(outcome, identity) {
   });
 }
 function paymentRequiredTask(outcome, identity) {
-  return task(identity, A2A_TASK_STATE_FAILED, {
-    name: outcome.resourceId,
-    parts: [{ data: { ...toPaymentRequiredEnvelope(outcome) }, mediaType: A2A_JSON_MEDIA_TYPE }]
-  });
+  const envelope = toPaymentRequiredEnvelope(outcome);
+  return withStatusMessage(
+    task(identity, A2A_TASK_STATE_FAILED, {
+      name: outcome.resourceId,
+      parts: [{ data: { ...envelope }, mediaType: A2A_JSON_MEDIA_TYPE }]
+    }),
+    envelope.message,
+    identity.statusMessageId
+  );
+}
+function inputRequired(base, metadata, messageId) {
+  return withStatusMessage(
+    { ...base, status: { ...base.status, state: A2A_TASK_STATE_INPUT_REQUIRED } },
+    "Payment is required. Send the x402 payment payload on this task.",
+    messageId,
+    metadata
+  );
+}
+function withStatusMessage(base, text, messageId, metadata) {
+  return {
+    ...base,
+    status: {
+      ...base.status,
+      message: {
+        role: "ROLE_AGENT",
+        messageId,
+        contextId: base.contextId,
+        taskId: base.id,
+        parts: [{ text }],
+        ...metadata !== void 0 ? { metadata, extensions: [A2A_X402_EXTENSION_URI] } : {}
+      }
+    }
+  };
 }
 function failedTask(error, identity) {
-  return task(identity, A2A_TASK_STATE_FAILED, {
-    parts: [{ data: { ...toErrorEnvelope(error) }, mediaType: A2A_JSON_MEDIA_TYPE }]
-  });
+  const envelope = toErrorEnvelope(error);
+  return withStatusMessage(
+    task(identity, A2A_TASK_STATE_FAILED, {
+      parts: [{ data: { ...envelope }, mediaType: A2A_JSON_MEDIA_TYPE }]
+    }),
+    envelope.message,
+    identity.statusMessageId
+  );
 }
 
 // src/protocols/a2a/adapter.ts
 var MAX_REQUEST_BODY_BYTES = 256 * 1024;
+var VERSION_PATTERN = /^(\d+\.\d+)(?:\.\d+)?$/;
+var A2A_VERSION_PARAMETER = "A2A-Version";
+var AGENT_CARD_CACHE_CONTROL = "public, max-age=300";
 var DEFAULT_AGENT_DESCRIPTION = "Agent Commerce Gateway: canonical commerce resources exposed as A2A skills.";
 var A2aProtocolAdapter = class {
   name = "a2a";
@@ -3754,6 +4275,10 @@ var A2aProtocolAdapter = class {
   // Built once at start: resources are fixed at config load, and a per-request
   // build would be work an unauthenticated GET could trigger at will
   card;
+  cardBody = "";
+  cardEtag = "";
+  // Purchases waiting for an x402 extension payment
+  pendingPayments;
   constructor(options = {}) {
     this.mountPath = options.mountPath ?? A2A_DEFAULT_MOUNT_PATH;
     this.agentName = options.agentName ?? A2A_DEFAULT_AGENT_NAME;
@@ -3790,6 +4315,9 @@ var A2aProtocolAdapter = class {
       mountPath: this.mountPath,
       resources
     });
+    this.pendingPayments = createPendingPayments(context.clock);
+    this.cardBody = JSON.stringify(this.card);
+    this.cardEtag = `"${createHash("sha256").update(this.cardBody).digest("base64url")}"`;
     this.started = true;
     context.logger.info(
       { mountPath: this.mountPath, cardPath: A2A_AGENT_CARD_PATH, skillCount: resources.length },
@@ -3807,7 +4335,14 @@ var A2aProtocolAdapter = class {
         this.writeJson(res, 405, { error: "Method not allowed. The Agent Card is read-only." });
         return;
       }
-      this.writeJson(res, 200, this.card);
+      const cacheHeaders = { "cache-control": AGENT_CARD_CACHE_CONTROL, etag: this.cardEtag };
+      if (matchesEtag(req.headers["if-none-match"], this.cardEtag)) {
+        res.writeHead(304, cacheHeaders);
+        res.end();
+        return;
+      }
+      res.writeHead(200, { "content-type": A2A_JSON_MEDIA_TYPE, ...cacheHeaders });
+      res.end(this.cardBody);
     } catch (err) {
       this.context?.logger.error({ err: toLogInfo(err) }, "a2a adapter: agent card request failed");
       this.writeJson(res, 500, { error: "Internal server error." });
@@ -3836,21 +4371,19 @@ var A2aProtocolAdapter = class {
         );
         return;
       }
-      const version = req.headers[A2A_VERSION_HEADER];
-      const declared = Array.isArray(version) ? version[0] : version;
-      if (declared !== A2A_PROTOCOL_VERSION) {
+      const read = await readCappedBody(req, MAX_REQUEST_BODY_BYTES);
+      if (read.kind === "too-large") {
         this.writeJson(
           res,
-          200,
+          413,
           jsonRpcError(
             null,
-            A2A_ERROR_UNSUPPORTED_OPERATION,
-            `Unsupported A2A protocol version. Send the ${A2A_VERSION_HEADER} header with "${A2A_PROTOCOL_VERSION}".`
+            JSONRPC_INVALID_REQUEST,
+            `Request body exceeds the ${MAX_REQUEST_BODY_BYTES}-byte limit.`
           )
         );
         return;
       }
-      const read = await readCappedBody(req, MAX_REQUEST_BODY_BYTES);
       if (read.kind !== "ok") {
         this.writeJson(
           res,
@@ -3864,10 +4397,31 @@ var A2aProtocolAdapter = class {
         this.writeJson(res, 200, jsonRpcError(parsed.id, parsed.error.code, parsed.error.message));
         return;
       }
+      const version = req.headers[A2A_VERSION_HEADER];
+      const declared = (Array.isArray(version) ? version[0] : version) ?? new URL(req.url ?? "/", "http://localhost").searchParams.get(A2A_VERSION_PARAMETER);
+      if (declared?.match(VERSION_PATTERN)?.[1] !== A2A_PROTOCOL_VERSION) {
+        this.writeJson(
+          res,
+          200,
+          jsonRpcError(
+            parsed.request.id,
+            A2A_ERROR_VERSION_NOT_SUPPORTED,
+            `Unsupported A2A protocol version. Send the ${A2A_VERSION_PARAMETER} header with "${A2A_PROTOCOL_VERSION}".`
+          )
+        );
+        return;
+      }
+      const response = await this.dispatch(
+        parsed.request.id,
+        parsed.request.method,
+        parsed.request.params,
+        requestsX402Extension(req.headers[A2A_EXTENSIONS_HEADER])
+      );
       this.writeJson(
         res,
         200,
-        await this.dispatch(parsed.request.id, parsed.request.method, parsed.request.params)
+        response,
+        usesX402Extension(response) ? { [A2A_EXTENSIONS_HEADER]: A2A_X402_EXTENSION_URI } : {}
       );
     } catch (err) {
       this.context?.logger.error({ err: toLogInfo(err) }, "a2a adapter: request handling failed");
@@ -3878,7 +4432,21 @@ var A2aProtocolAdapter = class {
       );
     }
   }
-  async dispatch(id, method, params) {
+  async dispatch(id, method, params, x402Extension) {
+    if (A2A_PUSH_CONFIG_METHODS.includes(method)) {
+      return jsonRpcError(
+        id,
+        A2A_ERROR_PUSH_NOTIFICATION_NOT_SUPPORTED,
+        `A2A method "${method}" is not supported: this agent does not support push notifications.`
+      );
+    }
+    if (A2A_TASK_LOOKUP_METHODS.includes(method)) {
+      return jsonRpcError(
+        id,
+        A2A_ERROR_TASK_NOT_FOUND,
+        "Task not found. Finished tasks are not retained; continue a pending payment with SendMessage."
+      );
+    }
     if (A2A_UNSUPPORTED_METHODS.includes(method)) {
       return jsonRpcError(
         id,
@@ -3889,18 +4457,21 @@ var A2aProtocolAdapter = class {
     if (method !== A2A_METHOD_SEND_MESSAGE) {
       return jsonRpcError(id, JSONRPC_METHOD_NOT_FOUND, `Unknown method "${method}".`);
     }
+    const resumed = await this.resumePayment(id, params);
+    if (resumed !== void 0) return resumed;
     let invocation;
     try {
       invocation = parseInvocation(params);
     } catch (err) {
       const error = toCommerceError(err);
-      const code = error.code === "PROTOCOL_UNSUPPORTED" ? A2A_ERROR_UNSUPPORTED_OPERATION : JSONRPC_INVALID_PARAMS;
+      const a2aErrorCode = error.details?.["a2aErrorCode"];
+      const code = typeof a2aErrorCode === "number" ? a2aErrorCode : error.code === "PROTOCOL_UNSUPPORTED" ? A2A_ERROR_UNSUPPORTED_OPERATION : JSONRPC_INVALID_PARAMS;
       return jsonRpcError(id, code, error.message);
     }
-    return this.execute(id, invocation);
+    return this.execute(id, invocation, x402Extension);
   }
   // One accepted invocation, one `pipeline.execute()`
-  async execute(id, invocation) {
+  async execute(id, invocation, x402Extension) {
     const context = this.context;
     if (context === void 0) {
       return jsonRpcError(id, JSONRPC_INTERNAL_ERROR, "A2A adapter is not running.");
@@ -3936,9 +4507,29 @@ var A2aProtocolAdapter = class {
         ...authorization !== void 0 ? { authorization } : {}
       };
       const outcome = await context.pipeline.execute(request);
+      if (outcome.kind !== "payment-required") {
+        return this.taskResult(id, completedTask(outcome, identity));
+      }
+      const task2 = paymentRequiredTask(outcome, identity);
+      const envelope = outcome.requirement.challenge.envelope;
+      if (!x402Extension || outcome.requirement.provider !== "x402" || !isRecord(envelope)) {
+        return this.taskResult(id, task2);
+      }
+      const network = outcome.requirement.network;
+      this.pendingPayments?.put(
+        identity.taskId,
+        {
+          contextId: identity.contextId,
+          resourceId: invocation.resourceId,
+          input,
+          ...authorization !== void 0 ? { authorization } : {},
+          ...network !== void 0 ? { network } : {}
+        },
+        outcome.requirement.expiresAt
+      );
       return this.taskResult(
         id,
-        outcome.kind === "payment-required" ? paymentRequiredTask(outcome, identity) : completedTask(outcome, identity)
+        inputRequired(task2, paymentRequiredMetadata(envelope), identity.statusMessageId)
       );
     } catch (err) {
       const error = toCommerceError(err);
@@ -3949,11 +4540,139 @@ var A2aProtocolAdapter = class {
       return this.taskResult(id, failedTask(error, identity));
     }
   }
+  /**
+   * A message on a task waiting for an x402 extension payment, recognized by
+   * its `taskId` whether or not the header activated the extension again. Any
+   * other task id falls through to `parseInvocation`, which answers
+   * TaskNotFoundError.
+   */
+  async resumePayment(id, params) {
+    const context = this.context;
+    const message = isRecord(params) ? params["message"] : void 0;
+    const taskId = isRecord(message) ? message["taskId"] : void 0;
+    if (context === void 0 || typeof taskId !== "string") return void 0;
+    const pending = this.pendingPayments?.get(taskId);
+    if (pending === void 0) return void 0;
+    const messageId = isRecord(message) ? message["messageId"] : void 0;
+    if (typeof messageId !== "string" || messageId.length === 0) {
+      return jsonRpcError(
+        id,
+        JSONRPC_INVALID_PARAMS,
+        'Message must carry a non-empty "messageId".'
+      );
+    }
+    const roleProblem = userRoleProblem(isRecord(message) ? message["role"] : void 0);
+    if (roleProblem !== void 0) return jsonRpcError(id, JSONRPC_INVALID_PARAMS, roleProblem);
+    const contextId = isRecord(message) ? message["contextId"] : void 0;
+    if (contextId !== void 0 && contextId !== pending.contextId) {
+      return jsonRpcError(
+        id,
+        JSONRPC_INVALID_PARAMS,
+        'Message "contextId" does not match the task.'
+      );
+    }
+    const submission = readPaymentSubmission(message);
+    if (submission === void 0) {
+      return jsonRpcError(
+        id,
+        JSONRPC_INVALID_PARAMS,
+        `For a pending task, set "${X402_PAYMENT_STATUS_KEY}" to "payment-submitted" and provide a "${X402_PAYMENT_PAYLOAD_KEY}" object, or set it to "payment-rejected".`
+      );
+    }
+    let authorization = pending.authorization;
+    if (authorization === void 0 && submission.kind === "submitted") {
+      try {
+        authorization = readFollowUpAuthorization(message);
+      } catch (err) {
+        return jsonRpcError(id, JSONRPC_INVALID_PARAMS, toCommerceError(err).message);
+      }
+    }
+    this.pendingPayments?.delete(taskId);
+    const statusMessageId = context.ids.next("a2a-msg");
+    const identity = {
+      taskId,
+      contextId: pending.contextId,
+      artifactId: context.ids.next("a2a-artifact"),
+      statusMessageId,
+      timestamp: context.clock.nowIso()
+    };
+    if (submission.kind === "rejected") {
+      const declined = {
+        id: taskId,
+        contextId: pending.contextId,
+        status: { state: A2A_TASK_STATE_FAILED, timestamp: identity.timestamp },
+        artifacts: []
+      };
+      return this.taskResult(
+        id,
+        withStatusMessage(
+          declined,
+          "Payment was declined.",
+          statusMessageId,
+          paymentRejectedMetadata()
+        )
+      );
+    }
+    return this.taskResult(
+      id,
+      await this.payPending(
+        context,
+        { ...pending, ...authorization !== void 0 ? { authorization } : {} },
+        submission.payload,
+        identity
+      )
+    );
+  }
+  // The pending purchase, now with the x402 `PaymentPayload` as its proof
+  async payPending(context, pending, payload, identity) {
+    const requestId = context.ids.next("a2a");
+    const request = {
+      requestId,
+      resourceId: pending.resourceId,
+      input: pending.input,
+      protocol: "a2a",
+      receivedAt: context.clock.nowIso(),
+      // The same encoding as the HTTP header's base64 PaymentPayload JSON
+      payment: {
+        method: "x402",
+        payload: Buffer.from(JSON.stringify(payload), "utf8").toString("base64")
+      },
+      ...pending.authorization !== void 0 ? { authorization: pending.authorization } : {}
+    };
+    let error;
+    try {
+      const outcome = await context.pipeline.execute(request);
+      if (outcome.kind === "delivered" && outcome.payment !== void 0) {
+        return withStatusMessage(
+          completedTask(outcome, identity),
+          "Payment settled.",
+          identity.statusMessageId,
+          paymentCompletedMetadata(outcome.payment)
+        );
+      }
+      error = new CommerceError("PAYMENT_INVALID", "The payment was not accepted.", { requestId });
+    } catch (err) {
+      error = toCommerceError(err);
+      context.logger.warn(
+        { resourceId: pending.resourceId, requestId, err: toLogInfo(error) },
+        "a2a adapter: x402 extension payment failed"
+      );
+    }
+    const metadata = paymentFailureMetadata(error, pending.network);
+    let text = "Payment failed.";
+    if (metadata[X402_PAYMENT_STATUS_KEY] === "payment-completed") {
+      text = "Payment settled, but the resource could not be delivered.";
+    } else if (!error.code.startsWith("PAYMENT_")) {
+      text = "The resource could not be delivered.";
+    }
+    return withStatusMessage(failedTask(error, identity), text, identity.statusMessageId, metadata);
+  }
   taskIdentity(context, requestId) {
     return {
       taskId: requestId,
       contextId: context.ids.next("a2a-ctx"),
       artifactId: context.ids.next("a2a-artifact"),
+      statusMessageId: context.ids.next("a2a-msg"),
       timestamp: context.clock.nowIso()
     };
   }
@@ -3971,15 +4690,27 @@ var A2aProtocolAdapter = class {
   async stop() {
     this.started = false;
     this.card = void 0;
+    this.cardBody = "";
+    this.cardEtag = "";
+    this.pendingPayments?.clear();
+    this.pendingPayments = void 0;
     this.skillsById = /* @__PURE__ */ new Map();
     this.context = void 0;
   }
-  writeJson(res, status, body) {
+  writeJson(res, status, body, headers = {}) {
     if (res.headersSent) return;
-    res.writeHead(status, { "content-type": A2A_JSON_MEDIA_TYPE });
+    res.writeHead(status, { "content-type": A2A_JSON_MEDIA_TYPE, ...headers });
     res.end(JSON.stringify(body));
   }
 };
+function usesX402Extension(response) {
+  const result = response["result"];
+  return result?.task?.status.message?.extensions?.includes(A2A_X402_EXTENSION_URI) === true;
+}
+function matchesEtag(header2, etag) {
+  if (header2 === void 0) return false;
+  return header2.split(",").map((tag) => tag.trim().replace(/^W\//, "")).some((tag) => tag === "*" || tag === etag);
+}
 function createA2aAdapter(options = {}) {
   return new A2aProtocolAdapter(options);
 }
@@ -3993,7 +4724,8 @@ function toCanonicalRequest(options) {
     input: canonicalInput(request),
     protocol: "acp",
     receivedAt,
-    ...idempotencyKey !== void 0 ? { idempotencyKey } : {}
+    ...idempotencyKey !== void 0 ? { idempotencyKey } : {},
+    ...request.forwardedHeaders !== void 0 && Object.keys(request.forwardedHeaders).length > 0 ? { backendHeaders: request.forwardedHeaders } : {}
   };
 }
 function canonicalInput(request) {
@@ -4001,7 +4733,7 @@ function canonicalInput(request) {
   const optionalKeys = ACP_OPERATION_OPTIONAL_INPUT_KEYS[request.route.operation] ?? [];
   const input = {};
   if (keys.includes("path") && request.route.sessionId !== void 0) {
-    input["path"] = { checkout_session_id: request.route.sessionId };
+    input["path"] = { [ACP_SESSION_ID_INPUT_KEY]: request.route.sessionId };
   }
   if (keys.includes("body")) {
     input["body"] = request.body;
@@ -4016,7 +4748,9 @@ var ACP_CAPABILITIES = [
   "rest transport",
   "well-known discovery",
   "bearer authentication",
-  "API-Version negotiation",
+  "API-Version enforcement",
+  // Forwarded as received: the gateway verifies neither signature header
+  "request header forwarding to the merchant",
   "checkout service",
   ...ACP_CHECKOUT_OPERATIONS
 ];
@@ -4099,10 +4833,10 @@ function writeAcpFailure(res, failure, headers = {}) {
   writeAcpJson(res, failure.status, failure.error, headers);
 }
 function operationKey(scope) {
-  return sha2562(`acp-operation:${scope.deployment}:${scope.endpoint}:${scope.key}`);
+  return sha256(`acp-operation:${scope.deployment}:${scope.endpoint}:${scope.key}`);
 }
 function requestFingerprint(body) {
-  return sha2562(canonicalize(body));
+  return sha256(canonicalize(body));
 }
 function canonicalize(value) {
   if (value === null) return "null";
@@ -4113,7 +4847,7 @@ function canonicalize(value) {
   }
   return JSON.stringify(value) ?? "null";
 }
-function sha2562(value) {
+function sha256(value) {
   return createHash("sha256").update(value, "utf8").digest("hex");
 }
 
@@ -4130,7 +4864,7 @@ function createAcpIdempotencyStore(options) {
     logger
   });
   migrate(db, logger);
-  resolveOrphanedClaims(db, logger);
+  resolveOrphanedClaims(db, logger, options.releaseOrphans === true);
   const selectStmt = db.prepare(
     `SELECT state, fingerprint, status, body_json FROM acp_idempotency
       WHERE deployment = ? AND endpoint = ? AND idempotency_key = ?`
@@ -4212,7 +4946,17 @@ function createAcpIdempotencyStore(options) {
     }
   };
 }
-function resolveOrphanedClaims(db, logger) {
+function resolveOrphanedClaims(db, logger, release) {
+  if (release) {
+    const { changes: changes2 } = db.prepare("DELETE FROM acp_idempotency WHERE state = 'in_flight'").run();
+    if (changes2 > 0) {
+      logger.warn(
+        { released: changes2 },
+        "acp idempotency: freed claims left in flight by an earlier process; merchant deduplication is enabled"
+      );
+    }
+    return;
+  }
   const { changes } = db.prepare("UPDATE acp_idempotency SET state = 'unresolved' WHERE state = 'in_flight'").run();
   if (changes > 0) {
     logger.warn(
@@ -4257,8 +5001,7 @@ function migrate(db, logger) {
 }
 
 // src/protocols/acp/router.ts
-var MAX_SESSION_ID_LENGTH = 128;
-var SESSION_ID_PATTERN = /^[A-Za-z0-9._~-]{1,128}$/;
+var MAX_SEGMENT_LENGTH = 512;
 var COLLECTION = "checkout_sessions";
 function matchAcpRoute(method, url, mountPath) {
   const segments = routeSegments(url, mountPath);
@@ -4276,7 +5019,7 @@ function matchAcpRoute(method, url, mountPath) {
     };
   }
   const sessionId = segments[1];
-  if (sessionId === void 0 || !SESSION_ID_PATTERN.test(sessionId)) return { kind: "not-found" };
+  if (sessionId === void 0 || !isSessionId(sessionId)) return { kind: "not-found" };
   if (segments.length === 2) {
     if (verb === "GET") {
       return {
@@ -4313,8 +5056,16 @@ function matchAcpRoute(method, url, mountPath) {
   }
   return { kind: "not-found" };
 }
+function isSessionId(value) {
+  if (value.length === 0) return false;
+  for (const char of value) {
+    const code = char.charCodeAt(0);
+    if (code < 32 || code === 127) return false;
+  }
+  return true;
+}
 function endpointPath(mountPath, segments) {
-  return `${mountPath.replace(/\/+$/, "")}/${segments.join("/")}`;
+  return `${mountPath.replace(/\/+$/, "")}/${segments.map(encodeURIComponent).join("/")}`;
 }
 function routeSegments(url, mountPath) {
   if (url === void 0) return void 0;
@@ -4325,7 +5076,7 @@ function routeSegments(url, mountPath) {
   const segments = [];
   for (const raw of rest.split("/")) {
     if (raw.length === 0) continue;
-    if (raw.length > MAX_SESSION_ID_LENGTH) return void 0;
+    if (raw.length > MAX_SEGMENT_LENGTH) return void 0;
     try {
       segments.push(decodeURIComponent(raw));
     } catch {
@@ -8269,6 +9020,7 @@ function acpValidators() {
   });
   addFormats(ajv);
   const document = relaxExtensibleEnums(structuredClone(schema_agentic_checkout_default));
+  openCapabilityValues(document);
   const schemaId = typeof document["$id"] === "string" ? document["$id"] : "";
   ajv.addSchema(document);
   const compiled = /* @__PURE__ */ new Map();
@@ -8300,6 +9052,14 @@ function relaxExtensibleEnums(node) {
   for (const value of Object.values(record)) relaxExtensibleEnums(value);
   return node;
 }
+function openCapabilityValues(document) {
+  const defs = document["$defs"];
+  const properties = defs["InterventionCapabilities"]?.properties ?? {};
+  for (const list of ["supported", "required"]) {
+    const items = properties[list]?.items;
+    if (items !== void 0) delete items["enum"];
+  }
+}
 function validateAcpDocument(definition, value) {
   const validate = acpValidators().get(definition);
   if (validate === void 0) return { code: "unknown_definition" };
@@ -8330,7 +9090,23 @@ var REQUEST_DEFINITIONS = {
   cancelCheckoutSession: "cancelRequest",
   getCheckoutSession: void 0
 };
+function acpEchoHeaders(req) {
+  const echo = {};
+  const presentedRequestId = normalizeRequestId(header(req, ACP_REQUEST_ID_HEADER));
+  if (presentedRequestId !== void 0) echo[ACP_REQUEST_ID_HEADER] = presentedRequestId;
+  const presentedKey = header(req, ACP_IDEMPOTENCY_KEY_HEADER)?.trim();
+  if (req.method === "POST" && presentedKey !== void 0 && isUsableIdempotencyKey(presentedKey)) {
+    echo[ACP_IDEMPOTENCY_KEY_HEADER] = presentedKey;
+  }
+  return echo;
+}
 async function guardAcpRequest(req, options) {
+  const echo = acpEchoHeaders(req);
+  const failed = (failure2, extra = {}) => ({
+    ok: false,
+    ...failure2,
+    headers: { ...echo, ...extra }
+  });
   const matched = matchAcpRoute(req.method, req.url, options.mountPath);
   if (matched.kind === "not-found") {
     return failed(acpFailure(404, "invalid_request", "not_found", "Unknown ACP route."));
@@ -8342,7 +9118,8 @@ async function guardAcpRequest(req, options) {
         "invalid_request",
         "method_not_allowed",
         `This ACP route accepts ${matched.allow.join(", ")}.`
-      )
+      ),
+      { allow: matched.allow.join(", ") }
     );
   }
   const route = matched.route;
@@ -8353,7 +9130,9 @@ async function guardAcpRequest(req, options) {
         "invalid_request",
         "unauthorized",
         'A valid "Authorization: Bearer <token>" header is required.'
-      )
+      ),
+      // RFC 9110 requires a challenge on every 401
+      { "www-authenticate": "Bearer" }
     );
   }
   const version = header(req, ACP_API_VERSION_HEADER);
@@ -8381,8 +9160,8 @@ async function guardAcpRequest(req, options) {
   }
   let idempotencyKey;
   if (route.acceptsBody) {
-    const presented = header(req, ACP_IDEMPOTENCY_KEY_HEADER)?.trim();
-    if (presented === void 0 || presented.length === 0) {
+    const presentedKey = header(req, ACP_IDEMPOTENCY_KEY_HEADER)?.trim();
+    if (presentedKey === void 0 || presentedKey.length === 0) {
       return failed(
         acpFailure(
           400,
@@ -8392,7 +9171,7 @@ async function guardAcpRequest(req, options) {
         )
       );
     }
-    if (presented.length > ACP_MAX_IDEMPOTENCY_KEY_LENGTH || !isVisibleAscii(presented)) {
+    if (!isUsableIdempotencyKey(presentedKey)) {
       return failed(
         acpFailure(
           400,
@@ -8402,7 +9181,7 @@ async function guardAcpRequest(req, options) {
         )
       );
     }
-    idempotencyKey = presented;
+    idempotencyKey = presentedKey;
   }
   const read = await readCappedBody(req, options.maxBodyBytes ?? ACP_MAX_REQUEST_BODY_BYTES);
   if (read.kind === "too-large") {
@@ -8481,12 +9260,23 @@ function ok(route, body, req, idempotencyKey) {
       route,
       body,
       ...requestId !== void 0 ? { requestId } : {},
-      ...idempotencyKey !== void 0 ? { idempotencyKey } : {}
+      ...idempotencyKey !== void 0 ? { idempotencyKey } : {},
+      forwardedHeaders: forwardedHeaders(req, requestId)
     }
   };
 }
-function failed(failure) {
-  return { ok: false, ...failure };
+function forwardedHeaders(req, requestId) {
+  const forwarded = {};
+  for (const name of ACP_FORWARDED_HEADERS) {
+    const value = name === ACP_REQUEST_ID_HEADER ? requestId : header(req, name)?.trim();
+    if (value !== void 0 && value.length > 0 && value.length <= ACP_MAX_FORWARDED_HEADER_LENGTH && isVisibleAscii(value)) {
+      forwarded[name] = value;
+    }
+  }
+  return forwarded;
+}
+function isUsableIdempotencyKey(value) {
+  return value.length > 0 && value.length <= ACP_MAX_IDEMPOTENCY_KEY_LENGTH && isVisibleAscii(value);
 }
 function normalizeRequestId(value) {
   if (value === void 0) return void 0;
@@ -8544,8 +9334,36 @@ function toAcpResponse(operation, outcome) {
       }
     };
   }
+  const htmlPath = rawHtmlPath(outcome.body, "$");
+  if (htmlPath !== void 0) {
+    return {
+      response: asResponse(PROCESSING_ERROR),
+      logDetail: { reason: "backend-markdown-has-raw-html", operation, path: htmlPath }
+    };
+  }
   return { response: { status: expected, body: outcome.body } };
 }
+var RAW_HTML = /<\/?[A-Za-z][A-Za-z0-9-]*(?=[\s/>]|$)|<!--|<\?|<![A-Za-z]|<!\[CDATA\[/;
+var CODE_SPAN = /(`+)[\s\S]*?\1/g;
+function rawHtmlPath(node, path2) {
+  if (Array.isArray(node)) {
+    for (const [index, item] of node.entries()) {
+      const found = rawHtmlPath(item, `${path2}[${index}]`);
+      if (found !== void 0) return found;
+    }
+    return void 0;
+  }
+  if (!isRecord(node)) return void 0;
+  const content = node["content"];
+  if (node["content_type"] === "markdown" && typeof content === "string" && RAW_HTML.test(content.replace(CODE_SPAN, ""))) {
+    return `${path2}.content`;
+  }
+  for (const [key, value] of Object.entries(node)) {
+    const found = rawHtmlPath(value, `${path2}.${key}`);
+    if (found !== void 0) return found;
+  }
+  return void 0;
+}
 function responseDefinition(operation, body) {
   if (operation !== "completeCheckoutSession") return "checkoutSession";
   const status = body?.status;
@@ -8581,8 +9399,39 @@ function mapCommerceErrorToAcp(error, operation) {
   }
 }
 function fromBackendStatus(error, operation) {
-  const status = error.details?.["status"];
-  switch (typeof status === "number" ? status : 0) {
+  const failure = statusFailure(error, operation);
+  return failure.status < 500 ? withMerchantError(failure, error) : failure;
+}
+function isMerchantRateLimit(error) {
+  return error.code === "BACKEND_ERROR" && error.details?.["status"] === 429;
+}
+function merchantRetryAfterSeconds(error) {
+  const value = error.cause instanceof BackendErrorResponse ? error.cause.headers["retry-after"] : void 0;
+  if (value === void 0 || !/^\d{1,9}$/.test(value.trim())) {
+    return ACP_MERCHANT_RETRY_AFTER_DEFAULT_SECONDS;
+  }
+  return Math.min(Math.max(Number(value), 1), ACP_MERCHANT_RETRY_AFTER_MAX_SECONDS);
+}
+var MERCHANT_CODE = /^(?!idempotency_)[a-z][a-z0-9_]{0,63}$/;
+var MERCHANT_PARAM = /^\$[\x20-\x7e]{0,255}$/;
+function withMerchantError(failure, error) {
+  const body = error.cause instanceof BackendErrorResponse ? error.cause.body : void 0;
+  if (!isRecord(body) || validateAcpDocument("error", body) !== void 0) return failure;
+  const { type, code, param } = body;
+  if (typeof code !== "string" || !MERCHANT_CODE.test(code)) return failure;
+  const relayParam = typeof param === "string" && MERCHANT_PARAM.test(param) ? param : void 0;
+  return acpFailure(
+    failure.status,
+    type,
+    code,
+    failure.error.message,
+    relayParam !== void 0 ? { param: relayParam } : {}
+  );
+}
+function statusFailure(error, operation) {
+  const merchantStatus = error.details?.["status"];
+  const status = typeof merchantStatus === "number" ? merchantStatus : 0;
+  switch (status) {
     case 404:
       return acpFailure(
         404,
@@ -8605,7 +9454,7 @@ function fromBackendStatus(error, operation) {
     case 400:
     case 422:
       return acpFailure(
-        422,
+        status,
         "invalid_request",
         "invalid_request_body",
         "The merchant rejected this checkout request."
@@ -8617,6 +9466,17 @@ function fromBackendStatus(error, operation) {
         "checkout_session_conflict",
         "This checkout session is in a state that does not allow this operation."
       );
+    case 429:
+    case 503:
+      return {
+        ...acpFailure(
+          503,
+          "service_unavailable",
+          "service_unavailable",
+          "The merchant is temporarily unavailable."
+        ),
+        retryAfterSeconds: merchantRetryAfterSeconds(error)
+      };
     default:
       return acpFailure(
         502,
@@ -8627,7 +9487,11 @@ function fromBackendStatus(error, operation) {
   }
 }
 function asResponse(failure) {
-  return { status: failure.status, body: failure.error };
+  return {
+    status: failure.status,
+    body: failure.error,
+    ...failure.retryAfterSeconds !== void 0 ? { retryAfterSeconds: failure.retryAfterSeconds } : {}
+  };
 }
 
 // src/protocols/acp/adapter.ts
@@ -8648,8 +9512,8 @@ var PRE_BACKEND_ERROR_CODES = /* @__PURE__ */ new Set([
   "AUTHORIZATION_REPLAYED",
   "AUTHORIZATION_PROVIDER_UNAVAILABLE"
 ]);
-function reachedFor(code) {
-  return PRE_BACKEND_ERROR_CODES.has(code) ? "no" : "unknown";
+function reachedFor(error) {
+  return PRE_BACKEND_ERROR_CODES.has(error.code) || isMerchantRateLimit(error) ? "no" : "unknown";
 }
 function notReached(failure) {
   return { response: asResponse(failure), reached: "no" };
@@ -8727,6 +9591,7 @@ var AcpProtocolAdapter = class {
     this.idempotency = createAcpIdempotencyStore({
       path: this.idempotencyOptions.path,
       retentionHours: this.idempotencyOptions.retentionHours,
+      releaseOrphans: this.idempotencyOptions.merchantIdempotent === true,
       logger: context.logger
     });
     this.discovery = document;
@@ -8763,7 +9628,8 @@ var AcpProtocolAdapter = class {
             "invalid_request",
             "method_not_allowed",
             "The ACP discovery document is read-only."
-          )
+          ),
+          { allow: "GET" }
         );
         return;
       }
@@ -8783,7 +9649,8 @@ var AcpProtocolAdapter = class {
             "service_unavailable",
             "service_unavailable",
             "The ACP adapter is not running."
-          )
+          ),
+          acpEchoHeaders(req)
         );
         return;
       }
@@ -8792,14 +9659,14 @@ var AcpProtocolAdapter = class {
         isAuthorized: this.isAuthorized
       });
       if (!guarded.ok) {
-        writeAcpFailure(res, guarded);
+        writeAcpFailure(res, guarded, guarded.headers);
         return;
       }
       const request = guarded.value;
       const response = await this.dispatch(request);
       writeAcpJson(res, response.status, response.body, this.responseHeaders(request, response));
     } catch (err) {
-      this.fail(res, err, "acp adapter: request handling failed");
+      this.fail(res, err, "acp adapter: request handling failed", acpEchoHeaders(req));
     }
   }
   /**
@@ -8833,7 +9700,7 @@ var AcpProtocolAdapter = class {
         return asResponse(
           acpFailure(
             409,
-            "processing_error",
+            "invalid_request",
             "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."
           )
@@ -8859,7 +9726,7 @@ var AcpProtocolAdapter = class {
     }
     if (outcome.response.status < 500) {
       store.complete(scope, outcome.response);
-    } else if (outcome.reached === "no") {
+    } else if (outcome.reached === "no" || this.idempotencyOptions.merchantIdempotent === true) {
       store.release(scope);
     } else {
       store.markUnresolved(scope);
@@ -8917,18 +9784,19 @@ var AcpProtocolAdapter = class {
         {
           resourceId: resource.id,
           requestId: canonical.requestId,
-          reached: reachedFor(error.code),
+          reached: reachedFor(error),
           err: toLogInfo(error)
         },
         "acp adapter: checkout execution failed"
       );
       return {
         response: asResponse(mapCommerceErrorToAcp(error, request.route.operation)),
-        reached: reachedFor(error.code)
+        reached: reachedFor(error)
       };
     }
   }
-  // Protocol-owned headers only; a merchant backend's headers are never proxied
+  // Protocol-owned headers only. No merchant header is proxied: `Retry-After`
+  // is written from seconds the mapping parsed and capped.
   responseHeaders(request, response) {
     const replayed = response?.replayed === true;
     return {
@@ -8938,11 +9806,12 @@ var AcpProtocolAdapter = class {
       ...response?.retryAfterSeconds !== void 0 ? { "retry-after": String(response.retryAfterSeconds) } : {}
     };
   }
-  fail(res, err, message) {
+  fail(res, err, message, headers = {}) {
     this.context?.logger.error({ err: toLogInfo(err) }, message);
     writeAcpFailure(
       res,
-      acpFailure(500, "processing_error", "internal_error", "Internal server error.")
+      acpFailure(500, "processing_error", "internal_error", "Internal server error."),
+      headers
     );
   }
   async health() {
@@ -9218,6 +10087,9 @@ function createSqliteReceiptStore(options) {
   const listPaymentAttemptsByRequestStmt = db.prepare(
     "SELECT * FROM payment_attempts WHERE request_id = ? ORDER BY created_at DESC, seq DESC LIMIT ?"
   );
+  const paymentAttemptStatusStmt = db.prepare(
+    "SELECT status FROM payment_attempts WHERE replay_key = ?"
+  );
   let closed = false;
   const descriptor = {
     name: "sqlite-receipt-store",
@@ -9274,10 +10146,15 @@ function createSqliteReceiptStore(options) {
         });
       } catch (err) {
         if (isUniqueConstraintOn(err, "payment_attempts.replay_key")) {
+          const existing = paymentAttemptStatusStmt.get(reservation.replayKey);
           throw new CommerceError(
             "PAYMENT_REPLAYED",
             `Payment authorization has already been used (replayKey=${reservation.replayKey})`,
-            { requestId: reservation.requestId, resourceId: reservation.resourceId }
+            {
+              requestId: reservation.requestId,
+              resourceId: reservation.resourceId,
+              ...existing !== void 0 ? { details: { attemptStatus: existing.status } } : {}
+            }
           );
         }
         throw toCommerceError(err, "STORAGE_ERROR", "Failed to reserve payment attempt");