@devlab.group/agent-commerce 1.5.0 → 1.6.1

package/dist/index.js

@@ -1,16 +1,18 @@
-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-US622BKF.js';
-import { MPP_DEFAULT_NETWORK, isMppNetwork, MPP_NETWORKS, MPP_MIN_CHALLENGE_SECRET_LENGTH, MPP_PROFILE } from './chunk-6D2EZ5ME.js';
-import { resolveX402Deployment, resolveDeploymentMode, requireNetworkProfile } from './chunk-PBYN7EK2.js';
-import { RESERVED_INPUT_FIELDS, PROTOCOL_NAMES, PAYMENT_METHOD_NAMES, PAYMENT_HEADER, AUTHORIZATION_HEADER, CommerceError, systemClock, NOOP_LOGGER, PACKAGE_VERSION, toCommerceError, DEFAULT_BACKEND_TIMEOUT_MS, toErrorEnvelope, isHttpProtocolAdapter, isCommerceError, parseAuthorizationHeader, toPaymentRequiredEnvelope, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER } from './chunk-5GEWKNIH.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-5GEWKNIH.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-VKDXMXHL.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-CBJIT7QP.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-N5KRK7YA.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-N5KRK7YA.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 { createRequire } from 'module';
 import pino from 'pino';
-import Fastify from 'fastify';
 import Ajv2020 from 'ajv/dist/2020.js';
 import addFormats from 'ajv-formats';
 
