@devlab.group/agent-commerce 1.2.0 → 1.3.0

package/dist/cli/index.js

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 import { ZodError, z } from 'zod';
-import { existsSync, mkdirSync, accessSync, constants, closeSync, openSync, readFileSync, chmodSync, promises } from 'fs';
+import { existsSync, mkdirSync, accessSync, constants, readFileSync, closeSync, openSync, chmodSync, promises } from 'fs';
 import * as path from 'path';
 import { resolve, dirname, basename as basename$1, extname, join } from 'path';
 import { stringify, parse, Document, YAMLError } from 'yaml';
 import { CommanderError, Command } from 'commander';
 import picocolors from 'picocolors';
 import { randomUUID } from 'crypto';
-import Database from 'better-sqlite3';
 import { createRequire } from 'module';
+import Database from 'better-sqlite3';
 import { writeFile, stat, readFile, rename, rm } from 'fs/promises';
 import { validate } from '@scalar/openapi-parser';
 import * as clack from '@clack/prompts';
@@ -35,7 +35,7 @@ var init_filename = __esm({
 var PROTOCOL_NAMES;
 var init_common = __esm({
   "src/core/domain/common.ts"() {
-    PROTOCOL_NAMES = ["http", "mcp", "a2a"];
+    PROTOCOL_NAMES = ["http", "mcp", "a2a", "acp"];
   }
 });
 
@@ -335,6 +335,30 @@ var init_networks = __esm({
   }
 });
 
+// src/protocols/acp/constants.ts
+var ACP_SPEC_VERSION, ACP_API_VERSION, ACP_WELL_KNOWN_PATH, ACP_CHECKOUT_OPERATIONS, ACP_OPERATION_INPUT_KEYS;
+var init_constants = __esm({
+  "src/protocols/acp/constants.ts"() {
+    ACP_SPEC_VERSION = "2026-04-17";
+    ACP_API_VERSION = "2026-04-17";
+    ACP_WELL_KNOWN_PATH = "/.well-known/acp.json";
+    ACP_CHECKOUT_OPERATIONS = [
+      "createCheckoutSession",
+      "updateCheckoutSession",
+      "getCheckoutSession",
+      "completeCheckoutSession",
+      "cancelCheckoutSession"
+    ];
+    ACP_OPERATION_INPUT_KEYS = {
+      createCheckoutSession: ["body"],
+      updateCheckoutSession: ["path", "body"],
+      getCheckoutSession: ["path"],
+      completeCheckoutSession: ["path", "body"],
+      cancelCheckoutSession: ["path"]
+    };
+  }
+});
+
 // src/config/env.ts
 function substituteEnv(value, env, path2 = "$") {
   if (typeof value === "string") {
@@ -691,7 +715,8 @@ function normalise(raw) {
     a2a: {
       enabled: toBoolean(raw.protocols.a2a?.enabled ?? false, "protocols.a2a.enabled"),
       mountPath: raw.protocols.a2a?.mountPath ?? DEFAULT_A2A_MOUNT_PATH
-    }
+    },
+    acp: normaliseAcp(raw.protocols.acp)
   };
   validateMountPaths(protocols);
   const x402Raw = raw.payments.x402;
@@ -745,6 +770,7 @@ function normalise(raw) {
   const resources = Object.entries(raw.resources).map(
     ([id, entry]) => normaliseResource(id, entry, protocols, x402)
   );
+  if (protocols.acp.enabled) validateAcpCheckoutMapping(protocols.acp, resources);
   return {
     version: SUPPORTED_CONFIG_VERSION,
     merchant: {
@@ -771,7 +797,8 @@ function normalise(raw) {
 function validateMountPaths(protocols) {
   const mounts = [
     ["mcp", protocols.mcp],
-    ["a2a", protocols.a2a]
+    ["a2a", protocols.a2a],
+    ["acp", protocols.acp]
   ].filter(([, p]) => p.enabled);
   for (const [index, [nameA, a]] of mounts.entries()) {
     for (const [nameB, b] of mounts.slice(index + 1)) {
@@ -787,6 +814,145 @@ function validateMountPaths(protocols) {
     }
   }
 }
+function acpInvalid(path2, message, extra = {}) {
+  return new CommerceError("CONFIG_INVALID", message, { details: { path: path2, ...extra } });
+}
+function normaliseAcp(raw) {
+  const mountPath = raw?.mountPath ?? DEFAULT_ACP_MOUNT_PATH;
+  if (raw === void 0 || !toBoolean(raw.enabled, "protocols.acp.enabled")) {
+    return { enabled: false, mountPath };
+  }
+  if (raw.auth === void 0) {
+    throw acpInvalid(
+      "protocols.acp.auth",
+      'protocols.acp.auth is required when ACP is enabled - every ACP checkout endpoint is authenticated, and "bearer" is the only scheme supported in this release'
+    );
+  }
+  if (raw.idempotency === void 0) {
+    throw acpInvalid(
+      "protocols.acp.idempotency",
+      "protocols.acp.idempotency is required when ACP is enabled - it names the SQLite file holding checkout idempotency records, and ACP makes the Idempotency-Key mandatory on every checkout POST"
+    );
+  }
+  const discovery = raw.discovery;
+  return {
+    enabled: true,
+    mountPath,
+    auth: raw.auth,
+    idempotency: {
+      path: raw.idempotency.path,
+      retentionHours: toNumber(
+        raw.idempotency.retentionHours ?? ACP_RETENTION_HOURS,
+        "protocols.acp.idempotency.retentionHours",
+        { 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`.
+    ...discovery !== void 0 ? {
+      discovery: {
+        ...discovery.documentationUrl !== void 0 ? { documentationUrl: discovery.documentationUrl } : {},
+        ...discovery.supportedCurrencies !== void 0 ? { supportedCurrencies: discovery.supportedCurrencies } : {},
+        ...discovery.supportedLocales !== void 0 ? { supportedLocales: discovery.supportedLocales } : {},
+        ...discovery.interventionTypes !== void 0 ? { interventionTypes: discovery.interventionTypes } : {}
+      }
+    } : {}
+  };
+}
+function normaliseAcpOperations(checkout) {
+  const configured = checkout?.operations ?? {};
+  for (const key of Object.keys(configured)) {
+    if (!ACP_CHECKOUT_OPERATIONS.includes(key)) {
+      throw acpInvalid(
+        `protocols.acp.checkout.operations.${key}`,
+        `protocols.acp.checkout.operations names unknown ACP checkout operation "${key}". Supported: ${ACP_CHECKOUT_OPERATIONS.join(", ")}.`
+      );
+    }
+  }
+  const operations = {};
+  const claimedBy = /* @__PURE__ */ new Map();
+  for (const operation of ACP_CHECKOUT_OPERATIONS) {
+    const path2 = `protocols.acp.checkout.operations.${operation}`;
+    const resourceId = configured[operation];
+    if (resourceId === void 0) {
+      throw acpInvalid(
+        path2,
+        `${path2} is required when ACP is enabled - all five checkout operations must be mapped, since ACP discovery advertises the checkout service as a whole`
+      );
+    }
+    const claimed = claimedBy.get(resourceId);
+    if (claimed !== void 0) {
+      throw acpInvalid(
+        path2,
+        `${path2} maps resource "${resourceId}", which is already mapped to "${claimed}" - each ACP checkout operation needs its own resource`,
+        { resourceId }
+      );
+    }
+    claimedBy.set(resourceId, operation);
+    operations[operation] = resourceId;
+  }
+  return operations;
+}
+function validateAcpCheckoutMapping(acp, resources) {
+  const byId = new Map(resources.map((resource) => [resource.id, resource]));
+  for (const operation of ACP_CHECKOUT_OPERATIONS) {
+    const resourceId = acp.checkout.operations[operation];
+    const path2 = `protocols.acp.checkout.operations.${operation}`;
+    const resource = byId.get(resourceId);
+    if (resource === void 0) {
+      throw acpInvalid(
+        path2,
+        `${path2} maps resource "${resourceId}", which is not defined under "resources"`,
+        { resourceId }
+      );
+    }
+    if (!resource.exposedVia.includes("acp")) {
+      throw acpInvalid(
+        path2,
+        `Resource "${resourceId}" implements ACP operation "${operation}" but does not list "acp" in its expose - the mapping says which resource serves the operation, expose says ACP may invoke it, and both are required`,
+        { resourceId }
+      );
+    }
+    if (resource.pricing.type !== "free" || resource.paymentMethods.length > 0) {
+      throw acpInvalid(
+        path2,
+        `Resource "${resourceId}" implements ACP operation "${operation}" and must use pricing.type "free" with no "payments" - ACP checkout carries the merchant's own purchase payment, so the gateway does not also charge for the invocation`,
+        { resourceId }
+      );
+    }
+    validateAcpOperationInput(path2, operation, resource);
+  }
+}
+function validateAcpOperationInput(path2, operation, resource) {
+  const schema = resource.inputSchema;
+  if (schema === void 0) return;
+  const keys = ACP_OPERATION_INPUT_KEYS[operation];
+  const properties = schema["properties"];
+  if (schema["additionalProperties"] === false && isPlainObject2(properties)) {
+    for (const key of keys) {
+      if (!Object.hasOwn(properties, key)) {
+        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`,
+          { resourceId: resource.id }
+        );
+      }
+    }
+  }
+  const required = schema["required"];
+  if (Array.isArray(required)) {
+    for (const entry of required) {
+      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(", ")})`,
+          { resourceId: resource.id }
+        );
+      }
+    }
+  }
+}
 function normaliseResource(id, entry, protocols, x402) {
   if (entry.input !== void 0) validateResourceSchemaKeywords(id, "input", entry.input);
   const inputProperties = entry.input?.["properties"];
@@ -807,7 +973,7 @@ function normaliseResource(id, entry, protocols, x402) {
       const hint = protocol === "ucp" ? " (UCP is planned, not supported in this release)" : "";
       throw new CommerceError(
         "CONFIG_INVALID",
-        `Resource "${id}" exposes unsupported protocol "${protocol}"${hint}. Supported: http, mcp, a2a.`,
+        `Resource "${id}" exposes unsupported protocol "${protocol}"${hint}. Supported: ${PROTOCOL_NAMES.join(", ")}.`,
         { details: { path: `resources.${id}.expose`, resourceId: id, protocol } }
       );
     }
@@ -835,6 +1001,13 @@ function normaliseResource(id, entry, protocols, x402) {
       { details: { path: `resources.${id}.expose`, resourceId: id } }
     );
   }
+  if (entry.expose.includes("acp") && !protocols.acp.enabled) {
+    throw new CommerceError(
+      "CONFIG_INVALID",
+      `Resource "${id}" is exposed via "acp" but protocols.acp.enabled is false`,
+      { details: { path: `resources.${id}.expose`, resourceId: id } }
+    );
+  }
   if (entry.expose.includes("http") && !protocols.http.enabled) {
     throw new CommerceError(
       "CONFIG_INVALID",
@@ -1185,12 +1358,13 @@ function validateAddress(path2, value) {
     );
   }
 }
-var SUPPORTED_CONFIG_VERSION, ADDRESS_PATTERN, ZERO_ADDRESS_PATTERN, MCP_TOOL_NAME_PATTERN, NumberOrString, BooleanOrString, MerchantSchema, ServerSchema, StorageSchema, RESERVED_GATEWAY_PATHS, MountPathSchema, ProtocolsSchema, DEFAULT_A2A_MOUNT_PATH, BackendMethodSchema, BackendInputBindingsSchema, BackendHandlerSchema, PricingSchema, JsonSchemaValueSchema, ResourceEntrySchema, ResourcesMapSchema, FacilitatorAuthSchema, FacilitatorSchema, X402Schema, PaymentsSchema, RawConfigSchema, SUPPORTED_PROTOCOLS, SUPPORTED_PAYMENT_METHODS, EMPTY_CLOSED_OBJECT_SCHEMA, UNSUPPORTED_SCHEMA_KEYWORDS, PRICING_AMOUNT_PATTERN, ZERO_AMOUNT_PATTERN;
+var SUPPORTED_CONFIG_VERSION, ADDRESS_PATTERN, ZERO_ADDRESS_PATTERN, MCP_TOOL_NAME_PATTERN, NumberOrString, BooleanOrString, MerchantSchema, ServerSchema, StorageSchema, RESERVED_GATEWAY_PATHS, MountPathSchema, AcpAuthSchema, AcpIdempotencySchema, AcpCheckoutSchema, AcpDiscoverySchema, ProtocolsSchema, DEFAULT_A2A_MOUNT_PATH, DEFAULT_ACP_MOUNT_PATH, ACP_RETENTION_HOURS, BackendMethodSchema, BackendInputBindingsSchema, BackendHandlerSchema, PricingSchema, JsonSchemaValueSchema, ResourceEntrySchema, ResourcesMapSchema, FacilitatorAuthSchema, FacilitatorSchema, X402Schema, PaymentsSchema, RawConfigSchema, SUPPORTED_PROTOCOLS, SUPPORTED_PAYMENT_METHODS, EMPTY_CLOSED_OBJECT_SCHEMA, UNSUPPORTED_SCHEMA_KEYWORDS, PRICING_AMOUNT_PATTERN, ZERO_AMOUNT_PATTERN;
 var init_schema = __esm({
   "src/config/schema.ts"() {
     init_execution();
     init_core();
     init_guardrails();
+    init_constants();
     init_env();
     SUPPORTED_CONFIG_VERSION = 1;
     ADDRESS_PATTERN = /^0x[0-9a-fA-F]{40}$/;
@@ -1235,6 +1409,8 @@ var init_schema = __esm({
       // Fixed by the A2A specification, so it is the adapter's to serve and never
       // a configurable mount's to claim.
       "/.well-known/agent-card.json",
+      // Likewise fixed by the ACP specification.
+      ACP_WELL_KNOWN_PATH,
       "/api/resources",
       "/api/resources/:id/invoke",
       "/api/receipts",
@@ -1256,6 +1432,15 @@ var init_schema = __esm({
         message: `must not collide with a route the gateway already serves (${RESERVED_GATEWAY_PATHS.join(", ")}); pick a dedicated prefix such as "/mcp".`
       }
     );
+    AcpAuthSchema = z.object({ type: z.literal("bearer"), token: z.string().min(1) }).strict();
+    AcpIdempotencySchema = z.object({ path: z.string().min(1), retentionHours: NumberOrString.optional() }).strict();
+    AcpCheckoutSchema = z.object({ operations: z.record(z.string().min(1)) }).strict();
+    AcpDiscoverySchema = z.object({
+      documentationUrl: z.string().min(1).optional(),
+      supportedCurrencies: z.array(z.string().min(1)).optional(),
+      supportedLocales: z.array(z.string().min(1)).optional(),
+      interventionTypes: z.array(z.string().min(1)).optional()
+    }).strict();
     ProtocolsSchema = z.object({
       http: z.object({ enabled: BooleanOrString }).strict(),
       mcp: z.object({
@@ -1267,9 +1452,23 @@ var init_schema = __esm({
       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.
+      acp: z.object({
+        enabled: BooleanOrString,
+        mountPath: MountPathSchema.optional(),
+        auth: AcpAuthSchema.optional(),
+        idempotency: AcpIdempotencySchema.optional(),
+        checkout: AcpCheckoutSchema.optional(),
+        discovery: AcpDiscoverySchema.optional()
       }).strict().optional()
     }).strict();
     DEFAULT_A2A_MOUNT_PATH = "/a2a";
+    DEFAULT_ACP_MOUNT_PATH = "/acp";
+    ACP_RETENTION_HOURS = 24;
     BackendMethodSchema = z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]);
     BackendInputBindingsSchema = z.object({
       path: z.string().min(1).optional(),
@@ -1589,9 +1788,94 @@ var A2A_UNSUPPORTED = [
   "artifact types beyond Agent Commerce outcome data"
 ];
 
+// src/cli/commands/doctor.ts
+init_constants();
+
+// src/protocols/acp/descriptor.ts
+init_constants();
+[
+  "rest transport",
+  "well-known discovery",
+  "bearer authentication",
+  "API-Version negotiation",
+  "checkout service",
+  ...ACP_CHECKOUT_OPERATIONS
+];
+var ACP_UNSUPPORTED = [
+  // Services this seller does not implement, named as ACP names them. The
+  // discovery document advertises `checkout` alone, and these are the reason.
+  "carts service",
+  "feed service",
+  "standalone orders service",
+  "delegate_payment",
+  "delegate_authentication",
+  // Bindings and delivery directions.
+  "ACP MCP transport binding",
+  "webhooks",
+  "outbound merchant-to-agent delivery",
+  "ACP client role",
+  // Request authentication beyond the bearer token.
+  "Signature header verification",
+  "Timestamp replay-window verification",
+  // Extensions and versioning.
+  "discount extension",
+  "general ACP extension framework",
+  "multiple ACP API versions",
+  "seller-backed payment handler integration"
+];
+
 // src/storage/receipts/store.ts
 init_core();
-var PACKAGE_VERSION = "1.2.0" ;
+var PACKAGE_VERSION = "1.3.0" ;
+
+// src/storage/sqlite.ts
+init_core();
+function openSqliteDatabase(options) {
+  const { path: path2, label, logger } = options;
+  const isFileBacked = path2 !== ":memory:";
+  if (isFileBacked) {
+    const dir = dirname(path2);
+    if (dir !== "" && dir !== "." && !existsSync(dir)) {
+      mkdirSync(dir, { recursive: true, mode: 448 });
+    }
+  }
+  if (isFileBacked && existsSync(path2)) {
+    try {
+      accessSync(path2, constants.W_OK);
+    } catch {
+      throw new CommerceError(
+        "STORAGE_ERROR",
+        `${label} "${path2}" exists but is not writable by this process (uid ${typeof process.getuid === "function" ? process.getuid() : "unknown"}). If this is a container that recently changed user, an existing volume may still be owned by the previous one - recreate it (docker compose down -v) or fix its ownership.`,
+        { details: { path: path2 } }
+      );
+    }
+  }
+  if (isFileBacked) {
+    try {
+      closeSync(openSync(path2, "a", 384));
+    } catch {
+    }
+  }
+  const db = new Database(path2);
+  db.pragma("journal_mode = WAL");
+  db.pragma("foreign_keys = ON");
+  if (isFileBacked) restrictDatabasePermissions(path2, label, logger);
+  return db;
+}
+function restrictDatabasePermissions(path2, label, logger) {
+  for (const file of [path2, `${path2}-wal`, `${path2}-shm`]) {
+    try {
+      chmodSync(file, 384);
+    } catch (error) {
+      const code = error.code;
+      if (code === "ENOENT") continue;
+      logger.warn(
+        { file, label, error: code ?? "unknown" },
+        "could not restrict database permissions to owner-only"
+      );
+    }
+  }
+}
 
 // src/storage/receipts/redact.ts
 var SECRET_KEY_PATTERN = /private[-_ ]?key|secret|password|mnemonic|seed[-_ ]?phrase|api[-_ ]?key|authoriz(e|ation)|^auth$|auth[-_]?header|payment[-_ ]?proof|^proof$|x-payment|signature|signed[-_ ]?message|token|bearer|credential|cookie|session|jwt/i;
@@ -1779,54 +2063,14 @@ var defaultIds = {
 function isUniqueConstraintOn(err, column) {
   return err instanceof Error && "code" in err && err.code === "SQLITE_CONSTRAINT_UNIQUE" && err.message.includes(column);
 }
-function restrictDatabasePermissions(path2, logger) {
-  for (const file of [path2, `${path2}-wal`, `${path2}-shm`]) {
-    try {
-      chmodSync(file, 384);
-    } catch (error) {
-      const code = error.code;
-      if (code === "ENOENT") continue;
-      logger.warn(
-        { file, error: code ?? "unknown" },
-        "could not restrict receipt database permissions to owner-only"
-      );
-    }
-  }
-}
 function createSqliteReceiptStore(options) {
   const logger = options.logger ?? NOOP_LOGGER;
   const clock = options.clock ?? systemClock;
   const ids = options.ids ?? defaultIds;
   const path2 = options.path;
   const isFileBacked = path2 !== ":memory:";
-  if (isFileBacked) {
-    const dir = dirname(path2);
-    if (dir !== "" && dir !== "." && !existsSync(dir)) {
-      mkdirSync(dir, { recursive: true, mode: 448 });
-    }
-  }
-  if (isFileBacked && existsSync(path2)) {
-    try {
-      accessSync(path2, constants.W_OK);
-    } catch {
-      throw new CommerceError(
-        "STORAGE_ERROR",
-        `Receipt database "${path2}" exists but is not writable by this process (uid ${typeof process.getuid === "function" ? process.getuid() : "unknown"}). If this is a container that recently changed user, an existing volume may still be owned by the previous one \u2014 recreate it (docker compose down -v) or fix its ownership.`,
-        { details: { path: path2 } }
-      );
-    }
-  }
-  if (isFileBacked) {
-    try {
-      closeSync(openSync(path2, "a", 384));
-    } catch {
-    }
-  }
-  const db = new Database(path2);
-  db.pragma("journal_mode = WAL");
-  db.pragma("foreign_keys = ON");
+  const db = openSqliteDatabase({ path: path2, label: "Receipt database", logger });
   migrate(db);
-  if (isFileBacked) restrictDatabasePermissions(path2, logger);
   const insertReceiptStmt = db.prepare(
     `INSERT INTO receipts (id, request_id, resource_id, payment_json, delivered_at, backend_status, duration_ms, protocol, metadata_json)
      VALUES (@id, @request_id, @resource_id, @payment_json, @delivered_at, @backend_status, @duration_ms, @protocol, @metadata_json)`
@@ -2344,7 +2588,7 @@ function maskMiddle(value, keep = 6) {
 }
 createRequire(import.meta.url);
 function readVersionReport() {
-  const injected = '{"cliVersion":"1.2.0","pinned":[{"name":"@coinbase/x402","version":"2.1.0","via":"@devlab.group/agent-commerce"},{"name":"@modelcontextprotocol/sdk","version":"1.30.0","via":"@devlab.group/agent-commerce"},{"name":"@x402/core","version":"2.23.0","via":"@devlab.group/agent-commerce"},{"name":"@x402/evm","version":"2.23.0","via":"@devlab.group/agent-commerce"},{"name":"viem","version":"2.55.18","via":"@devlab.group/agent-commerce"},{"name":"better-sqlite3","version":"13.0.3","via":"@devlab.group/agent-commerce"},{"name":"fastify","version":"5.12.0","via":"@devlab.group/agent-commerce"},{"name":"pino","version":"10.3.1","via":"@devlab.group/agent-commerce"},{"name":"zod","version":"3.25.76","via":"@devlab.group/agent-commerce"}]}' ;
+  const injected = '{"cliVersion":"1.3.0","pinned":[{"name":"@coinbase/x402","version":"2.1.0","via":"@devlab.group/agent-commerce"},{"name":"@modelcontextprotocol/sdk","version":"1.30.0","via":"@devlab.group/agent-commerce"},{"name":"@x402/core","version":"2.23.0","via":"@devlab.group/agent-commerce"},{"name":"@x402/evm","version":"2.23.0","via":"@devlab.group/agent-commerce"},{"name":"viem","version":"2.55.18","via":"@devlab.group/agent-commerce"},{"name":"better-sqlite3","version":"13.0.3","via":"@devlab.group/agent-commerce"},{"name":"fastify","version":"5.12.0","via":"@devlab.group/agent-commerce"},{"name":"pino","version":"10.3.1","via":"@devlab.group/agent-commerce"},{"name":"zod","version":"3.25.76","via":"@devlab.group/agent-commerce"}]}' ;
   {
     return JSON.parse(injected);
   }
@@ -2406,6 +2650,73 @@ function findX402Mismatch(configured, live) {
   if (diffs.length === 0) return void 0;
   return `${diffs.join("; ")} \u2014 the gateway may be running against an older deployment; restart it or re-run chain:deploy`;
 }
+function acpIdempotencyCheck(idempotency) {
+  const retention = `retention ${idempotency.retentionHours}h`;
+  if (idempotency.retentionHours < 24) {
+    return {
+      name: "ACP idempotency",
+      status: "FAIL",
+      detail: `${retention} is below the 24h ACP minimum \u2014 a replayed key could run a checkout twice`
+    };
+  }
+  if (idempotency.path === ":memory:") {
+    return {
+      name: "ACP idempotency",
+      status: "WARN",
+      detail: `in-memory store, ${retention} \u2014 replay protection is lost on every restart; use a file path in production`
+    };
+  }
+  const directory = dirname(idempotency.path);
+  if (existsSync(idempotency.path)) {
+    try {
+      accessSync(idempotency.path, constants.W_OK);
+      return { name: "ACP idempotency", status: "PASS", detail: `writable, ${retention}` };
+    } catch {
+      return {
+        name: "ACP idempotency",
+        status: "FAIL",
+        detail: `"${idempotency.path}" exists but is not writable by this user \u2014 the adapter cannot claim idempotency keys`
+      };
+    }
+  }
+  if (directory !== "" && directory !== "." && !existsSync(directory)) {
+    return {
+      name: "ACP idempotency",
+      status: "WARN",
+      detail: `no store yet at "${idempotency.path}" and its directory does not exist \u2014 it is created when the gateway starts, provided that path is writable`
+    };
+  }
+  return {
+    name: "ACP idempotency",
+    status: "WARN",
+    detail: `no store yet at "${idempotency.path}" \u2014 it is created the first time the gateway starts (${retention})`
+  };
+}
+function acpMappingCheck(config, operations) {
+  const byId = new Map(config.resources.map((resource) => [resource.id, resource]));
+  const problems = [];
+  for (const [operation, resourceId] of Object.entries(operations)) {
+    const resource = byId.get(resourceId);
+    if (resource === void 0) {
+      problems.push(`${operation} -> "${resourceId}" does not exist`);
+      continue;
+    }
+    if (!resource.exposedVia.includes("acp")) {
+      problems.push(`${operation} -> "${resourceId}" is not exposed via acp`);
+    }
+    if (resource.pricing.type !== "free" || resource.paymentMethods.length > 0) {
+      problems.push(`${operation} -> "${resourceId}" is not free to invoke`);
+    }
+  }
+  if (problems.length > 0) {
+    return { name: "ACP checkout mapping", status: "FAIL", detail: problems.join("; ") };
+  }
+  return {
+    name: "ACP checkout mapping",
+    status: "PASS",
+    detail: `5 operations mapped to free acp-exposed resources (${Object.values(operations).join(", ")})`
+  };
+}
 async function runDoctor(options, deps = {}) {
   const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
   const loadConfig2 = deps.loadConfig ?? loadConfigDynamic;
@@ -2487,7 +2798,7 @@ async function runDoctor(options, deps = {}) {
     checks.push({
       name: "Protocols",
       status: "PASS",
-      detail: `http=${config.protocols.http.enabled ? "on" : "off"} mcp=${config.protocols.mcp.enabled ? `on (${mcpMountPath})` : "off"} a2a=${config.protocols.a2a.enabled ? `on (${a2aMountPath})` : "off"}`
+      detail: `http=${config.protocols.http.enabled ? "on" : "off"} mcp=${config.protocols.mcp.enabled ? `on (${mcpMountPath})` : "off"} a2a=${config.protocols.a2a.enabled ? `on (${a2aMountPath})` : "off"} acp=${config.protocols.acp.enabled ? `on (${config.protocols.acp.mountPath})` : "off"}`
     });
   }
   if (config === void 0) {
@@ -2506,6 +2817,30 @@ async function runDoctor(options, deps = {}) {
       detail: A2A_UNSUPPORTED.join(", ")
     });
   }
+  if (config === void 0) {
+    checks.push({ name: "ACP", status: "WARN", detail: "skipped \u2014 config invalid" });
+  } else if (!config.protocols.acp.enabled) {
+    checks.push({ name: "ACP", status: "INFO", detail: "disabled" });
+  } else {
+    const acp = config.protocols.acp;
+    checks.push({
+      name: "ACP",
+      status: "PASS",
+      detail: `experimental \xB7 spec ${ACP_SPEC_VERSION} \xB7 API-Version ${ACP_API_VERSION} \xB7 service checkout \xB7 mount ${acp.mountPath} \xB7 discovery ${ACP_WELL_KNOWN_PATH}`
+    });
+    checks.push({
+      name: "ACP auth",
+      status: "PASS",
+      detail: `bearer token configured (${acp.auth.token.length} characters, not shown)`
+    });
+    checks.push(acpIdempotencyCheck(acp.idempotency));
+    checks.push(acpMappingCheck(config, acp.checkout.operations));
+    checks.push({
+      name: "ACP unsupported",
+      status: "INFO",
+      detail: ACP_UNSUPPORTED.join(", ")
+    });
+  }
   const x402 = config?.payments.x402;
   if (x402 === void 0 || !x402.enabled) {
     checks.push({ name: "Payments", status: "INFO", detail: "x402 not configured" });
@@ -3801,7 +4136,7 @@ async function runValidate(options, io, deps = {}) {
     io.stdout(`      merchant: ${config.merchant.name} (${config.merchant.id})`);
     io.stdout(`      resources: ${config.resources.length}`);
     io.stdout(
-      `      protocols: http=${config.protocols.http.enabled ? "on" : "off"} mcp=${config.protocols.mcp.enabled ? "on" : "off"} a2a=${config.protocols.a2a.enabled ? "on" : "off"}`
+      `      protocols: http=${config.protocols.http.enabled ? "on" : "off"} mcp=${config.protocols.mcp.enabled ? "on" : "off"} a2a=${config.protocols.a2a.enabled ? "on" : "off"} acp=${config.protocols.acp.enabled ? "on" : "off"}`
     );
     io.stdout(`      payments: x402=${config.payments.x402?.enabled === true ? "on" : "off"}`);
     return 0;