@devlab.group/agent-commerce 0.1.0-alpha.0

package/dist/index.js

@@ -0,0 +1,2930 @@
+import { CommerceError, PAYMENT_INPUT_FIELD, systemClock, NOOP_LOGGER, PACKAGE_VERSION, toCommerceError, DEFAULT_BACKEND_TIMEOUT_MS, toErrorEnvelope, isHttpProtocolAdapter, isCommerceError, PAYMENT_HEADER, toPaymentRequiredEnvelope, PAYMENT_RESPONSE_HEADER } from './chunk-CZ6ZDAYD.js';
+export { COMMERCE_ERROR_CODES, COMMERCE_ERROR_HTTP_STATUS, COMMERCE_EVENT_TYPES, CommerceError, DEFAULT_BACKEND_TIMEOUT_MS, DELIVERY_SUMMARY_META_KEY, NOOP_LOGGER, PAYMENT_HEADER, PAYMENT_INPUT_FIELD, PAYMENT_RESPONSE_HEADER, RETRYABLE_ERROR_CODES, isCommerceError, isHttpProtocolAdapter, isPaymentRequiredEnvelope, systemClock, toCommerceError, toDeliverySummary, toErrorEnvelope, toPaymentRequiredEnvelope } from './chunk-CZ6ZDAYD.js';
+import { promises, existsSync, mkdirSync, accessSync, constants, chmodSync } from 'fs';
+import * as path from 'path';
+import { dirname } from 'path';
+import { parse, YAMLError } from 'yaml';
+import { z } from 'zod';
+import { randomUUID, timingSafeEqual, createHash } from 'crypto';
+import { createRequire } from 'module';
+import pino from 'pino';
+import Fastify from 'fastify';
+import Database from 'better-sqlite3';
+
+// src/config/env.ts
+var PLACEHOLDER_PATTERN = /\$\{([A-Za-z_][A-Za-z0-9_]*)(:-([^}]*))?\}/g;
+function substituteEnv(value, env, path2 = "$") {
+  if (typeof value === "string") {
+    return substituteString(value, env, path2);
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry, index) => substituteEnv(entry, env, `${path2}[${index}]`));
+  }
+  if (isPlainObject(value)) {
+    const result = {};
+    for (const [key, entry] of Object.entries(value)) {
+      result[key] = substituteEnv(entry, env, `${path2}.${key}`);
+    }
+    return result;
+  }
+  return value;
+}
+function substituteString(value, env, path2) {
+  const substituted = substituteOnce(value, env, path2);
+  PLACEHOLDER_PATTERN.lastIndex = 0;
+  if (PLACEHOLDER_PATTERN.test(substituted)) {
+    PLACEHOLDER_PATTERN.lastIndex = 0;
+    const residual = PLACEHOLDER_PATTERN.exec(substituted)?.[0] ?? "${\u2026}";
+    PLACEHOLDER_PATTERN.lastIndex = 0;
+    throw new CommerceError(
+      "CONFIG_INVALID",
+      `Configuration value at "${path2}" still contains the unresolved placeholder "${residual}" after substitution \u2014 nested placeholders (e.g. "\${A:-\${B}}") are not supported. Use a plain default, or set the variable.`,
+      { details: { path: path2, residual } }
+    );
+  }
+  return substituted;
+}
+function substituteOnce(value, env, path2) {
+  return value.replace(
+    PLACEHOLDER_PATTERN,
+    (_match, name, hasDefault, def) => {
+      const envValue = env[name];
+      if (hasDefault !== void 0) {
+        if (envValue === void 0 || envValue === "") return def ?? "";
+        return envValue;
+      }
+      if (envValue === void 0) {
+        throw new CommerceError(
+          "CONFIG_INVALID",
+          `Unresolved environment variable "\${${name}}" referenced at config path "${path2}"`,
+          { details: { variable: name, path: path2 } }
+        );
+      }
+      return envValue;
+    }
+  );
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/config/filename.ts
+var DEFAULT_CONFIG_FILENAME = "config.yaml";
+
+// src/core/execution/backend-http.ts
+var MAX_BODY_SNIPPET_LENGTH = 512;
+var PATH_PARAM_PATTERN = /\{([a-zA-Z0-9_.-]+)\}/g;
+var MAX_RESPONSE_BODY_BYTES = 1024 * 1024;
+var HttpBackendExecutor = class {
+  fetchImpl;
+  logger;
+  constructor(options = {}) {
+    this.fetchImpl = options.fetchImpl ?? fetch;
+    this.logger = options.logger ?? NOOP_LOGGER;
+  }
+  async call(handler, request) {
+    const timeoutMs = handler.timeoutMs ?? DEFAULT_BACKEND_TIMEOUT_MS;
+    const inputRecord = isPlainObject2(request.input) ? request.input : {};
+    let target;
+    let remaining;
+    try {
+      const templated = applyPathTemplate(handler.url, inputRecord);
+      target = new URL(templated.url);
+      remaining = templated.remaining;
+    } catch (error) {
+      if (error instanceof Error && error.message.startsWith("invalid-path-parameter:")) {
+        const field = error.message.slice("invalid-path-parameter:".length);
+        throw new CommerceError("INPUT_INVALID", `Path parameter "${field}" is not a valid value`, {
+          requestId: request.requestId,
+          resourceId: request.resourceId,
+          details: { field }
+        });
+      }
+      if (error instanceof Error && error.message.startsWith("missing-path-parameter:")) {
+        const field = error.message.slice("missing-path-parameter:".length);
+        throw new CommerceError("INPUT_INVALID", `Path parameter "${field}" was not supplied`, {
+          requestId: request.requestId,
+          resourceId: request.resourceId,
+          details: { field }
+        });
+      }
+      throw new CommerceError("BACKEND_ERROR", "Backend URL could not be constructed from input", {
+        requestId: request.requestId,
+        resourceId: request.resourceId,
+        details: { reason: describeConstructionError(error) },
+        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 headers = { ...handler.headers ?? {} };
+    let body;
+    if (handler.method === "GET" || handler.method === "DELETE") {
+      checkQueryCollision(target, remaining, {
+        requestId: request.requestId,
+        resourceId: request.resourceId
+      });
+      for (const [key, value] of Object.entries(remaining)) {
+        target.searchParams.set(key, stringifyPrimitive(value));
+      }
+    } else {
+      body = JSON.stringify(remaining);
+      if (!hasHeader(headers, "content-type")) {
+        headers["content-type"] = "application/json";
+      }
+    }
+    const started = performance.now();
+    let response;
+    try {
+      response = await this.fetchImpl(target, {
+        method: handler.method,
+        headers,
+        ...body !== void 0 ? { body } : {},
+        redirect: "manual",
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+    } catch (error) {
+      const durationMs2 = Math.round(performance.now() - started);
+      if (isAbortError(error)) {
+        throw new CommerceError(
+          "BACKEND_TIMEOUT",
+          `Backend request timed out after ${timeoutMs}ms`,
+          {
+            requestId: request.requestId,
+            resourceId: request.resourceId,
+            details: { timeoutMs, durationMs: durationMs2 },
+            cause: error
+          }
+        );
+      }
+      throw new CommerceError("BACKEND_ERROR", "Backend request failed (transport error)", {
+        requestId: request.requestId,
+        resourceId: request.resourceId,
+        details: { durationMs: durationMs2 },
+        cause: error
+      });
+    }
+    const durationMs = Math.round(performance.now() - started);
+    const isRedirect = response.type === "opaqueredirect" || response.status >= 300 && response.status < 400;
+    if (isRedirect) {
+      throw new CommerceError(
+        "BACKEND_ERROR",
+        "Backend responded with a redirect, which is not followed",
+        {
+          requestId: request.requestId,
+          resourceId: request.resourceId,
+          details: { status: response.status, reason: "redirect-not-followed" }
+        }
+      );
+    }
+    const responseHeaders = headersToRecord(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");
+      throw new CommerceError(
+        "BACKEND_ERROR",
+        tooLarge ? "Backend response exceeded the maximum allowed size" : "Backend response could not be read",
+        {
+          requestId: request.requestId,
+          resourceId: request.resourceId,
+          details: tooLarge ? { reason: "response-too-large", maxBytes: MAX_RESPONSE_BODY_BYTES } : { reason: "read-error" },
+          cause: error
+        }
+      );
+    }
+    if (response.status < 200 || response.status >= 300) {
+      this.logger.debug(
+        {
+          requestId: request.requestId,
+          resourceId: request.resourceId,
+          status: response.status,
+          bodySnippet: truncateSnippet(parsedBody)
+        },
+        "Backend responded with a non-2xx status"
+      );
+      throw new CommerceError("BACKEND_ERROR", `Backend responded with status ${response.status}`, {
+        requestId: request.requestId,
+        resourceId: request.resourceId,
+        details: { status: response.status }
+      });
+    }
+    return {
+      status: response.status,
+      headers: responseHeaders,
+      body: parsedBody,
+      durationMs
+    };
+  }
+};
+function extractPathParameterNames(url) {
+  return [...url.matchAll(PATH_PARAM_PATTERN)].map((match) => match[1]);
+}
+function findUnparsedBraceToken(url) {
+  const residue = url.replace(PATH_PARAM_PATTERN, "");
+  const index = residue.search(/[{}]/);
+  if (index === -1) return void 0;
+  const token = /\{[^{}]*\}?|\}/.exec(residue.slice(index));
+  return token?.[0] ?? residue[index];
+}
+function validateBackendRequestShape(handler, input, context) {
+  const inputRecord = isPlainObject2(input) ? input : {};
+  let templated;
+  try {
+    templated = applyPathTemplate(handler.url, inputRecord);
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith("invalid-path-parameter:")) {
+      const field = error.message.slice("invalid-path-parameter:".length);
+      throw new CommerceError("INPUT_INVALID", `Path parameter "${field}" is not a valid value`, {
+        requestId: context.requestId,
+        resourceId: context.resourceId,
+        details: { field }
+      });
+    }
+    if (error instanceof Error && error.message.startsWith("missing-path-parameter:")) {
+      const field = error.message.slice("missing-path-parameter:".length);
+      throw new CommerceError("INPUT_INVALID", `Path parameter "${field}" was not supplied`, {
+        requestId: context.requestId,
+        resourceId: context.resourceId,
+        details: { field }
+      });
+    }
+    return;
+  }
+  if (handler.method === "GET" || handler.method === "DELETE") {
+    let target;
+    try {
+      target = new URL(templated.url);
+    } catch {
+      return;
+    }
+    checkQueryCollision(target, templated.remaining, context);
+  }
+}
+function checkQueryCollision(target, remaining, context) {
+  const templateKeys = new Set(target.searchParams.keys());
+  for (const key of Object.keys(remaining)) {
+    if (templateKeys.has(key)) {
+      throw new CommerceError(
+        "INPUT_INVALID",
+        `Input key "${key}" collides with a query parameter already set on backend.url`,
+        { requestId: context.requestId, resourceId: context.resourceId, details: { field: key } }
+      );
+    }
+  }
+}
+function isPlainObject2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+var TRAVERSAL_PATH_VALUES = /* @__PURE__ */ new Set(["", ".", ".."]);
+function applyPathTemplate(template, input) {
+  const remaining = { ...input };
+  let missing;
+  let invalid;
+  const url = template.replace(PATH_PARAM_PATTERN, (_match, key) => {
+    if (!Object.hasOwn(remaining, key)) {
+      missing = key;
+      return "";
+    }
+    const value = remaining[key];
+    delete remaining[key];
+    const raw = stringifyPrimitive(value);
+    if (TRAVERSAL_PATH_VALUES.has(raw)) {
+      invalid = key;
+      return "";
+    }
+    return encodeURIComponent(raw);
+  });
+  if (missing !== void 0) {
+    throw new Error(`missing-path-parameter:${missing}`);
+  }
+  if (invalid !== void 0) {
+    throw new Error(`invalid-path-parameter:${invalid}`);
+  }
+  return { url, remaining };
+}
+function describeConstructionError(error) {
+  if (error instanceof Error && error.message.startsWith("missing-path-parameter:")) {
+    return error.message;
+  }
+  return "invalid-url";
+}
+function stringifyPrimitive(value) {
+  if (value === void 0 || value === null) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+function hasHeader(headers, name) {
+  const target = name.toLowerCase();
+  return Object.keys(headers).some((key) => key.toLowerCase() === target);
+}
+function headersToRecord(headers) {
+  const record = {};
+  headers.forEach((value, key) => {
+    record[key] = value;
+  });
+  return record;
+}
+async function readBodyCapped(response, maxBytes) {
+  if (!response.body) return "";
+  const reader = response.body.getReader();
+  const chunks = [];
+  let total = 0;
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > maxBytes) {
+        await reader.cancel();
+        throw new Error(`response-body-too-large:${maxBytes}`);
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+async function parseBody(response, contentType) {
+  const text = await readBodyCapped(response, MAX_RESPONSE_BODY_BYTES);
+  if (text.length === 0) return text;
+  if (contentType.includes("json")) {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+  return text;
+}
+function truncateSnippet(body) {
+  const text = typeof body === "string" ? body : safeStringify(body);
+  return text.length > MAX_BODY_SNIPPET_LENGTH ? `${text.slice(0, MAX_BODY_SNIPPET_LENGTH)}\u2026` : text;
+}
+function safeStringify(value) {
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(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",
+  "number",
+  "integer",
+  "boolean",
+  "array",
+  "null"
+]);
+function compileJsonSchema(schema) {
+  return (input) => {
+    if (schema === void 0) return { valid: true, value: input };
+    const errors = validateNode(schema, input, "$");
+    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);
+    case "array":
+      return Array.isArray(value);
+    case "string":
+      return typeof value === "string";
+    case "boolean":
+      return typeof value === "boolean";
+    case "number":
+      return typeof value === "number" && Number.isFinite(value);
+    case "integer":
+      return typeof value === "number" && Number.isInteger(value);
+    case "null":
+      return value === null;
+    default:
+      return true;
+  }
+}
+function describeType(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  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;
+  }
+}
+function own(obj, key) {
+  return Object.hasOwn(obj, key) ? obj[key] : void 0;
+}
+function typeList(raw) {
+  if (typeof raw === "string") return [raw];
+  if (Array.isArray(raw) && raw.every((entry) => typeof entry === "string")) {
+    return raw;
+  }
+  return void 0;
+}
+function isObjectSchemaNode(schema) {
+  const types = typeList(schema["type"]);
+  if (types !== void 0) return types.includes("object");
+  return Object.hasOwn(schema, "properties") || Object.hasOwn(schema, "required");
+}
+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) {
+    if (!types.some((entry) => matchesType(entry, value))) {
+      errors.push({
+        path: path2,
+        message: `expected type "${types.join(" | ")}" but got ${describeType(value)}`
+      });
+      return errors;
+    }
+  }
+  const enumRaw = own(schema, "enum");
+  if (Array.isArray(enumRaw)) {
+    const allowed = enumRaw;
+    if (!allowed.some((candidate) => deepEqual(candidate, value))) {
+      errors.push({ path: path2, message: `must be one of ${JSON.stringify(allowed)}` });
+    }
+  }
+  if (isObjectSchemaNode(schema) && isPlainObject3(value)) {
+    errors.push(...validateObject(schema, value, path2));
+  } else if ((types?.includes("array") ?? false) && Array.isArray(value)) {
+    errors.push(...validateArray(schema, value, path2));
+  }
+  return errors;
+}
+function validateObject(schema, value, path2) {
+  const errors = [];
+  const propsRaw = own(schema, "properties");
+  const properties = isPlainObject3(propsRaw) ? propsRaw : {};
+  const requiredRaw = own(schema, "required");
+  const required = Array.isArray(requiredRaw) ? requiredRaw.filter((entry) => typeof entry === "string") : [];
+  for (const key of required) {
+    if (!Object.hasOwn(value, key)) {
+      errors.push({ path: `${path2}.${key}`, message: "is required" });
+    }
+  }
+  const additional = own(schema, "additionalProperties");
+  for (const key of Object.keys(value)) {
+    const propSchemaRaw = own(properties, key);
+    if (propSchemaRaw !== void 0) {
+      if (isPlainObject3(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)) {
+      errors.push(...validateNode(additional, value[key], `${path2}.${key}`));
+    }
+  }
+  return errors;
+}
+function validateArray(schema, value, path2) {
+  const errors = [];
+  const itemsRaw = own(schema, "items");
+  if (isPlainObject3(itemsRaw)) {
+    value.forEach((item, index) => {
+      errors.push(...validateNode(itemsRaw, item, `${path2}[${index}]`));
+    });
+  }
+  return errors;
+}
+
+// src/core/execution/pipeline.ts
+function createExecutionPipeline(options) {
+  const validators = /* @__PURE__ */ new Map();
+  function getValidator(resource) {
+    const cached = validators.get(resource.id);
+    if (cached) return cached;
+    const compiled = compileJsonSchema(resource.inputSchema);
+    validators.set(resource.id, compiled);
+    return compiled;
+  }
+  async function safeEmit(event) {
+    try {
+      await options.events.emit(event);
+    } catch (error) {
+      options.logger.error(
+        { err: describeError2(error), eventType: event.type, requestId: event.requestId },
+        "Event sink failed; commerce flow continues"
+      );
+    }
+  }
+  async function safePersist(op, label, requestId) {
+    try {
+      await op();
+    } catch (error) {
+      options.logger.error(
+        { err: describeError2(error), requestId },
+        `Persistence failed: ${label}`
+      );
+    }
+  }
+  function buildEvent(partial) {
+    return { id: options.ids.next("evt"), at: options.clock.nowIso(), ...partial };
+  }
+  async function execute(request) {
+    const pipelineStart = options.clock.monotonicMs();
+    const resource = options.resources.get(request.resourceId);
+    if (!resource || !resource.exposedVia.includes(request.protocol)) {
+      throw new CommerceError(
+        "RESOURCE_NOT_FOUND",
+        `Resource "${request.resourceId}" was not found`,
+        {
+          requestId: request.requestId,
+          resourceId: request.resourceId
+        }
+      );
+    }
+    await safeEmit(
+      buildEvent({
+        type: "resource.requested",
+        requestId: request.requestId,
+        resourceId: resource.id,
+        adapter: request.protocol
+      })
+    );
+    const strippedInput = stripPaymentField(request.input);
+    const validation = getValidator(resource)(strippedInput);
+    if (!validation.valid) {
+      throw new CommerceError(
+        "INPUT_INVALID",
+        `Input for resource "${resource.id}" failed validation`,
+        {
+          requestId: request.requestId,
+          resourceId: resource.id,
+          details: { errors: validation.errors }
+        }
+      );
+    }
+    const validInput = validation.value;
+    validateBackendRequestShape(resource.handler, validInput, {
+      requestId: request.requestId,
+      resourceId: resource.id
+    });
+    if (resource.pricing.type === "dynamic") {
+      throw new CommerceError(
+        "CONFIG_INVALID",
+        `Resource "${resource.id}" uses unsupported dynamic pricing`,
+        {
+          requestId: request.requestId,
+          resourceId: resource.id
+        }
+      );
+    }
+    let paymentResult;
+    if (resource.pricing.type === "fixed") {
+      const pricing = resource.pricing;
+      const provider = pickProvider(options.paymentProviders, resource.paymentMethods);
+      if (!provider) {
+        throw new CommerceError(
+          "PAYMENT_PROVIDER_UNAVAILABLE",
+          `No enabled payment provider for resource "${resource.id}"`,
+          {
+            requestId: request.requestId,
+            resourceId: resource.id,
+            details: { paymentMethods: resource.paymentMethods }
+          }
+        );
+      }
+      let requirement;
+      try {
+        requirement = await provider.createRequirement({
+          requestId: request.requestId,
+          resource,
+          amount: pricing.amount,
+          currency: pricing.currency,
+          requestedAt: options.clock.nowIso()
+        });
+      } catch (error) {
+        throw isCommerceError(error) ? error : new CommerceError("PAYMENT_PROVIDER_UNAVAILABLE", "Payment provider is unavailable", {
+          requestId: request.requestId,
+          resourceId: resource.id,
+          cause: error
+        });
+      }
+      if (!request.payment) {
+        await safeEmit(
+          buildEvent({
+            type: "payment.required",
+            requestId: request.requestId,
+            resourceId: resource.id,
+            adapter: request.protocol,
+            paymentProvider: provider.name
+          })
+        );
+        return {
+          kind: "payment-required",
+          requestId: request.requestId,
+          resourceId: resource.id,
+          requirement
+        };
+      }
+      const payment = request.payment;
+      let verification;
+      try {
+        verification = await provider.verify({
+          requestId: request.requestId,
+          resource,
+          requirement,
+          submission: payment
+        });
+      } catch (error) {
+        const mapped = isCommerceError(error) ? error : new CommerceError("PAYMENT_INVALID", "Payment verification failed", {
+          requestId: request.requestId,
+          resourceId: resource.id,
+          cause: error
+        });
+        await safeEmit(
+          buildEvent({
+            type: "payment.rejected",
+            requestId: request.requestId,
+            resourceId: resource.id,
+            adapter: request.protocol,
+            paymentProvider: provider.name,
+            status: "error",
+            data: { reason: mapped.code }
+          })
+        );
+        throw mapped;
+      }
+      if (verification.status !== "verified") {
+        await safeEmit(
+          buildEvent({
+            type: "payment.rejected",
+            requestId: request.requestId,
+            resourceId: resource.id,
+            adapter: request.protocol,
+            paymentProvider: provider.name,
+            status: "error",
+            data: verification.rejectionReason ? { reason: verification.rejectionReason } : {}
+          })
+        );
+        throw new CommerceError(
+          "PAYMENT_INVALID",
+          verification.rejectionReason ?? "Payment was rejected",
+          {
+            requestId: request.requestId,
+            resourceId: resource.id
+          }
+        );
+      }
+      if (!verification.replayKey) {
+        await safeEmit(
+          buildEvent({
+            type: "payment.rejected",
+            requestId: request.requestId,
+            resourceId: resource.id,
+            adapter: request.protocol,
+            paymentProvider: provider.name,
+            status: "error",
+            data: { reason: "missing-replay-key" }
+          })
+        );
+        throw new CommerceError("PAYMENT_INVALID", "Payment provider did not return a replay key", {
+          requestId: request.requestId,
+          resourceId: resource.id
+        });
+      }
+      const replayKey = verification.replayKey;
+      try {
+        await options.store.reservePaymentAttempt({
+          requestId: request.requestId,
+          resourceId: resource.id,
+          provider: provider.name,
+          replayKey,
+          amount: verification.amount,
+          currency: verification.currency,
+          ...verification.payer !== void 0 ? { payer: verification.payer } : {},
+          ...verification.payee !== void 0 ? { payee: verification.payee } : {}
+        });
+      } catch (error) {
+        const mapped = toCommerceError(
+          error,
+          "STORAGE_ERROR",
+          "Payment attempt could not be recorded"
+        );
+        await safeEmit(
+          buildEvent({
+            type: "payment.rejected",
+            requestId: request.requestId,
+            resourceId: resource.id,
+            adapter: request.protocol,
+            paymentProvider: provider.name,
+            status: "error",
+            data: { reason: mapped.code }
+          })
+        );
+        throw mapped;
+      }
+      await safeEmit(
+        buildEvent({
+          type: "payment.verified",
+          requestId: request.requestId,
+          resourceId: resource.id,
+          adapter: request.protocol,
+          paymentProvider: provider.name,
+          status: "ok"
+        })
+      );
+      let settlement;
+      try {
+        settlement = await provider.settle({
+          requestId: request.requestId,
+          resource,
+          requirement,
+          submission: payment,
+          verification
+        });
+      } catch (error) {
+        const uncertainTxHash = uncertainSettlementTxHash(error);
+        await safePersist(
+          () => options.store.updatePaymentAttempt(
+            uncertainTxHash !== void 0 ? { replayKey, status: "settlement-uncertain", externalReference: uncertainTxHash } : {
+              replayKey,
+              status: "failed",
+              ...error instanceof Error ? { rejectionReason: error.message } : {}
+            }
+          ),
+          uncertainTxHash !== void 0 ? "updatePaymentAttempt(settlement-uncertain)" : "updatePaymentAttempt(failed)",
+          request.requestId
+        );
+        await safeEmit(
+          buildEvent({
+            type: "payment.rejected",
+            requestId: request.requestId,
+            resourceId: resource.id,
+            adapter: request.protocol,
+            paymentProvider: provider.name,
+            status: "error",
+            data: uncertainTxHash !== void 0 ? { reason: "settlement-uncertain", transactionHash: uncertainTxHash } : { reason: "settlement-threw" }
+          })
+        );
+        throw new CommerceError(
+          "PAYMENT_SETTLEMENT_FAILED",
+          uncertainTxHash !== void 0 ? "Settlement could not be confirmed" : "Payment settlement failed",
+          {
+            requestId: request.requestId,
+            resourceId: resource.id,
+            cause: error,
+            ...uncertainTxHash !== void 0 ? { details: { settlementUncertain: true, transactionHash: uncertainTxHash } } : {}
+          }
+        );
+      }
+      if (settlement.status !== "settled") {
+        await safePersist(
+          () => options.store.updatePaymentAttempt({
+            replayKey,
+            status: "rejected",
+            ...settlement.rejectionReason !== void 0 ? { rejectionReason: settlement.rejectionReason } : {}
+          }),
+          "updatePaymentAttempt(rejected)",
+          request.requestId
+        );
+        await safeEmit(
+          buildEvent({
+            type: "payment.rejected",
+            requestId: request.requestId,
+            resourceId: resource.id,
+            adapter: request.protocol,
+            paymentProvider: provider.name,
+            status: "error",
+            data: settlement.rejectionReason ? { reason: settlement.rejectionReason } : {}
+          })
+        );
+        throw new CommerceError(
+          "PAYMENT_SETTLEMENT_FAILED",
+          settlement.rejectionReason ?? "Settlement was rejected",
+          {
+            requestId: request.requestId,
+            resourceId: resource.id
+          }
+        );
+      }
+      await safePersist(
+        () => options.store.updatePaymentAttempt({
+          replayKey,
+          status: "settled",
+          ...settlement.externalReference !== void 0 ? { externalReference: settlement.externalReference } : {}
+        }),
+        "updatePaymentAttempt(settled)",
+        request.requestId
+      );
+      await safeEmit(
+        buildEvent({
+          type: "payment.settled",
+          requestId: request.requestId,
+          resourceId: resource.id,
+          adapter: request.protocol,
+          paymentProvider: provider.name,
+          status: "ok"
+        })
+      );
+      paymentResult = settlement;
+    }
+    const backendStart = options.clock.monotonicMs();
+    let backendResponse;
+    try {
+      backendResponse = await options.backend.call(resource.handler, {
+        requestId: request.requestId,
+        resourceId: resource.id,
+        input: validInput
+      });
+    } catch (error) {
+      const commerceError = toCommerceError(error, "BACKEND_ERROR", "Backend call failed");
+      await safeEmit(
+        buildEvent({
+          type: "backend.failed",
+          requestId: request.requestId,
+          resourceId: resource.id,
+          adapter: request.protocol,
+          status: "error",
+          durationMs: Math.round(options.clock.monotonicMs() - backendStart),
+          data: { code: commerceError.code }
+        })
+      );
+      if (paymentResult !== void 0) {
+        const failedReceipt = {
+          id: options.ids.next("receipt"),
+          requestId: request.requestId,
+          resourceId: resource.id,
+          deliveredAt: options.clock.nowIso(),
+          backendStatus: backendErrorStatus(commerceError),
+          protocol: request.protocol,
+          payment: paymentResult,
+          metadata: { delivered: false, backendErrorCode: commerceError.code }
+        };
+        await safePersist(
+          () => options.store.saveReceipt(failedReceipt),
+          "saveReceipt(backend-failed-after-settlement)",
+          request.requestId
+        );
+        throw new CommerceError(
+          "BACKEND_ERROR",
+          "Payment settled but the backend call failed; the payment was not refunded automatically",
+          {
+            requestId: request.requestId,
+            resourceId: resource.id,
+            cause: commerceError,
+            details: {
+              payment: {
+                status: paymentResult.status,
+                provider: paymentResult.provider,
+                amount: paymentResult.amount,
+                currency: paymentResult.currency,
+                ...paymentResult.externalReference !== void 0 ? { externalReference: paymentResult.externalReference } : {}
+              }
+            }
+          }
+        );
+      }
+      throw commerceError;
+    }
+    await safeEmit(
+      buildEvent({
+        type: "backend.called",
+        requestId: request.requestId,
+        resourceId: resource.id,
+        adapter: request.protocol,
+        status: "ok",
+        durationMs: backendResponse.durationMs,
+        data: { status: backendResponse.status }
+      })
+    );
+    const receipt = {
+      id: options.ids.next("receipt"),
+      requestId: request.requestId,
+      resourceId: resource.id,
+      deliveredAt: options.clock.nowIso(),
+      backendStatus: backendResponse.status,
+      durationMs: backendResponse.durationMs,
+      protocol: request.protocol,
+      ...paymentResult !== void 0 ? { payment: paymentResult } : {}
+    };
+    await safePersist(() => options.store.saveReceipt(receipt), "saveReceipt", request.requestId);
+    const totalDurationMs = Math.round(options.clock.monotonicMs() - pipelineStart);
+    await safeEmit(
+      buildEvent({
+        type: "resource.delivered",
+        requestId: request.requestId,
+        resourceId: resource.id,
+        adapter: request.protocol,
+        status: "ok",
+        durationMs: totalDurationMs
+      })
+    );
+    return {
+      kind: "delivered",
+      requestId: request.requestId,
+      resourceId: resource.id,
+      backendStatus: backendResponse.status,
+      body: backendResponse.body,
+      headers: backendResponse.headers,
+      ...paymentResult !== void 0 ? { payment: paymentResult } : {},
+      receipt,
+      durationMs: totalDurationMs
+    };
+  }
+  return { execute };
+}
+function backendErrorStatus(error) {
+  const status = error.details?.["status"];
+  return typeof status === "number" ? status : 0;
+}
+function uncertainSettlementTxHash(error) {
+  if (!isCommerceError(error) || error.code !== "PAYMENT_PROVIDER_UNAVAILABLE") return void 0;
+  const hash = error.details?.["transactionHash"];
+  return typeof hash === "string" ? hash : void 0;
+}
+function pickProvider(providers, methods) {
+  for (const method of methods) {
+    const found = providers.find((provider) => provider.name === method);
+    if (found) return found;
+  }
+  return void 0;
+}
+var RESERVED_INPUT_KEYS = /* @__PURE__ */ new Set([PAYMENT_INPUT_FIELD, "__proto__"]);
+function stripPaymentField(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;
+  const rest = {};
+  for (const key of Object.keys(record)) {
+    if (!RESERVED_INPUT_KEYS.has(key)) rest[key] = record[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 {
+  byId = /* @__PURE__ */ new Map();
+  ordered;
+  constructor(resources) {
+    for (const resource of resources) {
+      if (this.byId.has(resource.id)) {
+        throw new CommerceError("CONFIG_INVALID", `Duplicate resource id "${resource.id}"`, {
+          details: { resourceId: resource.id }
+        });
+      }
+      this.byId.set(resource.id, resource);
+    }
+    this.ordered = [...resources];
+  }
+  get(id) {
+    return this.byId.get(id);
+  }
+  list() {
+    return this.ordered;
+  }
+  listExposedVia(protocol) {
+    return this.ordered.filter((resource) => resource.exposedVia.includes(protocol));
+  }
+  has(id) {
+    return this.byId.has(id);
+  }
+};
+function createResourceRegistry(resources) {
+  return new ResourceRegistryImpl(resources);
+}
+
+// src/config/schema.ts
+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({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  publicBaseUrl: z.string().min(1)
+}).strict();
+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. */
+  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.
+  allowedOrigins: z.array(
+    z.string().min(1).refine((origin) => origin !== "*", {
+      message: `wildcard "*" is not supported \u2014 allowedOrigins entries are matched literally against the browser's Origin header, so "*" would match nothing. List each scheme://host[:port] explicitly.`
+    }).refine((origin) => !origin.endsWith("/"), {
+      message: 'must not end with "/" \u2014 a browser Origin header never has a trailing slash, so this entry would match nothing. Use e.g. "http://localhost:5173".'
+    })
+  ).optional()
+}).strict();
+var StorageSchema = z.object({
+  receipts: z.object({
+    driver: z.literal("sqlite"),
+    path: z.string().min(1)
+  }).strict()
+}).strict();
+var ProtocolsSchema = z.object({
+  http: z.object({ enabled: BooleanOrString }).strict(),
+  mcp: z.object({
+    enabled: BooleanOrString,
+    mountPath: z.string().min(1)
+  }).strict()
+}).strict();
+var BackendMethodSchema = z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]);
+var BackendHandlerSchema = z.object({
+  type: z.literal("http"),
+  method: BackendMethodSchema,
+  url: z.string().min(1),
+  headers: z.record(z.string(), z.string()).optional(),
+  timeoutMs: NumberOrString.optional()
+}).strict();
+var PricingSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("free") }).strict(),
+  z.object({
+    type: z.literal("fixed"),
+    amount: z.string().min(1),
+    currency: z.string().min(1)
+  }).strict(),
+  z.object({
+    type: z.literal("dynamic"),
+    resolver: z.string().min(1)
+  }).strict()
+]);
+var JsonSchemaValueSchema = z.record(z.string(), z.unknown());
+var ResourceEntrySchema = z.object({
+  name: z.string().min(1),
+  description: z.string().optional(),
+  input: JsonSchemaValueSchema.optional(),
+  output: JsonSchemaValueSchema.optional(),
+  backend: BackendHandlerSchema,
+  pricing: PricingSchema,
+  expose: z.array(z.string().min(1)).min(1),
+  payments: z.array(z.string().min(1)).optional()
+}).strict();
+var ResourcesMapSchema = z.record(z.string().min(1), ResourceEntrySchema);
+var FacilitatorSchema = z.discriminatedUnion("mode", [
+  z.object({
+    mode: z.literal("local"),
+    signerPrivateKey: z.string().min(1)
+  }).strict(),
+  z.object({
+    mode: z.literal("remote"),
+    url: z.string().min(1)
+  }).strict()
+]);
+var X402Schema = z.object({
+  enabled: BooleanOrString,
+  network: z.string().min(1),
+  rpcUrl: z.string().min(1),
+  asset: z.string().min(1),
+  assetName: z.string().min(1),
+  assetVersion: z.string().min(1),
+  assetDecimals: NumberOrString,
+  payTo: z.string().min(1),
+  maxTimeoutSeconds: NumberOrString,
+  facilitator: FacilitatorSchema
+}).strict();
+var PaymentsSchema = z.object({
+  x402: X402Schema.optional()
+}).strict();
+var RawConfigSchema = z.object({
+  version: z.literal(SUPPORTED_CONFIG_VERSION),
+  merchant: MerchantSchema,
+  server: ServerSchema,
+  storage: StorageSchema,
+  protocols: ProtocolsSchema,
+  resources: ResourcesMapSchema,
+  payments: PaymentsSchema
+}).strict();
+function parseConfig(raw, env) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new CommerceError(
+      "CONFIG_INVALID",
+      'Configuration root must be a mapping (object) at "$"',
+      {
+        details: { path: "$" }
+      }
+    );
+  }
+  checkVersion(raw);
+  const substituted = substituteEnv(raw, env);
+  const parsed = parseWithZod(RawConfigSchema, substituted);
+  return normalise(parsed);
+}
+function checkVersion(raw) {
+  if (!("version" in raw)) {
+    throw new CommerceError("CONFIG_INVALID", 'Configuration is missing required field "version"', {
+      details: { path: "version" }
+    });
+  }
+  const rawVersion = raw["version"];
+  const version = typeof rawVersion === "string" ? Number(rawVersion) : rawVersion;
+  if (version !== SUPPORTED_CONFIG_VERSION) {
+    throw new CommerceError(
+      "CONFIG_INVALID",
+      `Unsupported config version "${String(rawVersion)}": this gateway only supports version ${SUPPORTED_CONFIG_VERSION}`,
+      { details: { path: "version", supported: SUPPORTED_CONFIG_VERSION } }
+    );
+  }
+}
+function parseWithZod(schema, value) {
+  const result = schema.safeParse(value);
+  if (!result.success) {
+    throw zodErrorToConfigError(result.error);
+  }
+  return result.data;
+}
+function zodErrorToConfigError(error) {
+  const issues = error.issues.map(describeIssue);
+  const first = issues[0];
+  const message = first ? `Configuration invalid at "${first.path}": ${first.message}` : "Configuration invalid";
+  return new CommerceError("CONFIG_INVALID", message, { details: { issues } });
+}
+function describeIssue(issue) {
+  const path2 = issue.path.length > 0 ? issue.path.join(".") : "$";
+  return { path: path2, message: issue.message, code: issue.code };
+}
+function toNumber(value, path2, bounds = {}) {
+  if (typeof value === "string" && !/^\s*\d+\s*$/.test(value)) {
+    throw new CommerceError(
+      "CONFIG_INVALID",
+      `Configuration value at "${path2}" must be an integer written in decimal digits (got ${value === "" ? "an empty string" : `"${value}"`})`,
+      { details: { path: path2 } }
+    );
+  }
+  const n = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(n) || !Number.isInteger(n)) {
+    throw new CommerceError(
+      "CONFIG_INVALID",
+      `Configuration value at "${path2}" must be an integer`,
+      {
+        details: { path: path2 }
+      }
+    );
+  }
+  if (bounds.min !== void 0 && n < bounds.min) {
+    throw new CommerceError(
+      "CONFIG_INVALID",
+      `Configuration value at "${path2}" must be >= ${bounds.min}`,
+      {
+        details: { path: path2 }
+      }
+    );
+  }
+  if (bounds.max !== void 0 && n > bounds.max) {
+    throw new CommerceError(
+      "CONFIG_INVALID",
+      `Configuration value at "${path2}" must be <= ${bounds.max}`,
+      {
+        details: { path: path2 }
+      }
+    );
+  }
+  return n;
+}
+function toBoolean(value, path2) {
+  if (typeof value === "boolean") return value;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "true") return true;
+  if (normalized === "false") return false;
+  throw new CommerceError(
+    "CONFIG_INVALID",
+    `Configuration value at "${path2}" must be a boolean ("true" or "false")`,
+    { details: { path: path2 } }
+  );
+}
+var SUPPORTED_PROTOCOLS = /* @__PURE__ */ new Set(["http", "mcp"]);
+var SUPPORTED_PAYMENT_METHODS = /* @__PURE__ */ new Set(["x402"]);
+function normalise(raw) {
+  const protocols = {
+    http: { enabled: toBoolean(raw.protocols.http.enabled, "protocols.http.enabled") },
+    mcp: {
+      enabled: toBoolean(raw.protocols.mcp.enabled, "protocols.mcp.enabled"),
+      mountPath: raw.protocols.mcp.mountPath
+    }
+  };
+  const x402Raw = raw.payments.x402;
+  if (x402Raw?.facilitator.mode === "remote") {
+    throw new CommerceError(
+      "CONFIG_INVALID",
+      'payments.x402.facilitator.mode "remote" is not supported in v0.1.0-alpha; use "local" (the deterministic dev-chain facilitator)',
+      { details: { path: "payments.x402.facilitator.mode" } }
+    );
+  }
+  const x402 = x402Raw ? {
+    enabled: toBoolean(x402Raw.enabled, "payments.x402.enabled"),
+    network: x402Raw.network,
+    rpcUrl: x402Raw.rpcUrl,
+    asset: x402Raw.asset,
+    assetName: x402Raw.assetName,
+    assetVersion: x402Raw.assetVersion,
+    assetDecimals: toNumber(x402Raw.assetDecimals, "payments.x402.assetDecimals", {
+      min: 0,
+      max: 36
+    }),
+    payTo: x402Raw.payTo,
+    maxTimeoutSeconds: toNumber(x402Raw.maxTimeoutSeconds, "payments.x402.maxTimeoutSeconds", {
+      min: 1
+    }),
+    // Only "local" can reach here — "remote" was rejected above.
+    facilitator: {
+      mode: "local",
+      signerPrivateKey: x402Raw.facilitator.signerPrivateKey
+    }
+  } : void 0;
+  if (x402) {
+    validateAddress("payments.x402.payTo", x402.payTo);
+    validateAddress("payments.x402.asset", x402.asset);
+  }
+  const resources = Object.entries(raw.resources).map(
+    ([id, entry]) => normaliseResource(id, entry, protocols, x402)
+  );
+  return {
+    version: SUPPORTED_CONFIG_VERSION,
+    merchant: {
+      id: raw.merchant.id,
+      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.
+    server: {
+      port: toNumber(raw.server.port, "server.port", { min: 0, max: 65535 }),
+      host: raw.server.host,
+      ...raw.server.adminToken !== void 0 ? { adminToken: raw.server.adminToken } : {},
+      allowedOrigins: raw.server.allowedOrigins ?? []
+    },
+    storage: { receipts: { driver: "sqlite", path: raw.storage.receipts.path } },
+    protocols,
+    resources,
+    payments: {
+      ...x402 !== void 0 ? { x402 } : {}
+    }
+  };
+}
+function normaliseResource(id, entry, protocols, x402) {
+  if (entry.input !== void 0) validateResourceSchemaKeywords(id, "input", entry.input);
+  const inputProperties = entry.input?.["properties"];
+  if (inputProperties && typeof inputProperties === "object" && PAYMENT_INPUT_FIELD in inputProperties) {
+    throw new CommerceError(
+      "CONFIG_INVALID",
+      `Resource "${id}" declares an input property "${PAYMENT_INPUT_FIELD}", which is reserved for payment proofs`,
+      {
+        details: {
+          path: `resources.${id}.input.properties.${PAYMENT_INPUT_FIELD}`,
+          resourceId: id
+        }
+      }
+    );
+  }
+  for (const protocol of entry.expose) {
+    if (!SUPPORTED_PROTOCOLS.has(protocol)) {
+      const hint = protocol === "ucp" ? " (UCP is planned, not supported in v0.1.0-alpha)" : "";
+      throw new CommerceError(
+        "CONFIG_INVALID",
+        `Resource "${id}" exposes unsupported protocol "${protocol}"${hint}. Supported: http, mcp.`,
+        { details: { path: `resources.${id}.expose`, resourceId: id, protocol } }
+      );
+    }
+  }
+  if (entry.expose.includes("mcp")) {
+    if (!protocols.mcp.enabled) {
+      throw new CommerceError(
+        "CONFIG_INVALID",
+        `Resource "${id}" is exposed via "mcp" but protocols.mcp.enabled is false`,
+        { details: { path: `resources.${id}.expose`, resourceId: id } }
+      );
+    }
+    if (!MCP_TOOL_NAME_PATTERN.test(id)) {
+      throw new CommerceError(
+        "CONFIG_INVALID",
+        `Resource "${id}" is exposed via "mcp" but its id is not a legal MCP tool name (allowed: A-Z, a-z, 0-9, "_", "-", ".", 1-128 chars)`,
+        { details: { path: `resources.${id}`, resourceId: id } }
+      );
+    }
+  }
+  if (entry.expose.includes("http") && !protocols.http.enabled) {
+    throw new CommerceError(
+      "CONFIG_INVALID",
+      `Resource "${id}" is exposed via "http" but protocols.http.enabled is false`,
+      { details: { path: `resources.${id}.expose`, resourceId: id } }
+    );
+  }
+  validateBackendUrl(id, entry.backend.url);
+  validatePathParametersDeclared(id, entry.backend.url, entry.input);
+  if (entry.pricing.type === "dynamic") {
+    throw new CommerceError(
+      "CONFIG_INVALID",
+      `Resource "${id}" uses pricing.type "dynamic", which is not supported in v0.1.0-alpha`,
+      { details: { path: `resources.${id}.pricing.type`, resourceId: id } }
+    );
+  }
+  if (entry.pricing.type === "fixed") {
+    validatePricingAmount(id, entry.pricing.amount, x402);
+  }
+  const paymentMethods = entry.payments ?? [];
+  if (entry.pricing.type === "fixed") {
+    if (paymentMethods.length === 0) {
+      throw new CommerceError(
+        "CONFIG_INVALID",
+        `Resource "${id}" has fixed pricing but declares no "payments" (a paid resource must name at least one payment method)`,
+        { details: { path: `resources.${id}.payments`, resourceId: id } }
+      );
+    }
+    for (const method of paymentMethods) {
+      if (!SUPPORTED_PAYMENT_METHODS.has(method)) {
+        throw new CommerceError(
+          "CONFIG_INVALID",
+          `Resource "${id}" names unsupported payment method "${method}". Supported: x402.`,
+          { details: { path: `resources.${id}.payments`, resourceId: id, method } }
+        );
+      }
+      if (method === "x402" && (!x402 || !x402.enabled)) {
+        throw new CommerceError(
+          "CONFIG_INVALID",
+          `Resource "${id}" names payment method "x402" which is not configured or not enabled under payments.x402`,
+          { details: { path: `resources.${id}.payments`, resourceId: id, method } }
+        );
+      }
+    }
+  }
+  const pricing = entry.pricing.type === "free" ? { type: "free" } : { type: "fixed", amount: entry.pricing.amount, currency: entry.pricing.currency };
+  return {
+    id,
+    name: entry.name,
+    ...entry.description !== void 0 ? { description: entry.description } : {},
+    inputSchema: entry.input !== void 0 ? defaultClosedObjectSchema(entry.input) : EMPTY_CLOSED_OBJECT_SCHEMA,
+    ...entry.output !== void 0 ? { outputSchema: entry.output } : {},
+    handler: {
+      type: "http",
+      method: entry.backend.method,
+      url: entry.backend.url,
+      ...entry.backend.headers !== void 0 ? { headers: entry.backend.headers } : {},
+      ...entry.backend.timeoutMs !== void 0 ? {
+        timeoutMs: toNumber(entry.backend.timeoutMs, `resources.${id}.backend.timeoutMs`, {
+          min: 1
+        })
+      } : {}
+    },
+    pricing,
+    exposedVia: entry.expose,
+    paymentMethods
+  };
+}
+function defaultClosedObjectSchema(schema) {
+  const isObjectSchema = isObjectSchemaNode(schema);
+  const result = { ...schema };
+  if (isObjectSchema) {
+    const properties = schema["properties"];
+    if (isPlainObject4(properties)) {
+      result["properties"] = Object.fromEntries(
+        Object.entries(properties).map(([key, sub]) => [
+          key,
+          isPlainObject4(sub) ? defaultClosedObjectSchema(sub) : sub
+        ])
+      );
+    }
+    if (!Object.hasOwn(schema, "additionalProperties")) {
+      result["additionalProperties"] = false;
+    }
+  }
+  const items = schema["items"];
+  if (isPlainObject4(items)) {
+    result["items"] = defaultClosedObjectSchema(items);
+  }
+  return result;
+}
+var EMPTY_CLOSED_OBJECT_SCHEMA = {
+  type: "object",
+  properties: {},
+  additionalProperties: false
+};
+var UNSUPPORTED_SCHEMA_KEYWORDS = [
+  "pattern",
+  "minLength",
+  "maxLength",
+  "format",
+  "minimum",
+  "maximum",
+  "exclusiveMinimum",
+  "exclusiveMaximum",
+  "multipleOf",
+  "oneOf",
+  "anyOf",
+  "allOf",
+  "not",
+  "$ref",
+  "const",
+  "patternProperties",
+  "minItems",
+  "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;
+  if (Array.isArray(type)) return !type.includes("object");
+  return true;
+}
+function validateResourceSchemaKeywords(id, path2, schema) {
+  for (const keyword of UNSUPPORTED_SCHEMA_KEYWORDS) {
+    if (Object.hasOwn(schema, keyword)) {
+      console.warn(
+        `[agent-commerce] resource "${id}" ${path2} uses JSON Schema keyword "${keyword}", which this gateway does not enforce (see src/core/execution/validation.ts for the supported subset). Remove it or treat it as documentation only.`
+      );
+    }
+  }
+  if ((Object.hasOwn(schema, "properties") || Object.hasOwn(schema, "required")) && excludesObjectType(schema)) {
+    throw new CommerceError(
+      "CONFIG_INVALID",
+      `Resource "${id}" ${path2} declares "properties" and/or "required" but its "type" (${JSON.stringify(schema["type"])}) does not include "object" \u2014 the validator will never route a value through either check under that type, so this schema claims to constrain input it does not actually enforce. Remove "properties"/"required", or include "object" in "type".`,
+      { details: { path: `resources.${id}.${path2}`, resourceId: id } }
+    );
+  }
+  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 undeclared = requiredRaw.filter(
+      (name) => typeof name === "string" && !Object.hasOwn(declared, name)
+    );
+    if (undeclared.length > 0) {
+      throw new CommerceError(
+        "CONFIG_INVALID",
+        `Resource "${id}" ${path2} lists ${undeclared.map((n) => `"${n}"`).join(", ")} in "required" but does not declare ${undeclared.length === 1 ? "it" : "them"} in "properties". The schema is closed (additionalProperties: false), so ${undeclared.length === 1 ? "that name is" : "those names are"} rejected as an unknown key and no input can ever satisfy this schema. Declare ${undeclared.length === 1 ? "it" : "them"} in "properties".`,
+        { details: { path: `resources.${id}.${path2}`, resourceId: id, undeclared } }
+      );
+    }
+  }
+  const properties = schema["properties"];
+  if (isPlainObject4(properties)) {
+    for (const [key, sub] of Object.entries(properties)) {
+      if (isPlainObject4(sub)) validateResourceSchemaKeywords(id, `${path2}.properties.${key}`, sub);
+    }
+  }
+  const items = schema["items"];
+  if (isPlainObject4(items)) {
+    validateResourceSchemaKeywords(id, `${path2}.items`, items);
+  } else if (Array.isArray(items)) {
+    console.warn(
+      `[agent-commerce] resource "${id}" ${path2}.items is a tuple (an array of schemas), which this gateway does not enforce \u2014 only a single schema applied to every array element is supported (see src/core/execution/validation.ts). Each position's schema is unenforced; treat it as documentation only.`
+    );
+  }
+}
+var PRICING_AMOUNT_PATTERN = /^\d+(?:\.\d+)?$/;
+var ZERO_AMOUNT_PATTERN = /^0(?:\.0+)?$/;
+function validatePricingAmount(id, amount, x402) {
+  const path2 = `resources.${id}.pricing.amount`;
+  if (!PRICING_AMOUNT_PATTERN.test(amount)) {
+    throw new CommerceError(
+      "CONFIG_INVALID",
+      `Resource "${id}" has pricing.amount "${amount}", which is not a plain positive decimal (no currency symbol, no thousands separator, no exponent \u2014 e.g. "0.01")`,
+      { details: { path: path2, resourceId: id } }
+    );
+  }
+  if (ZERO_AMOUNT_PATTERN.test(amount)) {
+    throw new CommerceError(
+      "CONFIG_INVALID",
+      `Resource "${id}" has pricing.amount "0" \u2014 a paid resource cannot cost zero; use "pricing: { type: free }" instead`,
+      { details: { path: path2, resourceId: id } }
+    );
+  }
+  if (x402 !== void 0) {
+    const fractionalDigits = amount.includes(".") ? amount.split(".")[1]?.length ?? 0 : 0;
+    if (fractionalDigits > x402.assetDecimals) {
+      throw new CommerceError(
+        "CONFIG_INVALID",
+        `Resource "${id}" has pricing.amount "${amount}" with more precision (${fractionalDigits} fractional digits) than the configured asset supports (${x402.assetDecimals} decimals)`,
+        { details: { path: path2, resourceId: id } }
+      );
+    }
+  }
+}
+function validatePathParametersDeclared(id, url, input) {
+  const stray = findUnparsedBraceToken(url);
+  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`,
+      { details: { path: `resources.${id}.backend.url`, resourceId: id, token: stray } }
+    );
+  }
+  const params = extractPathParameterNames(url);
+  if (params.length === 0) return;
+  const propertiesRaw = input?.["properties"];
+  const properties = isPlainObject4(propertiesRaw) ? propertiesRaw : {};
+  const requiredRaw = input?.["required"];
+  const required = new Set(
+    Array.isArray(requiredRaw) ? requiredRaw.filter((entry) => typeof entry === "string") : []
+  );
+  for (const param of params) {
+    const path2 = `resources.${id}.backend.url`;
+    if (!Object.hasOwn(properties, param)) {
+      throw new CommerceError(
+        "CONFIG_INVALID",
+        `Resource "${id}" has backend.url path parameter "{${param}}" which is not declared in its input schema \u2014 the caller has no way to supply it, so every call would settle payment (if priced) and then fail to reach the backend`,
+        { 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 its input schema but not listed in "required" \u2014 a caller that omits it hits the same unservable-request problem as an undeclared parameter`,
+        { details: { path: path2, resourceId: id, param } }
+      );
+    }
+  }
+}
+function validateBackendUrl(id, url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new CommerceError(
+      "CONFIG_INVALID",
+      `Resource "${id}" has an invalid backend.url "${url}": must be an absolute http:// or https:// URL`,
+      { details: { path: `resources.${id}.backend.url`, resourceId: id } }
+    );
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new CommerceError(
+      "CONFIG_INVALID",
+      `Resource "${id}" has a backend.url with scheme "${parsed.protocol}": must be http:// or https://`,
+      { details: { path: `resources.${id}.backend.url`, resourceId: id } }
+    );
+  }
+}
+function validateAddress(path2, value) {
+  if (!ADDRESS_PATTERN.test(value)) {
+    throw new CommerceError(
+      "CONFIG_INVALID",
+      `Configuration value at "${path2}" is not a plausible address (expected "0x" followed by 40 hex characters)`,
+      { details: { path: path2 } }
+    );
+  }
+  if (ZERO_ADDRESS_PATTERN.test(value)) {
+    throw new CommerceError(
+      "CONFIG_INVALID",
+      `Configuration value at "${path2}" must not be the zero address`,
+      {
+        details: { path: path2 }
+      }
+    );
+  }
+}
+
+// src/config/load.ts
+var CONFIG_PATH_ENV_VAR = "AGENT_COMMERCE_CONFIG";
+async function loadConfig(options = {}) {
+  const env = options.env ?? process.env;
+  const cwd = options.cwd ?? process.cwd();
+  const configPath = resolveConfigPath(options.path, env, cwd);
+  let text;
+  try {
+    text = await promises.readFile(configPath, "utf8");
+  } catch (error) {
+    throw new CommerceError("CONFIG_INVALID", `Could not read configuration file "${configPath}"`, {
+      details: { path: configPath },
+      cause: error
+    });
+  }
+  let raw;
+  try {
+    raw = parse(text);
+  } catch (error) {
+    const { reason, details } = describeYamlError(error);
+    throw new CommerceError(
+      "CONFIG_INVALID",
+      `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).
+        cause: error
+      }
+    );
+  }
+  return parseConfig(raw, env);
+}
+var YAML_ERROR_EXPLANATIONS = {
+  DUPLICATE_KEY: "map keys must be unique",
+  BAD_INDENT: "bad indentation",
+  TAB_AS_INDENT: "tabs cannot be used for indentation",
+  MISSING_CHAR: "a required character is missing",
+  BLOCK_AS_IMPLICIT_KEY: "a block value cannot be used as a key (missing quotes, or a stray colon)",
+  MULTILINE_IMPLICIT_KEY: "a key spans multiple lines (missing quotes, or a stray colon)",
+  UNEXPECTED_TOKEN: "unexpected token"
+};
+function describeYamlError(error) {
+  if (!(error instanceof YAMLError)) {
+    return { reason: "unknown YAML parse error", details: {} };
+  }
+  const start = error.linePos?.[0];
+  const where = start === void 0 ? "" : ` at line ${String(start.line)}, column ${String(start.col)}`;
+  const explanation = YAML_ERROR_EXPLANATIONS[error.code];
+  const what = explanation === void 0 ? error.code : `${error.code} (${explanation})`;
+  return {
+    reason: `${what}${where}`,
+    details: {
+      yamlErrorCode: error.code,
+      ...start === void 0 ? {} : { line: start.line, column: start.col }
+    }
+  };
+}
+function resolveConfigPath(explicitPath, env, cwd) {
+  if (explicitPath) return path.resolve(cwd, explicitPath);
+  const fromEnv = env[CONFIG_PATH_ENV_VAR];
+  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 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",
+  "apiKey",
+  "adminToken",
+  "token"
+];
+var REDACT_PATHS = [
+  "req.headers.authorization",
+  'req.headers["x-payment"]',
+  ...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;
+}
+var CORS_METHODS = "GET,POST,DELETE,OPTIONS";
+var CORS_HEADERS = "content-type,x-payment,x-request-id,authorization";
+function buildAccessControlHook(options) {
+  const allowedOrigins = new Set(options.allowedOrigins.map((origin) => origin.toLowerCase()));
+  const publicHostname = hostnameOf(options.publicBaseUrl);
+  return async (request, reply) => {
+    const host = request.headers.host;
+    if (!isAllowedHost(host, publicHostname)) {
+      reply.status(403).send({ status: "error", code: "FORBIDDEN", message: "Host not allowed" });
+      return;
+    }
+    const origin = request.headers.origin;
+    if (origin !== void 0) {
+      if (!allowedOrigins.has(origin.toLowerCase())) {
+        reply.status(403).send({ status: "error", code: "FORBIDDEN", message: "Origin not allowed" });
+        return;
+      }
+      reply.header("access-control-allow-origin", origin);
+      reply.header("access-control-allow-methods", CORS_METHODS);
+      reply.header("access-control-allow-headers", CORS_HEADERS);
+      reply.header("vary", "Origin");
+      if (request.method === "OPTIONS") {
+        reply.status(204).send();
+      }
+    }
+  };
+}
+function buildOperatorTokenHook(adminToken) {
+  return async (request, reply) => {
+    if (!adminToken) {
+      reply.status(404).send();
+      return;
+    }
+    if (!isValidAdminToken(request.headers.authorization, adminToken)) {
+      reply.status(401).send({ status: "error", code: "UNAUTHORIZED", message: "Admin token required" });
+    }
+  };
+}
+function hostnameOf(value) {
+  try {
+    const hostname = new URL(
+      value.includes("://") ? value : `http://${value}`
+    ).hostname.toLowerCase();
+    return hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
+  } catch {
+    return "";
+  }
+}
+var LOOPBACK_HOSTNAMES = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "::1"]);
+function isAllowedHost(hostHeader, publicHostname) {
+  if (!hostHeader) return false;
+  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;
+async function startAndMountAdapters(options) {
+  const runtimes = [];
+  for (const adapter of options.adapters) {
+    const adapterLogger = options.logger.child({ adapter: adapter.name });
+    const adapterContext = { ...options.context, logger: adapterLogger };
+    try {
+      await adapter.start(adapterContext);
+    } catch (error) {
+      const detail = describeError3(error);
+      adapterLogger.error(
+        { err: detail },
+        "Protocol adapter failed to start; gateway continues without it"
+      );
+      runtimes.push({
+        adapter,
+        startFailure: { status: "fail", detail, checkedAt: options.clock.nowIso() }
+      });
+      continue;
+    }
+    if (isHttpProtocolAdapter(adapter)) {
+      mountHttpAdapter(options.server, adapter, adapterLogger);
+    }
+    runtimes.push({ adapter });
+  }
+  return runtimes;
+}
+var MOUNT_MAX_CONCURRENT_REQUESTS = 20;
+var MOUNT_BUSY_RETRY_AFTER_SECONDS = 1;
+function mountHttpAdapter(server, adapter, logger) {
+  const mountPath = adapter.mountPath;
+  const wildcard = mountPath.endsWith("/") ? `${mountPath}*` : `${mountPath}/*`;
+  let inFlight = 0;
+  void server.register(async (instance) => {
+    instance.addContentTypeParser(
+      ["application/json", "text/plain"],
+      (_request, _payload, done) => {
+        done(null);
+      }
+    );
+    instance.addContentTypeParser("*", (_request, _payload, done) => {
+      done(null);
+    });
+    const handler = async (request, reply) => {
+      if (inFlight >= MOUNT_MAX_CONCURRENT_REQUESTS) {
+        const error = new CommerceError(
+          "GATEWAY_BUSY",
+          "Too many requests already parsing on this mount; retry shortly."
+        );
+        reply.status(error.httpStatus).header("retry-after", String(MOUNT_BUSY_RETRY_AFTER_SECONDS)).send(toErrorEnvelope(error));
+        return;
+      }
+      inFlight += 1;
+      try {
+        const stopEnforcing = enforceMountBodyLimit(
+          request.raw,
+          reply.raw,
+          MOUNT_BODY_LIMIT_BYTES,
+          logger
+        );
+        try {
+          await adapter.handleHttp(request.raw, reply.raw);
+        } catch (error) {
+          logger.error({ err: describeError3(error) }, "Protocol adapter request handler threw");
+          if (!reply.raw.headersSent) {
+            reply.raw.statusCode = 500;
+            reply.raw.end();
+          }
+        }
+        stopEnforcing();
+        reply.hijack();
+      } finally {
+        inFlight -= 1;
+      }
+    };
+    instance.all(mountPath, handler);
+    instance.all(wildcard, handler);
+  });
+}
+function enforceMountBodyLimit(req, res, maxBytes, logger) {
+  const socket = req.socket;
+  let total = 0;
+  let stopped = false;
+  const onData = (chunk) => {
+    total += chunk.length;
+    if (total > maxBytes) {
+      stop();
+      logger.warn({ maxBytes }, "Request body exceeded the mount body limit; connection closed");
+      if (!res.headersSent) {
+        const body = JSON.stringify({
+          jsonrpc: "2.0",
+          id: null,
+          error: { code: -32600, message: `Request body exceeds the ${maxBytes}-byte mount limit` }
+        });
+        try {
+          res.writeHead(413, {
+            "content-type": "application/json",
+            "content-length": Buffer.byteLength(body)
+          });
+          res.end(body, () => socket.destroy());
+          return;
+        } catch {
+        }
+      }
+      socket.destroy();
+    }
+  };
+  const stop = () => {
+    if (stopped) return;
+    stopped = true;
+    socket.removeListener("data", onData);
+    socket.removeListener("close", stop);
+  };
+  socket.on("data", onData);
+  socket.once("close", stop);
+  return stop;
+}
+async function getAdapterHealth(runtime, clock) {
+  if (runtime.startFailure) return runtime.startFailure;
+  try {
+    return await runtime.adapter.health();
+  } catch (error) {
+    return { status: "fail", detail: describeError3(error), checkedAt: clock.nowIso() };
+  }
+}
+async function stopAdapters(runtimes, logger) {
+  for (const runtime of runtimes) {
+    try {
+      await runtime.adapter.stop();
+    } catch (error) {
+      logger.child({ adapter: runtime.adapter.name }).error({ err: describeError3(error) }, "Protocol adapter failed to stop cleanly");
+    }
+  }
+}
+function describeError3(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/gateway/public-resource.ts
+function toPublicResource(resource) {
+  return {
+    id: resource.id,
+    name: resource.name,
+    ...resource.description !== void 0 ? { description: resource.description } : {},
+    ...resource.inputSchema !== void 0 ? { inputSchema: resource.inputSchema } : {},
+    ...resource.outputSchema !== void 0 ? { outputSchema: resource.outputSchema } : {},
+    method: resource.handler.method,
+    pricing: resource.pricing,
+    exposedVia: resource.exposedVia,
+    paymentMethods: resource.paymentMethods
+  };
+}
+
+// src/gateway/readiness.ts
+var STORE_DETAIL = {
+  pass: void 0,
+  warn: "store-degraded",
+  fail: "store-unwritable"
+};
+var ADAPTER_DETAIL = {
+  pass: void 0,
+  warn: "adapter-degraded",
+  fail: "adapter-unreachable"
+};
+var PAYMENT_PROVIDER_DETAIL = {
+  pass: void 0,
+  warn: "payment-provider-degraded",
+  fail: "payment-provider-unreachable"
+};
+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(async (provider) => {
+      let health;
+      try {
+        health = await provider.health();
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        options.logger.error(
+          { err: message, provider: provider.name },
+          "payment provider health() threw"
+        );
+        health = { status: "fail", checkedAt: options.clock.nowIso() };
+      }
+      if (health.detail !== void 0) {
+        options.logger.debug(
+          { provider: provider.name, detail: health.detail },
+          "payment provider health detail (not sent to the client)"
+        );
+      }
+      const detail = PAYMENT_PROVIDER_DETAIL[health.status];
+      return {
+        name: provider.name,
+        status: health.status,
+        ...detail !== void 0 ? { detail } : {}
+      };
+    })
+  );
+  const storeReady = storeHealth.status !== "fail";
+  const adaptersReady = adapterChecks.every((check) => check.status !== "fail");
+  const paymentProvidersReady = paymentProviderChecks.every((check) => check.status !== "fail");
+  const storeDetail = storeThrew ? "store-unreachable" : STORE_DETAIL[storeHealth.status];
+  return {
+    ready: storeReady && adaptersReady && paymentProvidersReady,
+    store: {
+      name: "store",
+      status: storeHealth.status,
+      ...storeDetail !== void 0 ? { detail: storeDetail } : {}
+    },
+    adapters: adapterChecks,
+    paymentProviders: paymentProviderChecks
+  };
+}
+var READINESS_TTL_MS = 2e3;
+function createReadinessProbe(options, ttlMs = READINESS_TTL_MS) {
+  let cached;
+  let 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;
+    }
+  };
+}
+
+// src/gateway/well-known.ts
+var GATEWAY_SUPPORTED_SPEC = "agent-commerce/v0.1.0-alpha";
+async function buildWellKnownDocument(options) {
+  const adapters = await Promise.all(
+    options.adapterRuntimes.map(async (runtime) => ({
+      ...runtime.adapter.descriptor,
+      health: await getAdapterHealth(runtime, options.clock)
+    }))
+  );
+  const x402 = options.config.payments.x402;
+  return {
+    gateway: {
+      implementationVersion: PACKAGE_VERSION,
+      supportedSpec: GATEWAY_SUPPORTED_SPEC
+    },
+    merchant: options.config.merchant,
+    protocols: options.config.protocols,
+    adapters,
+    paymentProviders: options.paymentProviders.map((provider) => provider.descriptor),
+    store: options.store.descriptor,
+    payments: {
+      ...x402 !== void 0 ? {
+        x402: {
+          enabled: x402.enabled,
+          network: x402.network,
+          asset: x402.asset,
+          assetName: x402.assetName,
+          assetVersion: x402.assetVersion,
+          assetDecimals: x402.assetDecimals,
+          payTo: x402.payTo,
+          maxTimeoutSeconds: x402.maxTimeoutSeconds,
+          // Never the signerPrivateKey — only whether the facilitator is
+          // local (dev-chain only) or remote, plus its (non-secret) URL.
+          facilitator: x402.facilitator.mode === "local" ? { mode: "local" } : { mode: "remote", url: x402.facilitator.url }
+        }
+      } : {}
+    }
+  };
+}
+
+// src/gateway/routes.ts
+var SSE_HEARTBEAT_MS = 15e3;
+var MAX_SSE_SUBSCRIBERS = 32;
+function registerRoutes(options) {
+  const { server } = options;
+  const readinessProbe = createReadinessProbe({
+    store: options.store,
+    adapterRuntimes: options.adapterRuntimes,
+    paymentProviders: options.paymentProviders,
+    clock: options.clock,
+    logger: options.logger
+  });
+  server.get("/health", async () => ({ status: "ok" }));
+  server.get("/ready", async (_request, reply) => {
+    const readiness = await readinessProbe.check();
+    reply.status(readiness.ready ? 200 : 503);
+    return readiness;
+  });
+  server.get(
+    "/.well-known/agent-commerce",
+    async () => buildWellKnownDocument({
+      config: options.config,
+      paymentProviders: options.paymentProviders,
+      store: options.store,
+      adapterRuntimes: options.adapterRuntimes,
+      clock: options.clock
+    })
+  );
+  server.get("/api/resources", async () => ({
+    resources: options.resources.list().map(toPublicResource)
+  }));
+  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) => {
+    try {
+      const limit = parseLimit(request.query["limit"]);
+      return { events: await options.store.listEvents(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")) {
+      throw new CommerceError("RESOURCE_NOT_FOUND", `Resource "${resourceId}" was not found`, {
+        requestId: request.id,
+        resourceId
+      });
+    }
+    const paymentHeader = request.headers[PAYMENT_HEADER];
+    const paymentValue = Array.isArray(paymentHeader) ? paymentHeader[0] : paymentHeader;
+    const paymentMethod = resource.paymentMethods[0];
+    const payment = paymentValue !== void 0 && paymentMethod !== void 0 ? { method: paymentMethod, payload: paymentValue } : void 0;
+    const canonicalRequest = {
+      requestId: request.id,
+      resourceId,
+      input: request.body ?? {},
+      protocol: "http",
+      receivedAt: options.clock.nowIso(),
+      ...payment !== void 0 ? { payment } : {}
+    };
+    const outcome = await options.pipeline.execute(canonicalRequest);
+    if (outcome.kind === "payment-required") {
+      reply.status(402).send(toPaymentRequiredEnvelope(outcome));
+      return;
+    }
+    if (outcome.payment) {
+      reply.header(PAYMENT_RESPONSE_HEADER, encodePaymentSummary(outcome.payment));
+    }
+    reply.status(outcome.backendStatus).send(outcome.body);
+  } catch (error) {
+    const commerceError = toCommerceError(error);
+    const settledPayment = errorPaymentSummary(commerceError);
+    if (settledPayment !== void 0) {
+      reply.header(PAYMENT_RESPONSE_HEADER, encodePaymentSummary(settledPayment));
+    }
+    reply.status(commerceError.httpStatus).send(toErrorEnvelope(commerceError));
+  }
+}
+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, externalReference } = rec;
+  if (typeof status !== "string" || typeof provider !== "string" || typeof amount !== "string" || typeof currency !== "string") {
+    return void 0;
+  }
+  return {
+    status,
+    provider,
+    amount,
+    currency,
+    ...typeof externalReference === "string" ? { externalReference } : {}
+  };
+}
+function encodePaymentSummary(payment) {
+  const summary = {
+    status: payment.status,
+    provider: payment.provider,
+    amount: payment.amount,
+    currency: payment.currency,
+    ...payment.externalReference !== void 0 ? { externalReference: payment.externalReference } : {}
+  };
+  return Buffer.from(JSON.stringify(summary), "utf8").toString("base64");
+}
+function parseLimit(value) {
+  if (Array.isArray(value)) return parseLimit(value[0]);
+  let n;
+  if (typeof value === "number" && Number.isFinite(value)) n = Math.trunc(value);
+  else if (typeof value === "string" && value.length > 0) {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) n = Math.trunc(parsed);
+  }
+  if (n === void 0) return void 0;
+  if (n <= 0) {
+    throw new CommerceError(
+      "INPUT_INVALID",
+      `Query parameter "limit" must be a positive integer (got ${n})`,
+      {
+        details: { field: "limit" }
+      }
+    );
+  }
+  return n;
+}
+
+// src/gateway/server.ts
+var REQUEST_ID_HEADER = "x-request-id";
+var CLIENT_REQUEST_ID_PATTERN = /^[A-Za-z0-9._:-]{1,64}$/;
+async function createGateway(options) {
+  const clock = options.clock ?? systemClock;
+  const ids = options.ids ?? createDefaultIdGenerator();
+  const logger = options.logger ?? createGatewayLogger({ name: options.config.merchant.id }).core;
+  const backend = options.backend ?? new HttpBackendExecutor({ logger });
+  const resources = createResourceRegistry(options.config.resources);
+  const eventBus = createEventBus({ store: options.store, logger });
+  const pipeline = createExecutionPipeline({
+    resources,
+    paymentProviders: options.paymentProviders,
+    store: options.store,
+    backend,
+    events: eventBus,
+    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.
+    bodyLimit: MOUNT_BODY_LIMIT_BYTES,
+    genReqId: (rawReq) => {
+      const header = rawReq.headers[REQUEST_ID_HEADER];
+      const value = Array.isArray(header) ? header[0] : header;
+      return value !== void 0 && CLIENT_REQUEST_ID_PATTERN.test(value) ? value : ids.next("req");
+    },
+    logger: fastifyLoggerOptions({ name: `${options.config.merchant.id}-http` })
+  });
+  server.setNotFoundHandler(buildNotFoundHandler());
+  server.addHook(
+    "onRequest",
+    buildAccessControlHook({
+      publicBaseUrl: options.config.merchant.publicBaseUrl,
+      allowedOrigins: options.config.server.allowedOrigins
+    })
+  );
+  const adapterRuntimes = [];
+  registerRoutes({
+    server,
+    config: options.config,
+    pipeline,
+    resources,
+    store: options.store,
+    paymentProviders: options.paymentProviders,
+    eventBus,
+    clock,
+    adapterRuntimes,
+    logger
+  });
+  const context = {
+    pipeline,
+    resources,
+    events: eventBus,
+    logger,
+    clock,
+    ids,
+    publicBaseUrl: options.config.merchant.publicBaseUrl
+  };
+  const started = await startAndMountAdapters({
+    server,
+    adapters: options.protocolAdapters,
+    context,
+    logger,
+    clock
+  });
+  adapterRuntimes.push(...started);
+  await server.ready();
+  return {
+    pipeline,
+    resources,
+    async listen() {
+      const url = await server.listen({
+        port: options.config.server.port,
+        host: options.config.server.host
+      });
+      return { url };
+    },
+    async close() {
+      await stopAdapters(adapterRuntimes, logger);
+      await server.close();
+    },
+    server
+  };
+}
+
+// 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;
+var REDACTED = "[REDACTED]";
+function isSecretKey(key) {
+  return SECRET_KEY_PATTERN.test(key);
+}
+function redact(value) {
+  return redactValue(value);
+}
+function redactValue(value) {
+  if (Array.isArray(value)) {
+    return value.map(redactValue);
+  }
+  if (value !== null && typeof value === "object") {
+    const out = {};
+    for (const [key, inner] of Object.entries(value)) {
+      out[key] = isSecretKey(key) ? REDACTED : redactValue(inner);
+    }
+    return out;
+  }
+  return value;
+}
+
+// src/storage/receipts/rows.ts
+function receiptToRow(receipt) {
+  return {
+    id: receipt.id,
+    request_id: receipt.requestId,
+    resource_id: receipt.resourceId,
+    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,
+    metadata_json: receipt.metadata !== void 0 ? JSON.stringify(redact(receipt.metadata)) : null
+  };
+}
+function rowToReceipt(row) {
+  const payment = row.payment_json !== null ? JSON.parse(row.payment_json) : void 0;
+  const metadata = row.metadata_json !== null ? JSON.parse(row.metadata_json) : void 0;
+  return {
+    id: row.id,
+    requestId: row.request_id,
+    resourceId: row.resource_id,
+    deliveredAt: row.delivered_at,
+    backendStatus: row.backend_status,
+    ...payment !== void 0 ? { payment } : {},
+    ...row.duration_ms !== null ? { durationMs: row.duration_ms } : {},
+    ...row.protocol !== null ? { protocol: row.protocol } : {},
+    ...metadata !== void 0 ? { metadata } : {}
+  };
+}
+function eventToRow(event) {
+  return {
+    id: event.id,
+    type: event.type,
+    request_id: event.requestId,
+    resource_id: event.resourceId !== void 0 ? 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,
+    data_json: event.data !== void 0 ? JSON.stringify(redact(event.data)) : null
+  };
+}
+function rowToEvent(row) {
+  const data = row.data_json !== null ? JSON.parse(row.data_json) : void 0;
+  return {
+    id: row.id,
+    type: row.type,
+    requestId: row.request_id,
+    at: row.at,
+    ...row.resource_id !== null ? { resourceId: row.resource_id } : {},
+    ...row.adapter !== null ? { adapter: row.adapter } : {},
+    ...row.payment_provider !== null ? { paymentProvider: row.payment_provider } : {},
+    ...row.duration_ms !== null ? { durationMs: row.duration_ms } : {},
+    ...row.status !== null ? { status: row.status } : {},
+    ...data !== void 0 ? { data } : {}
+  };
+}
+function rowToPaymentAttempt(row) {
+  return {
+    id: row.id,
+    requestId: row.request_id,
+    resourceId: row.resource_id,
+    provider: row.provider,
+    replayKey: row.replay_key,
+    status: row.status,
+    amount: row.amount,
+    currency: row.currency,
+    ...row.payer !== null ? { payer: row.payer } : {},
+    ...row.payee !== null ? { payee: row.payee } : {},
+    ...row.external_reference !== null ? { externalReference: row.external_reference } : {},
+    ...row.rejection_reason !== null ? { rejectionReason: row.rejection_reason } : {},
+    createdAt: row.created_at,
+    updatedAt: row.updated_at
+  };
+}
+
+// src/storage/receipts/schema.ts
+var MIGRATIONS = [
+  {
+    version: 1,
+    up(db) {
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS receipts (
+          seq             INTEGER PRIMARY KEY AUTOINCREMENT,
+          id              TEXT NOT NULL UNIQUE,
+          request_id      TEXT NOT NULL,
+          resource_id     TEXT NOT NULL,
+          payment_json    TEXT,
+          delivered_at    TEXT NOT NULL,
+          backend_status  INTEGER NOT NULL,
+          duration_ms     INTEGER,
+          protocol        TEXT,
+          metadata_json   TEXT
+        );
+        CREATE INDEX IF NOT EXISTS idx_receipts_request_id ON receipts(request_id);
+        CREATE INDEX IF NOT EXISTS idx_receipts_delivered_at ON receipts(delivered_at);
+
+        CREATE TABLE IF NOT EXISTS events (
+          seq               INTEGER PRIMARY KEY AUTOINCREMENT,
+          id                TEXT NOT NULL UNIQUE,
+          type              TEXT NOT NULL,
+          request_id        TEXT NOT NULL,
+          resource_id       TEXT,
+          at                TEXT NOT NULL,
+          adapter           TEXT,
+          payment_provider  TEXT,
+          duration_ms       INTEGER,
+          status            TEXT,
+          data_json         TEXT
+        );
+        CREATE INDEX IF NOT EXISTS idx_events_request_id ON events(request_id);
+        CREATE INDEX IF NOT EXISTS idx_events_at ON events(at);
+
+        CREATE TABLE IF NOT EXISTS payment_attempts (
+          seq                 INTEGER PRIMARY KEY AUTOINCREMENT,
+          id                  TEXT NOT NULL UNIQUE,
+          request_id          TEXT NOT NULL,
+          resource_id         TEXT NOT NULL,
+          provider             TEXT NOT NULL,
+          replay_key          TEXT NOT NULL UNIQUE,
+          status              TEXT NOT NULL,
+          amount              TEXT NOT NULL,
+          currency            TEXT NOT NULL,
+          payer               TEXT,
+          payee               TEXT,
+          external_reference  TEXT,
+          rejection_reason    TEXT,
+          created_at          TEXT NOT NULL,
+          updated_at          TEXT NOT NULL
+        );
+        CREATE INDEX IF NOT EXISTS idx_payment_attempts_request_id ON payment_attempts(request_id);
+        CREATE INDEX IF NOT EXISTS idx_payment_attempts_created_at ON payment_attempts(created_at);
+      `);
+    }
+  }
+];
+var SCHEMA_VERSION = MIGRATIONS[MIGRATIONS.length - 1]?.version ?? 0;
+function migrate(db) {
+  const current = db.pragma("user_version", { simple: true });
+  for (const migration of MIGRATIONS) {
+    if (migration.version <= current) continue;
+    const apply = db.transaction(() => {
+      migration.up(db);
+      db.pragma(`user_version = ${migration.version}`);
+    });
+    apply();
+  }
+}
+
+// src/storage/receipts/store.ts
+var DEFAULT_LIST_LIMIT = 50;
+var MAX_LIST_LIMIT = 500;
+function clampListLimit(limit) {
+  const base = limit !== void 0 && Number.isFinite(limit) ? limit : DEFAULT_LIST_LIMIT;
+  return Math.min(Math.max(Math.trunc(base), 1), MAX_LIST_LIMIT);
+}
+var defaultIds = {
+  next: (prefix) => prefix !== void 0 ? `${prefix}_${randomUUID()}` : randomUUID()
+};
+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 } }
+      );
+    }
+  }
+  const db = new Database(path2);
+  db.pragma("journal_mode = WAL");
+  db.pragma("foreign_keys = ON");
+  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)`
+  );
+  const getReceiptStmt = db.prepare("SELECT * FROM receipts WHERE id = ?");
+  const listReceiptsStmt = db.prepare(
+    "SELECT * FROM receipts ORDER BY delivered_at DESC, seq DESC LIMIT ?"
+  );
+  const listReceiptsByRequestStmt = db.prepare(
+    "SELECT * FROM receipts WHERE request_id = ? ORDER BY delivered_at DESC, seq DESC LIMIT ?"
+  );
+  const countReceiptsStmt = db.prepare(
+    "SELECT COUNT(*) AS count FROM receipts"
+  );
+  const countUndeliveredReceiptsStmt = db.prepare(
+    "SELECT COUNT(*) AS count FROM receipts WHERE backend_status NOT BETWEEN 200 AND 299"
+  );
+  const insertEventStmt = db.prepare(
+    `INSERT INTO events (id, type, request_id, resource_id, at, adapter, payment_provider, duration_ms, status, data_json)
+     VALUES (@id, @type, @request_id, @resource_id, @at, @adapter, @payment_provider, @duration_ms, @status, @data_json)`
+  );
+  const listEventsStmt = db.prepare(
+    "SELECT * FROM events ORDER BY at DESC, seq DESC LIMIT ?"
+  );
+  const listEventsByRequestStmt = db.prepare(
+    "SELECT * FROM events WHERE request_id = ? ORDER BY at DESC, seq DESC LIMIT ?"
+  );
+  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 = ?"
+  );
+  const updatePaymentAttemptStmt = db.prepare(
+    `UPDATE payment_attempts SET status = @status,
+       external_reference = COALESCE(@external_reference, external_reference),
+       rejection_reason = COALESCE(@rejection_reason, rejection_reason),
+       updated_at = @updated_at
+     WHERE replay_key = @replay_key`
+  );
+  const listPaymentAttemptsStmt = db.prepare(
+    "SELECT * FROM payment_attempts ORDER BY created_at DESC, seq DESC LIMIT ?"
+  );
+  const listPaymentAttemptsByRequestStmt = db.prepare(
+    "SELECT * FROM payment_attempts WHERE request_id = ? ORDER BY created_at DESC, seq DESC LIMIT ?"
+  );
+  let closed = false;
+  const descriptor = {
+    name: "sqlite-receipt-store",
+    kind: "storage",
+    implementationVersion: PACKAGE_VERSION,
+    supportedSpec: `sqlite-schema-v${SCHEMA_VERSION}`,
+    capabilities: ["receipts", "events", "payment-attempts"],
+    status: "stable"
+  };
+  const store = {
+    async init() {
+      const version = db.pragma("user_version", { simple: true });
+      if (version !== SCHEMA_VERSION) {
+        throw new CommerceError(
+          "STORAGE_ERROR",
+          `Receipt store schema version mismatch (found ${version}, expected ${SCHEMA_VERSION})`
+        );
+      }
+    },
+    async appendEvent(event) {
+      try {
+        insertEventStmt.run(eventToRow(event));
+      } catch (err) {
+        logger.warn(
+          {
+            err: err instanceof Error ? err.message : String(err),
+            eventId: event.id,
+            requestId: event.requestId
+          },
+          "receipt-store: failed to persist commerce event"
+        );
+      }
+    },
+    async reservePaymentAttempt(reservation) {
+      const now = clock.nowIso();
+      const id = ids.next("attempt");
+      try {
+        insertPaymentAttemptStmt.run({
+          id,
+          request_id: reservation.requestId,
+          resource_id: reservation.resourceId,
+          provider: reservation.provider,
+          replay_key: reservation.replayKey,
+          status: "reserved",
+          amount: reservation.amount,
+          currency: reservation.currency,
+          payer: reservation.payer ?? null,
+          payee: reservation.payee ?? null,
+          external_reference: null,
+          rejection_reason: null,
+          created_at: now,
+          updated_at: now
+        });
+      } catch (err) {
+        if (isUniqueConstraintOn(err, "payment_attempts.replay_key")) {
+          throw new CommerceError(
+            "PAYMENT_REPLAYED",
+            `Payment authorisation 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) {
+      try {
+        const result = updatePaymentAttemptStmt.run({
+          replay_key: update.replayKey,
+          status: update.status,
+          external_reference: update.externalReference ?? null,
+          rejection_reason: update.rejectionReason ?? null,
+          updated_at: clock.nowIso()
+        });
+        if (result.changes === 0) {
+          throw new CommerceError(
+            "STORAGE_ERROR",
+            `No payment attempt found for replayKey=${update.replayKey}`
+          );
+        }
+      } catch (err) {
+        throw toCommerceError(err, "STORAGE_ERROR", "Failed to update payment attempt");
+      }
+    },
+    async saveReceipt(receipt) {
+      try {
+        insertReceiptStmt.run(receiptToRow(receipt));
+      } catch (err) {
+        throw toCommerceError(err, "STORAGE_ERROR", "Failed to save receipt");
+      }
+    },
+    async getReceipt(id) {
+      const row = getReceiptStmt.get(id);
+      return row !== void 0 ? rowToReceipt(row) : void 0;
+    },
+    async listReceipts(listOptions = {}) {
+      const limit = clampListLimit(listOptions.limit);
+      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. */
+    async countReceipts() {
+      return countReceiptsStmt.get()?.count ?? 0;
+    },
+    /** Exact count of non-2xx receipts — see the interface doc for why this exists. */
+    async countUndeliveredReceipts() {
+      return countUndeliveredReceiptsStmt.get()?.count ?? 0;
+    },
+    async listEvents(listOptions = {}) {
+      const limit = clampListLimit(listOptions.limit);
+      const rows = listOptions.requestId !== void 0 ? listEventsByRequestStmt.all(listOptions.requestId, limit) : listEventsStmt.all(limit);
+      return rows.map(rowToEvent);
+    },
+    async listPaymentAttempts(listOptions = {}) {
+      const limit = clampListLimit(listOptions.limit);
+      const rows = listOptions.requestId !== void 0 ? listPaymentAttemptsByRequestStmt.all(listOptions.requestId, limit) : listPaymentAttemptsStmt.all(limit);
+      return rows.map(rowToPaymentAttempt);
+    },
+    descriptor,
+    async health() {
+      const startedAt = clock.monotonicMs();
+      if (closed) {
+        return { status: "fail", detail: "store-unavailable", checkedAt: clock.nowIso() };
+      }
+      if (isFileBacked) {
+        try {
+          accessSync(path2, constants.W_OK);
+        } catch (err) {
+          logger.warn(
+            { err: err instanceof Error ? err.message : String(err) },
+            "receipt-store: health check failed (store not writable)"
+          );
+          return {
+            status: "fail",
+            detail: "store-unwritable",
+            checkedAt: clock.nowIso(),
+            durationMs: clock.monotonicMs() - startedAt
+          };
+        }
+      }
+      try {
+        const version = db.pragma("user_version", { simple: true });
+        if (version !== SCHEMA_VERSION) {
+          logger.warn(
+            { found: version, expected: SCHEMA_VERSION },
+            "receipt-store: health check failed (schema version mismatch)"
+          );
+          return {
+            status: "fail",
+            detail: "store-schema-mismatch",
+            checkedAt: clock.nowIso(),
+            durationMs: clock.monotonicMs() - startedAt
+          };
+        }
+        return {
+          status: "pass",
+          detail: `sqlite schema v${SCHEMA_VERSION} writable`,
+          checkedAt: clock.nowIso(),
+          durationMs: clock.monotonicMs() - startedAt
+        };
+      } catch (err) {
+        logger.warn(
+          { err: err instanceof Error ? err.message : String(err) },
+          "receipt-store: health check failed (store unavailable)"
+        );
+        return {
+          status: "fail",
+          detail: "store-unavailable",
+          checkedAt: clock.nowIso(),
+          durationMs: clock.monotonicMs() - startedAt
+        };
+      }
+    },
+    async close() {
+      if (!closed) {
+        closed = true;
+        db.close();
+      }
+    }
+  };
+  return store;
+}
+
+export { createGateway, createSqliteReceiptStore, loadConfig, parseConfig, createSqliteReceiptStore as receipts };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map