@devlab.group/agent-commerce 1.5.0 → 1.6.1

package/dist/index.d.ts

@@ -1,49 +1,40 @@
-import { f as Ap2AuthorizationConfig } from './types-CJtwLu1c.js';
-import { I as IsoTimestamp, D as DecimalAmount, P as PaymentMethodName, a as CommerceResource, b as PaymentSubmission, B as BackendHandler, A as AdapterDescriptor, c as AdapterHealth, R as ResourceRegistry, d as PaymentProvider, L as Logger, C as Clock, e as IdGenerator } from './runtime-DC5XQ9Cc.js';
-export { f as AuthorizationMethodName, g as BackendMethod, h as DEFAULT_BACKEND_TIMEOUT_MS, J as JsonSchema, N as NOOP_LOGGER, i as PAYMENT_METHOD_NAMES, j as PROTOCOL_NAMES, k as PaymentChallenge, l as PaymentContext, m as PaymentRequirement, n as PaymentResult, o as PaymentSettlementContext, p as PaymentVerificationContext, q as Pricing, r as ProtocolName, s as systemClock } from './runtime-DC5XQ9Cc.js';
-import { M as MppNetwork } from './constants-6mypC60h.js';
-import { X as X402FacilitatorConfig } from './guardrails-Dmwi63KB.js';
-import { a as AuthorizationRequirement, b as AuthorizationSubmission, A as AuthorizationProvider } from './authorization-DA7mjy_O.js';
-export { c as AuthorizationFinalizeContext, d as AuthorizationRecord, e as AuthorizationVerification, f as AuthorizationVerificationContext } from './authorization-DA7mjy_O.js';
-import { D as DeliveredOutcome, P as PaymentRequiredOutcome, C as CommerceEvent, a as PaymentAttempt, b as CommerceReceipt, E as ExecutionPipeline, c as ProtocolAdapter, H as HttpProtocolAdapter, A as AdapterHttpRoute, d as ProtocolAdapterContext } from './protocol-adapter-APRjs1E2.js';
-export { e as COMMERCE_EVENT_TYPES, f as CanonicalRequest, g as CommerceEventType, h as EventSink, i as ExecutionOutcome, j as isHttpProtocolAdapter } from './protocol-adapter-APRjs1E2.js';
+import { f as Ap2AuthorizationConfig } from './types-O6lg3Q5V.js';
+import { I as IsoTimestamp, D as DecimalAmount, P as PaymentMethodName, a as CommerceResource, b as PaymentSubmission, B as BackendHandler, A as AdapterDescriptor, c as AdapterHealth, R as ResourceRegistry, d as PaymentProvider, L as Logger, C as Clock, e as IdGenerator } from './runtime-CiYbgGpi.js';
+export { f as AuthorizationMethodName, g as BackendMethod, h as DEFAULT_BACKEND_TIMEOUT_MS, J as JsonSchema, N as NOOP_LOGGER, i as PAYMENT_METHOD_NAMES, j as PROTOCOL_NAMES, k as PaymentChallenge, l as PaymentContext, m as PaymentRequirement, n as PaymentResult, o as PaymentSettlementContext, p as PaymentVerificationContext, q as Pricing, r as ProtocolName, s as systemClock } from './runtime-CiYbgGpi.js';
+import { M as MppNetwork } from './constants-Bkq04FRZ.js';
+import { X as X402FacilitatorConfig } from './guardrails-71XwtXlT.js';
+import { a as AuthorizationRequirement, b as AuthorizationSubmission, A as AuthorizationProvider } from './authorization-BpbWGGrf.js';
+export { c as AuthorizationFinalizeContext, d as AuthorizationRecord, e as AuthorizationVerification, f as AuthorizationVerificationContext } from './authorization-BpbWGGrf.js';
+import { D as DeliveredOutcome, P as PaymentRequiredOutcome, C as CommerceEvent, a as PaymentAttempt, b as CommerceReceipt, E as ExecutionPipeline, c as ProtocolAdapter, H as HttpProtocolAdapter, A as AdapterHttpRoute, d as ProtocolAdapterContext } from './protocol-adapter-DTkrXTev.js';
+export { e as COMMERCE_EVENT_TYPES, f as CanonicalRequest, g as CommerceEventType, h as EventSink, i as ExecutionOutcome, j as isHttpProtocolAdapter } from './protocol-adapter-DTkrXTev.js';
 import { FastifyInstance } from 'fastify';
 import { IncomingMessage, ServerResponse } from 'node:http';
 
 /**
- * Typed domain error codes.
- *
- * FROZEN CONTRACT. Protocol adapters map these codes into their own response
- * format. Never throw a bare string or untyped Error across a package boundary.
+ * Typed domain error codes. FROZEN CONTRACT. Protocol adapters map them into
+ * their own response format. Never throw a bare string or untyped Error across
+ * an area boundary.
  */
 declare const COMMERCE_ERROR_CODES: readonly ["CONFIG_INVALID", "RESOURCE_NOT_FOUND", "INPUT_INVALID", "PAYMENT_REQUIRED", "PAYMENT_INVALID", "PAYMENT_REPLAYED", "PAYMENT_PROVIDER_UNAVAILABLE", "PAYMENT_SETTLEMENT_FAILED", "AUTHORIZATION_REQUIRED", "AUTHORIZATION_INVALID", "AUTHORIZATION_REPLAYED", "AUTHORIZATION_PROVIDER_UNAVAILABLE", "BACKEND_TIMEOUT", "BACKEND_ERROR", "PROTOCOL_UNSUPPORTED", "GATEWAY_BUSY", "STORAGE_ERROR", "INTERNAL_ERROR"];
 type CommerceErrorCode = (typeof COMMERCE_ERROR_CODES)[number];
 /**
- * Canonical HTTP status for each error code.
- *
- * Paid resources fail closed: every payment failure maps to a 4xx/5xx status
- * and never to a successful delivery.
+ * Canonical HTTP status for each error code. Every payment failure maps to a
+ * 4xx or 5xx status, never to a delivery.
  */
 declare const COMMERCE_ERROR_HTTP_STATUS: Readonly<Record<CommerceErrorCode, number>>;