@@ -26,7 +28,7 @@ function substituteEnv(value, env, path2 = "$") {
   if (Array.isArray(value)) {
     return value.map((entry, index) => substituteEnv(entry, env, `${path2}[${index}]`));
   }
-  if (isPlainObject(value)) {
+  if (isRecord(value)) {
     const result = {};
     for (const [key, entry] of Object.entries(value)) {
       result[key] = substituteEnv(entry, env, `${path2}.${key}`);
@@ -43,16 +45,15 @@ function assertTemplateIsSupported(value, path2) {
   if (NESTED_PLACEHOLDER.test(value)) {
     throw new CommerceError(
       "CONFIG_INVALID",
-      `Configuration value at "${path2}" nests placeholders (e.g. "\${A:-\${B}}"), which is not supported \u2014 the inner one is not resolved and its closing brace ends up in the value. Use a plain default, or set the variable.`,
+      `Configuration value at "${path2}" nests placeholders (e.g. "\${A:-\${B}}"), which is not supported: the inner one is not resolved and its closing brace ends up in the value. Use a plain default, or set the variable.`,
       { details: { path: path2 } }
     );
   }
-  BRACE_TOKEN.lastIndex = 0;
   for (const [token] of value.matchAll(BRACE_TOKEN)) {
     if (SUPPORTED_TOKEN.test(token)) continue;
     throw new CommerceError(
       "CONFIG_INVALID",
-      `Configuration value at "${path2}" contains "${token}", which is not a supported placeholder. Only "\${VAR}" and "\${VAR:-default}" are recognised; shell forms such as "\${VAR-default}", "\${VAR:=default}" and "\${VAR:?message}" would load as literal text.`,
+      `Configuration value at "${path2}" contains "${token}", which is not a supported placeholder. Only "\${VAR}" and "\${VAR:-default}" are recognized; shell forms such as "\${VAR-default}", "\${VAR:=default}" and "\${VAR:?message}" would load as literal text.`,
       { details: { path: path2, token } }
     );
   }
@@ -77,9 +78,6 @@ function substituteOnce(value, env, path2) {
     }
   );
 }
-function isPlainObject(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 
 // src/config/filename.ts
 var DEFAULT_CONFIG_FILENAME = "config.yaml";
@@ -98,7 +96,7 @@ var HttpBackendExecutor = class {
   }
   async call(handler, request) {
     const timeoutMs = handler.timeoutMs ?? DEFAULT_BACKEND_TIMEOUT_MS;
-    const inputRecord = isPlainObject2(request.input) ? request.input : {};
+    const inputRecord = isRecord(request.input) ? request.input : {};
     const context = { requestId: request.requestId, resourceId: request.resourceId };
     const parts = buildBackendRequestParts(handler, inputRecord, context);
     let target;
@@ -111,26 +109,17 @@ var HttpBackendExecutor = class {
         cause: error
       });
     }
-    const literalPrefix = handler.url.split("{")[0] ?? handler.url;
-    try {
-      const literalPrefixPathname = new URL(literalPrefix).pathname;
-      if (!target.pathname.startsWith(literalPrefixPathname)) {
-        throw new CommerceError(
-          "INPUT_INVALID",
-          "Path parameters resolved outside the configured backend path",
-          {
-            requestId: request.requestId,
-            resourceId: request.resourceId
-          }
-        );
-      }
-    } catch (error) {
-      if (error instanceof CommerceError) throw error;
+    const prefixPathname = literalPrefixPathname(handler);
+    if (prefixPathname !== void 0 && !target.pathname.startsWith(prefixPathname)) {
+      throw new CommerceError(
+        "INPUT_INVALID",
+        "Path parameters resolved outside the configured backend path",
+        context
+      );
     }
-    const headers = { ...handler.headers ?? {} };
+    const headers = buildHeaders(handler, context);
     if (request.idempotencyKey !== void 0) {
-      deleteHeader(headers, IDEMPOTENCY_KEY_HEADER);
-      headers[IDEMPOTENCY_KEY_HEADER] = request.idempotencyKey;
+      setHeader(headers, IDEMPOTENCY_KEY_HEADER, request.idempotencyKey, context);
     }
     let body;
     checkQueryCollision(target, parts.query, context);
@@ -139,9 +128,7 @@ var HttpBackendExecutor = class {
     }
     if (parts.body !== void 0) {
       body = JSON.stringify(parts.body.value);
-      if (!hasHeader(headers, "content-type")) {
-        headers["content-type"] = "application/json";
-      }
+      if (!headers.has("content-type")) headers.set("content-type", "application/json");
     }
     const started = performance.now();
     let response;
@@ -187,13 +174,13 @@ var HttpBackendExecutor = class {
         }
       );
     }
-    const responseHeaders = headersToRecord(response.headers);
+    const responseHeaders = Object.fromEntries(response.headers);
     const contentType = response.headers.get("content-type") ?? "";
     let parsedBody;
     try {
       parsedBody = await parseBody(response, contentType);
     } catch (error) {
-      const tooLarge = error instanceof Error && error.message.startsWith("response-body-too-large");
+      const tooLarge = isCommerceError(error);
       throw new CommerceError(
         "BACKEND_ERROR",
         tooLarge ? "Backend response exceeded the maximum allowed size" : "Backend response could not be read",
@@ -240,8 +227,9 @@ function findUnparsedBraceToken(url) {
   return token?.[0] ?? residue[index];
 }
 function validateBackendRequestShape(handler, input, context) {
-  const inputRecord = isPlainObject2(input) ? input : {};
+  const inputRecord = isRecord(input) ? input : {};
   const parts = buildBackendRequestParts(handler, inputRecord, context);
+  buildHeaders(handler, context);
   let target;
   try {
     target = new URL(parts.url);
@@ -269,7 +257,7 @@ function buildBackendRequestParts(handler, input, context) {
 function resolveBoundGroup(input, key, kind, context) {
   const value = input[key];
   if (value === void 0) return {};
-  if (!isPlainObject2(value)) {
+  if (!isRecord(value)) {
     throw new CommerceError(
       "INPUT_INVALID",
       `Input "${key}" must be an object of ${kind} parameters`,
@@ -290,14 +278,11 @@ function checkQueryCollision(target, remaining, context) {
     }
   }
 }
-function isPlainObject2(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 var TRAVERSAL_PATH_VALUES = /* @__PURE__ */ new Set(["", ".", ".."]);
 function applyPathTemplate(template, input, context) {
   const remaining = { ...input };
   let missing;
-  let invalid;
+  let invalid2;
   const url = template.replace(PATH_PARAM_PATTERN, (_match, key) => {
     if (!Object.hasOwn(remaining, key)) {
       missing = key;
@@ -307,7 +292,7 @@ function applyPathTemplate(template, input, context) {
     delete remaining[key];
     const raw = stringifyPrimitive(value);
     if (TRAVERSAL_PATH_VALUES.has(raw)) {
-      invalid = key;
+      invalid2 = key;
       return "";
     }
     return encodeURIComponent(raw);
@@ -318,10 +303,10 @@ function applyPathTemplate(template, input, context) {
       details: { field: missing }
     });
   }
-  if (invalid !== void 0) {
-    throw new CommerceError("INPUT_INVALID", `Path parameter "${invalid}" is not a valid value`, {
+  if (invalid2 !== void 0) {
+    throw new CommerceError("INPUT_INVALID", `Path parameter "${invalid2}" is not a valid value`, {
       ...context,
-      details: { field: invalid }
+      details: { field: invalid2 }
     });
   }
   return { url, remaining };
@@ -336,22 +321,38 @@ function stringifyPrimitive(value) {
     return String(value);
   }
 }
-function hasHeader(headers, name) {
-  const target = name.toLowerCase();
-  return Object.keys(headers).some((key) => key.toLowerCase() === target);
+function buildHeaders(handler, context) {
+  try {
+    return new Headers(handler.headers);
+  } catch {
+    throw invalidHeaderError(context);
+  }
 }
-function deleteHeader(headers, name) {
-  const target = name.toLowerCase();
-  for (const key of Object.keys(headers)) {
-    if (key.toLowerCase() === target) delete headers[key];
+function setHeader(headers, name, value, context) {
+  try {
+    headers.set(name, value);
+  } catch {
+    throw invalidHeaderError(context);
   }
 }
-function headersToRecord(headers) {
-  const record = {};
-  headers.forEach((value, key) => {
-    record[key] = value;
+function invalidHeaderError(context) {
+  return new CommerceError("BACKEND_ERROR", "Backend request headers are invalid", {
+    ...context,
+    details: { reason: "invalid-header" }
   });
-  return record;
+}
+var prefixPathnames = /* @__PURE__ */ new WeakMap();
+function literalPrefixPathname(handler) {
+  let cached = prefixPathnames.get(handler);
+  if (cached === void 0) {
+    try {
+      cached = new URL(handler.url.split("{")[0] ?? handler.url).pathname;
+    } catch {
+      cached = null;
+    }
+    prefixPathnames.set(handler, cached);
+  }
+  return cached ?? void 0;
 }
 async function readBodyCapped(response, maxBytes) {
   if (!response.body) return "";
@@ -365,7 +366,7 @@ async function readBodyCapped(response, maxBytes) {
       total += value.byteLength;
       if (total > maxBytes) {
         await reader.cancel();
-        throw new Error(`response-body-too-large:${maxBytes}`);
+        throw new CommerceError("BACKEND_ERROR", `response body exceeded ${maxBytes} bytes`);
       }
       chunks.push(value);
     }
@@ -400,47 +401,6 @@ function safeStringify(value) {
 function isAbortError(error) {
   return error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError");
 }
-
-// src/core/execution/event-bus.ts
-function createEventBus(options) {
-  const subscribers = /* @__PURE__ */ new Set();
-  return {
-    async emit(event) {
-      try {
-        await options.store.appendEvent(event);
-      } catch (error) {
-        options.logger.error(
-          { err: describeError(error), eventType: event.type, requestId: event.requestId },
-          "Failed to persist commerce event"
-        );
-      }
-      for (const subscriber of subscribers) {
-        try {
-          subscriber(event);
-        } catch (error) {
-          options.logger.error(
-            { err: describeError(error), eventType: event.type, requestId: event.requestId },
-            "Event subscriber threw"
-          );
-        }
-      }
-    },
-    subscribe(fn) {
-      subscribers.add(fn);
-      return () => {
-        subscribers.delete(fn);
-      };
-    }
-  };
-}
-function describeError(error) {
-  if (error instanceof Error) {
-    return { message: error.message, name: error.name };
-  }
-  return { message: String(error) };
-}
-
-// src/core/execution/validation.ts
 var SUPPORTED_TYPES = /* @__PURE__ */ new Set([
   "object",
   "string",
@@ -457,13 +417,10 @@ function compileJsonSchema(schema) {
     return errors.length === 0 ? { valid: true, value: input } : { valid: false, errors };
   };
 }
-function isPlainObject3(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 function matchesType(type, value) {
   switch (type) {
     case "object":
-      return isPlainObject3(value);
+      return isRecord(value);
     case "array":
       return Array.isArray(value);
     case "string":
@@ -486,15 +443,7 @@ function describeType(value) {
   return typeof value;
 }
 function deepEqual(a, b) {
-  if (a === b) return true;
-  if (typeof a !== typeof b) return false;
-  if (a === null || b === null) return false;
-  if (typeof a !== "object") return false;
-  try {
-    return JSON.stringify(a) === JSON.stringify(b);
-  } catch {
-    return false;
-  }
+  return a === b || isDeepStrictEqual(a, b);
 }
 function own(obj, key) {
   return Object.hasOwn(obj, key) ? obj[key] : void 0;
@@ -514,8 +463,8 @@ function isObjectSchemaNode(schema) {
 function validateNode(schema, value, path2) {
   const errors = [];
   const types = typeList(own(schema, "type"));
-  const recognisedTypes = types?.filter((entry) => SUPPORTED_TYPES.has(entry));
-  if (types !== void 0 && recognisedTypes !== void 0 && recognisedTypes.length === types.length && types.length > 0) {
+  const recognizedTypes = types?.filter((entry) => SUPPORTED_TYPES.has(entry));
+  if (types !== void 0 && recognizedTypes !== void 0 && recognizedTypes.length === types.length && types.length > 0) {
     if (!types.some((entry) => matchesType(entry, value))) {
       errors.push({
         path: path2,
@@ -531,7 +480,7 @@ function validateNode(schema, value, path2) {
       errors.push({ path: path2, message: `must be one of ${JSON.stringify(allowed)}` });
     }
   }
-  if (isObjectSchemaNode(schema) && isPlainObject3(value)) {
+  if (isObjectSchemaNode(schema) && isRecord(value)) {
     errors.push(...validateObject(schema, value, path2));
   } else if ((types?.includes("array") ?? false) && Array.isArray(value)) {
     errors.push(...validateArray(schema, value, path2));
@@ -541,7 +490,7 @@ function validateNode(schema, value, path2) {
 function validateObject(schema, value, path2) {
   const errors = [];
   const propsRaw = own(schema, "properties");
-  const properties = isPlainObject3(propsRaw) ? propsRaw : {};
+  const properties = isRecord(propsRaw) ? propsRaw : {};
   const requiredRaw = own(schema, "required");
   const required = Array.isArray(requiredRaw) ? requiredRaw.filter((entry) => typeof entry === "string") : [];
   for (const key of required) {
@@ -553,14 +502,14 @@ function validateObject(schema, value, path2) {
   for (const key of Object.keys(value)) {
     const propSchemaRaw = own(properties, key);
     if (propSchemaRaw !== void 0) {
-      if (isPlainObject3(propSchemaRaw)) {
+      if (isRecord(propSchemaRaw)) {
         errors.push(...validateNode(propSchemaRaw, value[key], `${path2}.${key}`));
       }
       continue;
     }
     if (additional === false) {
       errors.push({ path: `${path2}.${key}`, message: "additional property not allowed" });
-    } else if (isPlainObject3(additional)) {
+    } else if (isRecord(additional)) {
       errors.push(...validateNode(additional, value[key], `${path2}.${key}`));
     }
   }
@@ -569,7 +518,7 @@ function validateObject(schema, value, path2) {
 function validateArray(schema, value, path2) {
   const errors = [];
   const itemsRaw = own(schema, "items");
-  if (isPlainObject3(itemsRaw)) {
+  if (isRecord(itemsRaw)) {
     value.forEach((item, index) => {
       errors.push(...validateNode(itemsRaw, item, `${path2}[${index}]`));
     });
@@ -592,7 +541,7 @@ function createExecutionPipeline(options) {
       await options.events.emit(event);
     } catch (error) {
       options.logger.error(
-        { err: describeError2(error), eventType: event.type, requestId: event.requestId },
+        { err: describeError(error), eventType: event.type, requestId: event.requestId },
         "Event sink failed; commerce flow continues"
       );
     }
@@ -602,7 +551,7 @@ function createExecutionPipeline(options) {
       await op();
     } catch (error) {
       options.logger.error(
-        { err: describeError2(error), requestId },
+        { err: describeError(error), requestId },
         `Persistence failed: ${label}`
       );
     }
@@ -689,7 +638,7 @@ function createExecutionPipeline(options) {
           await provider[action](verification.reservationId, context);
         } catch (error) {
           options.logger.error(
-            { err: describeError2(error), requestId: request.requestId, action },
+            { err: describeError(error), requestId: request.requestId, action },
             "Authorization finalization failed; the reservation stays reserved"
           );
         }
@@ -699,7 +648,7 @@ function createExecutionPipeline(options) {
   async function execute(request) {
     const pipelineStart = options.clock.monotonicMs();
     const resource = options.resources.get(request.resourceId);
-    if (!resource || !resource.exposedVia.includes(request.protocol)) {
+    if (!resource?.exposedVia.includes(request.protocol)) {
       throw new CommerceError(
         "RESOURCE_NOT_FOUND",
         `Resource "${request.resourceId}" was not found`,
@@ -1170,22 +1119,16 @@ function pickProvider(providers, methods) {
   }
   return void 0;
 }
-var RESERVED_INPUT_KEYS = /* @__PURE__ */ new Set([...RESERVED_INPUT_FIELDS, "__proto__"]);
+var RESERVED_INPUT_KEYS = [...RESERVED_INPUT_FIELDS, "__proto__"];
 function stripReservedFields(input) {
-  if (typeof input !== "object" || input === null || Array.isArray(input)) return input;
-  const record = input;
-  const hasReserved = [...RESERVED_INPUT_KEYS].some((key) => Object.hasOwn(record, key));
-  if (!hasReserved) return input;
+  if (!isRecord(input)) return input;
+  if (!RESERVED_INPUT_KEYS.some((key) => Object.hasOwn(input, key))) return input;
   const rest = {};
-  for (const key of Object.keys(record)) {
-    if (!RESERVED_INPUT_KEYS.has(key)) rest[key] = record[key];
+  for (const key of Object.keys(input)) {
+    if (!RESERVED_INPUT_KEYS.includes(key)) rest[key] = input[key];
   }
   return rest;
 }
-function describeError2(error) {
-  if (error instanceof Error) return { message: error.message, name: error.name };
-  return { message: String(error) };
-}
 
 // src/core/execution/registry.ts
 var ResourceRegistryImpl = class {
@@ -1219,6 +1162,22 @@ function createResourceRegistry(resources) {
   return new ResourceRegistryImpl(resources);
 }
 
+// src/core/execution/store-event-sink.ts
+function createStoreEventSink(options) {
+  return {
+    async emit(event) {
+      try {
+        await options.store.appendEvent(event);
+      } catch (error) {
+        options.logger.error(
+          { err: describeError(error), eventType: event.type, requestId: event.requestId },
+          "Failed to persist commerce event"
+        );
+      }
+    }
+  };
+}
+
 // src/protocols/acp/constants.ts
 var ACP_SPEC_VERSION = "2026-04-17";
 var ACP_API_VERSION = "2026-04-17";
@@ -1237,6 +1196,9 @@ var ACP_OPERATION_INPUT_KEYS = {
   completeCheckoutSession: ["path", "body"],
   cancelCheckoutSession: ["path"]
 };
+var ACP_OPERATION_OPTIONAL_INPUT_KEYS = {
+  cancelCheckoutSession: ["body"]
+};
 var ACP_JSON_MEDIA_TYPE = "application/json";
 var ACP_API_VERSION_HEADER = "api-version";
 var ACP_REQUEST_ID_HEADER = "request-id";
@@ -1249,7 +1211,6 @@ var ACP_MAX_REQUEST_ID_LENGTH = 128;
 var SUPPORTED_CONFIG_VERSION = 1;
 var ADDRESS_PATTERN = /^0x[0-9a-fA-F]{40}$/;
 var ZERO_ADDRESS_PATTERN = /^0x0{40}$/i;
-var MCP_TOOL_NAME_PATTERN = /^[A-Za-z0-9._-]{1,128}$/;
 var NumberOrString = z.union([z.number(), z.string()]);
 var BooleanOrString = z.union([z.boolean(), z.string()]);
 var MerchantSchema = z.object({
@@ -1260,14 +1221,14 @@ var MerchantSchema = z.object({
 var ServerSchema = z.object({
   port: NumberOrString,
   host: z.string().min(1),
-  /** Shared secret gating /api/receipts, /api/events, /api/events/stream. No token -> those routes 404. */
+  // Shared secret gating /api/receipts and /api/events. Without it both
+  // routes 404.
   adminToken: z.string().min(1).optional(),
-  /** Browser origins allowed to read the dashboard-facing routes. Empty by default: closed. */
-  // Entries are matched literally against the browser's
-  // `Origin` header, so `"*"` and a trailing slash match nothing at all -
-  // fail-closed (a lockout, not a bypass), but silently, and a lockout with
-  // no explanation is the kind of thing an operator "fixes" by disabling the
-  // check. Reject those two shapes with a pointer instead.
+  // Browser origins allowed to call the gateway; none by default. A request
+  // with any other `Origin` gets 403 on every route. Entries match the
+  // `Origin` header exactly (ignoring case), so `"*"` and a trailing slash
+  // would match nothing: a silent lockout that an operator might "fix" by
+  // disabling the check. Both are refused with a pointer.
   allowedOrigins: z.array(
     z.string().min(1).refine((origin) => origin !== "*", {
       message: `wildcard "*" is not supported - allowedOrigins entries are matched literally against the browser's Origin header, so "*" would match nothing. List each scheme://host[:port] explicitly.`
@@ -1286,16 +1247,14 @@ var RESERVED_GATEWAY_PATHS = [
   "/health",
   "/ready",
   "/.well-known/agent-commerce",
-  // Fixed by the A2A specification, so it is the adapter's to serve and never
-  // a configurable mount's to claim.
+  // Fixed by the A2A specification and served by the adapter
   "/.well-known/agent-card.json",
-  // Likewise fixed by the ACP specification.
+  // Fixed by the ACP specification
   ACP_WELL_KNOWN_PATH,
   "/api/resources",
   "/api/resources/:id/invoke",
   "/api/receipts",
-  "/api/events",
-  "/api/events/stream"
+  "/api/events"
 ];
 var MountPathSchema = z.string().min(1).refine((value) => value.startsWith("/"), {
   message: 'must start with "/" - it is an absolute gateway path, e.g. "/mcp".'
@@ -1327,16 +1286,14 @@ var ProtocolsSchema = z.object({
     enabled: BooleanOrString,
     mountPath: MountPathSchema
   }).strict(),
-  // Optional block: A2A is off unless an operator asks for it, and an
-  // existing config predating the adapter stays valid.
+  // Optional; A2A is off unless configured
   a2a: z.object({
     enabled: BooleanOrString,
     mountPath: MountPathSchema.optional()
   }).strict().optional(),
-  // Likewise optional and off by default. The sub-blocks are optional here
-  // and required by the business pass only when ACP is enabled, so a
-  // disabled placeholder block stays writable and an enabled one gets a
-  // message naming the piece it is missing.
+  // Optional and off by default. The business pass requires the sub-blocks
+  // only when ACP is enabled, so a disabled placeholder stays valid and an
+  // enabled block gets a message naming what it lacks.
   acp: z.object({
     enabled: BooleanOrString,
     mountPath: MountPathSchema.optional(),
@@ -1392,7 +1349,7 @@ var FacilitatorAuthSchema = z.discriminatedUnion("type", [
   z.object({ type: z.literal("none") }).strict(),
   z.object({ type: z.literal("bearer"), token: z.string().min(1) }).strict(),
   // Coinbase Developer Platform. Needs the optional peer `@coinbase/x402`,
-  // which signs a fresh JWT per request; a static header cannot express it.
+  // which signs a fresh JWT per request.
   z.object({
     type: z.literal("cdp"),
     apiKeyId: z.string().min(1),
@@ -1407,10 +1364,8 @@ var FacilitatorSchema = z.discriminatedUnion("mode", [
   z.object({
     mode: z.literal("remote"),
     url: z.string().min(1),
-    // Absent means "this facilitator takes no credential" - an explicit
-    // statement, normalised to `{ type: 'none' }` below. On a mainnet that
-    // combination is refused outright, so the default can never quietly
-    // become an unauthenticated production facilitator.
+    // Absent auth sends no credential and normalizes to `{ type: 'none' }`,
+    // which on mainnet requires `allowUnauthenticatedFacilitator`
     auth: FacilitatorAuthSchema.optional()
   }).strict()
 ]);
@@ -1425,9 +1380,9 @@ var X402Schema = z.object({
   payTo: z.string().min(1),
   maxTimeoutSeconds: NumberOrString,
   facilitator: FacilitatorSchema,
-  /** Real funds. Never defaulted - see src/payments/x402/guardrails.ts. */
+  // Real funds. Never defaulted; see src/payments/x402/guardrails.ts
   allowMainnet: BooleanOrString.optional(),
-  /** Accepts a mainnet facilitator that takes no credential. Never defaulted. */
+  // Accepts credential-free facilitator access on mainnet. Never defaulted
   allowUnauthenticatedFacilitator: BooleanOrString.optional()
 }).strict();
 var MppSchema = z.object({
@@ -1442,9 +1397,9 @@ var MppSchema = z.object({
   challengeSecret: z.string().min(1),
   challengeTtlSeconds: NumberOrString.optional(),
   facilitator: FacilitatorSchema,
-  // Real funds. Never defaulted - see src/payments/x402/guardrails.ts
+  // Real funds. Never defaulted; see src/payments/x402/guardrails.ts
   allowMainnet: BooleanOrString.optional(),
-  // Accepts a mainnet facilitator that takes no credential. Never defaulted
+  // Accepts credential-free facilitator access on mainnet. Never defaulted
   allowUnauthenticatedFacilitator: BooleanOrString.optional()
 }).strict();
 var PaymentsSchema = z.object({
@@ -1457,11 +1412,8 @@ var Ap2KeySchema = z.object({
 }).strict();
 var Ap2IssuerSchema = z.object({
   issuer: z.string().min(1),
-  /**
-   * Required, not defaulted. Without it, a mandate minted for another
-   * merchant would verify here, and there is no value worth guessing for
-   * something that decides that.
-   */
+  // Required, not defaulted: without it a mandate minted for another
+  // merchant would verify here
   audience: z.string().min(1),
   keys: z.array(Ap2KeySchema).min(1)
 }).strict();
@@ -1488,7 +1440,7 @@ var RawConfigSchema = z.object({
   authorization: AuthorizationSchema.optional()
 }).strict();
 function parseConfig(raw, env) {
-  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+  if (!isRecord(raw)) {
     throw new CommerceError(
       "CONFIG_INVALID",
       'Configuration root must be a mapping (object) at "$"',
@@ -1500,7 +1452,7 @@ function parseConfig(raw, env) {
   checkVersion(raw);
   const substituted = substituteEnv(raw, env);
   const parsed = parseWithZod(RawConfigSchema, substituted);
-  return normalise(parsed);
+  return normalize(parsed);
 }
 function checkVersion(raw) {
   if (!("version" in raw)) {
@@ -1508,12 +1460,12 @@ function checkVersion(raw) {
       details: { path: "version" }
     });
   }
-  const rawVersion = raw["version"];
-  const version = typeof rawVersion === "string" ? Number(rawVersion) : rawVersion;
+  const version = raw["version"];
   if (version !== SUPPORTED_CONFIG_VERSION) {
+    const hint = typeof version === "string" ? ", written as a number without quotes" : "";
     throw new CommerceError(
       "CONFIG_INVALID",
-      `Unsupported config version "${String(rawVersion)}": this gateway only supports version ${SUPPORTED_CONFIG_VERSION}`,
+      `Unsupported config version "${String(version)}": this gateway only supports version ${SUPPORTED_CONFIG_VERSION}${hint}`,
       { details: { path: "version", supported: SUPPORTED_CONFIG_VERSION } }
     );
   }
@@ -1587,7 +1539,7 @@ function toBoolean(value, path2) {
 var SUPPORTED_PROTOCOLS = new Set(PROTOCOL_NAMES);
 var SUPPORTED_PAYMENT_METHODS = new Set(PAYMENT_METHOD_NAMES);
 var SUPPORTED_AUTHORIZATION_METHODS = /* @__PURE__ */ new Set(["ap2"]);
-function normalise(raw) {
+function normalize(raw) {
   const protocols = {
     http: { enabled: toBoolean(raw.protocols.http.enabled, "protocols.http.enabled") },
     mcp: {
@@ -1598,7 +1550,7 @@ function normalise(raw) {
       enabled: toBoolean(raw.protocols.a2a?.enabled ?? false, "protocols.a2a.enabled"),
       mountPath: raw.protocols.a2a?.mountPath ?? DEFAULT_A2A_MOUNT_PATH
     },
-    acp: normaliseAcp(raw.protocols.acp)
+    acp: normalizeAcp(raw.protocols.acp)
   };
   validateMountPaths(protocols);
   const x402Raw = raw.payments.x402;
@@ -1621,7 +1573,7 @@ function normalise(raw) {
         min: 1
       }
     ),
-    facilitator: normaliseFacilitator(x402Raw.facilitator),
+    facilitator: normalizeFacilitator(x402Raw.facilitator),
     ...x402Raw.allowMainnet !== void 0 ? { allowMainnet: toBoolean(x402Raw.allowMainnet, "payments.x402.allowMainnet") } : {},
     ...x402Raw.allowUnauthenticatedFacilitator !== void 0 ? {
       allowUnauthenticatedFacilitator: toBoolean(
@@ -1644,13 +1596,13 @@ function normalise(raw) {
       ...x402.allowUnauthenticatedFacilitator !== void 0 ? { allowUnauthenticatedFacilitator: x402.allowUnauthenticatedFacilitator } : {}
     });
   }
-  const mpp = normaliseMpp(raw.payments.mpp);
-  const ap2 = normaliseAp2(raw.authorization?.ap2);
+  const mpp = normalizeMpp(raw.payments.mpp);
+  const ap2 = normalizeAp2(raw.authorization?.ap2);
   if (ap2?.enabled) {
     validateReplayStoreIsolated(ap2.replay.path, raw.storage.receipts.path, protocols.acp);
   }
   const resources = Object.entries(raw.resources).map(
-    ([id, entry]) => normaliseResource(id, entry, protocols, x402, mpp, ap2)
+    ([id, entry]) => normalizeResource(id, entry, protocols, x402, mpp, ap2)
   );
   if (protocols.acp.enabled) validateAcpCheckoutMapping(protocols.acp, resources);
   return {
@@ -1660,8 +1612,7 @@ function normalise(raw) {
       name: raw.merchant.name,
       publicBaseUrl: raw.merchant.publicBaseUrl
     },
-    // min 0, not 1: port 0 is the standard "let the OS pick a free port"
-    // convention, useful for tests and ephemeral dev/demo instances.
+    // Port 0 lets the OS pick a free port, for tests and throwaway instances
     server: {
       port: toNumber(raw.server.port, "server.port", { min: 0, max: 65535 }),
       host: raw.server.host,
@@ -1701,7 +1652,7 @@ function validateMountPaths(protocols) {
 function ap2Invalid(path2, message, extra = {}) {
   return new CommerceError("CONFIG_INVALID", message, { details: { path: path2, ...extra } });
 }
-function normaliseAp2(raw) {
+function normalizeAp2(raw) {
   if (raw === void 0) return void 0;
   if (!toBoolean(raw.enabled, "authorization.ap2.enabled")) return { enabled: false };
   const specVersion = raw.specVersion ?? AP2_SPEC_VERSION;
@@ -1721,14 +1672,14 @@ function normaliseAp2(raw) {
   if (raw.replay === void 0) {
     throw ap2Invalid(
       "authorization.ap2.replay",
-      "authorization.ap2.replay is required when AP2 is enabled - it names the SQLite file recording which mandates have been spent, and without it a verified mandate could authorise a second settlement"
+      "authorization.ap2.replay is required when AP2 is enabled - it names the SQLite file recording which mandates have been spent, and without it a verified mandate could authorize a second settlement"
     );
   }
-  const mandateIssuers = normaliseIssuers(
+  const mandateIssuers = normalizeIssuers(
     raw.trust?.mandateIssuers,
     "authorization.ap2.trust.mandateIssuers"
   );
-  const checkoutIssuers = normaliseIssuers(
+  const checkoutIssuers = normalizeIssuers(
     raw.trust?.checkoutIssuers,
     "authorization.ap2.trust.checkoutIssuers"
   );
@@ -1745,7 +1696,7 @@ function normaliseAp2(raw) {
     replay: { path: raw.replay.path }
   };
 }
-function normaliseIssuers(raw, path2) {
+function normalizeIssuers(raw, path2) {
   if (raw === void 0 || raw.length === 0) {
     throw ap2Invalid(
       path2,
@@ -1831,11 +1782,11 @@ function validateJwk(jwk, kid, path2) {
   if (jwk["kid"] !== void 0 && value("kid") !== kid) {
     fail(`declares kid "${value("kid")}", which disagrees with the configured kid "${kid}"`);
   }
-  const normalised = {};
+  const normalized = {};
   for (const member of AP2_JWK_MEMBERS) {
-    if (jwk[member] !== void 0) normalised[member] = value(member);
+    if (jwk[member] !== void 0) normalized[member] = value(member);
   }
-  return normalised;
+  return normalized;
 }
 function validateReplayStoreIsolated(replayPath, receiptsPath, acp) {
   if (replayPath === ":memory:") return;
@@ -1849,7 +1800,7 @@ function validateReplayStoreIsolated(replayPath, receiptsPath, acp) {
     );
   }
 }
-function normaliseResourceAuthorization(id, entry, pricing, ap2) {
+function normalizeResourceAuthorization(id, entry, pricing, ap2) {
   const required = entry.authorization?.required;
   if (required === void 0) return void 0;
   const path2 = `resources.${id}.authorization.required`;
@@ -1889,7 +1840,7 @@ function normaliseResourceAuthorization(id, entry, pricing, ap2) {
 function acpInvalid(path2, message, extra = {}) {
   return new CommerceError("CONFIG_INVALID", message, { details: { path: path2, ...extra } });
 }
-function normaliseAcp(raw) {
+function normalizeAcp(raw) {
   const mountPath = raw?.mountPath ?? DEFAULT_ACP_MOUNT_PATH;
   if (raw === void 0 || !toBoolean(raw.enabled, "protocols.acp.enabled")) {
     return { enabled: false, mountPath };
@@ -1919,9 +1870,8 @@ function normaliseAcp(raw) {
         { min: ACP_RETENTION_HOURS }
       )
     },
-    checkout: { operations: normaliseAcpOperations(raw.checkout) },
-    // Built key by key rather than passed through: absent metadata must stay
-    // absent from the discovery document, not appear there as `undefined`.
+    checkout: { operations: normalizeAcpOperations(raw.checkout) },
+    // Built key by key so absent metadata stays absent rather than `undefined`
     ...discovery !== void 0 ? {
       discovery: {
         ...discovery.documentationUrl !== void 0 ? { documentationUrl: discovery.documentationUrl } : {},
@@ -1932,7 +1882,7 @@ function normaliseAcp(raw) {
     } : {}
   };
 }
-function normaliseAcpOperations(checkout) {
+function normalizeAcpOperations(checkout) {
   const configured = checkout?.operations ?? {};
   for (const key of Object.keys(configured)) {
     if (!ACP_CHECKOUT_OPERATIONS.includes(key)) {
@@ -2000,13 +1950,15 @@ function validateAcpOperationInput(path2, operation, resource) {
   const schema = resource.inputSchema;
   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 && isPlainObject4(properties)) {
-    for (const key of keys) {
+  if (schema["additionalProperties"] === false && isRecord(properties)) {
+    for (const key of [...keys, ...optionalKeys]) {
       if (!Object.hasOwn(properties, key)) {
+        const when = keys.includes(key) ? "always sends" : "sends when the caller supplies it";
         throw acpInvalid(
           path2,
-          `Resource "${resource.id}" implements ACP operation "${operation}" but its input schema sets additionalProperties: false without declaring "${key}", which the adapter always sends for this operation`,
+          `Resource "${resource.id}" implements ACP operation "${operation}" but its input schema sets additionalProperties: false without declaring "${key}", which the adapter ${when} for this operation`,
           { resourceId: resource.id }
         );
       }
@@ -2018,17 +1970,17 @@ function validateAcpOperationInput(path2, operation, resource) {
       if (typeof entry === "string" && !keys.includes(entry)) {
         throw acpInvalid(
           path2,
-          `Resource "${resource.id}" implements ACP operation "${operation}" but its input schema requires "${entry}", which that operation never supplies (it sends: ${keys.join(", ")})`,
+          `Resource "${resource.id}" implements ACP operation "${operation}" but its input schema requires "${entry}", which that operation does not always supply (it always sends: ${keys.join(", ")})`,
           { resourceId: resource.id }
         );
       }
     }
   }
 }
-function normaliseFacilitator(raw) {
+function normalizeFacilitator(raw) {
   return raw.mode === "local" ? { mode: "local", signerPrivateKey: raw.signerPrivateKey } : { mode: "remote", url: raw.url, auth: raw.auth ?? { type: "none" } };
 }
-function normaliseMpp(raw) {
+function normalizeMpp(raw) {
   if (raw === void 0) return void 0;
   const network = raw.network ?? MPP_DEFAULT_NETWORK;
   if (!isMppNetwork(network)) {
@@ -2055,7 +2007,7 @@ function normaliseMpp(raw) {
         { min: 1 }
       )
     } : {},
-    facilitator: normaliseFacilitator(raw.facilitator),
+    facilitator: normalizeFacilitator(raw.facilitator),
     ...raw.allowMainnet !== void 0 ? { allowMainnet: toBoolean(raw.allowMainnet, "payments.mpp.allowMainnet") } : {},
     ...raw.allowUnauthenticatedFacilitator !== void 0 ? {
       allowUnauthenticatedFacilitator: toBoolean(
@@ -2092,7 +2044,7 @@ function normaliseMpp(raw) {
   });
   return mpp;
 }
-function normaliseResource(id, entry, protocols, x402, mpp, ap2) {
+function normalizeResource(id, entry, protocols, x402, mpp, ap2) {
   if (entry.input !== void 0) validateResourceSchemaKeywords(id, "input", entry.input);
   const inputProperties = entry.input?.["properties"];
   if (inputProperties && typeof inputProperties === "object") {
@@ -2158,6 +2110,7 @@ function normaliseResource(id, entry, protocols, x402, mpp, ap2) {
     );
   }
   validateBackendUrl(id, entry.backend.url);
+  validateBackendHeaders(id, entry.backend.headers);
   const pathScope = validateInputBindings(id, entry.backend, entry.input);
   validatePathParametersDeclared(id, entry.backend.url, pathScope.schema, pathScope.where);
   if (entry.pricing.type === "dynamic") {
@@ -2208,7 +2161,7 @@ function normaliseResource(id, entry, protocols, x402, mpp, ap2) {
     }
   }
   const pricing = entry.pricing.type === "free" ? { type: "free" } : { type: "fixed", amount: entry.pricing.amount, currency: entry.pricing.currency };
-  const authorization = normaliseResourceAuthorization(id, entry, pricing, ap2);
+  const authorization = normalizeResourceAuthorization(id, entry, pricing, ap2);
   return {
     id,
     name: entry.name,
@@ -2238,11 +2191,11 @@ function defaultClosedObjectSchema(schema) {
   const result = { ...schema };
   if (isObjectSchema) {
     const properties = schema["properties"];
-    if (isPlainObject4(properties)) {
+    if (isRecord(properties)) {
       result["properties"] = Object.fromEntries(
         Object.entries(properties).map(([key, sub]) => [
           key,
-          isPlainObject4(sub) ? defaultClosedObjectSchema(sub) : sub
+          isRecord(sub) ? defaultClosedObjectSchema(sub) : sub
         ])
       );
     }
@@ -2251,11 +2204,11 @@ function defaultClosedObjectSchema(schema) {
     }
   }
   const items = schema["items"];
-  if (isPlainObject4(items)) {
+  if (isRecord(items)) {
     result["items"] = defaultClosedObjectSchema(items);
   }
   const additional = schema["additionalProperties"];
-  if (isPlainObject4(additional)) {
+  if (isRecord(additional)) {
     result["additionalProperties"] = defaultClosedObjectSchema(additional);
   }
   return result;
@@ -2286,9 +2239,6 @@ var UNSUPPORTED_SCHEMA_KEYWORDS = [
   "maxItems",
   "uniqueItems"
 ];
-function isPlainObject4(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 function excludesObjectType(schema) {
   const type = schema["type"];
   if (type === void 0 || type === "object") return false;
@@ -2313,7 +2263,7 @@ function validateResourceSchemaKeywords(id, path2, schema) {
   const requiredRaw = schema["required"];
   const closed = !Object.hasOwn(schema, "additionalProperties") ? true : schema["additionalProperties"] === false;
   if (Array.isArray(requiredRaw) && closed && isObjectSchemaNode(schema)) {
-    const declared = isPlainObject4(schema["properties"]) ? schema["properties"] : {};
+    const declared = isRecord(schema["properties"]) ? schema["properties"] : {};
     const undeclared = requiredRaw.filter(
       (name) => typeof name === "string" && !Object.hasOwn(declared, name)
     );
@@ -2326,17 +2276,17 @@ function validateResourceSchemaKeywords(id, path2, schema) {
     }
   }
   const properties = schema["properties"];
-  if (isPlainObject4(properties)) {
+  if (isRecord(properties)) {
     for (const [key, sub] of Object.entries(properties)) {
-      if (isPlainObject4(sub)) validateResourceSchemaKeywords(id, `${path2}.properties.${key}`, sub);
+      if (isRecord(sub)) validateResourceSchemaKeywords(id, `${path2}.properties.${key}`, sub);
     }
   }
   const additional = schema["additionalProperties"];
-  if (isPlainObject4(additional)) {
+  if (isRecord(additional)) {
     validateResourceSchemaKeywords(id, `${path2}.additionalProperties`, additional);
   }
   const items = schema["items"];
-  if (isPlainObject4(items)) {
+  if (isRecord(items)) {
     validateResourceSchemaKeywords(id, `${path2}.items`, items);
   } else if (Array.isArray(items)) {
     console.warn(
@@ -2403,7 +2353,7 @@ function validateInputBindings(id, backend, input) {
     );
   }
   const seen = /* @__PURE__ */ new Map();
-  const properties = isPlainObject4(input?.["properties"]) ? input["properties"] : {};
+  const properties = isRecord(input?.["properties"]) ? input["properties"] : {};
   const required = new Set(
     Array.isArray(input?.["required"]) ? input["required"].filter((value) => typeof value === "string") : []
   );
@@ -2426,7 +2376,7 @@ function validateInputBindings(id, backend, input) {
       );
     }
     const declared = properties[property];
-    if (location !== "body" && isPlainObject4(declared) && !isObjectSchemaNode(declared)) {
+    if (location !== "body" && isRecord(declared) && !isObjectSchemaNode(declared)) {
       fail(
         `binds "${location}" to input property "${property}", which is not an object schema - ${location} parameters are read as an object of name/value pairs`,
         { location, property }
@@ -2442,7 +2392,7 @@ function validateInputBindings(id, backend, input) {
   if (bindings.path === void 0) return { schema: void 0, where: "its input schema" };
   const group = properties[bindings.path];
   return {
-    schema: isPlainObject4(group) ? group : void 0,
+    schema: isRecord(group) ? group : void 0,
     where: `input.properties.${bindings.path}`
   };
 }
@@ -2454,7 +2404,7 @@ function validatePathParametersDeclared(id, url, input, where) {
   if (stray !== void 0) {
     throw new CommerceError(
       "CONFIG_INVALID",
-      `Resource "${id}" has backend.url containing "${stray}", which is not a valid path parameter (allowed characters: A-Z a-z 0-9 _ . -). It would be sent to the backend literally, so a paid resource would settle payment and then never reach the backend`,
+      `Resource "${id}" has backend.url containing "${stray}", which is not a valid path parameter (allowed characters: A-Z a-z 0-9 _ . -). It would reach the backend as literal text, so a paid resource would take payment for a request the backend cannot serve`,
       { details: { path: `resources.${id}.backend.url`, resourceId: id, token: stray } }
     );
   }
@@ -2472,13 +2422,13 @@ function validatePathParametersDeclared(id, url, input, where) {
     if (origin === void 0 || !prefix.startsWith(`${origin}/`)) {
       throw new CommerceError(
         "CONFIG_INVALID",
-        `Resource "${id}" has a backend.url parameter before the end of the host ("${url}"). A caller-supplied value would choose which host the gateway calls, which is request forgery with the gateway's own network position. Parameters are supported inside the path and query only`,
+        `Resource "${id}" has a backend.url parameter before the end of the host. A caller-supplied value would choose which host the gateway calls, which is request forgery with the gateway's own network position. Parameters are supported inside the path and query only`,
         { details: { path: `resources.${id}.backend.url`, resourceId: id } }
       );
     }
   }
   const propertiesRaw = input?.["properties"];
-  const properties = isPlainObject4(propertiesRaw) ? propertiesRaw : {};
+  const properties = isRecord(propertiesRaw) ? propertiesRaw : {};
   const requiredRaw = input?.["required"];
   const required = new Set(
     Array.isArray(requiredRaw) ? requiredRaw.filter((entry) => typeof entry === "string") : []
@@ -2488,14 +2438,14 @@ function validatePathParametersDeclared(id, url, input, where) {
     if (!Object.hasOwn(properties, param)) {
       throw new CommerceError(
         "CONFIG_INVALID",
-        `Resource "${id}" has backend.url path parameter "{${param}}" which is not declared in ${where} - the caller has no way to supply it, so every call would settle payment (if priced) and then fail to reach the backend`,
+        `Resource "${id}" has backend.url path parameter "{${param}}" which is not declared in ${where} - the caller has no way to supply it, so every call would be refused`,
         { details: { path: path2, resourceId: id, param } }
       );
     }
     if (!required.has(param)) {
       throw new CommerceError(
         "CONFIG_INVALID",
-        `Resource "${id}" has backend.url path parameter "{${param}}" declared in ${where} but not listed in its "required" - a caller that omits it hits the same unservable-request problem as an undeclared parameter`,
+        `Resource "${id}" has backend.url path parameter "{${param}}" declared in ${where} but not listed in its "required" - a call that omits it would be refused`,
         { details: { path: path2, resourceId: id, param } }
       );
     }
@@ -2508,7 +2458,7 @@ function validateBackendUrl(id, url) {
   } catch {
     throw new CommerceError(
       "CONFIG_INVALID",
-      `Resource "${id}" has an invalid backend.url "${url}": must be an absolute http:// or https:// URL`,
+      `Resource "${id}" has an invalid backend.url: must be an absolute http:// or https:// URL`,
       { details: { path: `resources.${id}.backend.url`, resourceId: id } }
     );
   }
@@ -2520,6 +2470,19 @@ function validateBackendUrl(id, url) {
     );
   }
 }
+function validateBackendHeaders(id, headers) {
+  for (const [name, value] of Object.entries(headers ?? {})) {
+    try {
+      new Headers([[name, value]]);
+    } catch {
+      throw new CommerceError(
+        "CONFIG_INVALID",
+        `Resource "${id}" has backend header "${name}" with an illegal name or value (a name must be an HTTP token; a value must not contain NUL, a character above U+00FF, or a line break except at either end, which fetch trims)`,
+        { details: { path: `resources.${id}.backend.headers.${name}`, resourceId: id } }
+      );
+    }
+  }
+}
 function validateAddress(path2, value) {
   if (!ADDRESS_PATTERN.test(value)) {
     throw new CommerceError(
@@ -2564,9 +2527,8 @@ async function loadConfig(options = {}) {
       `Configuration file "${configPath}" is not valid YAML: ${reason}`,
       {
         details: { path: configPath, ...details },
-        // Retained for programmatic callers. Nothing in the CLI prints a
-        // `cause`, and nothing should start: this is the object whose
-        // `.message` carries the source excerpt (see below).
+        // Kept for programmatic callers. Never print it: its `.message` quotes
+        // the source line (see describeYamlError).
         cause: error
       }
     );
@@ -2604,95 +2566,47 @@ function resolveConfigPath(explicitPath, env, cwd) {
   if (fromEnv) return path.resolve(cwd, fromEnv);
   return path.resolve(cwd, DEFAULT_CONFIG_FILENAME);
 }
-function createDefaultIdGenerator() {
-  return {
-    next(prefix) {
-      const id = randomUUID();
-      return prefix ? `${prefix}_${id}` : id;
-    }
+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);
   };
 }
-var PINO_PRETTY_PATH = (() => {
+function sha256(value) {
+  return createHash("sha256").update(value, "utf8").digest();
+}
+async function readCappedBody(req, maxBytes) {
+  const chunks = [];
+  let total = 0;
   try {
-    return createRequire(import.meta.url).resolve("pino-pretty");
+    for await (const chunk of req) {
+      const buffer = chunk;
+      total += buffer.length;
+      if (total > maxBytes) return { kind: "too-large" };
+      chunks.push(buffer);
+    }
   } catch {
-    return void 0;
+    return { kind: "unreadable" };
   }
-})();
-var SECRET_FIELD_NAMES = [
-  "privateKey",
-  "signerPrivateKey",
-  "signature",
-  "seed",
-  "mnemonic",
-  "secret",
-  "challengeSecret",
-  "apiKey",
-  "adminToken",
-  "token"
-];
-var SECRET_HEADERS = ["authorization", PAYMENT_HEADER, AUTHORIZATION_HEADER];
-var REDACT_PATHS = [
-  ...SECRET_HEADERS.map((name) => `req.headers[${JSON.stringify(name)}]`),
-  ...SECRET_FIELD_NAMES,
-  ...SECRET_FIELD_NAMES.map((name) => `*.${name}`)
-];
-function baseLoggerOptions(options) {
-  const nodeEnv = options.nodeEnv ?? process.env["NODE_ENV"] ?? "development";
-  const wantPretty = options.prettyPrint ?? (nodeEnv !== "production" && nodeEnv !== "test");
-  const usePretty = wantPretty && PINO_PRETTY_PATH !== void 0;
-  return {
-    level: options.level ?? process.env["LOG_LEVEL"] ?? (nodeEnv === "test" ? "silent" : "info"),
-    ...options.name !== void 0 ? { name: options.name } : {},
-    redact: { paths: [...REDACT_PATHS], censor: "[REDACTED]" },
-    ...usePretty ? { transport: { target: PINO_PRETTY_PATH } } : {}
-  };
-}
-function sanitizeUrl(url) {
-  if (url === void 0) return void 0;
-  const queryIndex = url.indexOf("?");
-  return queryIndex === -1 ? url : `${url.slice(0, queryIndex)}?[REDACTED]`;
-}
-function redactedReqSerializer(req) {
-  return {
-    method: req.method,
-    url: sanitizeUrl(req.url),
-    host: req.host,
-    remoteAddress: req.ip,
-    remotePort: req.socket?.remotePort
-  };
-}
-function fastifyLoggerOptions(options = {}) {
-  return {
-    ...baseLoggerOptions(options),
-    serializers: { req: redactedReqSerializer }
-  };
-}
-function buildNotFoundHandler() {
-  return (request, reply) => {
-    const safeUrl = sanitizeUrl(request.raw.url) ?? "";
-    const message = `Route ${request.method}:${safeUrl} not found`;
-    request.log.info(message);
-    reply.code(404).send({ message, error: "Not Found", statusCode: 404 });
-  };
-}
-function createGatewayLogger(options = {}) {
-  const instance = pino(baseLoggerOptions(options));
-  return { pino: instance, core: wrapPino(instance) };
+  return { kind: "ok", text: Buffer.concat(chunks).toString("utf8") };
 }
-function wrapPino(instance) {
-  const logger = {
-    debug: (obj, msg) => instance.debug(obj, msg),
-    info: (obj, msg) => instance.info(obj, msg),
-    warn: (obj, msg) => instance.warn(obj, msg),
-    error: (obj, msg) => instance.error(obj, msg),
-    child: (bindings) => wrapPino(instance.child(bindings))
-  };
-  return logger;
+function joinUrl(baseUrl, mountPath) {
+  return `${baseUrl.replace(/\/+$/, "")}/${mountPath.replace(/^\/+|\/+$/g, "")}`;
 }
-var CORS_METHODS = "GET,POST,DELETE,OPTIONS";
-var CORS_HEADERS = "content-type,payment-signature,x-request-id,authorization";
-var CORS_EXPOSED_HEADERS = "payment-required,payment-response,www-authenticate,payment-receipt,x-request-id";
+
+// src/gateway/access-control.ts
+var CORS_METHODS = "GET,POST,OPTIONS";
+var CORS_HEADERS = [
+  "content-type",
+  PAYMENT_HEADER,
+  AUTHORIZATION_HEADER,
+  "x-request-id",
+  "authorization"
+].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);
@@ -2720,12 +2634,13 @@ function buildAccessControlHook(options) {
   };
 }
 function buildOperatorTokenHook(adminToken) {
+  const isValidAdminToken = adminToken ? createBearerCheck(adminToken) : void 0;
   return async (request, reply) => {
-    if (!adminToken) {
+    if (isValidAdminToken === void 0) {
       reply.status(404).send();
       return;
     }
-    if (!isValidAdminToken(request.headers.authorization, adminToken)) {
+    if (!isValidAdminToken(request.headers.authorization)) {
       reply.status(401).send({ status: "error", code: "UNAUTHORIZED", message: "Admin token required" });
     }
   };
@@ -2746,14 +2661,6 @@ function isAllowedHost(hostHeader, publicHostname) {
   const hostname = hostnameOf(hostHeader);
   return hostname !== "" && (hostname === publicHostname || LOOPBACK_HOSTNAMES.has(hostname));
 }
-function isValidAdminToken(authHeader, adminToken) {
-  const provided = authHeader?.startsWith("Bearer ") ? authHeader.slice("Bearer ".length) : void 0;
-  if (provided === void 0) return false;
-  return timingSafeEqual(hashToken(provided), hashToken(adminToken));
-}
-function hashToken(value) {
-  return createHash("sha256").update(value, "utf8").digest();
-}
 
 // src/gateway/adapters.ts
 var MOUNT_BODY_LIMIT_BYTES = 256 * 1024;
@@ -2766,7 +2673,7 @@ async function startAndMountAdapters(options) {
     try {
       await adapter.start(adapterContext);
     } catch (error) {
-      const detail = describeError3(error);
+      const detail = errorMessage(error);
       adapterLogger.error(
         { err: detail },
         "Protocol adapter failed to start; gateway continues without it"
@@ -2860,7 +2767,7 @@ function mountHttpAdapter(server, adapter, logger) {
         try {
           await handleHttp(request.raw, reply.raw);
         } catch (error) {
-          logger.error({ err: describeError3(error) }, "Protocol adapter request handler threw");
+          logger.error({ err: errorMessage(error) }, "Protocol adapter request handler threw");
           if (!reply.raw.headersSent) {
             reply.raw.statusCode = 500;
             reply.raw.end();
@@ -2927,7 +2834,7 @@ async function getAdapterHealth(runtime, clock) {
   try {
     return await runtime.adapter.health();
   } catch (error) {
-    return { status: "fail", detail: describeError3(error), checkedAt: clock.nowIso() };
+    return { status: "fail", detail: errorMessage(error), checkedAt: clock.nowIso() };
   }
 }
 async function stopAdapters(runtimes, logger) {
@@ -2935,13 +2842,99 @@ async function stopAdapters(runtimes, logger) {
     try {
       await runtime.adapter.stop();
     } catch (error) {
-      logger.child({ adapter: runtime.adapter.name }).error({ err: describeError3(error) }, "Protocol adapter failed to stop cleanly");
+      logger.child({ adapter: runtime.adapter.name }).error({ err: errorMessage(error) }, "Protocol adapter failed to stop cleanly");
     }
   }
 }
-function describeError3(error) {
+function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
+function createDefaultIdGenerator() {
+  return {
+    next(prefix) {
+      const id = randomUUID();
+      return prefix ? `${prefix}_${id}` : id;
+    }
+  };
+}
+var PINO_PRETTY_PATH = (() => {
+  try {
+    return createRequire(import.meta.url).resolve("pino-pretty");
+  } catch {
+    return void 0;
+  }
+})();
+var SECRET_FIELD_NAMES = [
+  "privateKey",
+  "signerPrivateKey",
+  "signature",
+  "seed",
+  "mnemonic",
+  "secret",
+  "challengeSecret",
+  "apiKey",
+  "adminToken",
+  "token"
+];
+var SECRET_HEADERS = ["authorization", PAYMENT_HEADER, AUTHORIZATION_HEADER];
+var REDACT_PATHS = [
+  ...SECRET_HEADERS.map((name) => `req.headers[${JSON.stringify(name)}]`),
+  ...SECRET_FIELD_NAMES,
+  ...SECRET_FIELD_NAMES.map((name) => `*.${name}`)
+];
+function baseLoggerOptions(options) {
+  const nodeEnv = options.nodeEnv ?? process.env["NODE_ENV"] ?? "development";
+  const wantPretty = options.prettyPrint ?? (nodeEnv !== "production" && nodeEnv !== "test");
+  const usePretty = wantPretty && PINO_PRETTY_PATH !== void 0;
+  return {
+    level: options.level ?? process.env["LOG_LEVEL"] ?? (nodeEnv === "test" ? "silent" : "info"),
+    ...options.name !== void 0 ? { name: options.name } : {},
+    redact: { paths: [...REDACT_PATHS], censor: "[REDACTED]" },
+    ...usePretty ? { transport: { target: PINO_PRETTY_PATH } } : {}
+  };
+}
+function sanitizeUrl(url) {
+  if (url === void 0) return void 0;
+  const queryIndex = url.indexOf("?");
+  return queryIndex === -1 ? url : `${url.slice(0, queryIndex)}?[REDACTED]`;
+}
+function redactedReqSerializer(req) {
+  return {
+    method: req.method,
+    url: sanitizeUrl(req.url),
+    host: req.host,
+    remoteAddress: req.ip,
+    remotePort: req.socket?.remotePort
+  };
+}
+function fastifyLoggerOptions(options = {}) {
+  return {
+    ...baseLoggerOptions(options),
+    serializers: { req: redactedReqSerializer }
+  };
+}
+function buildNotFoundHandler() {
+  return (request, reply) => {
+    const safeUrl = sanitizeUrl(request.raw.url) ?? "";
+    const message = `Route ${request.method}:${safeUrl} not found`;
+    request.log.info(message);
+    reply.code(404).send({ message, error: "Not Found", statusCode: 404 });
+  };
+}
+function createGatewayLogger(options = {}) {
+  const instance = pino(baseLoggerOptions(options));
+  return { pino: instance, core: wrapPino(instance) };
+}
+function wrapPino(instance) {
+  const logger = {
+    debug: (obj, msg) => instance.debug(obj, msg),
+    info: (obj, msg) => instance.info(obj, msg),
+    warn: (obj, msg) => instance.warn(obj, msg),
+    error: (obj, msg) => instance.error(obj, msg),
+    child: (bindings) => wrapPino(instance.child(bindings))
+  };
+  return logger;
+}
 
 // src/gateway/public-resource.ts
 function toPublicResource(resource) {
@@ -2962,7 +2955,8 @@ function toPublicResource(resource) {
 var STORE_DETAIL = {
   pass: void 0,
   warn: "store-degraded",
-  fail: "store-unwritable"
+  fail: "store-unwritable",
+  threw: "store-unreachable"
 };
 var ADAPTER_DETAIL = {
   pass: void 0,
@@ -2979,108 +2973,102 @@ var AUTHORIZATION_PROVIDER_DETAIL = {
   warn: "authorization-provider-degraded",
   fail: "authorization-provider-unreachable"
 };
-async function probeProvider(provider, kind, details, options) {
+async function probe(target, kind, details, options) {
   let health;
+  let threw = false;
   try {
-    health = await provider.health();
+    health = await target.health();
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    options.logger.error({ err: message, provider: provider.name }, `${kind} health() threw`);
+    options.logger.error({ err: message, name: target.name }, `${kind} health() threw`);
     health = { status: "fail", checkedAt: options.clock.nowIso() };
+    threw = true;
   }
   if (health.detail !== void 0) {
     options.logger.debug(
-      { provider: provider.name, detail: health.detail },
+      { name: target.name, detail: health.detail },
       `${kind} health detail (not sent to the client)`
     );
   }
-  const detail = details[health.status];
+  const detail = threw ? details.threw ?? details.fail : details[health.status];
   return {
-    name: provider.name,
-    status: health.status,
-    ...detail !== void 0 ? { detail } : {}
+    check: {
+      name: target.name,
+      status: health.status,
+      ...detail !== void 0 ? { detail } : {}
+    },
+    health
   };
 }
-async function checkReadiness(options) {
-  let storeHealth;
-  let storeThrew = false;
-  try {
-    storeHealth = await options.store.health();
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    options.logger.error({ err: message }, "store.health() threw");
-    storeHealth = { status: "fail", checkedAt: options.clock.nowIso() };
-    storeThrew = true;
-  }
-  if (storeHealth.detail !== void 0) {
-    options.logger.debug(
-      { detail: storeHealth.detail },
-      "store health detail (not sent to the client)"
-    );
-  }
-  const adapterChecks = await Promise.all(
-    options.adapterRuntimes.map(async (runtime) => {
-      const health = await getAdapterHealth(runtime, options.clock);
-      if (health.detail !== void 0) {
-        options.logger.debug(
-          { adapter: runtime.adapter.name, detail: health.detail },
-          "adapter health detail (not sent to the client)"
-        );
-      }
-      const detail = ADAPTER_DETAIL[health.status];
-      return {
-        name: runtime.adapter.name,
-        status: health.status,
-        ...detail !== void 0 ? { detail } : {}
-      };
-    })
-  );
-  const paymentProviderChecks = await Promise.all(
-    options.paymentProviders.map(
-      (provider) => probeProvider(provider, "payment provider", PAYMENT_PROVIDER_DETAIL, options)
-    )
-  );
-  const authorizationProviderChecks = await Promise.all(
-    options.authorizationProviders.map(
-      (provider) => probeProvider(provider, "authorization provider", AUTHORIZATION_PROVIDER_DETAIL, options)
+async function evaluate(options) {
+  const [store, adapters, paymentProviders, authorizationProviders] = await Promise.all([
+    probe({ name: "store", health: () => options.store.health() }, "store", STORE_DETAIL, options),
+    Promise.all(
+      options.adapterRuntimes.map(async (runtime) => ({
+        runtime,
+        probed: await probe(
+          // getAdapterHealth turns a throw into a failed result, so an adapter
+          // failure is logged at debug as a detail rather than at error
+          { name: runtime.adapter.name, health: () => getAdapterHealth(runtime, options.clock) },
+          "adapter",
+          ADAPTER_DETAIL,
+          options
+        )
+      }))
+    ),
+    Promise.all(
+      options.paymentProviders.map(
+        (provider) => probe(provider, "payment provider", PAYMENT_PROVIDER_DETAIL, options)
+      )
+    ),
+    // An unusable authorization provider blocks readiness on the same threshold
+    // as a payment one: a resource that requires a mandate cannot be served
+    // without it, and serving the challenge anyway promises what we cannot honor
+    Promise.all(
+      options.authorizationProviders.map(
+        (provider) => probe(provider, "authorization provider", AUTHORIZATION_PROVIDER_DETAIL, options)
+      )
     )
-  );
-  const storeReady = storeHealth.status !== "fail";
-  const adaptersReady = adapterChecks.every((check) => check.status !== "fail");
-  const paymentProvidersReady = paymentProviderChecks.every((check) => check.status !== "fail");
-  const authorizationProvidersReady = authorizationProviderChecks.every(
-    (check) => check.status !== "fail"
-  );
-  const storeDetail = storeThrew ? "store-unreachable" : STORE_DETAIL[storeHealth.status];
+  ]);
+  const checks = [
+    store,
+    ...adapters.map((a) => a.probed),
+    ...paymentProviders,
+    ...authorizationProviders
+  ];
   return {
-    ready: storeReady && adaptersReady && paymentProvidersReady && authorizationProvidersReady,
-    store: {
-      name: "store",
-      status: storeHealth.status,
-      ...storeDetail !== void 0 ? { detail: storeDetail } : {}
+    result: {
+      ready: checks.every((probed) => probed.check.status !== "fail"),
+      store: store.check,
+      adapters: adapters.map((a) => a.probed.check),
+      paymentProviders: paymentProviders.map((p) => p.check),
+      authorizationProviders: authorizationProviders.map((p) => p.check)
     },
-    adapters: adapterChecks,
-    paymentProviders: paymentProviderChecks,
-    authorizationProviders: authorizationProviderChecks
+    adapters: adapters.map(({ runtime, probed }) => ({
+      descriptor: runtime.adapter.descriptor,
+      health: probed.health
+    }))
   };
 }
 var READINESS_TTL_MS = 2e3;
 function createReadinessProbe(options, ttlMs = READINESS_TTL_MS) {
   let cached;
   let inFlight;
+  const current = async () => {
+    const now = options.clock.monotonicMs();
+    if (cached && now - cached.at < ttlMs) return cached.evaluation;
+    if (inFlight) return inFlight;
+    inFlight = evaluate(options).then((evaluation) => {
+      cached = { evaluation, at: options.clock.monotonicMs() };
+      return evaluation;
+    }).finally(() => {
+      inFlight = void 0;
+    });
+    return inFlight;
+  };
   return {
-    async check() {
-      const now = options.clock.monotonicMs();
-      if (cached && now - cached.at < ttlMs) return cached.result;
-      if (inFlight) return inFlight;
-      inFlight = checkReadiness(options).then((result) => {
-        cached = { result, at: options.clock.monotonicMs() };
-        return result;
-      }).finally(() => {
-        inFlight = void 0;
-      });
-      return inFlight;
-    }
+    check: async () => (await current()).result,
+    adapterHealth: async () => (await current()).adapters
   };
 }
 
@@ -3098,13 +3086,11 @@ function publicProtocols(protocols) {
     acp: { enabled: protocols.acp.enabled, mountPath: protocols.acp.mountPath }
   };
 }
-async function buildWellKnownDocument(options) {
-  const adapters = await Promise.all(
-    options.adapterRuntimes.map(async (runtime) => {
-      const health = await getAdapterHealth(runtime, options.clock);
-      return { ...runtime.adapter.descriptor, health: publicHealth(health) };
-    })
-  );
+function buildWellKnownDocument(options) {
+  const adapters = options.adapters.map(({ descriptor, health }) => ({
+    ...descriptor,
+    health: publicHealth(health)
+  }));
   const { x402, mpp } = options.config.payments;
   return {
     gateway: {
@@ -3128,14 +3114,11 @@ async function buildWellKnownDocument(options) {
           assetDecimals: x402.assetDecimals,
           payTo: x402.payTo,
           maxTimeoutSeconds: x402.maxTimeoutSeconds,
-          // Never the signerPrivateKey, and never the facilitator URL:
-          // a facilitator endpoint is a per-deployment operational detail
-          // that can carry a tenant path or an API key, exactly like
-          // `rpcUrl` above. Only whether it is local or remote is public.
+          // Only local or remote is public: the facilitator URL can carry
+          // a tenant path or an API key, and the signer key is secret
           facilitator: { mode: x402.facilitator.mode },
-          // Chain id 84532 is shared between the local dev chain and
-          // public Base Sepolia, so the network id alone cannot say which
-          // one a client is talking to. This can.
+          // Chain id 84532 is both the local dev chain and public Base
+          // Sepolia, so the network id alone cannot say which one this is
           mode: resolveDeploymentMode(
             requireNetworkProfile(x402.network, "payments.x402.network"),
             x402.facilitator.mode
@@ -3163,8 +3146,6 @@ async function buildWellKnownDocument(options) {
 }
 
 // src/gateway/routes.ts
-var SSE_HEARTBEAT_MS = 15e3;
-var MAX_SSE_SUBSCRIBERS = 32;
 function registerRoutes(options) {
   const { server } = options;
   const readinessProbe = createReadinessProbe({
@@ -3188,8 +3169,7 @@ function registerRoutes(options) {
       paymentProviders: options.paymentProviders,
       authorizationProviders: options.authorizationProviders,
       store: options.store,
-      adapterRuntimes: options.adapterRuntimes,
-      clock: options.clock
+      adapters: await readinessProbe.adapterHealth()
     })
   );
   server.get("/api/resources", async () => ({
@@ -3198,81 +3178,35 @@ function registerRoutes(options) {
   server.post("/api/resources/:id/invoke", async (request, reply) => {
     await handleInvoke(request, reply, options);
   });
-  const receiptsTokenHook = buildOperatorTokenHook(options.config.server.adminToken);
-  const eventsTokenHook = buildOperatorTokenHook(options.config.server.adminToken);
-  const eventsStreamTokenHook = buildOperatorTokenHook(options.config.server.adminToken);
-  server.get("/api/receipts", { onRequest: receiptsTokenHook }, async (request, reply) => {
-    try {
-      const limit = parseLimit(request.query["limit"]);
-      return { receipts: await options.store.listReceipts(limit !== void 0 ? { limit } : {}) };
-    } catch (error) {
-      const commerceError = toCommerceError(error);
-      reply.status(commerceError.httpStatus).send(toErrorEnvelope(commerceError));
-      return void 0;
-    }
-  });
-  server.get("/api/events", { onRequest: eventsTokenHook }, async (request, reply) => {
+  const tokenHook = buildOperatorTokenHook(options.config.server.adminToken);
+  server.get(
+    "/api/receipts",
+    { onRequest: tokenHook },
+    ledgerHandler("receipts", (list) => options.store.listReceipts(list))
+  );
+  server.get(
+    "/api/events",
+    { onRequest: tokenHook },
+    ledgerHandler("events", (list) => options.store.listEvents(list))
+  );
+}
+function ledgerHandler(key, list) {
+  return async (request, reply) => {
     try {
       const limit = parseLimit(request.query["limit"]);
-      return { events: await options.store.listEvents(limit !== void 0 ? { limit } : {}) };
+      return { [key]: await list(limit !== void 0 ? { limit } : {}) };
     } catch (error) {
       const commerceError = toCommerceError(error);
       reply.status(commerceError.httpStatus).send(toErrorEnvelope(commerceError));
       return void 0;
     }
-  });
-  let activeSseSubscribers = 0;
-  server.get("/api/events/stream", { onRequest: eventsStreamTokenHook }, (request, reply) => {
-    if (activeSseSubscribers >= MAX_SSE_SUBSCRIBERS) {
-      reply.status(503).send({
-        status: "error",
-        code: "UNAVAILABLE",
-        message: "Too many event-stream subscribers"
-      });
-      return;
-    }
-    reply.raw.writeHead(200, {
-      "Content-Type": "text/event-stream",
-      "Cache-Control": "no-cache",
-      Connection: "keep-alive"
-    });
-    activeSseSubscribers += 1;
-    reply.raw.write(": connected\n\n");
-    let writable = true;
-    reply.raw.on("drain", () => {
-      writable = true;
-    });
-    const unsubscribe = options.eventBus.subscribe((event) => {
-      queueMicrotask(() => {
-        if (!writable) return;
-        writable = reply.raw.write(`data: ${JSON.stringify(event)}
-
-`);
-      });
-    });
-    const heartbeat = setInterval(() => {
-      if (!writable) return;
-      writable = reply.raw.write(": heartbeat\n\n");
-    }, SSE_HEARTBEAT_MS);
-    heartbeat.unref();
-    let cleanedUp = false;
-    const cleanup = () => {
-      if (cleanedUp) return;
-      cleanedUp = true;
-      clearInterval(heartbeat);
-      unsubscribe();
-      activeSseSubscribers -= 1;
-    };
-    request.raw.on("close", cleanup);
-    reply.raw.on("error", cleanup);
-    reply.hijack();
-  });
+  };
 }
 async function handleInvoke(request, reply, options) {
   const resourceId = request.params.id;
   try {
     const resource = options.resources.get(resourceId);
-    if (!resource || !resource.exposedVia.includes("http")) {
+    if (!resource?.exposedVia.includes("http")) {
       throw new CommerceError("RESOURCE_NOT_FOUND", `Resource "${resourceId}" was not found`, {
         requestId: request.id,
         resourceId
@@ -3342,9 +3276,8 @@ function paymentProof(request, method) {
 }
 function errorPaymentSummary(error) {
   const payment = error.details?.["payment"];
-  if (typeof payment !== "object" || payment === null) return void 0;
-  const rec = payment;
-  const { status, provider, amount, currency, network, externalReference, receipt } = rec;
+  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;
   }
@@ -3397,6 +3330,11 @@ function parseLimit(value) {
 // src/gateway/server.ts
 var REQUEST_ID_HEADER = "x-request-id";
 var CLIENT_REQUEST_ID_PATTERN = /^[A-Za-z0-9._:-]{1,64}$/;
+function clientRequestIdOf(raw) {
+  const header2 = raw.headers[REQUEST_ID_HEADER];
+  const value = Array.isArray(header2) ? header2[0] : header2;
+  return value !== void 0 && CLIENT_REQUEST_ID_PATTERN.test(value) ? value : void 0;
+}
 function withProviderBackedMethodsFirst(resource, providers) {
   const backed = (method) => providers.some((provider) => provider.name === method);
   const ordered = [
@@ -3416,26 +3354,28 @@ async function createGateway(options) {
       (resource) => withProviderBackedMethodsFirst(resource, options.paymentProviders)
     )
   );
-  const eventBus = createEventBus({ store: options.store, logger });
+  const events = createStoreEventSink({ store: options.store, logger });
   const pipeline = createExecutionPipeline({
     resources,
     paymentProviders: options.paymentProviders,
     authorizationProviders,
     store: options.store,
     backend,
-    events: eventBus,
+    events,
     logger,
     clock,
     ids
   });
   const server = Fastify({
-    // One number for both surfaces — see adapters.ts's doc comment
-    // on MOUNT_BODY_LIMIT_BYTES for why they're enforced two different ways.
+    // Same cap as adapter mounts, which enforce it on the socket instead
     bodyLimit: MOUNT_BODY_LIMIT_BYTES,
-    genReqId: (rawReq) => {
-      const header2 = rawReq.headers[REQUEST_ID_HEADER];
-      const value = Array.isArray(header2) ? header2[0] : header2;
-      return value !== void 0 && CLIENT_REQUEST_ID_PATTERN.test(value) ? value : ids.next("req");
+    genReqId: () => ids.next("req"),
+    childLoggerFactory: (parent, bindings, childOptions, rawReq) => {
+      const clientRequestId = clientRequestIdOf(rawReq);
+      return parent.child(
+        clientRequestId !== void 0 ? { ...bindings, clientRequestId } : bindings,
+        childOptions
+      );
     },
     logger: fastifyLoggerOptions({ name: `${options.config.merchant.id}-http` })
   });
@@ -3456,7 +3396,6 @@ async function createGateway(options) {
     store: options.store,
     paymentProviders: options.paymentProviders,
     authorizationProviders,
-    eventBus,
     clock,
     adapterRuntimes,
     logger
@@ -3464,7 +3403,7 @@ async function createGateway(options) {
   const context = {
     pipeline,
     resources,
-    events: eventBus,
+    events,
     logger,
     clock,
     ids,
@@ -3497,6 +3436,554 @@ async function createGateway(options) {
   };
 }
 
+// src/protocols/a2a/constants.ts
+var A2A_SPEC_VERSION = "1.0.0";
+var A2A_PROTOCOL_VERSION = "1.0";
+var A2A_PROTOCOL_BINDING = "JSONRPC";
+var A2A_AGENT_CARD_PATH = "/.well-known/agent-card.json";
+var A2A_DEFAULT_MOUNT_PATH = "/a2a";
+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_UNSUPPORTED_METHODS = [
+  "SendStreamingMessage",
+  "GetTask",
+  "ListTasks",
+  "CancelTask",
+  "SubscribeToTask",
+  "CreateTaskPushNotificationConfig",
+  "GetTaskPushNotificationConfig",
+  "ListTaskPushNotificationConfigs",
+  "DeleteTaskPushNotificationConfig",
+  "GetExtendedAgentCard"
+];
+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
+  };
+}
+
+// src/protocols/a2a/jsonrpc.ts
+var JSONRPC_PARSE_ERROR = -32700;
+var JSONRPC_INVALID_REQUEST = -32600;
+var JSONRPC_METHOD_NOT_FOUND = -32601;
+var JSONRPC_INVALID_PARAMS = -32602;
+var JSONRPC_INTERNAL_ERROR = -32603;
+var A2A_ERROR_UNSUPPORTED_OPERATION = -32004;
+function readId(value) {
+  if (typeof value === "string" || typeof value === "number") return value;
+  return null;
+}
+function jsonRpcResult(id, result) {
+  return { jsonrpc: "2.0", id, result };
+}
+function jsonRpcError(id, code, message) {
+  return { jsonrpc: "2.0", id, error: { code, message } };
+}
+function parseJsonRpcRequest(rawBody) {
+  let payload;
+  try {
+    payload = JSON.parse(rawBody);
+  } catch {
+    return { ok: false, id: null, error: { code: JSONRPC_PARSE_ERROR, message: "Invalid JSON." } };
+  }
+  if (Array.isArray(payload)) {
+    return {
+      ok: false,
+      id: null,
+      error: {
+        code: JSONRPC_INVALID_REQUEST,
+        message: "Batch requests are not supported: send a single JSON-RPC request object."
+      }
+    };
+  }
+  if (!isRecord(payload)) {
+    return {
+      ok: false,
+      id: null,
+      error: { code: JSONRPC_INVALID_REQUEST, message: "Request must be a JSON-RPC 2.0 object." }
+    };
+  }
+  const id = readId(payload["id"]);
+  if (payload["jsonrpc"] !== "2.0") {
+    return {
+      ok: false,
+      id,
+      error: { code: JSONRPC_INVALID_REQUEST, message: 'Request must set "jsonrpc" to "2.0".' }
+    };
+  }
+  const method = payload["method"];
+  if (typeof method !== "string" || method.length === 0) {
+    return {
+      ok: false,
+      id,
+      error: { code: JSONRPC_INVALID_REQUEST, message: 'Request must carry a "method" string.' }
+    };
+  }
+  const params = payload["params"];
+  if (params !== void 0 && !isRecord(params)) {
+    return {
+      ok: false,
+      id,
+      error: {
+        code: JSONRPC_INVALID_PARAMS,
+        message: 'Request "params" must be an object.'
+      }
+    };
+  }
+  return { ok: true, request: { id, method, params: params ?? {} } };
+}
+var A2A_USER_ROLE = "ROLE_USER";
+var UnknownRecord = z.record(z.string(), z.unknown());
+var MessageSchema = z.object({
+  role: z.string(),
+  messageId: z.string().optional(),
+  parts: z.array(UnknownRecord),
+  taskId: z.string().optional(),
+  contextId: z.string().optional(),
+  referenceTaskIds: z.array(z.string()).optional()
+});
+var ParamsSchema = z.object({
+  message: MessageSchema,
+  taskId: z.string().optional(),
+  contextId: z.string().optional()
+});
+function invalid(message) {
+  return new CommerceError("INPUT_INVALID", message);
+}
+function unsupported(message) {
+  return new CommerceError("PROTOCOL_UNSUPPORTED", message);
+}
+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.");
+  }
+  if (params.contextId !== void 0 || message.contextId !== void 0) {
+    throw unsupported(
+      "Multi-turn conversational continuation is not supported: send a request with no contextId."
+    );
+  }
+  if (message.referenceTaskIds !== void 0 && message.referenceTaskIds.length > 0) {
+    throw unsupported("Referencing previous tasks is not supported.");
+  }
+}
+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.");
+  }
+  if ("text" in part) {
+    throw unsupported("Text parts are not supported: send a structured data part.");
+  }
+  if (!("data" in part)) {
+    throw invalid('Message part carries no "data": send a structured data 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}.`
+    );
+  }
+}
+function parseInvocation(rawParams) {
+  const parsed = ParamsSchema.safeParse(rawParams);
+  if (!parsed.success) {
+    throw invalid(
+      'Request must carry a "message" with a "role" and a "parts" array of structured data parts.'
+    );
+  }
+  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.parts.length === 0) {
+    throw invalid("Message carries no parts: send exactly one structured data part.");
+  }
+  if (message.parts.length > 1) {
+    throw unsupported(
+      `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 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 ?? {},
+    ...message.messageId !== void 0 ? { messageId: message.messageId } : {}
+  };
+}
+
+// src/protocols/a2a/task-mapping.ts
+function dataPayload(body) {
+  return isRecord(body) ? body : { value: body ?? null };
+}
+function task(identity, state, artifact) {
+  return {
+    id: identity.taskId,
+    contextId: identity.contextId,
+    status: { state, timestamp: identity.timestamp },
+    artifacts: [{ artifactId: identity.artifactId, ...artifact }]
+  };
+}
+function completedTask(outcome, identity) {
+  return task(identity, A2A_TASK_STATE_COMPLETED, {
+    name: outcome.resourceId,
+    parts: [{ data: dataPayload(outcome.body), mediaType: A2A_JSON_MEDIA_TYPE }],
+    // Same meta key MCP attaches its summary under, so a buyer reads the
+    // record of their own purchase the same way on either protocol
+    metadata: { [DELIVERY_SUMMARY_META_KEY]: { ...toDeliverySummary(outcome) } }
+  });
+}
+function paymentRequiredTask(outcome, identity) {
+  return task(identity, A2A_TASK_STATE_FAILED, {
+    name: outcome.resourceId,
+    parts: [{ data: { ...toPaymentRequiredEnvelope(outcome) }, mediaType: A2A_JSON_MEDIA_TYPE }]
+  });
+}
+function failedTask(error, identity) {
+  return task(identity, A2A_TASK_STATE_FAILED, {
+    parts: [{ data: { ...toErrorEnvelope(error) }, mediaType: A2A_JSON_MEDIA_TYPE }]
+  });
+}
+
+// src/protocols/a2a/adapter.ts
+var MAX_REQUEST_BODY_BYTES = 256 * 1024;
+var DEFAULT_AGENT_DESCRIPTION = "Agent Commerce Gateway: canonical commerce resources exposed as A2A skills.";
+var A2aProtocolAdapter = class {
+  name = "a2a";
+  mountPath;
+  descriptor;
+  additionalHttpRoutes;
+  agentName;
+  agentDescription;
+  agentVersion;
+  context;
+  started = false;
+  // The card lists only a2a-exposed resources, but a caller can name any id,
+  // so the adapter refuses another protocol's resource itself
+  skillsById = /* @__PURE__ */ new Map();
+  // 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;
+  constructor(options = {}) {
+    this.mountPath = options.mountPath ?? A2A_DEFAULT_MOUNT_PATH;
+    this.agentName = options.agentName ?? A2A_DEFAULT_AGENT_NAME;
+    this.agentDescription = options.agentDescription ?? DEFAULT_AGENT_DESCRIPTION;
+    this.agentVersion = options.agentVersion ?? PACKAGE_VERSION;
+    this.descriptor = buildDescriptor(PACKAGE_VERSION);
+    this.additionalHttpRoutes = [
+      {
+        method: "GET",
+        path: A2A_AGENT_CARD_PATH,
+        handleHttp: (req, res) => this.handleAgentCard(req, res)
+      }
+    ];
+  }
+  async start(context) {
+    this.context = context;
+    this.started = false;
+    let resources = [];
+    try {
+      resources = context.resources.listExposedVia("a2a");
+    } catch (err) {
+      context.logger.error(
+        { err: toLogInfo(err) },
+        "a2a adapter: failed to list a2a-exposed resources"
+      );
+      resources = [];
+    }
+    this.skillsById = new Map(resources.map((resource) => [resource.id, resource]));
+    this.card = buildAgentCard({
+      name: this.agentName,
+      description: this.agentDescription,
+      version: this.agentVersion,
+      publicBaseUrl: context.publicBaseUrl,
+      mountPath: this.mountPath,
+      resources
+    });
+    this.started = true;
+    context.logger.info(
+      { mountPath: this.mountPath, cardPath: A2A_AGENT_CARD_PATH, skillCount: resources.length },
+      "a2a adapter started"
+    );
+  }
+  /** `GET /.well-known/agent-card.json` */
+  async handleAgentCard(req, res) {
+    try {
+      if (!this.started || this.card === void 0) {
+        this.writeJson(res, 503, { error: "A2A adapter is not running." });
+        return;
+      }
+      if (req.method !== "GET") {
+        this.writeJson(res, 405, { error: "Method not allowed. The Agent Card is read-only." });
+        return;
+      }
+      this.writeJson(res, 200, this.card);
+    } catch (err) {
+      this.context?.logger.error({ err: toLogInfo(err) }, "a2a adapter: agent card request failed");
+      this.writeJson(res, 500, { error: "Internal server error." });
+    }
+  }
+  /** `POST <mountPath>`: the A2A JSON-RPC endpoint */
+  async handleHttp(req, res) {
+    try {
+      if (!this.started) {
+        this.writeJson(
+          res,
+          503,
+          jsonRpcError(null, JSONRPC_INTERNAL_ERROR, "A2A adapter is not running.")
+        );
+        return;
+      }
+      if (req.method !== "POST") {
+        this.writeJson(
+          res,
+          405,
+          jsonRpcError(
+            null,
+            JSONRPC_INVALID_REQUEST,
+            "Method not allowed. This endpoint only accepts POST."
+          )
+        );
+        return;
+      }
+      const version = req.headers[A2A_VERSION_HEADER];
+      const declared = Array.isArray(version) ? version[0] : version;
+      if (declared !== A2A_PROTOCOL_VERSION) {
+        this.writeJson(
+          res,
+          200,
+          jsonRpcError(
+            null,
+            A2A_ERROR_UNSUPPORTED_OPERATION,
+            `Unsupported A2A protocol version. Send the ${A2A_VERSION_HEADER} header with "${A2A_PROTOCOL_VERSION}".`
+          )
+        );
+        return;
+      }
+      const read = await readCappedBody(req, MAX_REQUEST_BODY_BYTES);
+      if (read.kind !== "ok") {
+        this.writeJson(
+          res,
+          200,
+          jsonRpcError(null, JSONRPC_PARSE_ERROR, "Could not read the request body.")
+        );
+        return;
+      }
+      const parsed = parseJsonRpcRequest(read.text);
+      if (!parsed.ok) {
+        this.writeJson(res, 200, jsonRpcError(parsed.id, parsed.error.code, parsed.error.message));
+        return;
+      }
+      this.writeJson(
+        res,
+        200,
+        await this.dispatch(parsed.request.id, parsed.request.method, parsed.request.params)
+      );
+    } catch (err) {
+      this.context?.logger.error({ err: toLogInfo(err) }, "a2a adapter: request handling failed");
+      this.writeJson(
+        res,
+        200,
+        jsonRpcError(null, JSONRPC_INTERNAL_ERROR, "Internal server error.")
+      );
+    }
+  }
+  async dispatch(id, method, params) {
+    if (A2A_UNSUPPORTED_METHODS.includes(method)) {
+      return jsonRpcError(
+        id,
+        A2A_ERROR_UNSUPPORTED_OPERATION,
+        `A2A method "${method}" is not supported by this deployment.`
+      );
+    }
+    if (method !== A2A_METHOD_SEND_MESSAGE) {
+      return jsonRpcError(id, JSONRPC_METHOD_NOT_FOUND, `Unknown method "${method}".`);
+    }
+    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;
+      return jsonRpcError(id, code, error.message);
+    }
+    return this.execute(id, invocation);
+  }
+  // One accepted invocation, one `pipeline.execute()`
+  async execute(id, invocation) {
+    const context = this.context;
+    if (context === void 0) {
+      return jsonRpcError(id, JSONRPC_INTERNAL_ERROR, "A2A adapter is not running.");
+    }
+    const resource = this.skillsById.get(invocation.resourceId);
+    if (resource === void 0) {
+      return this.taskResult(
+        id,
+        failedTask(
+          new CommerceError(
+            "RESOURCE_NOT_FOUND",
+            `Unknown canonical resource "${invocation.resourceId}".`
+          ),
+          this.taskIdentity(context, context.ids.next("a2a"))
+        )
+      );
+    }
+    const requestId = context.ids.next("a2a");
+    const identity = this.taskIdentity(context, requestId);
+    try {
+      const { input, payment, authorization } = extractReservedInputFields(
+        invocation.input,
+        resource,
+        requestId
+      );
+      const request = {
+        requestId,
+        resourceId: invocation.resourceId,
+        input,
+        protocol: "a2a",
+        receivedAt: context.clock.nowIso(),
+        ...payment !== void 0 ? { payment } : {},
+        ...authorization !== void 0 ? { authorization } : {}
+      };
+      const outcome = await context.pipeline.execute(request);
+      return this.taskResult(
+        id,
+        outcome.kind === "payment-required" ? paymentRequiredTask(outcome, identity) : completedTask(outcome, identity)
+      );
+    } catch (err) {
+      const error = toCommerceError(err);
+      context.logger.warn(
+        { resourceId: invocation.resourceId, requestId, err: toLogInfo(error) },
+        "a2a adapter: execution failed"
+      );
+      return this.taskResult(id, failedTask(error, identity));
+    }
+  }
+  taskIdentity(context, requestId) {
+    return {
+      taskId: requestId,
+      contextId: context.ids.next("a2a-ctx"),
+      artifactId: context.ids.next("a2a-artifact"),
+      timestamp: context.clock.nowIso()
+    };
+  }
+  // A2A's JSON-RPC result wraps the terminal task
+  taskResult(id, task2) {
+    return jsonRpcResult(id, { task: task2 });
+  }
+  async health() {
+    const checkedAt = this.context?.clock.nowIso() ?? (/* @__PURE__ */ new Date()).toISOString();
+    if (!this.started || this.card === void 0) {
+      return { status: "fail", detail: "A2A adapter has not been started.", checkedAt };
+    }
+    return { status: "pass", detail: `${this.skillsById.size} skill(s) published.`, checkedAt };
+  }
+  async stop() {
+    this.started = false;
+    this.card = void 0;
+    this.skillsById = /* @__PURE__ */ new Map();
+    this.context = void 0;
+  }
+  writeJson(res, status, body) {
+    if (res.headersSent) return;
+    res.writeHead(status, { "content-type": A2A_JSON_MEDIA_TYPE });
+    res.end(JSON.stringify(body));
+  }
+};
+function createA2aAdapter(options = {}) {
+  return new A2aProtocolAdapter(options);
+}
+
 // src/protocols/acp/checkout-mapping.ts
 function toCanonicalRequest(options) {
   const { request, resourceId, requestId, receivedAt, idempotencyKey } = options;
@@ -3511,13 +3998,14 @@ function toCanonicalRequest(options) {
 }
 function canonicalInput(request) {
   const keys = ACP_OPERATION_INPUT_KEYS[request.route.operation];
+  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 };
   }
   if (keys.includes("body")) {
     input["body"] = request.body;
-  } else if (request.route.acceptsBody && Object.keys(request.body).length > 0) {
+  } else if (optionalKeys.includes("body") && Object.keys(request.body).length > 0) {
     input["body"] = request.body;
   }
   return input;
@@ -3540,21 +4028,21 @@ var ACP_UNSUPPORTED = [
   "standalone orders service",
   "delegate_payment",
   "delegate_authentication",
-  // Bindings and delivery directions.
+  // Bindings and delivery directions
   "ACP MCP transport binding",
   "webhooks",
   "outbound merchant-to-agent delivery",
   "ACP client role",
-  // Request authentication beyond the bearer token.
+  // Request authentication beyond the bearer token
   "Signature header verification",
   "Timestamp replay-window verification",
-  // Extensions and versioning.
+  // Extensions, versioning and payment handlers
   "discount extension",
   "general ACP extension framework",
   "multiple ACP API versions",
   "seller-backed payment handler integration"
 ];
-function buildDescriptor(implementationVersion) {
+function buildDescriptor2(implementationVersion) {
   return {
     name: "acp",
     kind: "protocol",
@@ -3577,9 +4065,8 @@ function buildAcpDiscoveryDocument(options) {
       ...metadata.documentationUrl !== void 0 ? { documentation_url: metadata.documentationUrl } : {}
     },
     api_base_url: joinUrl(options.publicBaseUrl, options.mountPath),
-    // Only the REST binding. ACP's MCP transport is its own fixed checkout
-    // binding and is not the generic MCP adapter this gateway also serves;
-    // advertising it here because "we do MCP" would be a false claim.
+    // REST only: ACP's MCP transport is a fixed checkout binding, not the
+    // generic MCP adapter this gateway also serves
     transports: ["rest"],
     capabilities: {
       services: ["checkout"],
@@ -3589,9 +4076,6 @@ function buildAcpDiscoveryDocument(options) {
     }
   };
 }
-function joinUrl(baseUrl, mountPath) {
-  return `${baseUrl.replace(/\/+$/, "")}/${mountPath.replace(/^\/+|\/+$/g, "")}`;
-}
 
 // src/protocols/acp/errors.ts
 function acpFailure(status, type, code, message, extra = {}) {
@@ -3615,10 +4099,10 @@ function writeAcpFailure(res, failure, headers = {}) {
   writeAcpJson(res, failure.status, failure.error, headers);
 }
 function operationKey(scope) {
-  return sha256(`acp-operation:${scope.deployment}:${scope.endpoint}:${scope.key}`);
+  return sha2562(`acp-operation:${scope.deployment}:${scope.endpoint}:${scope.key}`);
 }
 function requestFingerprint(body) {
-  return sha256(canonicalize(body));
+  return sha2562(canonicalize(body));
 }
 function canonicalize(value) {
   if (value === null) return "null";
@@ -3629,7 +4113,7 @@ function canonicalize(value) {
   }
   return JSON.stringify(value) ?? "null";
 }
-function sha256(value) {
+function sha2562(value) {
   return createHash("sha256").update(value, "utf8").digest("hex");
 }
 
@@ -3646,6 +4130,7 @@ function createAcpIdempotencyStore(options) {
     logger
   });
   migrate(db, logger);
+  resolveOrphanedClaims(db, logger);
   const selectStmt = db.prepare(
     `SELECT state, fingerprint, status, body_json FROM acp_idempotency
       WHERE deployment = ? AND endpoint = ? AND idempotency_key = ?`
@@ -3727,6 +4212,15 @@ function createAcpIdempotencyStore(options) {
     }
   };
 }
+function resolveOrphanedClaims(db, logger) {
+  const { changes } = db.prepare("UPDATE acp_idempotency SET state = 'unresolved' WHERE state = 'in_flight'").run();
+  if (changes > 0) {
+    logger.warn(
+      { unresolved: changes },
+      "acp idempotency: marked claims left in flight by an earlier process as unresolved; reconcile these operations against the merchant before trusting a retry"
+    );
+  }
+}
 function migrate(db, logger) {
   const current = db.pragma("user_version", { simple: true });
   if (current >= SCHEMA_VERSION) return;
@@ -3761,17 +4255,6 @@ function migrate(db, logger) {
   });
   apply();
 }
-var BEARER_PREFIX = /^Bearer +/i;
-function isAuthorizedBearer(header2, expectedToken) {
-  if (header2 === void 0) return false;
-  if (!BEARER_PREFIX.test(header2)) return false;
-  const presented = header2.replace(BEARER_PREFIX, "");
-  if (presented.length === 0) return false;
-  return timingSafeEqual(sha2562(presented), sha2562(expectedToken));
-}
-function sha2562(value) {
-  return createHash("sha256").update(value, "utf8").digest();
-}
 
 // src/protocols/acp/router.ts
 var MAX_SESSION_ID_LENGTH = 128;
@@ -7777,12 +8260,11 @@ var validators;
 function acpValidators() {
   if (validators !== void 0) return validators;
   const ajv = new Ajv2020({
-    // The vendored document is the released spec: annotations we do not know
-    // are the spec's business, not a reason to refuse to start.
+    // The vendored document is the released spec; unknown annotations in it
+    // are no reason to refuse to start
     strict: false,
-    // One failure is all that leaves the adapter, and collecting every error
-    // in a deeply nested cart is work an unauthenticated caller could ask for
-    // repeatedly.
+    // Only one failure leaves the adapter, and collecting every error in a
+    // deeply nested cart is work a caller could request repeatedly
     allErrors: false
   });
   addFormats(ajv);
@@ -7864,7 +8346,7 @@ async function guardAcpRequest(req, options) {
     );
   }
   const route = matched.route;
-  if (!isAuthorizedBearer(header(req, "authorization"), options.token)) {
+  if (!options.isAuthorized(header(req, "authorization"))) {
     return failed(
       acpFailure(
         401,
@@ -7922,7 +8404,7 @@ async function guardAcpRequest(req, options) {
     }
     idempotencyKey = presented;
   }
-  const read = await readBody(req, options.maxBodyBytes ?? ACP_MAX_REQUEST_BODY_BYTES);
+  const read = await readCappedBody(req, options.maxBodyBytes ?? ACP_MAX_REQUEST_BODY_BYTES);
   if (read.kind === "too-large") {
     return failed(
       acpFailure(
@@ -8020,21 +8502,6 @@ function header(req, name) {
   const value = req.headers[name];
   return Array.isArray(value) ? value[0] : value;
 }
-async function readBody(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") };
-}
 
 // src/protocols/acp/response-mapping.ts
 var ACP_SUCCESS_STATUS = {
@@ -8192,15 +8659,12 @@ var AcpProtocolAdapter = class {
   mountPath;
   descriptor;
   additionalHttpRoutes;
-  token;
+  isAuthorized;
   operations;
   idempotencyOptions;
   /**
-   * What an idempotency claim is scoped to, from `context.publicBaseUrl`.
-   *
-   * Not readonly because, unlike the token, it is known only once the adapter
-   * starts. Worth that: scoping by the credential meant a rotation freed
-   * every outstanding claim.
+   * The deployment an idempotency claim is scoped to, `context.publicBaseUrl`.
+   * Not readonly because it is known only once the adapter starts.
    */
   deployment;
   discoveryMetadata;
@@ -8208,17 +8672,16 @@ var AcpProtocolAdapter = class {
   resources = /* @__PURE__ */ new Map();
   context;
   started = false;
-  // Built once at start: the document is fixed by config, and rebuilding it
-  // per request would let an unauthenticated GET do work a caller controls the
-  // cost of.
+  // Built once at start: the document is fixed by config, and a per-request
+  // build would be work an unauthenticated GET could trigger at will
   discovery;
   constructor(options) {
     this.mountPath = options.mountPath;
-    this.token = options.token;
+    this.isAuthorized = createBearerCheck(options.token);
     this.operations = options.operations;
     this.idempotencyOptions = options.idempotency;
     this.discoveryMetadata = options.discovery;
-    this.descriptor = buildDescriptor(PACKAGE_VERSION);
+    this.descriptor = buildDescriptor2(PACKAGE_VERSION);
     this.additionalHttpRoutes = [
       {
         method: "GET",
@@ -8235,12 +8698,12 @@ var AcpProtocolAdapter = class {
       mountPath: this.mountPath,
       ...this.discoveryMetadata !== void 0 ? { metadata: this.discoveryMetadata } : {}
     });
-    const invalid = validateAcpDocument("discoveryResponse", document);
-    if (invalid !== void 0) {
+    const invalid2 = validateAcpDocument("discoveryResponse", document);
+    if (invalid2 !== void 0) {
       throw new CommerceError(
         "CONFIG_INVALID",
-        `ACP discovery document does not conform to the ${this.descriptor.supportedSpec} snapshot at "${invalid.path ?? "$"}" (${invalid.code}) - check protocols.acp.discovery`,
-        { details: { path: invalid.path ?? "$", code: invalid.code } }
+        `ACP discovery document does not conform to the ${this.descriptor.supportedSpec} snapshot at "${invalid2.path ?? "$"}" (${invalid2.code}) - check protocols.acp.discovery`,
+        { details: { path: invalid2.path ?? "$", code: invalid2.code } }
       );
     }
     const exposed = new Map(
@@ -8277,7 +8740,7 @@ var AcpProtocolAdapter = class {
       "acp adapter started"
     );
   }
-  /** `GET /.well-known/acp.json` - public, unauthenticated, cacheable. */
+  /** `GET /.well-known/acp.json`: public, unauthenticated, cacheable */
   async handleDiscovery(req, res) {
     try {
       if (!this.started || this.discovery === void 0) {
@@ -8309,7 +8772,7 @@ var AcpProtocolAdapter = class {
       this.fail(res, err, "acp adapter: discovery request failed");
     }
   }
-  /** `<mountPath>/checkout_sessions...` - the five stable checkout routes. */
+  /** `<mountPath>/checkout_sessions...`: the five stable checkout routes */
   async handleHttp(req, res) {
     try {
       if (!this.started) {
@@ -8326,7 +8789,7 @@ var AcpProtocolAdapter = class {
       }
       const guarded = await guardAcpRequest(req, {
         mountPath: this.mountPath,
-        token: this.token
+        isAuthorized: this.isAuthorized
       });
       if (!guarded.ok) {
         writeAcpFailure(res, guarded);
@@ -8340,12 +8803,9 @@ var AcpProtocolAdapter = class {
     }
   }
   /**
-   * One request, at most one execution.
-   *
-   * A body-bearing route claims its idempotency key *before* the work starts,
-   * so a retry that arrives while the first one is still running finds the
-   * claim instead of starting a second checkout. A route with no key (the GET)
-   * is read-only and needs none.
+   * One request, at most one execution. A body-bearing route claims its
+   * idempotency key before the work starts, so a retry arriving meanwhile finds
+   * the claim; the read-only GET carries no key.
    */
   async dispatch(request) {
     const store = this.idempotency;
@@ -8406,13 +8866,7 @@ var AcpProtocolAdapter = class {
     }
     return outcome.response;
   }
-  /**
-   * One accepted request, one `pipeline.execute()`.
-   *
-   * Nothing here prices a resource, inspects a payment proof or calls a
-   * merchant backend: the adapter builds a canonical request and reads back
-   * what the pipeline decided.
-   */
+  // One accepted request, one `pipeline.execute()`
   async runCheckout(request, idempotencyKey) {
     const context = this.context;
     const resource = this.resources.get(request.route.operation);
@@ -8464,7 +8918,7 @@ var AcpProtocolAdapter = class {
           resourceId: resource.id,
           requestId: canonical.requestId,
           reached: reachedFor(error.code),
-          err: error.toInfo()
+          err: toLogInfo(error)
         },
         "acp adapter: checkout execution failed"
       );
@@ -8474,10 +8928,7 @@ var AcpProtocolAdapter = class {
       };
     }
   }
-  /**
-   * Protocol-owned headers only. A merchant backend's own headers are never
-   * proxied onto an ACP response.
-   */
+  // Protocol-owned headers only; a merchant backend's headers are never proxied
   responseHeaders(request, response) {
     const replayed = response?.replayed === true;
     return {
@@ -8488,7 +8939,7 @@ var AcpProtocolAdapter = class {
     };
   }
   fail(res, err, message) {
-    this.context?.logger.error({ err: toCommerceError(err).toInfo() }, message);
+    this.context?.logger.error({ err: toLogInfo(err) }, message);
     writeAcpFailure(
       res,
       acpFailure(500, "processing_error", "internal_error", "Internal server error.")
@@ -8551,8 +9002,8 @@ function receiptToRow(receipt) {
     payment_json: receipt.payment !== void 0 ? JSON.stringify(redact(receipt.payment)) : null,
     delivered_at: receipt.deliveredAt,
     backend_status: receipt.backendStatus,
-    duration_ms: receipt.durationMs !== void 0 ? receipt.durationMs : null,
-    protocol: receipt.protocol !== void 0 ? receipt.protocol : null,
+    duration_ms: receipt.durationMs ?? null,
+    protocol: receipt.protocol ?? null,
     metadata_json: receipt.metadata !== void 0 ? JSON.stringify(redact(receipt.metadata)) : null,
     authorization_json: receipt.authorization !== void 0 ? JSON.stringify(redact(receipt.authorization)) : null
   };
@@ -8579,12 +9030,12 @@ function eventToRow(event) {
     id: event.id,
     type: event.type,
     request_id: event.requestId,
-    resource_id: event.resourceId !== void 0 ? event.resourceId : null,
+    resource_id: event.resourceId ?? null,
     at: event.at,
-    adapter: event.adapter !== void 0 ? event.adapter : null,
-    payment_provider: event.paymentProvider !== void 0 ? event.paymentProvider : null,
-    duration_ms: event.durationMs !== void 0 ? event.durationMs : null,
-    status: event.status !== void 0 ? event.status : null,
+    adapter: event.adapter ?? null,
+    payment_provider: event.paymentProvider ?? null,
+    duration_ms: event.durationMs ?? null,
+    status: event.status ?? null,
     data_json: event.data !== void 0 ? JSON.stringify(redact(event.data)) : null
   };
 }
@@ -8688,7 +9139,7 @@ var MIGRATIONS = [
     }
   }
 ];
-var SCHEMA_VERSION2 = MIGRATIONS[MIGRATIONS.length - 1]?.version ?? 0;
+var SCHEMA_VERSION2 = MIGRATIONS.at(-1)?.version ?? 0;
 function migrate2(db) {
   const current = db.pragma("user_version", { simple: true });
   for (const migration of MIGRATIONS) {
@@ -8751,10 +9202,8 @@ function createSqliteReceiptStore(options) {
   );
   const insertPaymentAttemptStmt = db.prepare(
     `INSERT INTO payment_attempts (id, request_id, resource_id, provider, replay_key, status, amount, currency, payer, payee, external_reference, rejection_reason, created_at, updated_at)
-     VALUES (@id, @request_id, @resource_id, @provider, @replay_key, @status, @amount, @currency, @payer, @payee, @external_reference, @rejection_reason, @created_at, @updated_at)`
-  );
-  const getPaymentAttemptByIdStmt = db.prepare(
-    "SELECT * FROM payment_attempts WHERE id = ?"
+     VALUES (@id, @request_id, @resource_id, @provider, @replay_key, @status, @amount, @currency, @payer, @payee, @external_reference, @rejection_reason, @created_at, @updated_at)
+     RETURNING *`
   );
   const updatePaymentAttemptStmt = db.prepare(
     `UPDATE payment_attempts SET status = @status,
@@ -8805,8 +9254,9 @@ function createSqliteReceiptStore(options) {
     async reservePaymentAttempt(reservation) {
       const now = clock.nowIso();
       const id = ids.next("attempt");
+      let row;
       try {
-        insertPaymentAttemptStmt.run({
+        row = insertPaymentAttemptStmt.get({
           id,
           request_id: reservation.requestId,
           resource_id: reservation.resourceId,
@@ -8826,19 +9276,12 @@ function createSqliteReceiptStore(options) {
         if (isUniqueConstraintOn(err, "payment_attempts.replay_key")) {
           throw new CommerceError(
             "PAYMENT_REPLAYED",
-            `Payment authorisation has already been used (replayKey=${reservation.replayKey})`,
+            `Payment authorization has already been used (replayKey=${reservation.replayKey})`,
             { requestId: reservation.requestId, resourceId: reservation.resourceId }
           );
         }
         throw toCommerceError(err, "STORAGE_ERROR", "Failed to reserve payment attempt");
       }
-      const row = getPaymentAttemptByIdStmt.get(id);
-      if (row === void 0) {
-        throw new CommerceError(
-          "STORAGE_ERROR",
-          "Payment attempt vanished immediately after insert"
-        );
-      }
       return rowToPaymentAttempt(row);
     },
     async updatePaymentAttempt(update) {
@@ -8876,11 +9319,11 @@ function createSqliteReceiptStore(options) {
       const rows = listOptions.requestId !== void 0 ? listReceiptsByRequestStmt.all(listOptions.requestId, limit) : listReceiptsStmt.all(limit);
       return rows.map(rowToReceipt);
     },
-    /** Exact total, ignoring the listReceipts clamp — see the interface doc for why this exists. */
+    // Exact total, not bounded by the listReceipts clamp (see ReceiptStore.countReceipts)
     async countReceipts() {
       return countReceiptsStmt.get()?.count ?? 0;
     },
-    /** Exact count of non-2xx receipts — see the interface doc for why this exists. */
+    // Exact count of non-2xx receipts (see ReceiptStore.countUndeliveredReceipts)
     async countUndeliveredReceipts() {
       return countUndeliveredReceiptsStmt.get()?.count ?? 0;
     },
@@ -8959,6 +9402,6 @@ function createSqliteReceiptStore(options) {
   return store;
 }
 
-export { ACP_API_VERSION, ACP_SPEC_VERSION, ACP_WELL_KNOWN_PATH, createAcpAdapter, createGateway, createSqliteReceiptStore, loadConfig, parseConfig, createSqliteReceiptStore as receipts };
+export { A2A_AGENT_CARD_PATH, A2A_PROTOCOL_VERSION, A2A_SPEC_VERSION, ACP_API_VERSION, ACP_SPEC_VERSION, ACP_WELL_KNOWN_PATH, createA2aAdapter, createAcpAdapter, createGateway, createSqliteReceiptStore, loadConfig, parseConfig, createSqliteReceiptStore as receipts };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map