-/** Codes for which a client may reasonably retry the same request. */
+/** Codes for which a client may reasonably retry the same request */
 declare const RETRYABLE_ERROR_CODES: ReadonlySet<CommerceErrorCode>;
 
-/**
- * The single error type crossing package boundaries.
- *
- * FROZEN CONTRACT.
- */
-
 interface CommerceErrorOptions {
-    /** Structured, non-secret detail safe to return to a client. */
+    /** Structured, non-secret detail safe to return to a client */
     readonly details?: Readonly<Record<string, unknown>>;
     readonly cause?: unknown;
     readonly requestId?: string;
     readonly resourceId?: string;
-    /** Override the default HTTP status for this code. */
+    /** Override the default HTTP status for this code */
     readonly httpStatus?: number;
 }
-/** Serialisable wire form of a CommerceError. */
+/** Serializable wire form of a CommerceError */
 interface CommerceErrorInfo {
     readonly code: CommerceErrorCode;
     readonly message: string;
@@ -61,118 +52,93 @@ declare class CommerceError extends Error {
     readonly requestId?: string;
     readonly resourceId?: string;
     constructor(code: CommerceErrorCode, message: string, options?: CommerceErrorOptions);
-    /** Non-secret, client-safe representation. */
+    /** Non-secret, client-safe representation. `cause` is never included */
     toInfo(): CommerceErrorInfo;
 }
 declare function isCommerceError(value: unknown): value is CommerceError;
 /**
- * Normalise any thrown value into a CommerceError.
- *
- * Used at package boundaries so an unexpected failure never escapes untyped.
- *
- * SECURITY — do not "improve" this by propagating `value.message`.
- * `CommerceError.message` is client-visible: it is serialised by `toInfo()`
- * and `toErrorEnvelope()` and returned over HTTP and MCP. An arbitrary thrown
- * Error's message routinely carries internal detail — database connection
- * strings, internal hostnames, filesystem paths, backend URLs. Copying it into
- * a client-facing field turns every unexpected exception into an information
- * disclosure.
+ * Passes an existing CommerceError through. Other thrown values become a
+ * CommerceError with a caller-chosen message, for example
+ * `toCommerceError(err, 'BACKEND_ERROR', 'Backend call failed')`.
  *
- * The original value is preserved on `cause`, which is never serialised, so
- * logs and diagnostics keep the full detail while clients get only the
- * caller's deliberate, reviewed `fallbackMessage`.
- *
- * A caller that *wants* a specific client-facing message passes one:
- * toCommerceError(err, 'BACKEND_ERROR', 'Backend call failed')
+ * Arbitrary Error messages may contain internal URLs, hostnames or file paths.
+ * The original value remains on `cause` for internal logging; `toInfo()` and
+ * `toErrorEnvelope()` do not serialize it.
  */
 declare function toCommerceError(value: unknown, fallbackCode?: CommerceErrorCode, fallbackMessage?: string): CommerceError;
 
 /**
- * Gateway-defined wire envelopes.
+ * Gateway-defined wire envelopes and carriers. FROZEN CONTRACT.
  *
- * FROZEN CONTRACT. These are the *only* representations of "payment required"
- * and "error" that leave the gateway, whichever protocol carries them. The HTTP
- * routes, the MCP adapter and the demo buyer agent all use these helpers so the
- * three can never drift apart.
+ * The HTTP routes and the MCP and A2A adapters build their "payment required"
+ * and "error" bodies with these helpers, so those surfaces send the same
+ * shapes. The ACP adapter maps errors to ACP's own error format instead.
  */
 
 /**
- * Reserved input property carrying a payment proof on protocols that have no
- * header channel (MCP tool calls). Over HTTP the `PAYMENT-SIGNATURE` header is
- * used.
+ * Reserved input property carrying a payment proof on protocols with no header
+ * channel (MCP tool calls, A2A message data). HTTP uses a header instead.
  */
 declare const PAYMENT_INPUT_FIELD = "_payment";
 /**
- * HTTP request header carrying the payment proof.
+ * HTTP request header carrying an x402 payment proof. MPP proofs use
+ * `Authorization: Payment ...` instead.
  *
- * x402 v2 header names, lowercased because that is how Node presents incoming
- * headers. v1's `X-PAYMENT` / `X-PAYMENT-RESPONSE` pair is not accepted: this
- * gateway speaks one protocol version, and quietly honouring both would mean
- * two verification paths for the same money.
+ * The x402 v2 header names, lowercased as Node presents incoming headers. v1's
+ * `X-PAYMENT` / `X-PAYMENT-RESPONSE` pair is not accepted: honoring both
+ * versions would mean two verification paths for the same money.
  */
 declare const PAYMENT_HEADER = "payment-signature";
-/** HTTP response header carrying the settlement result. */
+/** HTTP response header carrying the settlement result */
 declare const PAYMENT_RESPONSE_HEADER = "payment-response";
 /**
- * Reserved input property carrying an authorization proof, the authorization
- * counterpart of {@link PAYMENT_INPUT_FIELD}.
+ * Reserved input property carrying an authorization proof, the counterpart of
+ * {@link PAYMENT_INPUT_FIELD}.
  *
- * Unlike `_payment`, which is a bare string, this one carries an object:
- * `{ method, payload }`. There is exactly one payment rail per resource, so a
- * payment proof's method can be inferred from the resource; an authorization
- * proof cannot lean on that, and guessing the method of a security control is
- * not a thing to do implicitly.
+ * `_payment` is a bare string whose method is taken from the resource's first
+ * payment method. This field is a `{ method, payload }` object, because the
+ * method of a security control should be stated, not inferred.
  */
 declare const AUTHORIZATION_INPUT_FIELD = "_authorization";
 /**
- * Every input property name the gateway claims for itself.
- *
- * One list, read by the config loader (which rejects a resource declaring any
- * of them), by the protocol adapters that lift them out of client input, and
- * by the pipeline that strips them again as defence in depth. Those three
- * agree by construction instead of by three copies of two strings.
+ * Every input property name the gateway claims for itself. The config loader
+ * rejects a resource declaring one, protocol adapters lift them out of client
+ * input, and the pipeline strips them again as defense in depth.
  */
 declare const RESERVED_INPUT_FIELDS: readonly string[];
 /**
- * HTTP request header carrying the authorization proof, base64url-encoded
- * JSON of the same `{ method, payload }` envelope the reserved input field
- * carries.
+ * HTTP request header carrying the authorization proof: base64url-encoded JSON
+ * of the same `{ method, payload }` object the reserved input field carries.
  *
- * This is an Agent Commerce transport carrier, not a header defined by any
- * authorization specification, so it is namespaced rather than borrowing
- * `Authorization`, which already means something else on every one of these
- * routes.
+ * An Agent Commerce carrier, not a header from any authorization
+ * specification. It is namespaced rather than reusing `Authorization`, which
+ * already carries other credentials, including MPP payment proofs.
  */
 declare const AUTHORIZATION_HEADER = "agent-authorization";
 /**
  * Hard cap on the encoded `Agent-Authorization` header.
  *
- * Node's own limit is ~16 KiB across *all* request headers, so an
- * authorization near that size would start evicting everything else and fail
- * as an unreadable transport error rather than a legible one. Capping well
- * below it means an oversized proof gets a deterministic
- * AUTHORIZATION_INVALID naming the limit.
+ * Node's default limit is 16 KiB across all request headers, and a request over
+ * it is refused before the gateway sees it. Capping well below that gives an
+ * oversized proof a deterministic `AUTHORIZATION_INVALID` naming the limit.
  */
 declare const MAX_AUTHORIZATION_HEADER_BYTES = 8192;
 /**
- * HTTP response header carrying the base64 payment challenge on a 402.
+ * HTTP response header carrying the base64 x402 challenge on a 402.
  *
- * The 402 body still carries {@link PaymentRequiredEnvelope} — richer, and the
- * only channel MCP has — but an x402 v2 client reads the challenge from this
- * header and ignores the body, so both are sent.
+ * The body still carries the richer {@link PaymentRequiredEnvelope}, the only
+ * channel MCP has, but an x402 v2 client reads the challenge from this header
+ * and ignores the body, so both are sent.
  */
 declare const PAYMENT_REQUIRED_HEADER = "payment-required";
 /**
  * Key under which a protocol adapter attaches a {@link DeliverySummary} to its
- * result metadata — MCP's `CallToolResult._meta`, and anywhere else a protocol
- * offers an out-of-band metadata channel.
+ * result metadata: MCP's `CallToolResult._meta` and the A2A task artifact's
+ * metadata.
  *
- * Frozen deliberately. The bug this whole mechanism exists to fix was two
- * surfaces disagreeing about what a payer gets back; a key name enforced only
- * by one side's tests would reintroduce exactly that drift. Producer and
- * consumer both import this constant.
- *
- * Follows MCP's `<namespace>/<name>` convention for `_meta` keys.
+ * Part of the frozen contract because producer and consumer must agree on it;
+ * both import this constant. Follows MCP's `<namespace>/<name>` convention for
+ * `_meta` keys.
  */
 declare const DELIVERY_SUMMARY_META_KEY = "agent-commerce/delivery";
 interface PaymentRequiredEnvelope {
@@ -190,24 +156,21 @@ interface PaymentRequiredEnvelope {
         readonly network?: string;
         readonly asset?: string;
         readonly expiresAt?: IsoTimestamp;
-        /** Provider-native requirement objects, passed through verbatim. */
+        /** Provider-native requirement objects, passed through verbatim */
         readonly accepts: readonly Readonly<Record<string, unknown>>[];
         /**
-         * The provider's own challenge document, verbatim — see
-         * {@link PaymentChallenge.envelope}. Present for providers that have one;
-         * a buyer's protocol client can hand this straight to its SDK.
+         * The provider's own challenge document, verbatim (see
+         * {@link PaymentChallenge.envelope}). Present for providers that have one;
+         * a buyer's protocol client can hand it straight to its SDK.
          */
         readonly envelope?: Readonly<Record<string, unknown>>;
     };
     /**
-     * Present only when the resource requires an authorization proof as well.
-     *
-     * Additive: a client that does not understand the field sees exactly the
-     * envelope it saw before. A client that does learns, before it spends
-     * anything, that paying alone will not get the resource delivered.
-     *
-     * This advertises a requirement; it does not issue anything. The proof is
-     * obtained from the merchant's own approval flow, outside the gateway.
+     * Present only when the resource also requires an authorization proof, so a
+     * client learns before it spends anything that paying alone will not get the
+     * resource delivered. A client that ignores the field sees the plain
+     * envelope. The proof comes from the merchant's own approval flow, outside
+     * the gateway.
      */
     readonly authorization?: {
         readonly required: readonly AuthorizationRequirement[];
@@ -223,17 +186,10 @@ interface ErrorEnvelope {
     readonly details?: Readonly<Record<string, unknown>>;
 }
 /**
- * What a buyer learns about their own completed purchase.
- *
- * A payer is entitled to the record of their own transaction — the request it
- * belonged to, whether it settled, and the settlement reference they can check
- * on-chain. They are NOT entitled to the merchant's ledger, which is why
- * `/api/receipts` is an operator route behind `server.adminToken`.
- *
- * Before this existed the two surfaces disagreed: HTTP callers received a
- * settlement summary in the payment-response header while MCP callers received
- * nothing, so an MCP buyer's only route to their own receipt was the merchant's
- * ledger. Both surfaces now emit this same shape.
+ * What a buyer learns about their own completed purchase: the request, whether
+ * it settled, and the settlement reference they can check on-chain. The
+ * merchant's ledger is not theirs to read, which is why `/api/receipts` is an
+ * operator route behind `server.adminToken`.
  */
 interface DeliverySummary {
     readonly requestId: string;
@@ -244,45 +200,42 @@ interface DeliverySummary {
         readonly status: 'verified' | 'settled' | 'rejected';
         readonly amount: DecimalAmount;
         readonly currency: string;
-        /** Settlement reference, e.g. an on-chain transaction hash. */
+        /** Settlement reference, e.g. an on-chain transaction hash */
         readonly externalReference?: string;
         readonly network?: string;
     };
 }
-/** Build the payer-facing summary of a delivered outcome. */
+/** Build the payer-facing summary of a delivered outcome */
 declare function toDeliverySummary(outcome: DeliveredOutcome): DeliverySummary;
 declare function toPaymentRequiredEnvelope(outcome: PaymentRequiredOutcome): PaymentRequiredEnvelope;
 declare function toErrorEnvelope(error: CommerceError): ErrorEnvelope;
 declare function isPaymentRequiredEnvelope(value: unknown): value is PaymentRequiredEnvelope;
 /**
- * Parses the `{ method, payload }` authorization envelope, whichever carrier
- * brought it.
+ * Parses the `{ method, payload }` authorization object, whichever carrier
+ * brought it. Absent returns `undefined`; malformed throws
+ * `AUTHORIZATION_INVALID`.
  *
- * Absent is `undefined`. Present but malformed throws, rather than being
- * dropped the way an unusable `_payment` is. A dropped payment leaves the
- * buyer holding a 402 they can act on. A silently dropped authorization would
- * come back as "not authorized" for a proof the client believes it sent, with
- * no way to tell a rejected mandate from a typo in the envelope around it.
+ * An unusable `_payment` is dropped, which leaves the buyer a 402 to act on. A
+ * dropped authorization would instead come back as "not authorized", with no
+ * way to tell a rejected mandate from a typo in the object around it.
  */
 declare function parseAuthorizationSubmission(value: unknown, requestId?: string): AuthorizationSubmission | undefined;
 /**
- * Decodes the base64url-JSON `Agent-Authorization` header.
- *
- * The size check runs on the encoded value before any decoding, so an
- * oversized header costs a length comparison rather than a base64 decode and
- * a JSON parse of whatever a caller chose to send.
+ * Decodes the base64url JSON `Agent-Authorization` header. The size check runs
+ * on the encoded value, so an oversized header costs a length comparison rather
+ * than a decode and a JSON parse.
  */
 declare function parseAuthorizationHeader(raw: string | readonly string[] | undefined, requestId?: string): AuthorizationSubmission | undefined;
 /**
- * Splits raw client input into resource input plus the reserved fields the
- * gateway claims, for every protocol that carries them in the input object
- * (MCP tool arguments, A2A message data). HTTP carries both in headers and
- * uses the two parse helpers directly.
+ * Splits raw client input into resource input plus the reserved fields, for
+ * protocols that carry them in the input object (MCP tool arguments, A2A
+ * message data). HTTP carries both in headers.
  *
- * A payment proof is labelled with the resource's first method. `createGateway`
- * puts provider-backed methods first so the label matches pipeline selection;
- * custom registries must preserve that ordering. Without a method, the proof is
- * dropped and the pipeline receives an unpaid request.
+ * A payment proof is labeled with the resource's first payment method.
+ * `createGateway` puts provider-backed methods first so the label matches the
+ * pipeline's selection; a custom registry must keep that order. A resource with
+ * no payment method gets no payment proof, so the request reaches the pipeline
+ * unpaid.
  */
 declare function extractReservedInputFields(rawInput: Record<string, unknown>, resource: CommerceResource | undefined, requestId?: string): {
     input: Record<string, unknown>;
@@ -291,26 +244,25 @@ declare function extractReservedInputFields(rawInput: Record<string, unknown>, r
 };
 
 /**
- * Merchant backend execution boundary.
- *
- * The only place in the system allowed to make an outbound HTTP call to a
- * merchant backend. Every call is bounded by a timeout; redirects are not
- * followed (see docs/security.md).
+ * The gateway's only boundary for calling a merchant backend. An
+ * implementation must bound every call with a timeout and must not follow
+ * redirects; the built-in HTTP executor does both (docs/security.md).
  */
 
 interface BackendRequest {
     readonly requestId: string;
     readonly resourceId: string;
-    /** Validated resource input. */
+    /** Validated resource input */
     readonly input: unknown;
     /**
-     * Names the *operation*, so the merchant can recognise a repeat of it.
+     * Names the operation, so the merchant can recognize a repeat of it. Not
+     * `requestId`, which is fresh per call and would make every retry look like
+     * new work.
      *
-     * Not `requestId`, which is fresh per call and would make every retry look
-     * like new work. An adapter sets this only when it can derive a value that
-     * survives a client retry, a reconnect and a gateway restart; the HTTP
-     * executor forwards it as the `Idempotency-Key` request header. Absent
-     * means the protocol has no such notion, and the merchant sees no header.
+     * An adapter sets it only when the value survives a client retry, a
+     * reconnect and a gateway restart. The HTTP executor sends it as the
+     * `Idempotency-Key` header, replacing one set in `BackendHandler.headers`;
+     * when absent, the executor adds none.
      */
     readonly idempotencyKey?: string;
 }
@@ -332,17 +284,16 @@ interface BackendExecutor {
 }
 
 /**
- * Persistence boundary for receipts, events and payment attempts.
- *
- * Implemented by src/storage/receipts. Core depends only on this
- * interface, never on SQLite.
+ * Persistence boundary for receipts, events and payment attempts, implemented
+ * by src/storage/receipts. Core depends only on this interface, never on
+ * SQLite.
  */
 
 interface PaymentAttemptReservation {
     readonly requestId: string;
     readonly resourceId: string;
     readonly provider: string;
-    /** Must be unique across the store — see PaymentResult.replayKey. */
+    /** Must be unique across the store; see `PaymentResult.replayKey` */
     readonly replayKey: string;
     readonly amount: string;
     readonly currency: string;
@@ -361,14 +312,12 @@ interface ListOptions {
 }
 interface ReceiptStore {
     init(): Promise<void>;
-    /** Append a canonical event. Must not throw into the caller's flow. */
+    /** Append a canonical event. Must not throw into the caller's flow */
     appendEvent(event: CommerceEvent): Promise<void>;
     /**
-     * Atomically claim a payment authorisation before settlement.
-     *
-     * Throws `CommerceError('PAYMENT_REPLAYED')` if `replayKey` was already
-     * reserved. This is the gateway's replay defence and is required for every
-     * paid request.
+     * Atomically claim a payment authorization before settlement: the gateway's
+     * replay defense, run for every paid request. Throws
+     * `CommerceError('PAYMENT_REPLAYED')` if `replayKey` was already reserved.
      */
     reservePaymentAttempt(reservation: PaymentAttemptReservation): Promise<PaymentAttempt>;
     updatePaymentAttempt(update: PaymentAttemptUpdate): Promise<void>;
@@ -376,33 +325,19 @@ interface ReceiptStore {
     getReceipt(id: string): Promise<CommerceReceipt | undefined>;
     listReceipts(options?: ListOptions): Promise<readonly CommerceReceipt[]>;
     /**
-     * Total receipts held, ignoring any list limit.
-     *
-     * `listReceipts` clamps to a bounded page (a store-level invariant, so an
-     * unbounded `limit` cannot dump the ledger). Counting by measuring the length
-     * of a list therefore silently saturates at the clamp — `doctor` reported
-     * "receipts=500" forever once 500 was passed. A diagnostic that quietly stops
-     * counting is worse than one that admits it cannot.
+     * Total receipts held. `listReceipts` clamps every page, so counting a list's
+     * length would stop at the clamp.
      */
     countReceipts(): Promise<number>;
     /**
-     * Receipts whose delivery did not succeed — `backendStatus` outside 2xx.
-     *
-     * A paid-but-undelivered purchase is the one row a merchant must notice:
-     * settlement is final and this release has no refunds, so *seeing* it is the only
-     * remedy available. Counted rather than listed for the same reason as
-     * {@link countReceipts} — `listReceipts` is clamped, so counting by list
-     * length silently saturates.
+     * Receipts whose delivery failed: `backendStatus` outside 2xx, including 0
+     * when no status is known. Counted rather than listed for the same reason as
+     * {@link countReceipts}.
      *
-     * In practice this is exactly "paid but undelivered", not "any failed
-     * delivery": the pipeline only ever persists a receipt when a payment was
-     * attempted (`paymentResult !== undefined`), so a free resource whose
-     * backend call fails throws without writing a receipt at all — there is no
-     * row for `countUndeliveredReceipts` to see. Free-resource failures are
-     * therefore *not* counted here, however natural it is to read the name as
-     * saying they are. Writing a receipt for a failed free delivery too would be
-     * a more complete ledger, but it changes what this count means — that is
-     * a product decision for after the alpha, not something to do here.
+     * In practice this is "paid but undelivered": the pipeline writes a receipt
+     * for a failed delivery only after a settled payment, so a free resource
+     * whose backend fails leaves no row here. It is the row a merchant must
+     * notice, because settlement is final and the gateway issues no refunds.
      */
     countUndeliveredReceipts(): Promise<number>;
     listEvents(options?: ListOptions): Promise<readonly CommerceEvent[]>;
@@ -429,7 +364,7 @@ interface ReceiptStore {
  */
 declare const ACP_SPEC_VERSION = "2026-04-17";
 declare const ACP_API_VERSION = "2026-04-17";
-/** Discovery path fixed by the ACP specification - never a configurable mount. */
+/** Discovery path fixed by the ACP specification, never a configurable mount */
 declare const ACP_WELL_KNOWN_PATH = "/.well-known/acp.json";
 /**
  * The stable checkout operations, by ACP operation id. All five are required
@@ -440,32 +375,25 @@ declare const ACP_CHECKOUT_OPERATIONS: readonly ["createCheckoutSession", "updat
 type AcpCheckoutOperation = (typeof ACP_CHECKOUT_OPERATIONS)[number];
 
 /**
- * `config.yaml` schema, validation and normalisation into the
- * canonical `GatewayConfig` (docs/contracts.md).
+ * `config.yaml` schema, validation and normalization into the canonical
+ * `GatewayConfig` (docs/contracts.md).
  *
- * Two-phase validation:
- * 1. Zod validates *shape* (types, required fields, unknown-key rejection).
- * Numeric/boolean leaves accept either their native type or a string
- * (env substitution always produces a string), and are left as-is here -
- * Zod's typed transforms have surprising inference interactions with
- * `.strict()` objects, so numeric/boolean coercion is done explicitly,
- * in plain TypeScript, in the normalisation pass below.
- * 2. A manual business-rule pass validates cross-references that need a
- * specific, actionable message (duplicate ids, disabled protocols/payment
- * methods, dynamic pricing, destination-address plausibility) and
- * performs the numeric/boolean coercion.
+ * 1. Zod validates shape: types, required fields, unknown keys. Numeric and
+ *    boolean leaves accept their native type or a string, because env
+ *    substitution produces strings. Zod transforms interact badly with
+ *    `.strict()` inference, so coercion happens in plain TypeScript in step 2.
+ * 2. A business-rule pass coerces those leaves and checks what needs a
+ *    specific message: cross-references, disabled protocols and payment
+ *    methods, dynamic pricing, addresses, duplicate trust entries.
  *
- * Env substitution (`${VAR}` / `${VAR:-default}`) runs over the raw parsed
- * value *before* either phase, so numeric/boolean fields can be templated too.
- * One exception, deliberate: `checkVersion` runs **before** substitution, so
- * `version:` cannot itself be templated. It is the compatibility gate that
- * decides whether this parser understands the document at all; resolving
- * environment variables to find out which schema version to expect would be
- * backwards. The order is intended; `version:` is the one exception to the
- * substitution rule, which this sentence exists to record.
+ * Env substitution (`${VAR}` / `${VAR:-default}`) runs over the raw value
+ * before both steps, so numeric and boolean fields can be templated. The one
+ * exception is `version:`, checked before substitution: it decides whether this
+ * parser understands the document at all, so it cannot depend on the
+ * environment.
  */
 
-/** Optional ACP discovery metadata. Absent fields are omitted from the document. */
+/** Optional ACP discovery metadata. Absent fields are omitted from the document */
 interface AcpDiscoveryConfig {
     readonly documentationUrl?: string;
     readonly supportedCurrencies?: readonly string[];
@@ -473,9 +401,8 @@ interface AcpDiscoveryConfig {
     readonly interventionTypes?: readonly string[];
 }
 /**
- * Discriminated on `enabled` so an enabled ACP config carries everything the
- * adapter needs, with no optional-field assertions at the mount point: a
- * half-configured checkout lifecycle is rejected at load instead.
+ * Discriminated on `enabled`, so an enabled ACP config carries everything the
+ * adapter needs; a half-configured checkout is rejected at load
  */
 type AcpProtocolConfig = {
     readonly enabled: false;
@@ -529,7 +456,7 @@ interface GatewayConfig {
         };
         readonly acp: AcpProtocolConfig;
     };
-    /** Canonical resources, already normalised. */
+    /** Canonical resources, already normalized */
     readonly resources: readonly CommerceResource[];
     readonly payments: {
         readonly x402?: {
@@ -562,10 +489,7 @@ interface GatewayConfig {
             readonly allowUnauthenticatedFacilitator?: boolean;
         };
     };
-    /**
-     * Absent when no `authorization:` block is configured, which is how every
-     * config written before AP2 existed reads.
-     */
+    /** Absent when no `authorization:` block is configured */
     readonly authorization?: {
         readonly ap2: Ap2AuthorizationConfig;
     };
@@ -579,22 +503,17 @@ interface LoadConfigOptions {
 }
 declare function loadConfig(options?: LoadConfigOptions): Promise<GatewayConfig>;
 
-/**
- * `createGateway()` — the Fastify server. Fully usable (and tested) with
- * fakes, without `main.ts` (docs/contracts.md "Composition root").
- */
-
 interface GatewayOptions {
     readonly config: GatewayConfig;
     readonly store: ReceiptStore;
     readonly paymentProviders: readonly PaymentProvider[];
-    /** Absent means no resource requires authorization, which is the default */
+    /** Defaults to none; each resource declares the methods it requires */
     readonly authorizationProviders?: readonly AuthorizationProvider[];
     readonly protocolAdapters: readonly ProtocolAdapter[];
     readonly logger?: Logger;
     readonly clock?: Clock;
     readonly ids?: IdGenerator;
-    /** Override for tests. */
+    /** Override for tests */
     readonly backend?: BackendExecutor;
 }
 interface GatewayInstance {
@@ -604,12 +523,79 @@ interface GatewayInstance {
         url: string;
     }>;
     close(): Promise<void>;
-    /** Fastify instance, for `.inject()` in tests. */
+    /** Fastify instance, for `.inject()` in tests */
     readonly server: FastifyInstance;
 }
 declare function createGateway(options: GatewayOptions): Promise<GatewayInstance>;
 
-/** Discovery metadata an operator may configure. Absent fields are omitted, never guessed. */
+/**
+ * A2A (Agent2Agent) protocol adapter, experimental.
+ *
+ * Serves two paths: the configured mount (`/a2a`), where the JSON-RPC endpoint
+ * lives, and the specification-fixed `/.well-known/agent-card.json`, declared
+ * through `additionalHttpRoutes` so the gateway needs no A2A-specific routing.
+ *
+ * Only the synchronous `SendMessage` path is in scope; every other A2A method
+ * is listed in `descriptor.unsupported` rather than half-served. This file
+ * never calls a merchant backend and never inspects a payment object.
+ */
+
+interface A2aAdapterOptions {
+    readonly mountPath?: string;
+    /** Agent name published on the card */
+    readonly agentName?: string;
+    readonly agentDescription?: string;
+    /** Version published on the card. Defaults to this package's version */
+    readonly agentVersion?: string;
+}
+declare class A2aProtocolAdapter implements HttpProtocolAdapter {
+    readonly name: "a2a";
+    readonly mountPath: string;
+    readonly descriptor: AdapterDescriptor;
+    readonly additionalHttpRoutes: readonly AdapterHttpRoute[];
+    private readonly agentName;
+    private readonly agentDescription;
+    private readonly agentVersion;
+    private context;
+    private started;
+    private skillsById;
+    private card;
+    constructor(options?: A2aAdapterOptions);
+    start(context: ProtocolAdapterContext): Promise<void>;
+    /** `GET /.well-known/agent-card.json` */
+    handleAgentCard(req: IncomingMessage, res: ServerResponse): Promise<void>;
+    /** `POST <mountPath>`: the A2A JSON-RPC endpoint */
+    handleHttp(req: IncomingMessage, res: ServerResponse): Promise<void>;
+    private dispatch;
+    private execute;
+    private taskIdentity;
+    private taskResult;
+    health(): Promise<AdapterHealth>;
+    stop(): Promise<void>;
+    private writeJson;
+}
+declare function createA2aAdapter(options?: A2aAdapterOptions): A2aProtocolAdapter;
+
+/**
+ * A2A pins, kept in one place so nothing infers one version from another.
+ *
+ * The specification revision and the negotiation version look alike but
+ * differ: `1.0.0` names the document this adapter was written against, `1.0`
+ * is what a client negotiates on the wire. Neither is this package's version
+ * (`PACKAGE_VERSION`).
+ */
+/** A2A specification revision this adapter targets */
+declare const A2A_SPEC_VERSION = "1.0.0";
+/** Protocol negotiation version carried on the wire */
+declare const A2A_PROTOCOL_VERSION = "1.0";
+/**
+ * Fixed by the A2A specification: a client fetches the card from this exact
+ * path, so it is not configurable. `src/config` reserves it against adapter
+ * mounts for the same reason.
+ */
+declare const A2A_AGENT_CARD_PATH = "/.well-known/agent-card.json";
+
+/** Discovery metadata an operator may configure. Absent fields are omitted, never guessed */
 interface AcpDiscoveryMetadata {
     readonly documentationUrl?: string;
     readonly supportedCurrencies?: readonly string[];
@@ -618,29 +604,25 @@ interface AcpDiscoveryMetadata {
 }
 
 /**
- * ACP (Agentic Commerce Protocol) adapter - experimental.
+ * ACP (Agentic Commerce Protocol) adapter, experimental.
  *
  * Serves two paths: the configured mount (`/acp`), where the five stable
  * checkout routes live, and the specification-fixed `/.well-known/acp.json`,
  * declared through `additionalHttpRoutes` so the gateway needs no ACP-specific
  * routing.
  *
- * Discovery and every protocol guard that must hold before canonical execution
- * are implemented. A guarded request is not executed yet: until checkout
- * operations reach the pipeline, a fully-valid request is answered with an
- * honest "not implemented" rather than a fabricated session.
- *
- * This file never calls a merchant backend and never inspects a payment
- * object.
+ * A request that passes every protocol guard runs its mapped resource through
+ * the pipeline, under an idempotency claim when it carries a key. This file
+ * never calls a merchant backend and never inspects a payment object.
  */
 
 interface AcpAdapterOptions {
     readonly mountPath: string;
-    /** The configured bearer token. Never logged, never echoed, never published. */
+    /** The configured bearer token. Never logged, never echoed, never published */
     readonly token: string;
-    /** Which canonical resource implements each ACP checkout operation. */
+    /** Which canonical resource implements each ACP checkout operation */
     readonly operations: Readonly<Record<AcpCheckoutOperation, string>>;
-    /** Where checkout idempotency records live, and how long they are kept. */
+    /** Where checkout idempotency records live, and how long they are kept */
     readonly idempotency: {
         readonly path: string;
         readonly retentionHours: number;
@@ -652,15 +634,12 @@ declare class AcpProtocolAdapter implements HttpProtocolAdapter {
     readonly mountPath: string;
     readonly descriptor: AdapterDescriptor;
     readonly additionalHttpRoutes: readonly AdapterHttpRoute[];
-    private readonly token;
+    private readonly isAuthorized;
     private readonly operations;
     private readonly 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.
      */
     private deployment;
     private readonly discoveryMetadata;
@@ -671,31 +650,17 @@ declare class AcpProtocolAdapter implements HttpProtocolAdapter {
     private discovery;
     constructor(options: AcpAdapterOptions);
     start(context: ProtocolAdapterContext): Promise<void>;
-    /** `GET /.well-known/acp.json` - public, unauthenticated, cacheable. */
+    /** `GET /.well-known/acp.json`: public, unauthenticated, cacheable */
     handleDiscovery(req: IncomingMessage, res: ServerResponse): Promise<void>;
-    /** `<mountPath>/checkout_sessions...` - the five stable checkout routes. */
+    /** `<mountPath>/checkout_sessions...`: the five stable checkout routes */
     handleHttp(req: IncomingMessage, res: ServerResponse): Promise<void>;
     /**
-     * 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.
      */
     private dispatch;
-    /**
-     * 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.
-     */
     private runCheckout;
-    /**
-     * Protocol-owned headers only. A merchant backend's own headers are never
-     * proxied onto an ACP response.
-     */
     private responseHeaders;
     private fail;
     health(): Promise<AdapterHealth>;
@@ -704,7 +669,7 @@ declare class AcpProtocolAdapter implements HttpProtocolAdapter {
 declare function createAcpAdapter(options: AcpAdapterOptions): AcpProtocolAdapter;
 
 interface SqliteReceiptStoreOptions {
-    /** File path, or ':memory:' for tests. Parent directory is created if missing. */
+    /** File path, or ':memory:' for tests. Parent directory is created if missing */
     readonly path: string;
     readonly logger?: Logger;
     readonly clock?: Clock;
@@ -712,4 +677,4 @@ interface SqliteReceiptStoreOptions {
 }
 declare function createSqliteReceiptStore(options: SqliteReceiptStoreOptions): ReceiptStore;
 
-export { ACP_API_VERSION, ACP_SPEC_VERSION, ACP_WELL_KNOWN_PATH, AUTHORIZATION_HEADER, AUTHORIZATION_INPUT_FIELD, type AcpAdapterOptions, AdapterDescriptor, AdapterHealth, AdapterHttpRoute, AuthorizationProvider, AuthorizationRequirement, AuthorizationSubmission, type BackendExecutor, BackendHandler, type BackendRequest, type BackendResponse, COMMERCE_ERROR_CODES, COMMERCE_ERROR_HTTP_STATUS, Clock, CommerceError, type CommerceErrorCode, type CommerceErrorInfo, type CommerceErrorOptions, CommerceEvent, CommerceReceipt, CommerceResource, DELIVERY_SUMMARY_META_KEY, DecimalAmount, DeliveredOutcome, type DeliverySummary, type ErrorEnvelope, ExecutionPipeline, type GatewayConfig, type GatewayInstance, type GatewayOptions, HttpProtocolAdapter, IdGenerator, IsoTimestamp, type ListOptions, Logger, MAX_AUTHORIZATION_HEADER_BYTES, PAYMENT_HEADER, PAYMENT_INPUT_FIELD, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER, PaymentAttempt, type PaymentAttemptReservation, type PaymentAttemptUpdate, PaymentMethodName, PaymentProvider, type PaymentRequiredEnvelope, PaymentRequiredOutcome, PaymentSubmission, ProtocolAdapter, ProtocolAdapterContext, RESERVED_INPUT_FIELDS, RETRYABLE_ERROR_CODES, type ReceiptStore, ResourceRegistry, createAcpAdapter, createGateway, createSqliteReceiptStore, extractReservedInputFields, isCommerceError, isPaymentRequiredEnvelope, loadConfig, parseAuthorizationHeader, parseAuthorizationSubmission, parseConfig, createSqliteReceiptStore as receipts, toCommerceError, toDeliverySummary, toErrorEnvelope, toPaymentRequiredEnvelope };
+export { A2A_AGENT_CARD_PATH, A2A_PROTOCOL_VERSION, A2A_SPEC_VERSION, type A2aAdapterOptions, ACP_API_VERSION, ACP_SPEC_VERSION, ACP_WELL_KNOWN_PATH, AUTHORIZATION_HEADER, AUTHORIZATION_INPUT_FIELD, type AcpAdapterOptions, AdapterDescriptor, AdapterHealth, AdapterHttpRoute, AuthorizationProvider, AuthorizationRequirement, AuthorizationSubmission, type BackendExecutor, BackendHandler, type BackendRequest, type BackendResponse, COMMERCE_ERROR_CODES, COMMERCE_ERROR_HTTP_STATUS, Clock, CommerceError, type CommerceErrorCode, type CommerceErrorInfo, type CommerceErrorOptions, CommerceEvent, CommerceReceipt, CommerceResource, DELIVERY_SUMMARY_META_KEY, DecimalAmount, DeliveredOutcome, type DeliverySummary, type ErrorEnvelope, ExecutionPipeline, type GatewayConfig, type GatewayInstance, type GatewayOptions, HttpProtocolAdapter, IdGenerator, IsoTimestamp, type ListOptions, Logger, MAX_AUTHORIZATION_HEADER_BYTES, PAYMENT_HEADER, PAYMENT_INPUT_FIELD, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER, PaymentAttempt, type PaymentAttemptReservation, type PaymentAttemptUpdate, PaymentMethodName, PaymentProvider, type PaymentRequiredEnvelope, PaymentRequiredOutcome, PaymentSubmission, ProtocolAdapter, ProtocolAdapterContext, RESERVED_INPUT_FIELDS, RETRYABLE_ERROR_CODES, type ReceiptStore, ResourceRegistry, createA2aAdapter, createAcpAdapter, createGateway, createSqliteReceiptStore, extractReservedInputFields, isCommerceError, isPaymentRequiredEnvelope, loadConfig, parseAuthorizationHeader, parseAuthorizationSubmission, parseConfig, createSqliteReceiptStore as receipts, toCommerceError, toDeliverySummary, toErrorEnvelope, toPaymentRequiredEnvelope };